qzkpwoxtl 0.1.0

package/README.md

@@ -0,0 +1,378 @@
+# one cli
+
+面向团队工作区的脚手架与治理工具，用于创建 workspace 骨架、添加模板化子项目，并持续同步 Docker、K8s、GitHub Actions、manifest 与 secrets。
+
+> 本工具发布在 npm 上的包名是 `qzkpwoxtl`（故意取了一个无意义名字以避免被外部用户偶然发现，仅供团队内部使用）。命令行入口仍然是 `one`。
+
+## 快速开始
+
+### 从 npm 安装（推荐）
+
+```bash
+# 全局安装
+pnpm add -g qzkpwoxtl
+# 或 npm install -g qzkpwoxtl
+# 或 yarn global add qzkpwoxtl
+
+one --help
+```
+
+一次性使用而不全局安装：
+
+```bash
+pnpm dlx qzkpwoxtl --help
+# 或 npx qzkpwoxtl --help
+```
+
+### 从源码本地开发
+
+```bash
+pnpm install
+pnpm one --help
+pnpm test
+pnpm test:e2e
+pnpm typecheck
+```
+
+将本地源码 link 为全局 `one`：
+
+```bash
+pnpm install
+pnpm build
+pnpm link --global
+one --help
+```
+
+## Skill
+
+仓库内置了可复用的 Codex skill，和源码一起版本化维护：
+
+- `skills/one-cli/SKILL.md`
+- `skills/one-cli/agents/openai.yaml`
+
+## 产品边界
+
+`one-cli` 负责的是工作区初始化与治理：
+
+- 创建根骨架：`create`
+- 添加 / 移除子项目：`add` / `remove`
+- 同步与检查基础设施：`sync` / `doctor` / `report`
+- 管理 manifest、模板契约、安装、升级与 secrets
+- 管理工作区级 AI 指南与 skills 入口
+
+`one-cli` 不负责代理子项目日常开发命令。各模板自己的 `dev` / `build` / `test` / `lint` 仍由子项目内脚本负责，CLI 只做编排与治理，不替代这些工具链。
+
+## 命令总览
+
+所有命令统一通过全局 `one` 执行。
+
+### 1. 创建骨架
+
+```bash
+one create [project-name] [-d <parent-dir>]
+# 直接 one 也等价于 one create
+one [project-name] [-d <parent-dir>]
+```
+
+说明：
+- `one` 工作区统一只支持 `pnpm`。
+- 根目录会自动生成 `pnpm-workspace.yaml`。
+- `-d, --dir`：指定创建父目录。
+- 创建流程会询问是否启用 Docker / K8s。
+- 会初始化 `one.manifest.json`。
+
+### 2. 添加子项目
+
+```bash
+one add [template-id] -n <subproject-name> [-d <one-project-root>]
+```
+
+说明：
+- 子项目统一使用 `pnpm`，不支持在同一工作区混用 `npm` / `yarn`。
+- `-d, --dir`：显式指定骨架项目根目录（可在任意目录执行）。
+- 模板渲染会自动忽略 `.git`。
+- 完成后自动同步：
+- 子项目 `Dockerfile`
+- 根目录 `docker-compose.yml`
+- 根目录 `k8s/deployment.yaml`
+- 根目录 `.github/workflows/ci-*.yml`
+- 根目录 `one.manifest.json`
+
+### 3. 查看模板
+
+```bash
+one list
+```
+
+### 4. 私有模板认证
+
+```bash
+one auth
+one auth --clear
+```
+
+### 5. 移除子项目
+
+```bash
+one remove [name-or-relative-path] [-d <one-project-root>] [-f] [--dry-run]
+```
+
+说明：
+- `-f, --force`：跳过确认。
+- `--dry-run`：仅预览，不做写入。
+- 自动清理对应 Docker/K8s/Actions/manifest。
+
+### 6. 一键同步配置
+
+```bash
+one sync [-d <one-project-root>] [--dry-run]
+```
+
+说明：
+- 扫描 `apps/`、`services/`、`packages/` 并补齐配置。
+- `--dry-run`：仅预览缺失项。
+
+### 7. 健康检查
+
+```bash
+one doctor [-d <one-project-root>] [--fix] [--json]
+```
+
+检查项：
+- 子项目 `Dockerfile`
+- `docker-compose` 服务项
+- `k8s` 工作负载
+- 子项目 GitHub Actions workflow
+- `one.manifest.json` 与实际目录一致性
+
+说明：
+- `--fix`：自动修复可修复项（等价于 sync + manifest rebuild）。
+- `--json`：输出机器可读结果，适合 CI。
+
+### 8. Manifest 管理
+
+```bash
+one manifest show [-d <one-project-root>]
+one manifest rebuild [-d <one-project-root>]
+```
+
+### 9. 依赖安装
+
+```bash
+one install [-d <one-project-root>] [--roots <dir1,dir2,...>]
+```
+
+说明：
+- 默认扫描 `apps/`、`services/`、`packages/` 下的所有子项目；
+- `--roots` 可覆盖扫描目录（例如 `--roots apps,services,modules`）；
+- 也支持在 `package.json` 配置扫描目录（`one.install.roots`）；
+- 优先级：`--roots` > `one.install.roots` > 默认目录；
+- 在项目根目录以及各子项目目录里执行对应包管理器的 install（按检测到的 lockfile 决定）。
+
+`package.json` 示例：
+
+```json
+{
+  "one": {
+    "install": {
+      "roots": ["apps", "services", "modules"]
+    }
+  }
+}
+```
+
+### 10. 模板契约检查
+
+```bash
+one template check [--id <template-id>] [--strict]
+```
+
+检查项：
+- 禁止项目级配置：`.github/.vscode/.husky/.changeset/commitlint/docker-compose/k8s/nginx`
+- 必需脚本：`lint`、`format`、`check`
+- 约束：`lint` 使用 `oxlint`，`format` 使用 `oxfmt`，`check` 同时包含 `lint` + `format`
+- 至少一个可运行脚本：`dev/start/preview/web`
+- lockfile：模板不应打包 lockfile（拉下后由用户自行 install）；存在则给 warning
+
+说明：
+- `--id`：仅检查指定模板。
+- `--strict`：warning 也视为失败（返回非 0）。
+
+### 11. AI 指南与 Skills
+
+```bash
+one ai init [-d <one-project-root>] [--ai <providers>] [--roots <dir1,dir2,...>] [--force] [--dry-run]
+one ai skills [-d <one-project-root>] [<skills-command...>]
+```
+
+说明：
+- `one ai init` 会扫描当前工作区子项目，按模板聚合最佳实践，生成 `AGENTS.md` 和 / 或 `CLAUDE.md`；
+- `codex` 对应 `AGENTS.md`，`claude-code` 对应 `CLAUDE.md`；
+- provider 默认读取 `package.json#one.ai.providers`，也可通过 `--ai codex,claude-code` 临时覆盖；
+- `--roots` 优先级与 `one install` 一致：`--roots` > `one.install.roots` > 默认目录；
+- 如果目标文件已存在但不包含 `one ai init` 管理标记，默认拒绝覆盖，需显式传 `--force`；
+- `one ai skills` 默认包装 `npx -y skills`，也可用 `one.ai.skillsCommand` 改写上游命令；
+- 执行 `add` / `remove` / `sync` 时，会自动对 `one.ai.providers` 中的所有 provider 注入 `--agent`；
+- 项目配置只记录已安装 skill name：`one.ai.skills.installed`。
+
+`package.json` 示例：
+
+```json
+{
+  "one": {
+    "ai": {
+      "providers": ["codex", "claude-code"],
+      "skillsCommand": "npx -y skills",
+      "skills": {
+        "installed": ["one-cli"]
+      }
+    }
+  }
+}
+```
+
+示例：
+
+```bash
+one ai skills add vercel-labs/agent-skills --skill web-design-guidelines
+one ai skills remove web-design-guidelines
+one ai skills sync
+one ai skills -- add vercel-labs/agent-skills --help
+```
+
+### 12. Secrets（SOPS + age，方案2）
+
+```bash
+one secrets init [-d <one-project-root>]
+one secrets set <KEY> [VALUE] [--env <env>] [--yes] [-d <one-project-root>]
+one secrets import-key [--from <key-path>] [-d <one-project-root>]
+one secrets export-key [--to <key-path>] [-d <one-project-root>]
+one secrets materialize [env] [-d <one-project-root>] [--force]
+one secrets edit [env] [-d <one-project-root>]
+one secrets doctor [-d <one-project-root>]
+```
+
+默认路径：
+- `export-key` 默认导出到本机项目密钥库：`$HOME/.config/one-cli/secrets/<project-id>/age.txt`；
+- `import-key` 默认从同一路径导入；
+- Windows 对应路径：`%USERPROFILE%\\.config\\one-cli\\secrets\\<project-id>\\age.txt`。
+
+推荐流程（已有历史密钥）：
+1. 在已有可解密工作区执行：`one secrets export-key`
+2. 新 worktree 执行：`one secrets import-key`
+3. 执行 `one secrets doctor`
+4. 执行 `one secrets materialize dev`
+5. 之后直接运行：`npx prisma migrate deploy` / `pnpm dev`
+
+推荐流程（全新项目）：
+1. `one secrets init`
+2. `one secrets set DATABASE_URL --env dev`
+3. `one secrets materialize dev`
+4. `one secrets export-key`
+
+补充说明：
+- `one secrets set <KEY> [VALUE]` 用于单个变量的精确新增/更新；
+- 未传 `VALUE` 时会走隐藏输入；
+- 如果 key 已存在且新值不同，交互终端会提示 `y/N` 确认，脚本场景可配合 `--yes` 使用；
+- 显式传入 `""` 时可将变量写为空字符串。
+
+注意：
+- 请将 `.secrets/.env.*.enc` 提交到 Git（它是密文），否则新 worktree 无法 `materialize`；
+- 不要提交 `.secrets/keys/age.txt`、`.env`、`*.plain.env`、`*.dec.env`；
+- `materialize` 默认不会覆盖内容不同的已有 `.env`，如需覆盖请使用 `--force`；
+- `one secrets doctor` 会检查“是否有可用解密身份源”。
+
+前置依赖：
+- 需要系统已安装 `sops` 与 `age`（提供 `age-keygen`）。
+
+```bash
+# macOS (Homebrew)
+brew install sops age
+
+# 验证
+sops --version
+age-keygen --version
+```
+
+常见报错：
+- `spawn sops ENOENT` / `spawn age-keygen ENOENT`：表示命令不存在（不在 `PATH` 中），不是 `one` 本身故障。先安装依赖并重新打开终端后重试。
+- `导入密钥与现有加密文件不匹配`：当前导入的私钥无法解密仓库内已有 `*.enc`。请在可解密工作区重新执行 `one secrets export-key`，再回到目标 worktree 执行 `one secrets import-key`。
+- `检测到现有 .env 与解密内容不一致`：`materialize` 默认保护本地已有 `.env`。确认可覆盖后执行 `one secrets materialize <env> --force`。
+- 可用 `one secrets doctor` 快速检查 secrets 相关环境是否齐全。
+
+### 13. 依赖升级
+
+```bash
+one upgrade [name-or-relative-path] [-d <one-project-root>] [--latest] [--test] [--build] [--dry-run]
+```
+
+说明：
+- 默认执行：依赖升级 + `check`（若存在）。
+- `--latest`：尽可能升级到最新（`npm` 仍使用 `npm update`，major 需手动调整）。
+- `--test`：升级后执行 `test`（若存在）。
+- `--build`：升级后执行 `build`（若存在）。
+- `--dry-run`：只预览命令，不执行升级。
+
+### 13. 状态报告
+
+```bash
+one report [-d <one-project-root>] [--json]
+```
+
+说明：
+- 汇总子项目、manifest、Docker/K8s、GitHub Actions 覆盖率和问题列表。
+- `--json`：输出机器可读报告。
+
+## 推荐工作流
+
+```bash
+one create my-workspace -d .
+one add api-nest -n backend-api -d ./my-workspace
+one add web-csr-react -n web-app -d ./my-workspace
+one doctor -d ./my-workspace --fix
+one report -d ./my-workspace
+```
+
+## CI 示例
+
+```bash
+one template check --strict
+one doctor --json -d <one-project-root>
+one report --json -d <one-project-root>
+```
+
+建议：
+- 将 `doctor --json` 的 `ok=false` 作为流水线失败条件。
+
+## 私有仓库权限说明
+
+`one add` 使用 `giget` 通过 GitHub API 下载模板 tarball，不是 `git clone`。  
+因此本机 `gh auth login` 后，CLI 不会自动复用 git 凭据，私有仓库可能出现 404/无权限。
+
+`one auth` 会自动：
+1. 调用 `gh auth token`
+2. 保存 token 到本地认证文件（默认 `~/.one-cli/auth.json`）
+3. 后续 `list/add` 自动携带认证访问私有仓库
+
+认证优先级：
+1. `GIGET_AUTH` 环境变量（最高）
+2. 本地认证文件（`one auth` 保存）
+3. 匿名访问（仅公开仓库）
+
+## 常见排查
+
+如果已登录 GitHub 仍无法访问私有模板：
+1. 执行 `gh auth status` 检查账号和 scope。
+2. 若模板在组织私有仓库，确认 token 已通过组织 SSO 授权。
+3. 确认 token 具备私有仓库读取权限（通常至少 `repo`）。
+
+也可临时设置：
+
+```bash
+export GIGET_AUTH="$(gh auth token)"
+```
+
+## 注册表来源
+
+- 默认使用仓库内置并随 npm 包一起分发的 `registry.json`。
+- 可通过 `ONE_REGISTRY_URL` 指向自定义注册表。

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };