Index of every page on this site: llms.txt
All skills
mvanhorn avatar

/printing-press

@9e1a8d4
Run it yourself

Set up a new integration, connector, or CLI binding for any API. Wrap or generate a ship-ready Go CLI from an OpenAPI, HAR, or Postman spec via the lean research -> generate -> build -> shipcheck loop. Use when the user says build a CLI, wrap this API, set up a new integration, add a connector, integrate with a service, or names an API by domain.

Use this Skill: https://skilld.dev/gh/mvanhorn/cli-printing-press/printing-press

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

phases20-promote-and-archive.md

≈5.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

20-promote-and-archive (Phase 5.6: Promote and Archive)

Receipt entry (required):

"$PRINTING_PRESS_BIN" phase-receipt enter --file "$PHASE_RECEIPT_LOG" --run-id "$RUN_ID" --phase "20-promote-and-archive"

Acceptance gate check

This gate guards promotion, so it applies only when the shipcheck verdict is ship or ship-with-gaps. A shipcheck hold reaches this phase from 12-shipcheck with no dogfood markers by design — it skips promotion entirely, archives manuscripts, and completes canonically to 21-next-steps. A dogfood fail reaches this phase from 18-dogfood-testing on the 18→20 hold handoff with a status: "fail" marker and does the same: archive, do not promote, and do not backtrack. A hold must NOT take the backtrack to 18-dogfood-testing below. A shipcheck hold's missing markers are expected, and a dogfood hold already has its failure marker. The binary rejects 20→18 when this visit arrived on the 12→20 hold jump.

For a ship-verdict run, verify the Phase 5 JSON gate marker before promoting:

  • If $PROOFS_DIR/phase5-acceptance.json exists with status: "pass" → proceed to promote.
  • If $PROOFS_DIR/phase5-acceptance.json exists with status: "fail" → CLI is on hold. Do NOT promote. Proceed to Archive Manuscripts.
  • If $PROOFS_DIR/phase5-skip.json exists and the auth-aware skip is valid → proceed to promote.
  • If neither JSON marker exists → Phase 5 was skipped or not recorded. Go back and run it, or record the valid skip with dogfood --write-skip as Phase 5 describes. Do NOT promote without one. Do not hand-write the marker.

Marker invalidation — any source edit after the acceptance run breaks the gate. The acceptance marker is bound to a source fingerprint (per-file hashes of the CLI tree). If you edit any .go file after the live dogfood run — adding a patch, an annotation, or a transport change — lock promote, publish validate, and publish package all fail with "phase5 marker source fingerprint does not match the current CLI source". Replacing only the stamped var version = "..." string in internal/cli/root.go, internal/cli/version.go, or cmd/<name>-pp-mcp/main.go does not; any other edit in those files does. lock promote copies that string from the library it replaces. shipcheck omits verify --fix when that marker's fingerprint matches the current tree. shipcheck --fix still repairs source and warns that the marker was invalidated. Re-run live dogfood (with --write-acceptance) after EVERY post-acceptance source change. A skip marker is refreshed the same way with dogfood --write-skip after the tree is final. Sync the fresh marker to both locations:

  • The embedded copy at $CLI_DIR/.manuscripts/<run>/proofs/ — what lock promote checks.
  • The archived copy at $PRESS_MANUSCRIPTS/<api>/<run>/proofs/ — what publish package reads first (manuscript lookup is archive-first; phase5-proof lookup is embedded-first, so a stale copy in either blocks promotion or packaging with the same confusing message).

When a ship-verdict run has a missing marker and you go back to run Phase 5, record the backtrack handoff so the receipt gate accepts the re-entry rather than treating it as an out-of-order jump:

"$PRINTING_PRESS_BIN" phase-receipt complete --file "$PHASE_RECEIPT_LOG" --run-id "$RUN_ID" --phase "20-promote-and-archive" --next "18-dogfood-testing" --note "acceptance marker missing: <what dogfood must produce>"

Promote to Library

If the shipcheck verdict is ship or ship-with-gaps, promote the verified CLI from the working directory to the library. This must happen BEFORE archiving — the CLI in the library is the primary deliverable, and Phase 6's publish path expects $PRESS_LIBRARY/<api>/ to hold the current run.

For reprints, creator attribution is guarded in two places. The generate command seeds $CLI_WORK_DIR from $PRESS_LIBRARY/<api>/.printing-press.json when that same-API manifest has a non-empty permanent creator, and records the reprinter as the first contributors[] entry when they differ from the creator. lock promote repeats the same check before swapping: if the staged working tree still carries the operator as creator, it restores the library creator, prepends the staged creator as contributor, and rewrites generated attribution surfaces (Go headers, README byline, SKILL author:, NOTICE/LICENSE copyright lines). A promoted reprint must never silently replace the library creator with the operator's git identity.

Pick the promote path by whether the library already holds hand-authored content. lock promote --dir performs an atomic swap of $CLI_WORK_DIR over $PRESS_LIBRARY/<api> — CHANGELOG.md and .printing-press-release.json are copied byte-identical from the replaced library tree onto the staged tree before the swap. Every other file in the library that is not in the fresh tree is gone after the swap. Whole hand-authored files (a separate internal/syncer/ package, novel-feature command files under internal/cli/ without the // Generated by ... header, hand-built migration files under internal/store/) survive a cli-printing-press regen-merge pass but are wiped by a bare swap. This is the same preservation dynamic called out under Hand-edits must be regen-mergeable.; the orchestration here must honor it. lock promote also fails closed before the swap when recorded patch files or call sites are missing from the staged tree (the working copy plus any library-only .printing-press-patches/ records unioned in). Restore the files or fix the records; do not swap past that gate.

Top-level .git survives that swap. On a reprint, lock promote moves the library's existing .git onto the promoted tree; that history wins when the workdir also has a .git. On a first print (no library .git), it copies the workdir's top-level .git into the new library. Nested .git entries stay dropped. A symlinked workdir .git is refused instead of carried. The in-place promote (--dir pointed at the library) keeps moving the library .git the same way.

Detect hand-authored content in the existing library:

LIB_TARGET="$PRESS_LIBRARY/<api>"
NOVEL_COUNT=0
if [ -d "$LIB_TARGET" ]; then
  MANIFEST="$LIB_TARGET/.printing-press.json"
  HAS_NOVEL_FIELD=false
  if [ -f "$MANIFEST" ]; then
    # `novel_features` is the canonical count when the field is present.
    # Distinguish absent (older manifest predating the field) from explicit zero —
    # `jq '.novel_features // [] | length'` collapses both to 0, which would
    # silently route older CLIs through the destructive Path A swap.
    HAS_NOVEL_FIELD=$(jq 'has("novel_features")' "$MANIFEST" 2>/dev/null || echo false)
  fi
  if [ "$HAS_NOVEL_FIELD" = "true" ]; then
    NOVEL_COUNT=$(jq -r '.novel_features | length' "$MANIFEST" 2>/dev/null || echo 0)
  else
    # File probe fallback fires in three cases: manifest missing entirely
    # (interrupted run, restored-from-backup state, much older CLI), manifest
    # present but predates the `novel_features` field, and manifest present
    # but corrupt-enough that `jq has()` errored. Any *.go file under
    # internal/cli/, internal/syncer/, or internal/store/ whose first 20
    # lines lack the "Generated by CLI Printing Press" header is hand-authored;
    # one such file is enough to route through Path B.
    for dir in "$LIB_TARGET/internal/cli" "$LIB_TARGET/internal/syncer" "$LIB_TARGET/internal/store"; do
      [ -d "$dir" ] || continue
      while IFS= read -r f; do
        if ! head -n 20 "$f" 2>/dev/null | grep -q "Generated by CLI Printing Press"; then
          NOVEL_COUNT=1
          break 2
        fi
      done < <(find "$dir" -type f -name '*.go')
    done
  fi
fi

The presence check (jq 'has("novel_features")') and the manifest existence check are independent. A library can exist with a hand-authored layer but no manifest at all (interrupted run, restored-from-backup state, much older CLI), so gating the file-probe fallback behind [ -f manifest ] would leave that case routing through the destructive Path A swap.

Before choosing Path B for NOVEL_COUNT > 0, distinguish preservation from from-scratch replacement. A reprint that rebuilt every prior novel into $CLI_WORK_DIR has no unique library content left to preserve; routing that run through regen-merge --apply turns ordinary older-generator drift into a manual halt and can preserve stale generated framework code.

Run a dry-run report and inspect it against the prior manifest / research novel list:

REGEN_DRY_RUN_REPORT="$PROOFS_DIR/regen-merge-dry-run-report.json"
PATH_A_REBUILT_NOVELS=0
if [ -d "$LIB_TARGET" ] && [ "$NOVEL_COUNT" -gt 0 ]; then
  if ! "$PRINTING_PRESS_BIN" regen-merge "$LIB_TARGET" \
      --fresh "$CLI_WORK_DIR" --json > "$REGEN_DRY_RUN_REPORT"; then
    # Real error (input error, missing fresh tree, unreadable library). Release
    # the upstream pipeline lock and surface the dry-run failure.
    "$PRINTING_PRESS_BIN" lock release --cli <api>-pp-cli
    echo "regen-merge dry-run failed; see $REGEN_DRY_RUN_REPORT" >&2
    exit 1
  fi

  DRY_RUN_BLOCKERS=$(jq '[.files[]? | select(.verdict == "NOVEL"
    or .verdict == "NOVEL-COLLISION")] | length' "$REGEN_DRY_RUN_REPORT")
  MISSING_REFERENTS=$(jq '[.lost_registrations[]?
    | select((.skipped_for_missing_referent // []) | length > 0)] | length' \
    "$REGEN_DRY_RUN_REPORT")
  if [ "$DRY_RUN_BLOCKERS" -eq 0 ] && [ "$MISSING_REFERENTS" -eq 0 ]; then
    PATH_A_REBUILT_NOVELS=1
  fi
fi

For a from-scratch reprint whose fresh tree reimplements all prior novels, prefer Path A. The dry-run should show the prior novel surfaces represented in fresh output, usually as TEMPLATED-CLEAN or NEW-TEMPLATE-EMISSION, and must not show any preservation-only novel surface that the fresh tree lacks. Treat generated-file TEMPLATED-BODY-DRIFT, TEMPLATED-VALUE-DRIFT, and stale templated-helper TEMPLATED-WITH-ADDITIONS as expected overwrite noise in this specific branch; Path A intentionally swaps in the fresh tree.

The override is forbidden unless the fresh tree contains the novels:

  • If DRY_RUN_BLOCKERS > 0 because any prior novel file still reports NOVEL, the fresh tree did not rebuild that hand-authored file. Use Path B so the file is preserved.
  • If DRY_RUN_BLOCKERS > 0 because any file reports NOVEL-COLLISION, halt through Path B's normal review gate. A collision is not version drift.
  • If MISSING_REFERENTS > 0 because lost_registrations[].skipped_for_missing_referent is non-empty, use Path B and investigate; the fresh tree is missing a command constructor that published wiring still references.
  • If you cannot prove the fresh tree rebuilt every prior novel feature from the manifest / research record, use Path B. A false Path A clobbers hand work; a false Path B only asks for review.

Path A — first print, no hand-authored content, or from-scratch reprint with all novels rebuilt (! -d "$LIB_TARGET" or NOVEL_COUNT == 0 or the guarded dry-run override above passed). Use the destructive swap. Fast path; hand-authored source is not preserved. The top-level .git rule above still applies:

# Atomic swap: copies working dir, writes manifest, updates run pointer, releases lock.
"$PRINTING_PRESS_BIN" lock promote --cli <api>-pp-cli --dir "$CLI_WORK_DIR"

The promote command handles the full sequence: refreshes stale host CLI/MCP binaries and their .mcpb bundle, stages the working directory, atomically swaps it into $PRESS_LIBRARY/<api> (slug-keyed), writes the .printing-press.json manifest, updates the CurrentRunPointer, and releases the lock — all in one step. When sources and bundle contents are unchanged, the refresh is a no-op. The --cli flag accepts the CLI binary name; the Go code translates to the slug-keyed library path internally.

Path B — reprint over a library with hand-authored content that the fresh tree did not fully rebuild (-d "$LIB_TARGET" AND NOVEL_COUNT > 0 AND the guarded Path A override did not pass). Use regen-merge to fold the fresh tree into the live library before promotion. regen-merge classifies every Go file under internal/ and cmd/ against the fresh tree, overwrites safely-templated files, re-injects AddCommand calls in root.go and resource-parents that the fresh tree lacks, and leaves files with hand-edited additions (TEMPLATED-WITH-ADDITIONS) untouched for human review. --apply writes via stage-and-swap-with-recovery, so partial failure can never lose data.

regen-merge --apply exits 0 even when it leaves TEMPLATED-WITH-ADDITIONS files (the human-review verdicts are reported, not raised as errors). The halt condition must be checked explicitly against the report — capture --json and inspect the verdict counts:

REGEN_REPORT="$PROOFS_DIR/regen-merge-report.json"
if ! "$PRINTING_PRESS_BIN" regen-merge "$LIB_TARGET" \
    --fresh "$CLI_WORK_DIR" --apply --json > "$REGEN_REPORT"; then
  # Real error (input error, apply failure). Release the lock — it was
  # acquired upstream by the press pipeline; regen-merge does not own it —
  # and surface the failure to the user.
  "$PRINTING_PRESS_BIN" lock release --cli <api>-pp-cli
  echo "regen-merge --apply failed; see $REGEN_REPORT" >&2
  exit 1
fi

# Halt on review-required verdicts before promoting. regen-merge exits 0
# in these cases; the JSON report is the source of truth.
NEEDS_REVIEW=$(jq '[.files[] | select(.verdict == "TEMPLATED-WITH-ADDITIONS"
  or .verdict == "TEMPLATED-BODY-DRIFT"
  or .verdict == "TEMPLATED-VALUE-DRIFT"
  or .verdict == "NOVEL-COLLISION")] | length' "$REGEN_REPORT")
if [ "$NEEDS_REVIEW" -gt 0 ]; then
  # Release the lock so the next reprint of this CLI is not blocked until
  # timeout. lock promote would have released it; the halt path must too.
  "$PRINTING_PRESS_BIN" lock release --cli <api>-pp-cli
  echo "regen-merge flagged $NEEDS_REVIEW file(s) for human review. " \
       "Inspect $REGEN_REPORT, resolve inline hand-edits, then re-run." >&2
  exit 1
fi

After regen-merge succeeds with no review-required verdicts, the live library directory is the new run. Do not then call lock promote --dir "$CLI_WORK_DIR" — that would atomically swap the working dir over the just-merged library and undo the preservation. Promote in place: point lock promote --dir at the library itself so the manifest write, run-pointer update, and lock release still run. Two extra steps are required compared to Path A:

  1. Copy the current run's PII-polish ledger into $LIB_TARGET before promote. lock promote --dir internally runs validatePIIGateForPromote against the target directory, which reads $LIB_TARGET/.printing-press-pii-polish.json. After regen-merge --apply the generator-emitted Go files have fresh line numbers, so the prior reprint's ledger (still sitting in $LIB_TARGET from the last atomic swap) has stale {file, line, kind, span} identity keys for those files and previously-accepted findings re-surface as pending — the gate fails before the swap and the lock stays held. Bringing the current run's ledger over fixes the identity match for generator-emitted files; hand-authored files with new findings still surface correctly as pending.
  2. Guard the promote with an explicit lock-release on failure. Unlike Path A, where a promote-gate failure simply leaves the working dir alone, a Path B failure leaves the lock held on the live library because the gate fires before the swap and before ReleaseLock. Mirror the lock-release guards from the regen-merge error branches above.
if [ -f "$CLI_WORK_DIR/.printing-press-pii-polish.json" ]; then
  cp "$CLI_WORK_DIR/.printing-press-pii-polish.json" "$LIB_TARGET/.printing-press-pii-polish.json"
else
  # Current run produced no PII findings (clean API or polish skipped).
  # Remove the stale prior-reprint ledger so the gate sees a clean state
  # — otherwise the old identity keys would replay against freshly
  # line-shifted generator files and surface false-positive pendings.
  rm -f "$LIB_TARGET/.printing-press-pii-polish.json"
fi
"$PRINTING_PRESS_BIN" lock promote --cli <api>-pp-cli --dir "$LIB_TARGET" || {
  "$PRINTING_PRESS_BIN" lock release --cli <api>-pp-cli
  echo "lock promote failed for $LIB_TARGET; lock released. " \
       "Inspect the PII gate output above and resolve before re-running." >&2
  exit 1
}

TEMPLATED-WITH-ADDITIONS and the other review verdicts represent inline hand-edits to generator-emitted files that need human review (see Hand-edits must be regen-mergeable. for the separate-file pattern that avoids this in future). The dry-run report (omit --apply) is the right tool for inspection once the halt path fires.

ship-with-gaps is promoted (on either path) because the verdict means "the CLI is shippable with documented, non-blocking gaps" — the gaps are recorded in the README's ## Known Gaps block and the user opts in via Phase 6's publish prompt. Treating ship-with-gaps as un-promotable would strand the verified working copy and leave the library on a stale prior run.

If the shipcheck verdict is hold, the lock was already released in Phase 4. Do NOT promote on either path. The working copy stays in $CLI_WORK_DIR and is not copied to the library. A dogfood hold is the same outcome: Phase 5 already released the lock, and a status: "fail" marker must not promote.

Archive Manuscripts

Archive the run's research, proofs, and discovery artifacts to $PRESS_MANUSCRIPTS/ unconditionally after promotion (or after lock release for hold verdicts). This happens regardless of the shipcheck verdict — even a hold run produces research and proofs that future runs should be able to reuse.

Archiving and publishing are separate concerns. Archiving preserves research for future /printing-press runs on the same API. Publishing ships the CLI to the library repo. A run that isn't ready to publish still produces valuable research.

# Archive under API slug (e.g., steam-web), matching the slug-keyed library layout.
API_SLUG="<api>"
mkdir -p "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID"
mkdir -p "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/research" "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/proofs"
cp -r "$RESEARCH_DIR/." "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/research/" 2>/dev/null || true
cp -f "$API_RUN_DIR/research.json" "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/research.json" 2>/dev/null || true
cp -r "$PROOFS_DIR/." "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/proofs/" 2>/dev/null || true

# Archive discovery artifacts (browser-sniff captures, URL lists, traffic analysis, browser-sniff report).
# This local archive keeps raw captures for later runs on this machine.
# publish package does not ship them: discovery/ in the library package keeps
# press-authored summaries (markdown reports, traffic-analysis.json,
# *-provenance.json, and the other summary files the press writes) unless
# --include-raw-captures is set.
# Session state lives outside $DISCOVERY_DIR (see 02-run-initialization.md), so the
# archive cannot pick it up. The legacy rm is a no-op safety net for an
# in-flight $DISCOVERY_DIR carried over from a pre-isolation run.
rm -f "$DISCOVERY_DIR/session-state.json" 2>/dev/null || true

# Strip response bodies from HAR before archiving to control size.
if [ -d "$DISCOVERY_DIR" ]; then
  for har in "$DISCOVERY_DIR"/browser-sniff-capture.har "$DISCOVERY_DIR"/browser-sniff-capture.json; do
    if [ -f "$har" ] && command -v jq >/dev/null 2>&1; then
      jq 'del(.log.entries[].response.content.text)' "$har" > "${har}.stripped" 2>/dev/null && mv "${har}.stripped" "$har" || rm -f "${har}.stripped"
    fi
  done
  cp -r "$DISCOVERY_DIR" "$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/discovery" 2>/dev/null || true
fi

# Wipe live-auth scratch dir now that the run is archived. The directory lives
# under ${TMPDIR:-/tmp}, so OS-level tmp reaping is the long-tail fallback, but
# we clean explicitly so back-to-back runs do not accumulate session state.
rm -rf "$SESSION_DIR" 2>/dev/null || true

MANDATORY: After archiving, you MUST proceed to Phase 6. Do not print a summary and stop. Do not treat archiving as the end of the run. The run ends when the user has been asked about next steps via the ship-path or hold-path menu.

Before following Next:, record the durable handoff. Point --evidence at the promoted CLI for ship or the archived manuscript for hold:

"$PRINTING_PRESS_BIN" phase-receipt complete --file "$PHASE_RECEIPT_LOG" --run-id "$RUN_ID" --phase "20-promote-and-archive" --evidence "<absolute-promoted-cli-or-manuscript-path>"

Next: phases/21-next-steps.md

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warningstoday3 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    The skill is a professional-grade development tool for generating Go-based CLIs from API specifications. It implements extensive security controls, including mandatory secret redaction, automated PII scrubbing, and dedicated code review phases that audit generated source code for security and correctness before execution.

  • Sockettoday

    3 alerts: gptAnomaly, gptSecurity

  • Snyktoday

    Risk: MEDIUM · 3 issues

Signed by skilld at 9e1a8d4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 19 hours ago.

Activeupdated 2 weeks ago
What it can do
Runs commands Reads files Edits files Network
version
3.0.0
min-binary-version
4.35.4
created_by
user
All 10 allowed tools
BashReadWriteEditGlobGrepWebFetchWebSearchAskUserQuestionAgent

README badge

README badge for mvanhorn/cli-printing-press/printing-press