api2cli-publish-to-npm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Publish to npm

发布到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>

将api2cli生成的CLI发布到npm registry，这样用户就可以通过

npm i -g <name>

全局安装，或者通过

npx <name>

直接运行。

Phase 1: Pre-flight

阶段1：预检查

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.

运行

npm whoami

。

若运行成功：记录用户名，继续后续流程。
若运行失败：告知用户需要先执行
```
npm login
```
，暂停流程等待用户确认登录完成。

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.

读取

package.json

中的

name

字段，按以下规则确定最终发布的包名：

若
```
name
```
包含模板占位符（
```
{{APP_CLI}}
```
），则从目录名推导包名（例如
```
~/.cli/typefully-cli/
```
→
```
typefully-cli
```
）。
运行
```
npm view <name> version
```
：
- 404（未找到）：属于首次发布，包名可用，直接使用。
- 返回「Unpublished」：包名在取消发布后会被冻结24小时，告知用户更换包名或等待冻结结束，可推荐
```
<app>-cli
```
  、
```
<app>db-cli
```
  等替代名称。
- 返回的版本属于当前登录的npm用户：属于重复发布新版本。
- 返回的版本属于其他用户：包名已被占用，自动切换为
```
@<npm-username>/<name>
```
  作用域名。

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.

首次发布：直接使用
```
package.json
```
中已有的版本号。
重复发布：读取当前已发布的最新版本号，递增修订号（例如
```
0.1.2
```
→
```
0.1.3
```
）。若用户明确要求升级次版本号或主版本号，则按用户需求处理。

Phase 2: Validate package.json

阶段2：校验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
```

修复

package.json

使其符合npm发布要求，详细规则可参考references/package-checklist.md。

静默应用以下修改：

```
name
```
和
```
version
```
字段与前面确定的取值一致
```
bin
```
字段与npm包名匹配，且指向
```
./dist/index.js
```
```
files
```
字段设置为
```
["dist/index.js", "README.md"]
```
——显式排除体积可达50MB以上的编译后二进制文件（例如
```
dist/<app>-cli
```
）
```
type
```
字段设置为
```
"module"
```

应用以下修改并简要告知用户：

```
description
```
字段：若为空或为占位符则补充内容
```
repository
```
字段：从
```
git remote get-url origin
```
的返回值读取
```
license
```
字段：若缺失则默认设置为
```
"MIT"
```
```
engines
```
字段：若脚本首行声明为
```
#!/usr/bin/env bun
```
则添加
```
"bun": ">=1.0"
```

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.

若最终npm包名与脚手架初始名称不同，需要更新

package.json

中的

name

和

bin

字段、

README.md

以及

SKILL.md

中所有命令引用。请进行全局搜索，避免部分替换遗漏代码块中的引用。

Phase 3: Audit README for npm consumers

阶段3：面向npm用户审核README

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

构建前，通读README，确保对于在npmjs.com上偶然发现这个包的陌生用户而言内容清晰易懂，而非仅面向单体仓库的贡献者。

Required sections

必填章节

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

Install section at the top with:
```
npm i -g <name>
# or
npx <name> --help
```
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
```
.
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.
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.

README必须包含以下所有章节，若有缺失或错误请重写：

安装章节位于顶部，包含以下内容：
```
npm i -g <name>
# 或者
npx <name> --help
```
使用章节使用最终的npm包名作为命令（例如
```
breweries-cli breweries list
```
），不要使用内部开发调用命令，比如
```
bun run dev --
```
、
```
make brew
```
或者
```
bun run src/index.ts
```
。
无绝对本地路径：扫描所有内容，删除或替换
```
/Users/
```
、
```
/home/
```
、
```
~/g/
```
等仅存在于开发者本机的路径，替换为通用说明。
无单体仓库内部操作指引：删除所有要求克隆仓库、在工作区根目录运行
```
bun install
```
、使用
```
make
```
、进入子包目录等操作步骤，若有必要可将这些内容移动到文档底部的
```
## 开发说明
```
章节。

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

npm的markdown渲染器会把裸写的

<text>

当成HTML标签过滤掉。检查所有选项描述，替换未转义的尖括号：

错误示例：
```
--format <text|json|csv|yaml>
```
正确示例：
```
--format <fmt>
```
，其中
```
<fmt>
```
可选值为：
```
text
```
、
```
json
```
、
```
csv
```
、
```
yaml
```
或者：放到代码块中，代码块内的尖括号不会被过滤

Phase 4: Build

阶段4：构建

bash

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:

bash

head -1 dist/index.js

It must be

#!/usr/bin/env bun

. If missing, prepend it:

bash

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

bash

bun run build

若构建失败：立即停止，展示错误信息，不要继续后续流程。尽可能协助修复构建问题后再重试。

构建完成后，验证脚本首行声明是否保留：

bash

head -1 dist/index.js

必须为

#!/usr/bin/env bun

，若缺失则手动添加：

bash

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

阶段5：验证

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:

bash

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

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

Run

npm pack --dry-run

and check:

包含
```
dist/index.js
```
没有混入
```
src/
```
、
```
node_modules/
```
、
```
.env
```
、密钥文件或大体积编译二进制文件
压缩包总大小小于200KB（JS CLI工具的常规大小），若体积过大则警告用户并检查package.json中的
```
files
```
字段配置

然后输出打包摘要供最终检查：

bash

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

继续流程前询问用户：「这个README作为npm包页面的内容是否合适？」

Phase 6: Confirm and publish

阶段6：确认并发布

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:

bash

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:

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

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

展示如下汇总信息供用户确认：

Ready to publish:
  <name>@<version>  (首次发布 / 版本更新)
  账号: <npm-username>
  包含文件:   dist/index.js, README.md, package.json (<size>)
  安装命令: npm i -g <name>
  直接运行:     npx <name> --help

询问用户：「确认发布吗？」

若用户确认，告知用户在终端运行以下命令：

bash

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

Agent无法直接运行

npm publish

，因为npm的双重认证需要交互式浏览器验证，必须由用户执行该命令，流程如下：

终端显示「请在以下地址验证你的账户：
```
<url>
```
」
用户打开浏览器完成身份验证（通行密钥、一次性验证码等）
发布完成

若发布失败，读取错误信息并协助用户解决问题。

Phase 7: Done

阶段7：完成

After successful publish, report:

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

发布成功后，告知用户以下信息：

包页面地址：
```
https://www.npmjs.com/package/<name>
```
全局安装命令：
```
npm i -g <name>
```
直接运行命令：
```
npx <name> --help
```

Updating an existing npm package

更新已有的npm包

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

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).
Rebuild:
```
bun run build
```
Verify shebang:
```
head -1 dist/index.js
```
must be
```
#!/usr/bin/env bun
```
Verify pack:
```
npm pack --dry-run 2>&1
```
— confirm files and size look correct

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.

当用户提出「更新npm包」或「发布新版本」需求时：

升级版本号：直接修改
```
package.json
```
中的版本号（默认升级修订号，例如
```
0.1.1
```
→
```
0.1.2
```
），不要使用
```
npm version
```
命令（会自动创建git标签）。
重新构建：
```
bun run build
```
验证脚本首行：
```
head -1 dist/index.js
```
必须为
```
#!/usr/bin/env bun
```
验证打包内容：
```
npm pack --dry-run 2>&1
```
，确认文件和体积符合要求

告知用户执行发布命令：在终端运行

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

如果更新包含包名变更（例如重命名命令），构建前请先按照阶段2中的包名变更检查清单处理。

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.

构建失败时禁止发布。
禁止在Agent的shell中运行
```
npm publish
```
——该操作需要交互式浏览器认证，必须告知用户在自己的终端中运行。
禁止自动重试
```
npm login
```
或通过程序处理双重认证。
除非用户明确要求，禁止发布
```
dist/index.js
```
和
```
README.md
```
之外的文件。
禁止运行
```
npm version
```
（会创建git标签），直接修改
```
package.json
```
中的版本号即可。
禁止将编译后的独立二进制文件（
```
dist/<app>-cli
```
）包含到发布包中——其体积通常超过50MB，npm用户不需要该文件。