/printing-press-publish

name: printing-press-publish
description: Publish a generated CLI to the printing-press-library repo
version: 0.1.0
min-binary-version: "4.0.0"
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
created_by: user

/printing-press publish

Publish a generated CLI from your local library to the [printing-press-library](https://github.com/mvanhorn/printing-press-library) repo as a pull request.

/printing-press publish notion-pp-cli
/printing-press publish notion
/printing-press publish notion --from-polish
/printing-press publish notion --skip-live-test=auth-unavailable
/printing-press publish notion --blocked-api-journal notion
/printing-press publish

PR shape guard

This skill opens only a generated CLI publish PR or, with `--blocked-api-journal`, a `blocked-apis.json` journal PR. It never opens a docs-only, plan, proposal, or spec PR as a substitute for a CLI that is not ready to publish. If generation, validation, or live testing is blocked, report the exact blocker and stop.

Direct User Invocation Required

Publishing can fork `mvanhorn/printing-press-library`, push a branch, and open or update a PR. Before setup or validation, check the invocation context. If this skill was invoked as a chained continuation from `printing-press-polish`'s Publish Offer, including an `AskUserQuestion` answer or auto-resolved polish recommendation, stop immediately and tell the user to send `/printing-press-publish <cli-name> --from-polish` in a fresh message. A fresh user-authored request that explicitly asks to publish is sufficient; do not add another confirmation prompt on top of a direct publish request.

If the fresh user-authored request includes `--from-polish`, record `POLISH_HANDOFF=true` for the terminal-state step and ignore that marker when resolving the CLI name. The marker is not a second confirmation and is not passed to `cli-printing-press`; it only preserves standalone polish's old post-publish retro offer after the fresh-turn publish completes.

If the request includes `--blocked-api-journal`, enter **Blocked API Journal Mode** below instead of the normal printed-CLI publish flow. This mode may be invoked from `/printing-press`'s hold-path menu after the user explicitly chose "Add to blocked-API journal"; that parent menu choice is sufficient user authorization for the public-library journal write. Do not require a second fresh-turn invocation for this journal-only mode.

If the fresh user-authored request includes `--skip-live-test=<reason>`, record the exact non-empty reason as `SKIP_LIVE_TEST_REASON` and remove the flag before resolving the CLI name. This is the only supported escape valve for the publish-time live test gate. Use it only for auth-unavailable, known upstream outage, LAN-unreachable hardware APIs, or similarly concrete operator-approved cases; never infer a skip from ordinary latency or from the presence of an older Phase 5 marker.

The public library treats `library/<category>/<api-slug>/.printing-press.json` and `manifest.json` as the source of truth for registry-display fields. Do not edit `registry.json`, README catalog cells, or `cli-skills/pp-<api-slug>/SKILL.md` in publish PRs; all three are bot-regenerated post-merge by the library's own workflows. The library's `Fail on changes to generated artifacts` check in `verify-library-conventions.yml` hard-fails any PR — fork or same-repo — whose diff against base touches `registry.json` or `cli-skills/pp-*/SKILL.md`, so a publish that includes either is pre-rejected before review.

The public library also owns per-CLI release accounting. Do not manually bump `CHANGELOG.md`, `.printing-press-release.json`, or runtime `var version = ...` for a publish PR. Fresh printed CLIs may include blank release-ledger skeletons; the library's post-merge workflow assigns the final `YYYY.M.N` release and stamps the runtime version after merge. When replacing an existing public library CLI, preserve its existing release-ledger files so changelog history is not lost in the reprint PR.

`blocked-apis.json` is different: it is a hand-maintained public-library journal, not a generated registry surface. Journal-only PRs may edit `blocked-apis.json` and must not stage `library/`, `registry.json`, README catalog cells, or `cli-skills/`.

Blocked API Journal Mode

Use this mode only when the invocation includes `--blocked-api-journal`. It records a held `/printing-press` attempt whose blocker is likely to repeat for other users until a machine or upstream issue changes.

Required fields from the caller:

• `slug`: canonical API slug, not the CLI binary name.
• `attempted_at`: `YYYY-MM-DD`.
• `verdict`: `hold`.
• `reason`: concise blocker reason, with no secrets, local paths, cookies,

tokens, or account-specific details.

• `blocking_issue`: Printing Press issue number if known, otherwise `null`.
• `permanent`: boolean.

If the caller did not provide one of these fields, infer only safe values from the current run context. If `reason` is missing or vague, stop and ask for one specific blocker sentence; do not write an unhelpful journal entry.

Run the normal Setup, Configuration, scoped clone cleanup, and GitHub auth checks, then prepare the public-library clone exactly as the normal publish flow does: fork if needed, ensure `upstream` points to `mvanhorn/printing-press-library`, fetch `upstream`, and reset the clone to `upstream/main` before editing.

Then update only `$PUBLISH_REPO_DIR/blocked-apis.json`:

cd "$PUBLISH_REPO_DIR"
if [ ! -f blocked-apis.json ]; then
  printf '[]\n' > blocked-apis.json
fi
jq --arg slug "<api-slug>" \
   --arg attempted_at "<YYYY-MM-DD>" \
   --arg verdict "hold" \
   --arg reason "<reason>" \
   --argjson blocking_issue '<number-or-null>' \
   --argjson permanent '<true-or-false>' '
  (if type == "array" then . else [] end)
  | map(select(.slug != $slug))
  + [{
      slug: $slug,
      attempted_at: $attempted_at,
      verdict: