fusion/docs/research/cli-printing-press.md

cli-printing-press research (FN-3761)

1) Summary

cli-printing-press is a Go-based generator (not a Node package) that takes API inputs (--spec, --docs, or --plan) and emits a full Go CLI project plus MCP server scaffolding via embedded templates. It has rich auth modeling (API key, bearer, cookie/composed, session-handshake, OAuth2 incl. authorization_code and client_credentials) and optional browser-sniff/traffic-analysis guidance. It validates generated output with Go quality gates. The project is opinionated around local filesystem output (~/printing-press/library/<name> by default), Go toolchain availability, and optional LLM/agent tooling for higher-level pipeline flows.

2) Source examined

• Repo: https://github.com/mvanhorn/cli-printing-press
• Examined commit: ecb35ab0d585693aa48550f2087191a287b35f61
• Commit date (UTC): 2026-05-09T00:16:50Z
• Latest Git tag seen: v4.0.6 (c9dd54ae61ce0d8d949dbed0257573194a536953), with current HEAD ahead by 21 commits.
• npm status: no published cli-printing-press package found on npm (npm view cli-printing-press version returned 404, 2026-05-08).

3) Inputs

One-line answer: Generation is primarily driven by an internal APISpec model plus generate CLI flags and optional research/traffic-analysis artifacts.

• Core generate entrypoint supports:
  • --spec (repeatable local/URL API spec),
  • --docs (doc-to-spec flow),
  • --plan (markdown plan-driven generation),
  • plus shaping flags (--spec-source, --client-pattern, --transport, --traffic-analysis, etc.). (internal/cli/root.go:78-399)
• Input normalization/validation exists for spec_source, client_pattern, http_transport enums. (internal/cli/root.go:461-517)
• Spec schema is a first-class typed model (APISpec) with fields for API topology, auth, tier routing, cache/share/mcp settings, etc. (internal/spec/spec.go:63-164)
• Auth input surface is broad (auth.type, env var specs, cookie/composed auth, session handshake fields, OAuth URLs/scopes/grant). (internal/spec/spec.go:432-490)
• Remote specs can be fetched and cached under ~/.cache/printing-press/specs with 24h cache behavior. (internal/cli/root.go:789-857)

4) Outputs

One-line answer: It emits a standalone Go project tree (CLI + MCP) with generated code/templates, optional archived input spec, and pipeline/provenance artifacts.

• README describes each run producing <api>-pp-cli and <api>-pp-mcp. (README.md:95-98)
• Default output location for generated projects is ~/printing-press/library/<name> unless overridden. (internal/cli/root.go:380, README.md:102-110)
• Generation writes many files from embedded templates (internal/generator/templates/**) across cmd/, internal/cli, internal/client, internal/store, internal/mcp, root go.mod/Makefile/.goreleaser.yaml, etc. (internal/generator/generator.go:1537-1593, internal/generator/generator.go:2554-2564)
• Input spec is archived alongside output as spec.yaml/spec.json (redacted) for reproducibility. (internal/cli/root.go:346-357)

5) Generation model / pipeline

One-line answer: generate parses/enriches inputs, builds a generator.Generator, renders templated project files, optionally validates/polishes, and can emit manifest/provenance artifacts.

• runGenerateProject: enrich spec, load research + traffic analysis, apply transport defaults, call Generate(), optionally Validate(), optionally polish. (internal/cli/root.go:436-459)
• Generator.Generate() orchestrates staged rendering: prepare output -> render core/support files -> resource commands -> auth files -> MCP entrypoint -> root/vision files. (internal/generator/generator.go:1537-1593)
• Validation gates include go mod tidy, govulncheck, go vet, go build, binary build, and smoke commands (--help, version, doctor). (internal/generator/validate.go:25-106)
• Determinism/idempotence notes:
  • Mostly template-driven/deterministic for same inputs.
  • Non-deterministic elements include currentYear template helper and environment-derived identity fallbacks (OwnerName, Printer) if missing. (internal/generator/generator.go:1549-1561, internal/generator/generator.go:2529)
  • Output claiming behavior (--force, auto-claim dirs) affects idempotence on existing dirs. (internal/cli/root.go:520-537, internal/cli/root.go:579-641)

6) Runtime assumptions

One-line answer: Generator runtime assumes modern Go toolchain + filesystem write access; generated CLIs assume Go-built binaries and local config/store files.

• Go module declares go 1.26.3. (go.mod:1-4)
• README install prerequisites: Go 1.26.3+ and Claude Code (for skill-driven flows). (README.md:23-35)
• Binary entrypoint is Go (cmd/printing-press/main.go). (cmd/printing-press/main.go:1-23)
• Validation and many flows assume shelling out to Go tooling is available. (internal/generator/validate.go:42-96)
• Filesystem assumptions include user home and cache dirs (~/.cache/printing-press/...) plus generated output trees. (internal/cli/root.go:798-857, README.md:102-110)

7) Network and external-service assumptions

One-line answer: The generator and generated CLIs both rely on HTTP(S), with optional browser-oriented transport modes and doc/spec fetches.

• Remote spec/doc ingestion uses outbound HTTP (http.Get, docs URL processing). (internal/cli/root.go:789-825, internal/cli/root.go:119-161)
• Spec model includes transport choices: standard, browser-http, browser-chrome, browser-chrome-h3. (internal/spec/spec.go:25-31, internal/cli/root.go:391, internal/cli/root.go:511-517)
• Generator may default transport from traffic-analysis/reachability hints. (internal/cli/root.go:539-549, internal/cli/root.go:440-449)
• README positions browser-sniffed traffic as supported input source (not only canonical OpenAPI). (README.md:95-97)
• No evidence of gRPC codegen path in primary generator surfaces; model and templates are HTTP/OpenAPI/GraphQL-centric. (internal/spec/spec.go:63-164, internal/generator/templates/graphql_client.go.tmpl)

8) Auth and credential patterns (OAuth status)

One-line answer: Upstream supports multiple auth modes including OAuth2, and OAuth is explicitly implemented (not absent).

• Auth types modeled include api_key, oauth2, bearer_token, cookie, composed, session_handshake, none. (internal/spec/spec.go:432-433)
• Env var credential modeling includes required/optional/sensitive/kind metadata. (internal/spec/spec.go:493-531)
• OAuth2 grant support includes both authorization_code and client_credentials. (internal/spec/spec.go:715-750)
• OAuth auth template (auth.go.tmpl) includes browser callback listener + auth code exchange. (internal/generator/templates/auth.go.tmpl)
• OAuth client-credentials template (auth_client_credentials.go.tmpl) includes token mint and persistence flow. (internal/generator/templates/auth_client_credentials.go.tmpl)
• Browser cookie/composed/session-oriented auth paths are implemented in auth_browser.go.tmpl. (internal/generator/templates/auth_browser.go.tmpl)

OAuth status for FN-3762 planning: Supported upstream (authorization_code and client_credentials); not a gap in upstream capability.

9) Extension points

One-line answer: Extension is primarily through spec fields, command flags, templating system, and pipeline commands/artifacts—not via a plugin API in this repo.

• Template-based generation from embedded internal/generator/templates files is the core extensibility mechanism. (internal/generator/generator.go:32-39, internal/generator/generator.go:2629-2647)
• CLI exposes many subcommands beyond generate (scorecard, dogfood, patch, vision, browser-sniff, pipeline/print, publish, etc.) that act as workflow extension points. (internal/cli/root.go:45-73)
• Spec-level optional features (Cache, Share, MCP, TierRouting, etc.) drive generated capability shape. (internal/spec/spec.go:131-164)
• No stable external plugin interface akin Fusion’s plugin SDK/types is visible in this project; customization appears source/template/spec driven.

10) Known limits and risks

One-line answer: Strongly Go/toolchain/filesystem-coupled; mixed deterministic/non-deterministic generation inputs; and broad auth/browser pathways increase operational complexity.

• Hard dependency on Go toolchain and ability to execute external Go commands during validation. (internal/generator/validate.go:42-96)
• Browser/web-surface scenarios can be rejected when discovery implies unshippable page-context requirements. (internal/cli/root.go:444-446)
• Output regeneration can overwrite unless guarded (--force semantics preserve only selected hand-authored files). (internal/cli/root.go:579-641)
• Security/secret handling risk surface exists around credential env vars and auth flows; mitigations are present but rely on correct spec/auth configuration. (internal/spec/spec.go:432-499, internal/generator/templates/auth*.go.tmpl)
• No npm package distribution path for the generator itself; this matters for Node-native embedding expectations. (Observed npm lookup + Go-first install path in README.md:29-35)

11) Mapping onto Fusion plugin architecture

One-line answer: The cleanest Fusion fit is as an orchestrated external-generator workflow (via plugin tools/routes/workflow steps), not as an in-process JS library import.

• Input ingest fit: Map Fusion plugin settings/forms to printing-press inputs (--spec, --docs, --plan, transport/auth-related knobs). Fusion plugin schemas/settings are a natural host. (docs/PLUGIN_AUTHORING.md, packages/core/src/plugin-types.ts)
• Generation execution fit: Invoke printing-press as a bounded subprocess from plugin tool/route/workflow-step handlers; avoid event-loop-blocking sync exec in engine paths. (AGENTS.md Engine Process Rules; packages/core/src/plugin-types.ts workflow/tool surfaces)
• Output storage fit: Upstream defaults to ~/printing-press/library/*; FN-3762 should decide whether Fusion uses worktree-local outputs, plugin-managed storage, or both.
• Invocation fit: Generated CLIs/MCP binaries can be exposed through plugin tools or workflow steps, with explicit filesystem boundaries and project scoping.
• Auth fit: Upstream OAuth/cookie/session modes exist, but Fusion must decide what subset is supported in v1 UX and where credentials are persisted.
• Bundling conflict note: printing-press is Go/binary-driven; Fusion’s @fusion/* noExternal bundling concerns are for TS/JS imports, so this integration should stay subprocess-oriented instead of trying to inline upstream code.

12) Open questions for FN-3762

1. Where should generated artifacts live in Fusion: project repo, .fusion/ plugin-private area, or dual-location publish model?
2. Should Fusion require preinstalled printing-press binary, or provide setup/install automation via plugin setup hooks?
3. Which upstream input modes are in v1 scope (--spec only vs --docs/browser-sniff flows too)?
4. How should Fusion surface/limit upstream auth modes (especially cookie/session-handshake) in UX and policy?
5. Should Fusion run upstream validation (go mod tidy, govulncheck, etc.) always, optionally, or in workflow-step phases only?
6. How should generated MCP binaries be registered/executed inside Fusion runtime boundaries?
7. What is the contract for regenerations (--force) when humans have hand-edited generated CLIs?

13) References

• Upstream README: README.md:21-140
• Upstream CLI entrypoint: cmd/printing-press/main.go:1-23
• Root command and subcommands: internal/cli/root.go:36-76
• Generate command flags + behavior: internal/cli/root.go:78-399
• Generate pipeline glue: internal/cli/root.go:436-459
• Input enum validation: internal/cli/root.go:491-517
• Output dir/claim semantics: internal/cli/root.go:520-641
• Remote spec caching/fetch: internal/cli/root.go:789-857
• APISpec model: internal/spec/spec.go:63-164
• Auth model: internal/spec/spec.go:432-531
• OAuth grant constants/validation: internal/spec/spec.go:715-750
• Generator orchestration: internal/generator/generator.go:1537-1593
• Auth template selection + MCP emission: internal/generator/generator.go:1800-1870
• Template rendering internals: internal/generator/generator.go:2629-2647
• Generated-project validation gates: internal/generator/validate.go:25-106
• Go runtime/deps baseline: go.mod:1-59
• Fusion plugin authoring context: docs/PLUGIN_AUTHORING.md
• Fusion plugin type seams: packages/core/src/plugin-types.ts
• Fusion SDK surface: packages/plugin-sdk/src/index.ts
• Fusion plugin loader context: packages/core/src/plugin-loader.ts
• Fusion constraints referenced: AGENTS.md (Package Structure, Storage Model, Engine Process Rules)