devkit

A personal CLI toolkit for everyday development tasks and automation.

安装后命令名是 k。

安装

npm install -g @secret-momo/devkit

也可以不安装直接运行：

npx @secret-momo/devkit --help

命令

k                  # 展示帮助，等同于 k --help
k <命令> --help    # 查看某个命令的参数

独立定时任务

不需要绑定到 k 的 macOS 定时任务放在 src/scheduled-tasks 下。当前提供用于人工控制 Codex 五小时时间窗口的 codex-window：每天在 08:00、13:30 触发低成本 Codex 请求；运行同目录的 stop.sh 会卸载并删除已安装的 LaunchAgent。详情见该目录的 README。

输出会自动跟随终端是否支持颜色，写到 stderr 的报错按 stderr 是否终端判断。需要关闭时设 NO_COLOR=1；注意 FORCE_COLOR 和 CI 只要存在就生效，所以 FORCE_COLOR=0 仍会着色、CI=1 下输出被重定向也会着色。

kill-port

k kill-port <端口号>

杀掉正在监听指定 TCP 端口的进程。用法、退出状态和验证步骤见 kill-port 说明。

gdb

k gdb

在当前 Git 仓库中多选分支，并删除选中的本地分支及对应远程分支。使用方法、远程分支判定规则和验证步骤见 gdb 说明。

nb

k nb <分支名>

以当前分支为基础创建并切换到新分支，然后推送到 origin 并设置 upstream。用法和失败后的处理见 nb 说明。

gfw

k gfw "feat: add login page"
k gfw clipboard # 使用剪贴板中的文本作为提交信息

将当前仓库的本地变更发送给配置的中继服务，然后同步本地 Git 分支。配置、文件内容处理和同步步骤见 gfw 说明。

开发

本项目使用 Bun 作为包管理器与运行时。

bun install
bun run dev        # 直接跑源码，可带参数：bun run dev kill-port 3000
bun run typecheck  # 类型检查
bun run lint       # 代码检查
bun run format     # 格式化
bun test           # 单元测试
bun run build      # 构建到 lib/

测试

单元测试：

bun test

手动验证 CLI 时，先在项目根目录运行 bun run build，再用 npm link 安装全局命令；结束后可用 npm unlink -g @secret-momo/devkit 卸载。也可以运行构建产物 node <devkit 目录>/lib/index.js。bun run dev 只在项目目录内执行；若需在其他仓库测试 gdb、nb 或 gfw，请使用上述方式。各命令的验证步骤见对应说明。

NPM Publish

公共包需要在 package.json 中声明：

"publishConfig": {
  "access": "public"
}

发布流程：

npm version patch   # 或 minor / major
npm publish

prepublishOnly 会依次执行 typecheck、lint、build。构建产物只有 lib/index.js —— 单文件 bundle，首行带 #!/usr/bin/env node，即 bin 指向的入口。这是纯 CLI，不产出类型声明；类型检查由 typecheck 单独负责。

包只有 bin 这一个入口，没有 main/module/exports：program.parseAsync() 在模块顶层执行，一旦这个包可以被解析，import '@secret-momo/devkit' 就会拿宿主进程的 argv 去跑 CLI（无参数时打印帮助并 exit 0，宿主自己的代码根本不会执行）。删掉入口字段后这种 import 直接以 ERR_MODULE_NOT_FOUND 失败。

bin 配置：

"bin": {
  "k": "./lib/index.js"
}

踩坑记录

1. 在 package.json 的 bin 中只能指定一个 JS 文件路径，不能放一个脚本命令（如：bun run src/index.ts），这样在 npm install -g 的时候并不会起任何作用；
2. 入口文件头必须加上 #! /usr/bin/env node，否则文件无法运行，这句话的意思是让系统自己去找 Node 的执行程序，而 #!/usr/bin/node 是明确告诉系统 Node 的执行程序在路径 /usr/bin/node，对于通过类似 nvm/fnm 安装 Node 肯定是不行的。

License

MIT © 2026 secretmomo