Docs/ecosystem 1.0 - #14
Merged
Merged
Conversation
…bundle retires zipnative-cli 1.0.0 and zipnative-mcp 1.0.0 are on npm, so the manifest (docs/assets/ecosystem.json) now records both satellites — version, repo, binary, pin, command groups, tools, prompts, env vars — and verify-docs polices the record: manifest-shape covers every package, jsonld-version checks satellite 'about' nodes, and the new satellite-counts rule ties every '15 commands' / '13 tools' / '7 prompts' literal to the manifest. The playgrounds drop the pre-publication fallback: load-engine.js is CDN-only (esm.sh → jsDelivr, capability probe kept, loud on-page error when both fail), the committed copy of dist/index.js and the docs:playground script are deleted, docs.yml no longer builds before verifying, and the playground-bundle rule becomes cdn-pin (pin == manifest, no local import, no stale bundle). verifiedOn → 2026-09-07.
…t say so zipnative-cli 1.0.0 and zipnative-mcp 1.0.0 replace every 'planned' mention: the README ecosystem table names the binaries, counts and the ^1.0.0 pin and gains the two npm badges; ROADMAP ticks the satellites (with publication dates) and keeps AES-read as the post-1.0 engine item; AGENTS records the shipped agent contract on both surfaces; llms.txt grows an Ecosystem section listing every command and tool by name.
…policed docs/data/surfaces.json records, per capability, what the library, the CLI and the MCP server each offer (23 rows, honest 'not supported' cells with the alternative named); docs/data/cli-surface.json is the pruned snapshot of the published CLI's own capability manifest plus its boolean-flag table. Two verify-docs rules keep them true: surfaces-shape (every named export, command and tool exists in api.json / the ecosystem manifest) and cli-surface-parity (snapshot version and command set equal the manifest, boolean flags belong to their command, every limit flag is global). Both artefacts join the llms index.
…grounds, choose matrix, Case 5 Three guides join the site in the pdfnative charter: guides/cli.md (the fifteen commands with every flag, the agent contract, global options, environment, security posture, what the CLI does not do), guides/mcp.md (client configuration for Claude Desktop, Claude Code, Cursor, VS Code and Streamable HTTP; the thirteen tools with inputs and outputs; the seven prompts; sandboxed resources; the seven environment variables; error and security models) and guides/choose.md (the capability × surface matrix, row for row the machine-readable surfaces.json). Two playgrounds join the five library ones: playgrounds/cli.html is a command builder driven by an embedded JSON copy of the CLI surface — every flag of every command, validation of the combinations the CLI refuses, 27 presets, a copy-ready POSIX line — and playgrounds/mcp.html is a tool explorer with the real MCP payloads and a Run button that executes the engine call behind twelve of the thirteen tools on a sample or on a dropped archive, honest about what only the Node server can do. Use case 5, 'Encrypt first, then archive', shows why no surface has a password: confidentiality is delegated to the document layer (pdfnative AES-256, Office) and the archive stays deterministic and verifiable — with a diagram in the use-case visual language, a TypeScript composition and a two-CLI pipeline. verify-docs grows cli-surface-parity parts 2 and 3 (guide and builder against the snapshot, boolean kinds against the CLI's table), mcp-surface-parity (guide headings, prompts, env vars, resource template, playground card order) and switcher-parity (ported from pdfnative). Hub, sitemap, footers and agent-brief updated.
…witcher, live npm strip, architecture consumers band The landing gains a 'Pick your surface' section (library, CLI, MCP server — each with its guide, playground and install line), a hero install switcher, the two satellite badges, and a live 'npm' strip fed by assets/versions.js (the pdfnative widget, three packages, the transitive pin shown; FALLBACK policed by the new versions-widget rule). architecture.svg grows a top 'ecosystem consumers' band — zipnative-cli and zipnative-mcp consuming the library via npm ^1.0.0 — above the untouched module diagram, with the desc, alt and legend updated. The MCP explorer's truncated-scan variant cuts at 40 % so the cut lands inside the entries.
Every HTML page's nav gains the Ecosystem entry; every guide and playground footer links the choose, CLI and MCP guides and the two satellite playgrounds (one idempotent sweep over 18 shells — the rendered articles are untouched, build-guides reports 0 updated). og-image.svg and social-preview.svg carry two accent pills, CLI and MCP, and a footer line naming the three surfaces; both PNGs re-rasterised at 1200×630 and 1280×640 with headless Edge.
…y rule CHANGELOG gains the [Unreleased] Documentation section describing this branch. verify-docs gains switcher-parity (every playground page lists every playground page in its sub-nav, marks itself aria-current, and the hub has a card for each) — the rule the previous commit message promised.
…rces and fixed Audit A (factual conformity, source trees and the published tarballs) and Audit B (perimeter coverage) were each re-verified by an adversarial third pass before any edit. CLI builder: the CLI's exit-2 refusals are errors with its own wording (--parallel + --pure-codecs without --deterministic, --workers without --parallel, --chunk-size without --stream, --from-manifest + paths, modify with no edit, stream --output-dir + --cat, stdin twice, --in-place from stdin, …), count flags (--max-entries, --max-ratio, max-entries=N …) get their own grammar, the --config/--no-config and --parallel/--codec rules state the real conditions, pwsh joins the completion enum, the EPUB preset no longer claims to store an extensionless mimetype. CLI guide: exact error envelope, verify --entry path, refused combinations, the 39-code ZIP_*→E_* table, the 14 remedies, the 11 diagnostics, batch-manifest and config-file rules, value grammars. MCP guide: no outputSchema revalidation claim, exact limits/strict/diagnostics per tool, tool titles, instructions block, _meta.apiVersion, MIME table, HTTP 404 and Origin-port rule, parallel defaults, cache namespace, server.json. MCP explorer: honours strict, limits, fields, verbosity, filter, entry options; inflate_raw runs the real payload; describe_engine reproduces the server's exact shape; stoppedAt follows the server's byte rule. Case 5: mergePdfs is synchronous, the pdfnative binary is pdfnative. surfaces.json/choose.md: strict on 7 tools, limits on 8, four new rows.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…rHTML CodeQL flagged five 'DOM text reinterpreted as HTML' sites in the CLI builder. Command names from the embedded surface table are escaped in the tab bar and the panel attributes, and the validation messages — which quote user-typed flag values and entry names — are escaped before their backtick spans become <code>. The MCP explorer escapes the tool id in the card heading for symmetry, and a raw NUL byte that had crept into a string literal is now the \u0000 escape sequence.
…ted fields The two remaining CodeQL 'DOM text reinterpreted as HTML' findings traced to fieldHtml() and positionalHtml(): the element ids and the data-scope / data-cmd / data-flag / data-pos attributes were built from the embedded surface table without esc(). Every leaf value that reaches innerHTML now passes through the escaper; the composites (labels, hints, options, panels) were already assembled from escaped parts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR — docs: the ecosystem on the site — zipnative-cli and zipnative-mcp 1.0.0
Branch
docs/ecosystem-1.0→main. Paste the body below into the pull request (theghCLI is not installed on the authoring machine).Summary
Documentation-only branch aligning the site and the repository docs on the published ecosystem:
zipnative1.0.0,zipnative-cli1.0.0 (npm 2026-09-05) andzipnative-mcp1.0.0 (npm 2026-09-07). No engine change;src/untouched.docs/assets/ecosystem.jsonrecords both packages in full (version, repo, binary, pin, command groups, tools, prompts, env vars) and is the single source of truth every count on the site is checked against.guides/cli.md(15 commands, every flag, agent contract, refused combinations, error classes / codes / remedies, batch-manifest and config rules),guides/mcp.md(client configuration, 13 tools with inputs/outputs, 7 prompts, resources, 7 env vars, protocol, error and security models),guides/choose.md(capability × surface matrix, twin ofdocs/data/surfaces.json).playgrounds/cli.html(command builder driven by an embedded copy of the CLI surface: every flag of every command, the CLI's own exit-2 refusals as errors, 27 presets; nothing executed, by design) andplaygrounds/mcp.html(real MCP payloads, client config, a Run button executing the engine call behind twelve of the thirteen tools on a sample or a dropped archive, honestBROWSER_LIMITATIONrefusals for what only the Node server can do).assets/versions.js),architecture.svgextended with an ecosystem-consumers band; nav/footers on every page; OG and social images carry CLI and MCP.load-engine.jsimports the published package (esm.sh → jsDelivr, capability probe, loud on-page error); the pre-publication fallback (committeddist/index.jscopy,docs:playground, the build step indocs.yml) is removed.playground-bundle→cdn-pin;manifest-shapefor every package;jsonld-versionon satelliteaboutnodes; newsatellite-counts,surfaces-shape,cli-surface-parity(snapshot ofzipnative schema manifestvs manifest, guide and builder),mcp-surface-parity,switcher-parity,versions-widget.verifiedOn→ 2026-09-07.Verification
npm run typecheck:scriptsnpm run docs:allnpm run verify:docsnpm run verify:docs -- --online --strict(the weeklynpm-driftjob)latest= 1.0.0 for all three packagesdist/index.js)Out of scope — to report to the satellite repositories
zipnative-cli: tagv1.0.0(== the npm tarball) shipsinspect --check safe-namesanderror.remedy, but its CHANGELOG files both under[Unreleased]; README says "20 checks" where the CHANGELOG says "19"; README line 134 says--max-outputis mandatory while the source and README line 741 make it optional (1 GiB default).zipnative-mcp:SERVER_INSTRUCTIONSsayszipBase64takes "no data: URI" whilearchive-input.tstolerates and strips the prefix; veraZIP corpus "38" (CHANGELOG) vs "37" (CLI README).Human steps after merge
docs/assets/social-preview.png(1280×640) in GitHub → Settings → Social preview.main:/docsautomatically; the CDN-only playgrounds need no build.🤖 Generated with Claude Code
PR — docs: the ecosystem on the site — zipnative-cli and zipnative-mcp 1.0.0
Branch
docs/ecosystem-1.0→main. Paste the body below into the pull request (theghCLI is not installed on the authoring machine).Summary
Documentation-only branch aligning the site and the repository docs on the published ecosystem:
zipnative1.0.0,zipnative-cli1.0.0 (npm 2026-09-05) andzipnative-mcp1.0.0 (npm 2026-09-07). No engine change;src/untouched.docs/assets/ecosystem.jsonrecords both packages in full (version, repo, binary, pin, command groups, tools, prompts, env vars) and is the single source of truth every count on the site is checked against.guides/cli.md(15 commands, every flag, agent contract, refused combinations, error classes / codes / remedies, batch-manifest and config rules),guides/mcp.md(client configuration, 13 tools with inputs/outputs, 7 prompts, resources, 7 env vars, protocol, error and security models),guides/choose.md(capability × surface matrix, twin ofdocs/data/surfaces.json).playgrounds/cli.html(command builder driven by an embedded copy of the CLI surface: every flag of every command, the CLI's own exit-2 refusals as errors, 27 presets; nothing executed, by design) andplaygrounds/mcp.html(real MCP payloads, client config, a Run button executing the engine call behind twelve of the thirteen tools on a sample or a dropped archive, honestBROWSER_LIMITATIONrefusals for what only the Node server can do).assets/versions.js),architecture.svgextended with an ecosystem-consumers band; nav/footers on every page; OG and social images carry CLI and MCP.load-engine.jsimports the published package (esm.sh → jsDelivr, capability probe, loud on-page error); the pre-publication fallback (committeddist/index.jscopy,docs:playground, the build step indocs.yml) is removed.playground-bundle→cdn-pin;manifest-shapefor every package;jsonld-versionon satelliteaboutnodes; newsatellite-counts,surfaces-shape,cli-surface-parity(snapshot ofzipnative schema manifestvs manifest, guide and builder),mcp-surface-parity,switcher-parity,versions-widget.verifiedOn→ 2026-09-07.Verification
npm run typecheck:scriptsnpm run docs:allnpm run verify:docsnpm run verify:docs -- --online --strict(the weeklynpm-driftjob)latest= 1.0.0 for all three packagesdist/index.js)Out of scope — to report to the satellite repositories
zipnative-cli: tagv1.0.0(== the npm tarball) shipsinspect --check safe-namesanderror.remedy, but its CHANGELOG files both under[Unreleased]; README says "20 checks" where the CHANGELOG says "19"; README line 134 says--max-outputis mandatory while the source and README line 741 make it optional (1 GiB default).zipnative-mcp:SERVER_INSTRUCTIONSsayszipBase64takes "no data: URI" whilearchive-input.tstolerates and strips the prefix; veraZIP corpus "38" (CHANGELOG) vs "37" (CLI README).Human steps after merge
docs/assets/social-preview.png(1280×640) in GitHub → Settings → Social preview.main:/docsautomatically; the CDN-only playgrounds need no build.🤖 Generated with Claude Code