create-yss-spec 3.5.4 → 3.5.6

package/vendor/cli-core/build.mjs

@@ -0,0 +1,302 @@
+// Build-time only: source revisions are resolved before reading any distribution bytes.
+import * as fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import {
+  ensure,
+  hash,
+  json,
+  relative,
+  governance,
+  safe,
+  write,
+  readJson,
+} from "./io.mjs";
+import { yaml, PROFILE, loadBundle } from "./bundle.mjs";
+import { familyFor } from "./family.mjs";
+const CORE_PATH = ".template-source/cli-core";
+const UPGRADE_SKILL = ".agents/skills/yss-harness-upgrade";
+const UPGRADE_PROTOCOL = ".template-spec/process/harness-upgrade.md";
+function upgradeResources(root) {
+  if (!fs.existsSync(path.join(root, UPGRADE_SKILL))) return {};
+  const files = {};
+  for (const ref of Object.keys(inventory(path.join(root, UPGRADE_SKILL)))) {
+    let bytes = fs.readFileSync(path.join(root, UPGRADE_SKILL, ref));
+    if (ref === 'SKILL.md') bytes = Buffer.from(bytes.toString().replace('../../../.template-spec/process/harness-upgrade.md', 'protocol.md'));
+    files[ref] = bytes;
+  }
+  files['protocol.md'] = fs.readFileSync(path.join(root, UPGRADE_PROTOCOL));
+  return files;
+}
+function archive(source, ref, consume, paths = []) {
+  const revision = execFileSync(
+    "git",
+    ["-C", source, "rev-parse", `${ref === "WORKTREE" ? "HEAD" : ref}^{commit}`],
+    { encoding: "utf8" },
+  ).trim();
+  ensure(/^[a-f0-9]{40}$/.test(revision), "source revision 必须是完整提交");
+  if (ref === "WORKTREE") {
+    return consume(fs.realpathSync(source), revision, "working-tree");
+  }
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "harness-source-"));
+  try {
+    const tar = execFileSync("git", ["-C", source, "archive", revision, ...paths], {
+      maxBuffer: 256 * 1024 * 1024,
+    });
+    execFileSync("tar", ["-xf", "-", "-C", scratch], { input: tar });
+    return consume(fs.realpathSync(scratch), revision, "committed");
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+function inventory(root) {
+  const files = {};
+  function walk(dir) {
+    for (const entry of fs
+      .readdirSync(path.join(root, dir), { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name, "en"))) {
+      const ref = dir ? `${dir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(ref);
+      else {
+        ensure(entry.isFile(), `核心不允许链接: ${ref}`);
+        files[ref] = {
+          digest: hash(fs.readFileSync(path.join(root, ref))),
+          mode: fs.statSync(path.join(root, ref)).mode & 0o111 ? 0o755 : 0o644,
+        };
+      }
+    }
+  }
+  walk("");
+  return Object.fromEntries(
+    Object.entries(files).sort(([a], [b]) => (a < b ? -1 : 1)),
+  );
+}
+export function verifyCore(packageRoot) {
+  const lock = readJson(packageRoot, "cli-core.lock.json");
+  ensure(
+    lock.schemaVersion === 1 &&
+      lock.protocolVersion === 1 &&
+      ["committed", "working-tree"].includes(lock.sourceState || "committed") &&
+      /^[a-f0-9]{40}$/.test(lock.sourceRevision),
+    "核心锁格式错误",
+  );
+  const files = inventory(path.join(packageRoot, "vendor/cli-core"));
+  ensure(
+    JSON.stringify(files) === JSON.stringify(lock.files) &&
+      hash(JSON.stringify(files)) === lock.digest,
+    "vendor/cli-core 漂移",
+  );
+  ensure(
+    readJson(packageRoot, "vendor/cli-core/package.json").version ===
+      lock.coreVersion,
+    "核心版本漂移",
+  );
+  if (lock.upgradeResources) ensure(JSON.stringify(inventory(path.join(packageRoot,'resources/upgrade-skill'))) === JSON.stringify(lock.upgradeResources), '升级技能资源漂移');
+  return lock;
+}
+export function syncCore(source, ref, packageRoot, check = false) {
+  const paths = [CORE_PATH];
+  for (const candidate of [UPGRADE_SKILL, UPGRADE_PROTOCOL]) {
+    if (ref === 'WORKTREE') { if (fs.existsSync(path.join(source,candidate))) paths.push(candidate); }
+    else { try { execFileSync('git',['-C',source,'cat-file','-e',`${ref}:${candidate}`],{stdio:'ignore'}); paths.push(candidate); } catch {} }
+  }
+  return archive(source, ref, (root, revision, sourceState) => {
+    const sourceRoot = path.join(root, CORE_PATH),
+      files = inventory(sourceRoot),
+      coreVersion = readJson(sourceRoot, "package.json").version;
+    const resources = upgradeResources(root);
+    const resourceInventory = Object.fromEntries(Object.entries(resources).sort(([a],[b])=>a<b?-1:1).map(([ref,bytes])=>[ref,{digest:hash(bytes),mode:0o644}]));
+    const lock = {
+      schemaVersion: 1,
+      sourceRepository:
+        "https://github.com/iloveZzz/yss-spec-project-template.git",
+      sourceRevision: revision,
+      sourceState,
+      sourcePath: CORE_PATH,
+      coreVersion,
+      protocolVersion: 1,
+      files,
+      digest: hash(JSON.stringify(files)),
+      ...(Object.keys(resources).length ? {upgradeResources:resourceInventory} : {}),
+    };
+    if (check) {
+      ensure(
+        json(readJson(packageRoot, "cli-core.lock.json")) === json(lock),
+        "核心来源锁漂移",
+      );
+      verifyCore(packageRoot);
+      return lock;
+    }
+    fs.rmSync(path.join(packageRoot, "vendor/cli-core"), {
+      recursive: true,
+      force: true,
+    });
+    for (const [ref, entry] of Object.entries(files))
+      write(
+        packageRoot,
+        `vendor/cli-core/${ref}`,
+        fs.readFileSync(path.join(sourceRoot, ref)),
+        entry.mode,
+      );
+    write(packageRoot, "cli-core.lock.json", json(lock));
+    if (Object.keys(resources).length) {
+      fs.rmSync(path.join(packageRoot,'resources/upgrade-skill'),{recursive:true,force:true});
+      for (const [ref,bytes] of Object.entries(resources)) write(packageRoot,`resources/upgrade-skill/${ref}`,bytes);
+    }
+    return lock;
+  }, paths);
+}
+function selected(ref, m) {
+  const top = ref.split("/")[0],
+    prefix = (p, base) => p === base || p.startsWith(base + "/");
+  return (
+    ((m.allowRootEntries || []).includes(top) ||
+      (m.allowRootFiles || []).includes(ref) ||
+      (m.allowFiles || []).includes(ref)) &&
+    ![
+      ...(m.excludeRootEntries || []),
+      ...(m.initExcludeRootEntries || []),
+    ].includes(top) &&
+    ![
+      ...(m.excludeRootFiles || []),
+      ...(m.initExcludeRootFiles || []),
+    ].includes(ref) &&
+    ![...(m.excludePaths || []), ...(m.initExcludePaths || [])].some((x) =>
+      prefix(ref, x),
+    ) &&
+    ref !== "scripts/instantiate-harness"
+  );
+}
+export function syncTemplate(source, ref, packageRoot, check = false) {
+  return archive(source, ref, (root, revision, sourceState) => {
+    const profile = yaml(fs.readFileSync(path.join(root, PROFILE))),
+      identity = yaml(fs.readFileSync(path.join(root, "yss-project.yaml")));
+    ensure(
+      identity.schema_version === 1 &&
+        identity.repository_mode === "template-source",
+      "来源不是 template-source",
+    );
+    const side = profile.profile_id === 'harness.business-ddd-strategy-handoff' ? 'design' : profile.profile_id?.match(/^harness\.(backend|frontend)-delivery$/)?.[1];
+    const family = familyFor(side);
+    ensure(readJson(packageRoot,'package.json').name === family.packageName, '来源 profile 与薄包身份不一致');
+    let manifestBytes;
+    if (side === 'design') {
+      const raw = yaml(fs.readFileSync(safe(root,'.template-spec/process/instance-distribution-manifest.yaml')));
+      ensure(raw.profile_id === family.profileId && raw.cli_package === family.packageName && raw.template_source === family.templateSource, '战略分发清单身份矛盾');
+      const manifest = {profileId:raw.profile_id};
+      for (const key of ['allow_root_entries','allow_root_files','allow_files','exclude_root_entries','exclude_root_files','exclude_paths','render_paths','init_exclude_root_entries','init_exclude_root_files','init_exclude_paths','instance_forbidden_paths']) manifest[key.replace(/_([a-z])/g,(_,c)=>c.toUpperCase())]=raw[key] || [];
+      manifestBytes = Buffer.from(json(manifest));
+    } else {
+      ensure(profile.instantiation?.cli_package === family.packageName && profile.instantiation?.metadata_file === family.metadataFile && profile.instantiation?.template_source === family.templateSource, '来源实例化合同矛盾');
+      manifestBytes = fs.readFileSync(safe(root, profile.instantiation.distribution_manifest));
+    }
+    const manifest = JSON.parse(manifestBytes),
+      entries = {},
+      blobs = new Map(),
+      canonical = path.join(root, ".agents/skills"),
+      captured = new Map();
+    function capture(physical, logical, ancestors = []) {
+      relative(logical);
+      const s = fs.lstatSync(physical);
+      if (s.isSymbolicLink()) {
+        const link = fs.readlinkSync(physical),
+          resolved = fs.realpathSync(physical);
+        ensure(
+          !path.isAbsolute(link) &&
+            resolved.startsWith(canonical + path.sep) &&
+            /^\.(agents|claude|codex|cursor|pi|qoder|trae)\/skills\//.test(
+              logical,
+            ),
+          `不允许的投影链接: ${logical}`,
+        );
+        ensure(!ancestors.includes(resolved), "投影链接循环");
+        return capture(resolved, logical, [...ancestors, resolved]);
+      }
+      if (s.isDirectory()) {
+        for (const name of fs.readdirSync(physical).sort()) {
+          if (name === ".DS_Store") continue;
+          capture(path.join(physical, name), `${logical}/${name}`, ancestors);
+        }
+        return;
+      }
+      if (!selected(logical, manifest)) return;
+      governance(logical);
+      ensure(s.isFile(), `未知分发类型: ${logical}`);
+      let content = captured.get(physical);
+      if (!content) {
+        const bytes = fs.readFileSync(physical);
+        content = { bytes, digest: hash(bytes) };
+        captured.set(physical, content);
+      }
+      const { bytes, digest } = content;
+      entries[logical] = {
+        type: "file",
+        digest,
+        mode: s.mode & 0o111 ? 0o755 : 0o644,
+        blob: `blobs/${digest}`,
+      };
+      blobs.set(digest, bytes);
+    }
+    for (const name of fs.readdirSync(root).sort())
+      if (selected(name, manifest)) capture(path.join(root, name), name);
+    // Explicit allowFiles may lie below an otherwise excluded directory.
+    for (const ref of manifest.allowFiles || [])
+      if (fs.existsSync(safe(root, ref))) capture(safe(root, ref), ref);
+    const files = Object.fromEntries(
+      Object.entries(entries).sort(([a], [b]) => (a < b ? -1 : 1)),
+    );
+    let previous = null;
+    try {
+      previous = process.env.YSS_TEMPLATE_BASELINE_SNAPSHOT
+        ? JSON.parse(fs.readFileSync(process.env.YSS_TEMPLATE_BASELINE_SNAPSHOT, "utf8"))
+        : readJson(packageRoot, "template.snapshot.json");
+    } catch {}
+    const retiredFiles = Object.fromEntries(
+      Object.entries({...(previous?.retiredFiles || {}), ...(previous?.files || {})})
+        .filter(([ref]) => !Object.hasOwn(files, ref))
+        .map(([ref, item]) => [ref, {type:"file", digest:item.digest, mode:item.mode}])
+        .sort(([a], [b]) => (a < b ? -1 : 1)),
+    );
+    const transitionBaselines = Object.fromEntries(
+      Object.entries({...(previous?.files || {}), ...(previous?.transitionBaselines || {})})
+        .filter(([ref, item]) => Object.hasOwn(files, ref) && item.digest !== files[ref].digest)
+        .map(([ref, item]) => [ref, {type:"file", digest:item.digest, mode:item.mode}])
+        .sort(([a], [b]) => (a < b ? -1 : 1)),
+    );
+    const snapshot = {
+      schemaVersion: 1,
+      ...family,
+      templateCommit: revision,
+      sourceState,
+      manifestHash: hash(manifestBytes),
+      files,
+      retiredFiles,
+      retiredFilesHash: hash(JSON.stringify(retiredFiles)),
+      transitionBaselines,
+      transitionBaselinesHash: hash(JSON.stringify(transitionBaselines)),
+      snapshotHash: hash(JSON.stringify(files)),
+      projectionRepresentation: "materialized-files",
+      pathEncoding: "sha256-blobs-v1",
+    };
+    if (check) {
+      ensure(
+        json(readJson(packageRoot, "template.snapshot.json")) ===
+          json(snapshot),
+        "模板来源快照漂移",
+      );
+      loadBundle(packageRoot);
+      return snapshot;
+    }
+    fs.rmSync(path.join(packageRoot, "template"), {
+      recursive: true,
+      force: true,
+    });
+    for (const [digest, bytes] of blobs)
+      write(packageRoot, `template/blobs/${digest}`, bytes);
+    write(packageRoot, "template.manifest.json", manifestBytes);
+    write(packageRoot, "template.snapshot.json", json(snapshot));
+    write(packageRoot, "config/family.json", json(family));
+    return snapshot;
+  });
+}

package/vendor/cli-core/bundle.mjs

@@ -0,0 +1,198 @@
+import * as fs from "node:fs";
+import { parseDocument } from "./vendor/yaml.mjs";
+import { ensure, hash, readJson, safe, governance } from "./io.mjs";
+import { familyFor, CHECKS } from './family.mjs';
+export const PROFILE = ".template-spec/process/harness-profile.yaml";
+export function yaml(bytes) {
+  const doc = parseDocument(String(bytes), { uniqueKeys: true });
+  ensure(!doc.errors.length, "YAML 不合法");
+  const data = doc.toJS({ maxAliasCount: 0 });
+  ensure(
+    data && typeof data === "object" && !Array.isArray(data),
+    "YAML 必须是对象",
+  );
+  return data;
+}
+export function loadBundle(root) {
+  const pkg = readJson(root, "package.json"),
+    family = readJson(root, "config/family.json"),
+    snapshot = readJson(root, "template.snapshot.json"),
+    core = readJson(root, "cli-core.lock.json");
+  const expected = familyFor(family.side);
+  for (const [key, value] of Object.entries(expected))
+    ensure(
+      family[key] === value && snapshot[key] === value,
+      `包内身份不一致: ${key}`,
+      "IDENTITY",
+    );
+  ensure(
+    pkg.name === family.packageName && snapshot.schemaVersion === 1,
+    "包身份或快照 schema 不支持",
+    "IDENTITY",
+  );
+  ensure(
+    /^[0-9a-f]{40}$/.test(snapshot.templateCommit) &&
+      ["committed", "working-tree"].includes(snapshot.sourceState || "committed") &&
+      hash(JSON.stringify(snapshot.files)) === snapshot.snapshotHash,
+    "快照摘要或 revision 不一致",
+    "BUNDLE",
+  );
+  ensure(
+    hash(fs.readFileSync(safe(root, "template.manifest.json"))) ===
+      snapshot.manifestHash,
+    "分发清单摘要不一致",
+    "BUNDLE",
+  );
+  const retiredFiles = snapshot.retiredFiles || {};
+  ensure(
+    (!snapshot.retiredFilesHash && !Object.keys(retiredFiles).length) ||
+      hash(JSON.stringify(retiredFiles)) === snapshot.retiredFilesHash,
+    "退出分发基线摘要不一致",
+    "BUNDLE",
+  );
+  for (const [ref, item] of Object.entries(retiredFiles)) {
+    governance(ref);
+    ensure(
+      item.type === "file" &&
+        [0o644, 0o755].includes(item.mode) &&
+        /^[0-9a-f]{64}$/.test(item.digest),
+      `退出分发基线不合法: ${ref}`,
+      "BUNDLE",
+    );
+  }
+  const transitionBaselines = snapshot.transitionBaselines || {};
+  ensure(
+    (!snapshot.transitionBaselinesHash && !Object.keys(transitionBaselines).length) ||
+      hash(JSON.stringify(transitionBaselines)) === snapshot.transitionBaselinesHash,
+    "受管范围迁移基线摘要不一致",
+    "BUNDLE",
+  );
+  for (const [ref, item] of Object.entries(transitionBaselines)) {
+    governance(ref);
+    ensure(
+      snapshot.files[ref] && item.type === "file" &&
+        [0o644, 0o755].includes(item.mode) &&
+        /^[0-9a-f]{64}$/.test(item.digest),
+      `受管范围迁移基线不合法: ${ref}`,
+      "BUNDLE",
+    );
+  }
+  ensure(
+    core.schemaVersion === 1 &&
+      core.protocolVersion === 1 &&
+      ["committed", "working-tree"].includes(core.sourceState || "committed") &&
+      /^[0-9a-f]{40}$/.test(core.sourceRevision) &&
+      /^[0-9a-f]{64}$/.test(core.digest),
+    "核心锁不合法",
+    "BUNDLE",
+  );
+  if (core.coreVersion === '0.2.0') ensure(core.files && Object.keys(core.files).length > 0, '核心文件清单缺失', 'BUNDLE');
+  for (const [ref, item] of Object.entries(core.files || {})) {
+    const file=safe(root, `vendor/cli-core/${ref}`);
+    ensure(hash(fs.readFileSync(file))===item.digest && (fs.statSync(file).mode & 0o111 ? 0o755 : 0o644)===item.mode, `核心文件漂移: ${ref}`, 'BUNDLE');
+  }
+  if (Object.keys(core.files || {}).length) ensure(hash(JSON.stringify(core.files))===core.digest, '核心清单摘要不一致', 'BUNDLE');
+  const manifest = readJson(root, "template.manifest.json");
+  const files = new Map();
+  const blobs = new Map();
+  for (const [ref, item] of Object.entries(snapshot.files)) {
+    governance(ref);
+    ensure(!(manifest.instanceForbiddenPaths || []).some(p=>ref===p || ref.startsWith(p+"/")), `快照含家族禁止分发路径: ${ref}`, "BUNDLE");
+    ensure(
+      item.type === "file" &&
+        [0o644, 0o755].includes(item.mode) &&
+        item.blob === `blobs/${item.digest}` &&
+        /^[0-9a-f]{64}$/.test(item.digest),
+      `快照类型/编码非法: ${ref}`,
+      "BUNDLE",
+    );
+    let bytes = blobs.get(item.digest);
+    if (!bytes) {
+      bytes = fs.readFileSync(safe(root, `template/${item.blob}`));
+      ensure(hash(bytes) === item.digest, `快照内容摘要不一致: ${ref}`, "BUNDLE");
+      blobs.set(item.digest, bytes);
+    }
+    files.set(ref, {
+      bytes: Buffer.from(bytes),
+      baseline: { type: "file", digest: item.digest, mode: item.mode },
+    });
+  }
+  for (const ref of [
+    "README.md",
+    "AGENTS.md",
+    "CONTEXT.md",
+    "yss-project.yaml",
+    PROFILE,
+  ])
+    ensure(files.has(ref), `缺少必需合同: ${ref}`, "BUNDLE");
+  const profile = yaml(files.get(PROFILE).bytes),
+    identity = yaml(files.get("yss-project.yaml").bytes);
+  ensure(
+    identity.schema_version === 1 &&
+      identity.repository_mode === "template-source",
+    "包内不是模板源",
+    "IDENTITY",
+  );
+  ensure(
+    [1, 2].includes(profile.schema_version) &&
+      profile.profile_id === family.profileId &&
+      (family.side === "design" || (profile.instantiation?.cli_package === family.packageName &&
+      profile.instantiation?.metadata_file === family.metadataFile &&
+      profile.instantiation?.template_source === family.templateSource)),
+    "模板 profile 与包身份矛盾",
+    "IDENTITY",
+  );
+  if (files.has("skills-lock.json")) for (const [, ref] of CHECKS) ensure(files.has(ref), `缺少实例校验器: ${ref}`, "BUNDLE");
+  return {
+    root,
+    pkg,
+    family,
+    snapshot,
+    core,
+    manifest,
+    retiredFiles,
+    transitionBaselines,
+    files,
+  };
+}
+export function render(bundle, variables) {
+  const result = new Map();
+  for (const [ref, item] of bundle.files) {
+    if (
+      !variables.includeExampleDocs &&
+      bundle.manifest.exampleDocPaths?.some(
+        (x) => ref === x || ref.startsWith(x + "/"),
+      )
+    )
+      continue;
+    let bytes = item.bytes;
+    if (ref === "yss-project.yaml")
+      bytes = Buffer.from(
+        "schema_version: 1\nrepository_mode: project-instance\n",
+      );
+    else if (ref === "README.md")
+      bytes = Buffer.from(
+        `# ${variables.projectName}\n\n本仓是 \`${bundle.family.profileId}\` 的 \`project-instance\`。\n\n先读 [AGENTS.md](AGENTS.md)、[CONTEXT.md](CONTEXT.md) 与 [profile](.template-spec/process/harness-profile.yaml)。\n\n业务领域：${variables.businessDomain}\n团队规模：${variables.teamSize}\n`,
+      );
+    if (bundle.family.side === "design" && ref === "AGENTS.md")
+      bytes = Buffer.from(bytes.toString().replace("**项目名称：** [填写]", () => `**项目名称：** ${variables.projectName}`).replace("**业务领域：** [填写]", () => `**业务领域：** ${variables.businessDomain}`).replace("**团队规模：** [填写]", () => `**团队规模：** ${variables.teamSize}`));
+    if (ref === ".template-spec/agents/issue-tracker.md")
+      bytes = Buffer.from(
+        bytes
+          .toString()
+          .replace(
+            "platform: local-markdown",
+            `platform: ${variables.issueTracker}`,
+          )
+          .replace(
+            "| `platform` | `local-markdown` |",
+            `| \`platform\` | \`${variables.issueTracker}\` |`,
+          ),
+      );
+    result.set(ref, {
+      bytes,
+      baseline: { ...item.baseline, digest: hash(bytes) },
+    });
+  }
+  return result;
+}

package/vendor/cli-core/cli.mjs

@@ -0,0 +1,182 @@
+import { runMigration } from "./migration-adapter.mjs";
+import { createInterface } from "node:readline/promises";
+import { doctor } from "./verification.mjs";
+import { inspectState, recoveryPreview, recover } from "./transaction.mjs";
+import { identity, recoveryIdentity } from "./identity.mjs";
+import * as fs from "node:fs";
+import path from "node:path";
+import { loadBundle } from "./bundle.mjs";
+import { update } from "./update.mjs";
+import { execute } from "./engine.mjs";
+import { ensure, targetPath, stat, write, json } from "./io.mjs";
+export function parse(argv) {
+  const args = [...argv],
+    options = {
+      command: "init",
+      projectName: "",
+      businessDomain: "未指定",
+      teamSize: "未指定",
+      issueTracker: "local-markdown",
+      includeExampleDocs: true,
+    };
+  if (args[0] && !args[0].startsWith("-")) options.command = args.shift();
+  const values = {
+    "--target-dir": "targetDir",
+    "--project-name": "projectName",
+    "--business-domain": "businessDomain",
+    "--team-size": "teamSize",
+    "--issue-tracker": "issueTracker",
+  };
+  const flags = {
+    "--plan": "plan",
+    "--prune": "prune",
+    "--migrate-layout": "migrateLayout",
+    "--apply": "apply",
+    "--dry-run": "dryRun",
+    "--force": "force",
+    "--json": "json",
+    "--git-init": "gitInit",
+    "--help": "help",
+    "-h": "help",
+    "--version": "version",
+    "-v": "version",
+    "--include-example-docs": "includeExampleDocs",
+  };
+  while (args.length) {
+    const flag = args.shift();
+    if (values[flag]) {
+      ensure(args.length && !args[0].startsWith("-"), `${flag} 缺少值`);
+      options[values[flag]] = args.shift();
+    } else if (flag === "--no-example-docs") options.includeExampleDocs = false;
+    else if (flags[flag]) options[flags[flag]] = true;
+    else throw new Error(`未知参数: ${flag}`);
+  }
+  ensure(
+    ["init", "attach", "sync", "diff", "doctor", "recover", "update", "upgrade"].includes(options.command),
+    "未知命令",
+  );
+  ensure(
+    !(options.apply && (options.dryRun || options.plan)),
+    "--apply 与 --dry-run 不可同时使用",
+  );
+  ensure(
+    !options.gitInit || options.command === "init",
+    "--git-init 仅用于 init",
+  );
+  const accepted = {
+    init: ['projectName','businessDomain','teamSize','targetDir','issueTracker','gitInit','includeExampleDocs','dryRun'],
+    attach: ['projectName','businessDomain','teamSize','targetDir','issueTracker','includeExampleDocs','dryRun','apply','force','plan','migrateLayout'],
+    sync: ['targetDir','dryRun','apply','force','plan','prune','migrateLayout'],
+    diff: ['targetDir','dryRun'], doctor: ['targetDir'], recover: ['targetDir','dryRun','apply'],
+    update: ['dryRun','force'], upgrade: ['dryRun','force'],
+  };
+  if (!options.help && !options.version) for (const flag of argv.filter(x=>x.startsWith('-'))) {
+    const key = flag === '--no-example-docs' ? 'includeExampleDocs' : values[flag] || flags[flag];
+    ensure(['help','version','json'].includes(key) || accepted[options.command].includes(key), `${flag} 不适用于 ${options.command}`);
+  }
+  if (options.issueTracker === "local") options.issueTracker = "local-markdown";
+  ensure(
+    ["local-markdown", "github", "gitlab"].includes(options.issueTracker),
+    "issue-tracker 必须为 local-markdown、github 或 gitlab",
+  );
+  for (const k of ["projectName", "businessDomain", "teamSize"])
+    ensure(!/[\x00-\x1f\x7f]/.test(options[k]), `${k} 不允许控制字符`);
+  return options;
+}
+export async function main(packageRoot, argv = process.argv.slice(2)) {
+  packageRoot = path.resolve(packageRoot);
+  const wantsJson = argv.includes("--json");
+  try {
+    if (argv[0] === "migrate") {
+      const result = runMigration(packageRoot, argv.slice(1));
+      process.stdout.write(json(result));
+      return;
+    }
+    const opts = parse(argv);
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(packageRoot, "package.json")),
+    );
+    if (opts.help) {
+      const help = `${pkg.name} init|attach|sync|diff|doctor|recover|update|upgrade|migrate\nmigrate plan|apply|status|recover|rollback：固定计划、持久归档和最近升级回退。\n--target-dir <目录> --project-name <名称> --business-domain <领域> --team-size <规模>\n--issue-tracker <local-markdown|github|gitlab> --git-init --no-example-docs\nattach/sync 默认只预览，写入必须 --apply；冲突显式 --apply --force。\n--plan --prune（仅 sync） --migrate-layout（旧目录显式迁移） --dry-run --json --version\ndoctor/diff/recover 默认只读；recover --apply 恢复未完成事务。init 只接受空目录。\n`;
+      process.stdout.write(wantsJson ? json({schemaVersion:1,command:"help",status:"ok",help}) : help);
+      return;
+    }
+    if (opts.version) {
+      process.stdout.write(wantsJson ? json({schemaVersion:1,command:"version",status:"ok",packageName:pkg.name,cliVersion:pkg.version}) : pkg.version + "\n");
+      return;
+    }
+    if (["update", "upgrade"].includes(opts.command)) {
+      const result = update(packageRoot, pkg, opts);
+      process.stdout.write(
+        wantsJson
+          ? json(result)
+          : `${result.status}: ${result.currentVersion} → ${result.latestVersion}\n${result.advice}\n`,
+      );
+      return;
+    }
+    if (pkg.name === 'create-yss-harness-design' && opts.command === 'init') {
+      const required = ['projectName','businessDomain','targetDir'];
+      const missing = required.filter(k=>!opts[k] || opts[k]==='未指定');
+      if (missing.length && process.stdin.isTTY && !wantsJson) {
+        const rl=createInterface({input:process.stdin,output:process.stderr});
+        try { for(const key of missing) opts[key]=(await rl.question(({projectName:'项目名称',businessDomain:'业务领域',targetDir:'目标目录'})[key]+': ')).trim(); }
+        finally { rl.close(); }
+      }
+      ensure(required.every(k=>opts[k] && opts[k]!=='未指定'),'init 需要 --project-name、--business-domain 和 --target-dir');
+      ensure(!required.some(k=>/[\x00-\x1f\x7f]/.test(opts[k])),'初始化参数含控制字符');
+    }
+    const bundle = loadBundle(packageRoot),
+      target = targetPath(opts.targetDir || process.cwd());
+    ensure(
+      target !== packageRoot &&
+        !target.startsWith(packageRoot + path.sep) &&
+        !packageRoot.startsWith(target + path.sep),
+      "目标不得覆盖 CLI 安装目录",
+    );
+    let result;
+    if (opts.command === 'doctor') result = doctor(bundle,target);
+    else if (opts.command === 'recover') {
+      ensure(stat(target)?.isDirectory(),'恢复目标不存在','PATH');
+      const state=inspectState(target,bundle.family);
+      if (!state.pending.length) { identity(target,bundle,'recover');result={schemaVersion:1,command:'recover',status:'preview',target,transactions:[],message:'没有未完成事务'}; }
+      else {
+        const validate=()=>recoveryIdentity(target,bundle,state);
+        result=opts.apply ? recover(target,bundle.family,state,validate) : recoveryPreview(target,bundle.family,state,validate);
+        result.command='recover';
+      }
+    } else result = execute(bundle, target, opts);
+    if (result.status === 'error') process.exitCode=1;
+    process.stdout.write(wantsJson ? json(result) : formatPlan(result));
+  } catch (error) {
+    if (wantsJson)
+      process.stdout.write(
+        json({
+          schemaVersion: 1,
+          command: argv[0]?.startsWith("-") ? "init" : argv[0] || "init",
+          ...error.result,
+          status: "error",
+          code: error.code || "INVALID",
+          message: error.message,
+        }),
+      );
+    if (error.result && !wantsJson)
+      process.stdout.write(formatPlan(error.result));
+    process.stderr.write(error.message + "\n");
+    process.exitCode = 1;
+  }
+}
+
+function formatPlan(result) {
+  const lines = [
+    `${result.status}: ${result.target}`,
+    `CLI ${result.cliVersion || "-"} / core ${result.coreVersion || "-"} / template ${result.templateCommit || "-"}`,
+  ];
+  for (const change of result.changes || [])
+    lines.push(`${change.action.padEnd(10)} ${change.path}`);
+  for (const check of result.checks || []) lines.push(`[${check.status}] ${check.name}: ${check.message || ''}`);
+  for (const transaction of result.transactions || []) lines.push(`恢复事务 ${transaction.id || transaction}: ${transaction.backupPath || ''}`);
+  if (result.advice) lines.push(result.advice);
+  if (result.backupPath) lines.push(`备份和恢复清单：${result.backupPath}`);
+  if (result.message) lines.push(result.message);
+  return lines.join("\n") + "\n";
+}