create-yss-spec 3.1.0 → 3.2.0

package/README.md

@@ -2,61 +2,53 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-## 用法
+源码候选版本：`3.2.0`。当前固定模板为 `yss-spec-project-template@0347a5f6d100791cf012ef0f4ae3e148eece644a`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准。
 
-```bash
-npm create yss-spec@latest
-```
-
-也可以使用 `npx`：
+## 本版模板能力
 
-```bash
-npx create-yss-spec@latest
-```
+技术设计统一通过 `yss-technical-design` 进入，按已确认架构调用 DDD `yss-tactical-design` 或传统 MVC `yss-mvc-design`。新合同使用 v2，旧 DDD 合同显式兼容读取；初始化和同步会分发对应技能、Schema 与校验工具。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
-查看用法、命令、参数和样例：
+## 快速开始
 
 ```bash
+npm create yss-spec@latest
 npx create-yss-spec@latest --help
+npx create-yss-spec@latest --version
 ```
 
-查看 CLI 版本：
+候选源码示例：
 
 ```bash
-npx create-yss-spec@latest --version
+npx create-yss-spec@latest \
+  --project-name "设备借用" \
+  --business-domain "内部设备管理" \
+  --target-dir ./equipment-project
 ```
 
-## 当前支持
+## 五家族身份保护
 
-- 交互式收集 `projectName`、`businessDomain`、`targetDir`
-- `--team-size`
-- `--dry-run`
-- 非空目录默认拒绝，初始化命令的 `--force` 允许重新生成
-- `--git-init`
-- `--issue-tracker github|gitlab`
-- `--include-example-docs`
-- `--no-example-docs`
-- `attach` 子命令：在已有项目中补齐研发管理资产
-- `sync` 子命令
-- `update` / `upgrade` 子命令：检查 npm 最新版本，如有更新则安装 CLI 自身
-- 基于 `.yss-template.json` 的模板版本基线和 managed baseline
-- 只使用当前 CLI 包内置、绑定不可变 commit 的模板快照
-- 初始化时将 `yss-project.yaml` 从 `template-source` 改写为 `project-instance`
-- 接管 / 升级时迁移 Spec / Ticket 路径并删除 `to-prd`、`to-issues` 旧 skill
-- 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
-- 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
-- init / sync 不把模板源治理笔记、wiki、审查证据、源仓 CI / Cloud 环境和公开发布清单写入项目实例；attach 会带上 `yss-public-skills.json` 供 `verify-template` 使用
-- 空 gitlink / detached HEAD / git-submodule 挂载点 fail closed，`--force` 也不能覆盖
+CLI 在规划和写入前检查模板家族身份，当前识别：
 
-本轮模板快照绑定 `yss-spec-project-template@248c1723cc0e4e88adabcf00931f78b9aa632d48`。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。实例会带上数字人角色叠加（`docs/agents/digital-human-roles.yaml`）、YSS 前端技能叠加层、DDD Tactical Design 与生命周期转换校验资产、唯一 `code-review` 入口及其 YSS / Alibaba 专项检查与 finding 分流合同、`.cursorrules` 与 `.agents/rules/yss-ai-skills.md`；审查临时目录 `docs/.scratch/` 与已退役的独立入口不进入快照。
+- `create-yss-spec` / `.yss-template.json`
+- `create-yss-harness-design` / `.yss-harness-design.json`
+- `create-yss-harness-dev` / `.yss-harness-dev.json`
+- repository-local backend / `.yss-harness-backend.json`
+- repository-local frontend / `.yss-harness-frontend.json`
 
-## 当前版本说明
+`docs/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
 
-当前 CLI 版本为 `3.1.0`，模板固定到 `248c1723cc0e4e88adabcf00931f78b9aa632d48`。本版本同步可离线核验的战略交接快照包、受控导入与逐条战术追溯，并强化关键决定的真实用户回复校验。
+后端/前端专职模板使用各自仓库的 `scripts/instantiate-harness --target <新目录>`，不由本 CLI 做跨家族原地迁移。
 
-## 接管已有项目
+## CLI 能力
 
-`attach` 只处理 manifest 声明的研发管理资产，不扫描或覆盖前后端运行时代码、业务目录、用户文件和 `.git`。必须先 dry-run，再显式 apply：
+- `attach`：接管已有未管理项目。
+- `sync`：同步受管资产。
+- `sync --dry-run`：传统文本预演。
+- `sync --plan`：结构化文本计划。
+- `sync --json`：Plan Schema v1。
+- `diff / diff --json`：只读差异。
+- `doctor / doctor --json`：只读健康诊断。
+- `update / upgrade`：只更新 CLI 程序，不同步实例资产。
 
 ```bash
 npx create-yss-spec@latest attach \
@@ -69,83 +61,121 @@ npx create-yss-spec@latest attach \
   --target-dir . \
   --project-name "项目名称" \
   --business-domain "业务领域" \
-  --apply [--force]
+  --apply
+
+npx create-yss-spec@latest sync --target-dir . --dry-run
+npx create-yss-spec@latest sync --target-dir .
 ```
 
-规则：
+同步安全规则：
 
-- 目标已有 `.yss-template.json` 时拒绝接管，请使用 `sync`。
-- `--dry-run` 与 `--apply` 互斥；非交互执行只依赖显式参数。
-- 根规则文件等受管冲突默认阻断；`--force` 才覆盖，并把被覆盖文件备份到目标目录外的临时目录。
-- 合法 `template-source` 身份会转换为 `project-instance`；非法身份、迁移冲突和 attach 时无法判断归属的扁平 Ticket 始终阻断。
-- Git worktree 有脏改动时只提醒，不自动 stash 或提交。
-- `.gitmodules`、gitlink 和 `apps/` 挂载工作树是用户资产；空 gitlink / detached HEAD 即使 `--force` 也阻断。
+- 默认只更新未被本地修改的受管文件。
+- `replace-with-force` 冲突只有显式 `--force` 才覆盖。
+- `manual` 冲突即使 `--force` 也不会覆盖。
+- `user-owned` / `protected`、gitlink/submodule/detached HEAD、路径越界和中间 symlink 均不可被 force 绕过。
+- 模板删除项只报告，不自动删除。
+- 校验失败通过 FileTransaction 回滚，并保留必要备份。
 
-## 同步已有模板实例仓库
+## Programmatic API v1
 
-当项目仓库已经由 `create-yss-spec` 初始化，或已经通过 `attach` 接管，并且根目录存在 `.yss-template.json` 时，可以执行：
+npm package 根入口已经开放稳定 Node.js API：
 
-```bash
-npx create-yss-spec@latest sync
+```js
+const {
+  API_VERSION,
+  projectDoctor,
+  projectDiff,
+  templatePlan,
+  templateApply,
+  toErrorEnvelope,
+} = require("create-yss-spec");
 ```
 
-只预演，不真实写入：
+当前 `API_VERSION = 1`。
 
-```bash
-npx create-yss-spec@latest sync --dry-run
+```js
+const plan = templatePlan({ targetDir: "/path/to/project" });
+const report = projectDoctor({ targetDir: "/path/to/project" });
+const result = templateApply({ targetDir: "/path/to/project", force: true });
 ```
 
-当前同步能力的边界：
+返回合同：
 
-- 只支持带模板元数据的模板实例仓库
-- 默认只更新未被本地修改的受管模板文件
-- 对本地已修改文件只提示和跳过，不自动覆盖
-- `--force` 先备份，再覆盖受管冲突文件；不覆盖模板无关文件
-- 对模板已删除文件只报告，不自动删除
-- 对已知的 Spec / Ticket 旧路径执行一次性迁移
-- `docs/requirements/tickets/` 只在 attach 时检查归属；sync 不迁移、不删除，也不因其中存在 Ticket 而阻断
-- 迁移目标已存在且内容不一致时停止，不静默覆盖
-- `.gitmodules`、gitlink（mode `160000`）和 `apps/` 下已挂载实现仓是用户资产，不创建、不覆盖、不删除
-- init / sync 保持实例边界：不复制 `wiki/`、`.github/`、`.template-source/`、源仓库 ADR、Cursor Cloud 环境配置、`docs/reviews/` 或根 `package.json`；共享 `scripts/`、`scripts/vendor/`、`.nvmrc` 和 `.gitignore` 属于实例门禁所需资产。attach 结束后会执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`，门禁失败会回滚文件和 metadata
+- `projectDoctor()` → Doctor Report v1
+- `projectDiff()` / `templatePlan()` → Plan Schema v1
+- `templateApply()` → Apply Result v1
+- `toErrorEnvelope(error)` → Error Envelope v1
 
-```bash
-npx create-yss-spec@latest sync --target-dir . --dry-run
-npx create-yss-spec@latest sync --target-dir . [--force]
+API 不解析 argv，也不负责 CLI 文本输出；CLI 与未来 MCP 复用同一 Planner / Policy / Security / Transaction 逻辑。
+
+## Policy 与 metadata baseline
+
+当前五类 ownership：
+
+- `managed`
+- `managed-customizable`
+- `generated`
+- `user-owned`
+- `protected`
+
+Customization Policy v1：
+
+- `replace-with-force`
+- `manual`
+
+Generator Policy v1 为 generated 资产记录稳定 `generatorId + generatorVersion`。
+
+`.yss-template.json` 会持久化 ownership/customization/generator policy version/hash，以及每个 managed file 的 ownership、mergeStrategy、generatorId/generatorVersion。Doctor 会报告 policy missing/drift/matched。
+
+## 模块化架构
+
+历史约 72KB 的 `src/cli.js` 已退役为兼容桥接。当前执行模型：
+
+```text
+CLI / Programmatic API
+          ↓
+Inspect → Desired State → Policy → Plan → Validate → Transaction → Verify → Metadata
 ```
 
-## 升级 CLI 自身
+核心机器合同：
+
+- Plan Schema v1
+- Error Envelope v1
+- Doctor Report v1
+- Apply Result v1
+- Ownership Policy v1
+- Customization Policy v1
+- Generator Policy v1
 
-`update`（别名 `upgrade`）检查 npm registry 上的最新 `create-yss-spec` 版本，如有更新则按当前安装方式自动安装。它升级的是 CLI 包本身，不会同步项目里的模板资产；模板同步仍使用 `sync`。
+## 使用未发布候选包
+
+从本仓固定提交构建候选包时，先使用 `scripts/sync-template.js` 中的 `DEFAULT_TEMPLATE_REF` 重建模板快照，再打包：
 
 ```bash
-npx create-yss-spec update
-npx create-yss-spec update --dry-run
-npx create-yss-spec upgrade
+YSS_SPEC_TEMPLATE_REPO=https://github.com/iloveZzz/yss-spec-project-template.git \
+YSS_SPEC_TEMPLATE_REF=017925706a981aec9eadefd470232bb531acd4d6 \
+node scripts/sync-template.js
+
+npm pack --ignore-scripts
 ```
 
-- 全局安装会执行 `npm install -g create-yss-spec@latest`
-- 项目本地依赖会在对应项目根执行 `npm install create-yss-spec@latest`
-- 通过 npx 运行或在源码目录中运行时只报告版本并给出安装建议，不覆盖当前文件
-- `--dry-run` 只查询和预览，不安装；`--force` 在已是最新时仍重新安装（npx / 源码目录除外）
+`--ignore-scripts` 仅用于已经显式重建并核对固定快照后的候选打包，不代表 npm 发布。
 
 ## 开发验证
 
-CLI 源码和研发记录由本仓库独立维护。首次测试会从
-[`iloveZzz/yss-spec-project-template`](https://github.com/iloveZzz/yss-spec-project-template)
-同步受管模板快照；正式发布应显式绑定确定 commit：
-
 ```bash
-YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm test
-YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm pack --dry-run
+npm run test:contracts
+npm run test:unit
+npm run test:integration
+YSS_SPEC_TEMPLATE_REF=017925706a981aec9eadefd470232bb531acd4d6 npm test
+npm pack --dry-run
 ```
 
-## 研发记录
+## 设计与手册
 
-- [初始化 CLI Discovery](docs/discovery/yss-spec-cli-init-discovery.md)
-- [模板同步 Discovery](docs/discovery/yss-spec-cli-template-sync-discovery.md)
-- [初始化 CLI PRD](docs/requirements/yss-spec-cli-init-prd.md)
-- [模板同步 PRD](docs/requirements/yss-spec-cli-template-sync-prd.md)
-- [垂直切片](docs/requirements/issues/)
-- [`yss-project.yaml` 跨仓库实现记录](docs/implementation/yss-project-repository-mode-contract.md)
-- [实施路由与 Build Architecture Checklist](docs/implementation/)
+- [CLI v4 模块化](docs/implementation/cli-v4-modularization.md)
+- [Machine Contracts v1](docs/implementation/machine-contracts-v1.md)
+- [Ownership Policy v1](docs/implementation/ownership-policy-v1.md)
+- [Lifecycle Policies v1](docs/implementation/lifecycle-policies-v1.md)
+- [Programmatic API v1](docs/implementation/programmatic-api-v1.md)
 - [完整中文使用手册](docs/user-guide/create-yss-spec-cli-guide.md)

package/bin/create-yss-spec.js

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
 
-const { runCli } = require("../src/cli");
+const { runCli } = require("../src/cli/index.js");
+const { serializeError } = require("../src/cli/error-output.js");
+
+const argv = process.argv.slice(2);
+const wantsJson = argv.includes("--json");
 
 (async () => {
-  await runCli(process.argv.slice(2));
+  await runCli(argv);
 })().catch((error) => {
-  console.error(error.message);
+  if (wantsJson) {
+    process.stdout.write(serializeError(error));
+  } else {
+    console.error(error.message);
+  }
   process.exitCode = 1;
 });

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "create-yss-spec",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Initialize a YSS spec project template repository",
+  "main": "src/api/index.js",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/iloveZzz/create-yss-spec.git"
@@ -23,7 +24,13 @@
   "scripts": {
     "sync-template": "node scripts/sync-template.js",
     "pretest": "npm run sync-template",
-    "test": "node --test tests/*.test.js",
+    "test": "node --test --test-concurrency=1 tests/*.test.js",
+    "test:contracts": "node --test tests/contracts.test.js tests/error-output.test.js tests/apply-result-contract.test.js",
+    "test:unit": "node --test tests/*planner*.test.js tests/filesystem-*.test.js tests/validation-modules.test.js tests/doctor-checks.test.js tests/ownership-policy.test.js tests/lifecycle-policy.test.js tests/lifecycle-metadata.test.js tests/verification-runtime.test.js tests/cli-modules.test.js tests/cli-entrypoint.test.js tests/self-update.test.js tests/plan-schema.test.js tests/contracts.test.js tests/error-output.test.js tests/apply-result-contract.test.js tests/programmatic-api-unit.test.js",
+    "test:integration": "npm run sync-template && node --test tests/init-cli.test.js tests/sync-command-modular.test.js tests/attach-command-modular.test.js tests/doctor-diff-command.test.js tests/programmatic-api.test.js tests/family-identity.test.js",
     "prepack": "npm run sync-template"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
   }
 }

package/src/api/_sync-service.js

@@ -0,0 +1,191 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
+const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
+const { runInTransaction } = require("../filesystem/transaction-runner");
+const { assertBundledFamily, assertTargetFamily } = require("../family-runtime");
+const { gitDirtyWarning } = require("../git/worktree");
+const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
+const { buildSyncPlanFromRuntime } = require("../template/sync-planner-runtime");
+const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { decorateMetadataOwnership } = require("../template/ownership-metadata");
+const { decorateMetadataLifecycle } = require("../template/lifecycle-metadata");
+const {
+  PACKAGE_ROOT,
+  PACKAGE_MANIFEST,
+  BUNDLED_TEMPLATE_ROOT,
+  TEMPLATE_METADATA_FILENAME,
+  fileHash,
+  readTemplateSnapshot,
+  readTargetIdentity,
+  buildSyncDesiredOperations,
+  loadTemplateMetadata,
+  writeTemplateMetadata,
+  buildNextSyncMetadata,
+  verifyGeneratedSyncInstance,
+} = require("../template/instance-runtime");
+
+const APPLY_RESULT_SCHEMA_VERSION = 1;
+
+function normalizeTargetDir(targetDir = ".", cwd = process.cwd()) {
+  return path.resolve(cwd, targetDir);
+}
+
+function isInsideTemplateRoot(targetDir) {
+  const relativePath = path.relative(BUNDLED_TEMPLATE_ROOT, targetDir);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+  );
+}
+
+function inspectExistingTargetDir(targetDir, { force = false } = {}) {
+  if (isInsideTemplateRoot(targetDir)) {
+    throw new Error("目标目录不能位于模板源仓库内部");
+  }
+  if (!fs.existsSync(targetDir) || pathKind(targetDir) !== "directory") {
+    throw new Error("attach 目标目录必须是已经存在的项目目录");
+  }
+  assertTargetWorkingTreeWritable(targetDir, {
+    force,
+    packageRoot: PACKAGE_ROOT,
+  });
+}
+
+function affectedPathsForManagedOperations(operations) {
+  return operations.map((operation) => normalizeRelativePath(operation.relativePath));
+}
+
+function affectedPathsForMigration(migrationPlan) {
+  return (migrationPlan.operations || []).flatMap((operation) =>
+    operation.kind === "move" ? [operation.from, operation.to] : [operation.path],
+  );
+}
+
+function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd() } = {}) {
+  const snapshot = readTemplateSnapshot();
+  assertBundledFamily(snapshot);
+  const resolvedTargetDir = normalizeTargetDir(targetDir, cwd);
+  assertTargetFamily(resolvedTargetDir);
+  inspectExistingTargetDir(resolvedTargetDir, { force: Boolean(force) });
+
+  const { metadata } = loadTemplateMetadata(resolvedTargetDir);
+  const identity = readTargetIdentity(resolvedTargetDir);
+  const desiredOperations = buildSyncDesiredOperations(
+    resolvedTargetDir,
+    metadata,
+    identity,
+  );
+  const migrationPlan = buildLegacyMigrationPlan(
+    resolvedTargetDir,
+    desiredOperations,
+    { checkFlatTickets: false },
+  );
+  const warning = gitDirtyWarning(resolvedTargetDir);
+
+  const { classified: syncPlan, plan } = buildSyncPlanFromRuntime({
+    targetDir: resolvedTargetDir,
+    metadata,
+    desiredOperations,
+    migration: migrationPlan,
+    warning,
+    toVersion: PACKAGE_MANIFEST.version,
+    getUnmanagedReason: (operation) =>
+      unmanagedPathReason(resolvedTargetDir, operation.relativePath, {
+        packageRoot: PACKAGE_ROOT,
+      }),
+    getPathKind: (operation) => pathKind(operation.targetPath),
+    getFileHash: (operation) => fileHash(operation.targetPath),
+  });
+
+  return {
+    targetDir: resolvedTargetDir,
+    metadata,
+    identity,
+    desiredOperations,
+    migrationPlan,
+    warning,
+    syncPlan,
+    plan,
+  };
+}
+
+function assertSyncApplicable(context) {
+  const { migrationPlan, syncPlan } = context;
+  if (migrationPlan.unsafe.length > 0) {
+    throw new Error("sync 被 unsafe 迁移项阻断；请先人工整理 Ticket 归属");
+  }
+  if (syncPlan.unsafe.length > 0) {
+    throw new Error(
+      "sync 被 unsafe 受管路径阻断；--force 不能绕过，请先人工整理目标路径",
+    );
+  }
+  if (migrationPlan.conflicts.length > 0) {
+    throw new Error("sync 被旧路径迁移冲突阻断，请先处理目标冲突");
+  }
+}
+
+function applySyncContext(context, { force = false } = {}) {
+  assertSyncApplicable(context);
+  const { targetDir, metadata, migrationPlan, syncPlan } = context;
+  const managedToApply = [
+    ...syncPlan.updated,
+    ...syncPlan.added,
+    ...(force ? syncPlan.forceableConflicts : []),
+  ];
+
+  const { backupPath } = runInTransaction({
+    targetDir,
+    operation: "sync",
+    affectedPaths: [
+      ...affectedPathsForManagedOperations(managedToApply),
+      ...affectedPathsForMigration(migrationPlan),
+      TEMPLATE_METADATA_FILENAME,
+    ],
+    execute: (transaction) => {
+      for (const operation of managedToApply) {
+        applyManagedOperation(operation, transaction);
+      }
+      applyMigrationOperations(migrationPlan, transaction);
+      verifyGeneratedSyncInstance(targetDir);
+      const nextMetadata = decorateMetadataLifecycle(
+        decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan)),
+      );
+      writeTemplateMetadata(targetDir, nextMetadata, transaction);
+    },
+  });
+
+  return {
+    schemaVersion: APPLY_RESULT_SCHEMA_VERSION,
+    operation: "sync",
+    targetDir,
+    backupPath,
+    template: context.plan.template,
+    stats: {
+      updated: syncPlan.updated.length,
+      added: syncPlan.added.length,
+      skipped: syncPlan.skipped.length,
+      removed: syncPlan.removed.length,
+      forceApplied: force ? syncPlan.forceableConflicts.length : 0,
+    },
+    skipped: syncPlan.skipped.map((operation) => ({
+      path: operation.relativePath,
+      reason: operation.reason,
+      ownership: operation.ownership || null,
+      mergeStrategy: operation.mergeStrategy || null,
+    })),
+    removed: [...syncPlan.removed],
+  };
+}
+
+module.exports = {
+  APPLY_RESULT_SCHEMA_VERSION,
+  normalizeTargetDir,
+  inspectExistingTargetDir,
+  buildSyncContext,
+  assertSyncApplicable,
+  applySyncContext,
+};

package/src/api/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const { normalizeError } = require("../cli/error-output");
+const { projectDoctor } = require("./project-doctor");
+const { projectDiff } = require("./project-diff");
+const { templatePlan } = require("./template-plan");
+const { templateApply } = require("./template-apply");
+
+const API_VERSION = 1;
+
+function toErrorEnvelope(error) {
+  return normalizeError(error);
+}
+
+module.exports = {
+  API_VERSION,
+  projectDoctor,
+  projectDiff,
+  templatePlan,
+  templateApply,
+  toErrorEnvelope,
+};

package/src/api/project-diff.js

@@ -0,0 +1,9 @@
+"use strict";
+
+const { templatePlan } = require("./template-plan");
+
+function projectDiff(options = {}) {
+  return templatePlan(options);
+}
+
+module.exports = { projectDiff };

package/src/api/project-doctor.js

@@ -0,0 +1,10 @@
+"use strict";
+
+const path = require("node:path");
+
+function projectDoctor({ targetDir = ".", cwd = process.cwd() } = {}) {
+  const { buildDoctorReport } = require("../commands/doctor");
+  return buildDoctorReport(path.resolve(cwd, targetDir));
+}
+
+module.exports = { projectDoctor };

package/src/api/template-apply.js

@@ -0,0 +1,10 @@
+"use strict";
+
+const { buildSyncContext, applySyncContext } = require("./_sync-service");
+
+function templateApply(options = {}) {
+  const context = buildSyncContext(options);
+  return applySyncContext(context, { force: Boolean(options.force) });
+}
+
+module.exports = { templateApply };

package/src/api/template-plan.js

@@ -0,0 +1,9 @@
+"use strict";
+
+const { buildSyncContext } = require("./_sync-service");
+
+function templatePlan(options = {}) {
+  return buildSyncContext(options).plan;
+}
+
+module.exports = { templatePlan };

package/src/cli/args.js

@@ -0,0 +1,60 @@
+"use strict";
+
+const { HELP_FLAGS, VERSION_FLAGS } = require("./flags");
+
+const VALUE_OPTIONS = new Map([
+  ["--project-name", "projectName"],
+  ["--business-domain", "businessDomain"],
+  ["--team-size", "teamSize"],
+  ["--target-dir", "targetDir"],
+  ["--issue-tracker", "issueTracker"],
+]);
+
+function parseArgs(argv = []) {
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    const next = argv[index + 1];
+
+    if (VALUE_OPTIONS.has(current)) {
+      if (!next || next.startsWith("--")) {
+        throw new Error(`${current} 需要一个值`);
+      }
+      options[VALUE_OPTIONS.get(current)] = next;
+      index += 1;
+      continue;
+    }
+
+    if (current === "--dry-run") {
+      options.dryRun = true;
+    } else if (current === "--plan") {
+      options.plan = true;
+    } else if (current === "--json") {
+      options.json = true;
+    } else if (current === "--apply") {
+      options.apply = true;
+    } else if (current === "--force") {
+      options.force = true;
+    } else if (current === "--git-init") {
+      options.gitInit = true;
+    } else if (current === "--include-example-docs") {
+      options.includeExampleDocs = true;
+    } else if (current === "--no-example-docs") {
+      options.includeExampleDocs = false;
+    } else if (HELP_FLAGS.has(current)) {
+      options.help = true;
+    } else if (VERSION_FLAGS.has(current)) {
+      options.version = true;
+    } else {
+      throw new Error(`不支持的参数：${current}`);
+    }
+  }
+
+  return options;
+}
+
+module.exports = {
+  VALUE_OPTIONS,
+  parseArgs,
+};