Adapters: safe execution of AUTO channels

An adapter performs a real external action via a legitimate API. AUTO never means unattended: every external action follows preview → confirm → execute → receipt.

The safety flow (non-negotiable, in this order)

1. Preview. Run the adapter script in --preview mode and show the user EXACTLY what will be sent: method, URL, full body, and the before → after change. Never summarize the payload — show it.
2. Confirm. Ask the user explicitly (one question, one action). Only after a yes, re-run with --execute --yes. --yes is the script-level assertion that this conversation happened; never pass it preemptively.
3. Execute. The script performs the calls and stops at the first failure.
4. Receipt. The script appends a receipt to launches/<slug>/log.md (--log): timestamp, adapter, mode, exact bodies sent, before-state, HTTP results, and resulting resource URLs. Receipts are the launch's audit trail.

--dry-run runs the full flow including the receipt but sends nothing — use it to demonstrate or test the flow safely. Both adapters print their full interface with --help.

Worked example (github-meta, full flow)

# 1. Preview — target is positional (<owner/repo>), at least one action required
node scripts/adapters/github-meta.mjs merriban/lockjack \
  --description "Read-only lockfile forensics for npm, pnpm, and yarn" \
  --topics "security,lockfile,supply-chain,sca,npm" --preview

# 2. Show the preview to the user, ask "send exactly this? yes/no"

# 3. Only after an explicit yes:
node scripts/adapters/github-meta.mjs merriban/lockjack \
  --description "Read-only lockfile forensics for npm, pnpm, and yarn" \
  --topics "security,lockfile,supply-chain,sca,npm" \
  --execute --yes --log launches/lockjack/log.md

# 4. Show the appended receipt from launches/lockjack/log.md

dev.to is identical in shape (--title + --body-file instead of the positional target); see node scripts/adapters/devto.mjs --help.

Credential hygiene

• Keys come from env vars or git-ignored .env.local (template + minimal-scope documentation: .env.example). Never ask the user to paste a token into chat.
• Tokens live in HTTP headers only. Every string an adapter prints or writes goes through scrub() (scripts/adapters/env.mjs), which redacts any registered credential — previews, receipts and log.md are token-free by design.
• GitHub: fine-grained PAT scoped to the single target repo, Administration: write
  • Metadata: read and nothing else (see .env.example for the exact setup).

Implemented in v0.1 (the only two — hard cap, see CLAUDE.md)

dev-to — scripts/adapters/devto.mjs

Creates the launch article as a draft. published: false is a frozen constant: there is no flag to publish, --publish/--published are rejected with an error, and the payload is asserted immediately before send. Publishing is a human act in the dev.to dashboard. Key: DEVTO_API_KEY. Limits: ≤ 4 tags.

github-meta — scripts/adapters/github-meta.mjs

Sets repo description (PATCH /repos/{owner}/{repo}) and/or replaces topics (PUT /repos/{owner}/{repo}/topics) via REST. Fetches current state first and previews a real diff; skips calls that would be no-ops. The social preview image has no API — the adapter prints the manual checklist instead, naming the exact file to upload (assets/brand/social-preview-1280x640-dark.png, the recommended one). Key: GITHUB_TOKEN (fine-grained, see .env.example). The gh CLI (gh repo edit) is an optional manual alternative; the adapter does not require it.

Roadmap stubs (documented, NOT implemented in v0.1)

Every stub follows the same safety flow when implemented. None of them may ever touch a channel classified assisted or excluded — that boundary is the product.