Publish to npm

Publish an api2cli-generated CLI to the npm registry so users can install it with npm i -g <name> or run it with npx <name>.

Phase 1: Pre-flight

Run these checks silently. Only stop if auth is missing.

Auth

Run npm whoami.

• If it succeeds: note the username, continue.
• If it fails: tell the user to run npm login first. Stop and wait until they confirm.

Resolve package name

Read name from package.json. Determine the publish name:

• If name has template placeholders ({{APP_CLI}}), derive the name from the directory name (e.g. ~/.cli/typefully-cli/ → typefully-cli).
• Run npm view <name> version:
  • 404 (not found): this is a first-time publish. Name is available; use it.
  • "Unpublished": the name is frozen for 24 hours after unpublish. Ask the user to pick a different name or wait. Check alternatives like <app>-cli, <app>db-cli, etc.
  • Returns a version owned by the same npm user: this is a repeat publish.
  • Returns a version owned by someone else: the name is taken. Switch to @<npm-username>/<name> automatically.

Resolve version

• First-time publish: use the version already in package.json.
• Repeat publish: read the currently published version, increment the patch number (e.g. 0.1.2 → 0.1.3). If the user explicitly asked for a minor or major bump, use that instead.

Phase 2: Validate package.json

Fix package.json so it's npm-ready. See references/package-checklist.md for details.

Apply silently:

• name and version match resolved values
• bin key matches the npm package name and points to ./dist/index.js
• files is ["dist/index.js", "README.md"] — explicitly exclude compiled binaries (e.g. dist/<app>-cli) which can be 50MB+
• type is "module"

Apply and mention briefly:

• description — set if missing or placeholder
• repository — read from git remote get-url origin
• license — default to "MIT" if missing
• engines — add "bun": ">=1.0" if shebang is #!/usr/bin/env bun

Name changes

If the npm package name differs from the scaffold name, update name and bin key in package.json, all command references in README.md, and SKILL.md. Do a thorough search — partial find-and-replace easily misses references in code blocks.

Phase 3: Audit README for npm consumers

Before building, read the README and check it makes sense to a stranger who found this package on npmjs.com — not a monorepo contributor.

Required sections

The README must have all of the following. If any are missing or wrong, rewrite them:

1. Install section at the top with:

   npm i -g <name>
   # or
   npx <name> --help
   

2. Usage section using the final npm package name as the command (e.g. breweries-cli breweries list), not internal dev invocations like bun run dev --, make brew, or bun run src/index.ts.

3. No absolute local paths — scan for /Users/, /home/, ~/g/, or any path that only exists on the author's machine. Remove or replace with generic instructions.

4. No monorepo-internal instructions — remove any steps that require cloning the repo, running bun install at a workspace root, using make, or cd-ing into a sub-package. Move these to a ## Development section at the bottom if needed.

Angle bracket escaping

npm's markdown renderer strips bare <text> as HTML tags. Check all option descriptions and replace unescaped angle brackets:

• Bad: --format <text|json|csv|yaml>
• Good: --format <fmt> where <fmt> is one of: text, json, csv, yaml
• Or: wrap in a code block where angle brackets are safe

Phase 4: Build

bun run build

• If build fails: STOP. Show the error. Do not continue. Help fix the build if possible, then retry.

After building, verify the shebang survived:

head -1 dist/index.js

It must be #!/usr/bin/env bun. If missing, prepend it:

echo '#!/usr/bin/env bun' | cat - dist/index.js > dist/tmp && mv dist/tmp dist/index.js
chmod +x dist/index.js

Phase 5: Verify

Run npm pack --dry-run and check:

• dist/index.js is included
• No src/, node_modules/, .env, token files, or large compiled binaries leaked in
• Total tarball size is under 200KB (typical for a bundled JS CLI). If larger, warn the user and check files in package.json

Then show the pack summary as a final sanity check:

npm pack --dry-run 2>&1 | head -30

Ask the user: "Does the README look right for an npm package page?" before continuing.

Phase 6: Confirm and publish

Present one summary for confirmation:

Ready to publish:
  <name>@<version>  (first-time / update)
  account: <npm-username>
  files:   dist/index.js, README.md, package.json (<size>)
  install: npm i -g <name>
  npx:     npx <name> --help

Ask: "Publish?"

If user confirms, tell them to run this command in their terminal:

cd <cli-directory> && npm publish --access public

The agent cannot run npm publish itself because npm's 2FA requires interactive browser authentication. The user must run the command, which will:

1. Show "Authenticate your account at: <url>"
2. Open their browser to authenticate (passkey, OTP, etc.)
3. Complete the publish

If publish fails, read the error and help the user resolve it.

Phase 7: Done

After successful publish, report:

• https://www.npmjs.com/package/<name>
• npm i -g <name>
• npx <name> --help

Updating an existing npm package

When the user asks to "update npm" or "publish a new version":

1. Bump version in package.json (patch by default, e.g. 0.1.1 → 0.1.2). Do not use npm version (it creates git tags).
2. Rebuild: bun run build
3. Verify shebang: head -1 dist/index.js must be #!/usr/bin/env bun
4. Verify pack: npm pack --dry-run 2>&1 — confirm files and size look correct
5. Tell user to publish in their terminal: cd <cli-directory> && npm publish --access public

If the update includes a name change (e.g. renaming the command), follow the Name Changes checklist in Phase 2 before building.

Do NOT

• Do not publish if the build failed.
• Do not run npm publish from the agent shell — it requires interactive browser auth. Always tell the user to run it in their terminal.
• Do not retry npm login or handle 2FA programmatically.
• Do not publish files outside dist/index.js and README.md unless the user explicitly asks.
• Do not run npm version (creates git tags); bump version in package.json directly.
• Do not include the compiled standalone binary (dist/<app>-cli) in the published package — it is 50MB+ and not needed for npm consumers.