printing-press library list --json

1. Exact match: If the argument matches a directory name (API slug) exactly, use it
2. CLI name match: If no exact match, try matching against

   cli_name

   fields, then derive the API slug from the manifest's

   api_name

   field
3. Suffix match: If no match yet, try

   <argument>-pp-cli

   against

   cli_name

   fields
4. Glob match: If no suffix match, search for entries where

   cli_name

   or

   api_name

   contains the argument as a substring. Cap at 5 most-recent matches. If multiple matches, present them via AskUserQuestion and let the user pick
5. No match: List all available CLIs and ask the user to pick or re-enter
6. No argument: If invoked with no name, list all CLIs sorted by modification time and let the user pick

api_name

cli_name

.printing-press.json

1. If the manifest has a

   category

   field, present it for confirmation:

   "Publishing as <category>. OK?" Give the user the option to change it

2. If no

   category

   but

   catalog_entry

   is present, look it up:
   bash

   printing-press catalog show <catalog_entry> --json

   Extract the category from the result. Present for confirmation
3. If neither provides a category, present the full list via AskUserQuestion:
   • developer-tools, monitoring, cloud, project-management
   • productivity, social-and-messaging, sales-and-crm, marketing
   • payments, auth, commerce, ai, media-and-entertainment, devices, other

$PUBLISH_REPO_DIR

1. Detect push access:
   bash

   GH_USER=$(gh api user --jq '.login')
   HAS_PUSH=$(gh api repos/mvanhorn/printing-press-library --jq '.permissions.push' 2>/dev/null || echo "false")

2. Detect git protocol:
   bash

   USE_SSH=false
   if ssh -T git@github.com 2>&1 | grep -q "successfully authenticated"; then
     USE_SSH=true
   fi

3. Clone based on access:
   Push access (

   HAS_PUSH

   is

   true

   ):
   bash

   # Clone directly — origin IS the upstream
   if [ "$USE_SSH" = "true" ]; then
     REPO_URL="git@github.com:mvanhorn/printing-press-library.git"
   else
     REPO_URL="https://github.com/mvanhorn/printing-press-library.git"
   fi
   git clone --depth 50 "$REPO_URL" "$PUBLISH_REPO_DIR"

   No push access (

   HAS_PUSH

   is

   false

   ):
   bash

   # Fork first — fail explicitly if forking is blocked
   if ! gh repo fork mvanhorn/printing-press-library --clone=false 2>&1; then
     echo "ERROR: Could not fork mvanhorn/printing-press-library."
     echo "The repo may restrict forking, or you may already have a fork with a different name."
     echo "Fork manually at https://github.com/mvanhorn/printing-press-library/fork"
     exit 1
   fi
   FORK="$GH_USER/printing-press-library"
   
   # Build URLs based on protocol preference
   if [ "$USE_SSH" = "true" ]; then
     FORK_URL="git@github.com:$FORK.git"
     UPSTREAM_URL="git@github.com:mvanhorn/printing-press-library.git"
   else
     FORK_URL="https://github.com/$FORK.git"
     UPSTREAM_URL="https://github.com/mvanhorn/printing-press-library.git"
   fi
   
   git clone --depth 50 "$FORK_URL" "$PUBLISH_REPO_DIR"
   cd "$PUBLISH_REPO_DIR"
   git remote add upstream "$UPSTREAM_URL"
   git fetch upstream

4. Cache the config:
   json

   {
     "managed_by": "printing-press-publish",
     "repo_url": "https://github.com/mvanhorn/printing-press-library",
     "access": "push or fork",
     "gh_user": "<gh username>",
     "protocol": "ssh or https",
     "clone_path": "<expanded $PUBLISH_REPO_DIR>",
     "scope_dir": "<absolute source worktree path>",
     "module_path_base": "github.com/mvanhorn/printing-press-library/library"
   }

   Write to

   $PUBLISH_CONFIG

   . The

   access

   field determines the flow for all subsequent steps. The

   gh_user

   field is used for cross-repo PR heads. The

   module_path_base

   always references the upstream repo (PRs land there).

cd "$PUBLISH_REPO_DIR"
git status --porcelain

• "Reset and start fresh"
• "Continue with existing changes"

git checkout -- . && git clean -fd

EXISTING_PR_NUMBER

"Found your open PR #N for

<api-slug>

. Will update it with the new version."

OWN_PR=true

• Update — Update your existing PR with the new version (default, preserves current behavior)
• Alongside — Rename yours with a qualifier and publish next to the existing one
• Bail — Cancel the publish

• Replace — Intentionally overwrite the existing CLI
• Alongside — Rename yours with a qualifier and publish next to the existing one
• Bail — Cancel the publish and view the existing CLI/PR

"This will replace the existing

<api-slug>

. Continue?"

"⚠️ This will replace

<author>

's

<api-slug>

(PR #N). Are you sure?"

• The PR description must include:

  ⚠️ **Replaces existing \

  <api-slug>`** — <reason provided by user or "newer version">`
• Set

  EXISTING_PR_NUMBER=""

  (create a new PR, don't update theirs)
• Proceed to Step 8 normally

**2. Generate rename suggestions** using slug format. Derive the new CLI name from the chosen slug:

- Numeric: `<api-slug>-2` (if that collides, try `-3`, `-4`, etc.)
- Non-numeric: `<api-slug>-alt`
- Custom: prompt the user for a qualifier word

After the user chooses a slug, compute:

```bash
NEW_API_SLUG="<chosen-slug>"
NEW_CLI_NAME="${NEW_API_SLUG}-pp-cli"

"Rename format:

<api-slug>-<qualifier>

. Pick a qualifier:"

1. 2

   →

   <api-slug>-2

2. alt

   →

   <api-slug>-alt

3. Enter custom qualifier

undefined

If a suggestion collides, skip it or increment the numeric suffix.

**4. Rename the CLI in the publish repo:**

Since Step 6 copied the staged CLI into `$PUBLISH_REPO_DIR`, the rename operates on that directory. Note: `--old-name`/`--new-name` still use CLI-name format (e.g., `dub-pp-cli`) because `RenameCLI` does content replacement — bare slugs would cause collateral damage. The `--dir` path uses the slug-keyed directory.

```bash
printing-press publish rename \
  --dir "$PUBLISH_REPO_DIR/library/<category>/<api-slug>" \
  --old-name <old-cli-name> \
  --new-name "$NEW_CLI_NAME" \
  --api-name "$ORIGINAL_API_SLUG" \
  --json

"success": true

new_dir

$PUBLISH_REPO_DIR/library/<category>/$NEW_API_SLUG

• Branch name:

  feat/$NEW_API_SLUG

  (not the old slug)
• PR title:

  feat($NEW_API_SLUG): add $NEW_API_SLUG

• Commit message:

  feat($NEW_API_SLUG): add $NEW_API_SLUG

• Registry.json entry:

  name

  →

  $NEW_API_SLUG

• Set

  EXISTING_PR_NUMBER=""

  (always a new PR for a renamed CLI)

• If merged: "Existing CLI at

  library/<category>/<api-slug>/

  "
• If open PR: "Open PR: <url>"

$PUBLISH_REPO_DIR

git checkout -- . && git clean -fd

Check for ANY open PR on this branch (not just ours)

**If another user's open PR exists on this branch** (`OTHER_PR` is non-empty and author is not `@me`):
> "Someone else has an open PR for `<api-slug>` (PR #N by @author). Creating a timestamped branch to avoid conflicts."

Auto-create a timestamped branch: `feat/<api-slug>-YYYYMMDD`. Do NOT offer to overwrite — that would stomp their work.

**If the branch exists but no competing PR** (stale branch from a previously closed/merged PR):

Ask via AskUserQuestion:
> "Found a stale branch `feat/<api-slug>` (likely from a previous publish). Overwrite it?"

- "Overwrite existing branch" — reuse the branch name
- "Create timestamped variant (feat/<api-slug>-YYYYMMDD)"

**If no branch exists:** Create normally.

```bash

access

gh_user

$PUBLISH_CONFIG

gh pr create

access

fork

--head <gh_user>:feat/<api-slug>

--head

gh pr create

access

push

--head feat/<api-slug>

• The manifest (

  description

  ,

  api_name

  ,

  category

  ,

  printing_press_version

  ,

  spec_url

  )
• The

  help_output

  captured in Step 4
• The CLI's README (first 2-3 paragraphs, or note that README is missing)
• Links to

  .manuscripts/<run-id>/research/

  and

  .manuscripts/<run-id>/proofs/

  within the PR branch
• The validation results from Step 4
• A Gaps section listing any missing manifest fields

references/secret-protection.md

undefined

• [Research Brief](<link to library/<category>/<api-slug>/.manuscripts/<run-id>/research/>)
• [Shipcheck Results](<link to library/<category>/<api-slug>/.manuscripts/<run-id>/proofs/>)

1. If

   gitleaks

   or

   trufflehog

   is installed, run it on the staged directory:
   bash

   if command -v gitleaks >/dev/null 2>&1; then
     gitleaks detect --source "<staging-dir>/library" --no-git --verbose 2>&1
   elif command -v trufflehog >/dev/null 2>&1; then
     trufflehog filesystem "<staging-dir>/library" 2>&1
   fi

   These tools use vendor-specific patterns (Steam keys, Stripe keys, GitHub tokens) with low false-positive rates. Their findings are warnings — the user reviews and decides.
2. If no scanning tool is installed, do a lightweight check:
   • Verify no

     .env

     files,

     session-state.json

     , or

     config.toml

     with real credentials exist in the staged directory
   • Check README examples use

     "your-key-here"

     placeholders, not real values
   • Check manuscripts (if included) don't contain auth headers or cookie values
3. Never include in the staged directory:

   • .env

     files

   • session-state.json

   • Config files with real credentials
   • HAR captures with un-stripped auth headers

• Tier 1 (auto-redact silently): vendor-prefix-anchored bearer tokens (

  Bearer cal_live_*

  ,

  Bearer sk_live_*

  ,

  Bearer ghp_*

  ,

  xoxp-*

  , etc.). Near-zero false-positive rate.
• Tier 2 (warn, batched user prompt): generic emails, generic bearer tokens, capitalized first+last name patterns. Allowlist suppresses spec-derived API vocabulary ("Event Types", "Booking Links") automatically.

<staging>.pre-pii-scrub/

• gh

  not authenticated: Detect in Step 1, tell user to run

  gh auth login

• CLI not found: Show available CLIs in Step 2, let user pick
• Validation fails: Show per-check results in Step 4, stop
• Repo unreachable: Report clearly in Step 5
• Fork creation fails:

  gh repo fork

  may fail if the user already has a fork with a different name, or if the org restricts forking. Report the error and suggest the user fork manually via the GitHub web UI.
• Collision check fails: If

  gh pr list

  or

  ls

  commands fail (network, auth), warn but don't block — proceed as if no collision exists
• Rename fails: Show the error from

  publish rename --json

  . Offer to retry with a different qualifier or bail. If the publish repo is in a partial state, reset with

  git checkout -- . && git clean -fd

  before retrying
• Branch conflict (no existing PR): Ask user in Step 8 (overwrite or timestamp)
• Push fails: For fork users, ensure they're pushing to their fork (origin), not upstream. Report the error, suggest checking

  gh auth status

  and

  git remote -v

• Cross-repo PR creation fails: If

  gh pr create --head user:branch

  fails with "head not found", the branch wasn't pushed to the fork. Verify with

  git ls-remote origin feat/<api-slug>