skill-family-engineering-kit 0.1.0

package/src/check.mjs

@@ -0,0 +1,415 @@
+import { CONTRACTS_VERSION, findSchemaByObject } from "skill-family-contracts";
+import {
+  computeResourceClosure,
+  digestBytes,
+  readFileContained,
+  validateContractDocument,
+} from "skill-family-harness-node";
+import { invalidParamsError, KIT_ERROR_KINDS } from "./errors.mjs";
+import { probeGitState } from "./gitprobe.mjs";
+import {
+  KIT_TOOL_NAME,
+  KIT_VERSION,
+  MANAGED_LOCK_PATH,
+  PROJECT_MANIFEST_PATH,
+} from "./skeleton.mjs";
+import {
+  listTargetEntries,
+  loadTargetFacts,
+  matchAnyGlob,
+  normalizeRelPath,
+  readOptionalFile,
+  readOptionalJson,
+  resolveTargetRoot,
+} from "./workspace.mjs";
+import {
+  checkIdentityDrift,
+  loadIdentityRecord,
+  validateIdentityAgainstProfile,
+} from "./identity-check.mjs";
+
+/**
+ * check — diagnosis only, never auto-fix.
+ *
+ * Seven diagnosis classes, exactly as the FND-030 and FND-045 hand-offs bound them:
+ *   contracts — discovered contract documents against registered schemas;
+ *   drift     — managed-file-lock entries vs actual bytes on disk;
+ *   closure   — harness resource closure over declared inputs/outputs;
+ *   version   — declared contracts version vs the frozen contracts version;
+ *   docs      — documentation facts (README presence, identity consistency);
+ *   git       — read-only Git pre-state (never a git write);
+ *   identity  — licensing and identity drift checks (FND-045).
+ *
+ * This module contains no write call of any kind. Mutation-looking flags
+ * (--fix, --apply, ...) are refused at intake by the CLI. Findings carry
+ * stable kinds and registered SFC codes; the exit code is the stable
+ * signal (0 clean, 1 findings, 2 rejected/usage/mechanism error).
+ */
+
+const CHECK_CLASSES = Object.freeze(["contracts", "drift", "closure", "version", "docs", "git", "identity"]);
+
+export { CHECK_CLASSES };
+
+function finding(checkClass, kind, code, message, extra) {
+  return { class: checkClass, kind, code, message, ...(extra ?? {}) };
+}
+
+async function checkContracts(rootAbs, docs, findings) {
+  const targets = [
+    ["project-manifest", PROJECT_MANIFEST_PATH],
+    ["managed-file-lock", MANAGED_LOCK_PATH],
+  ];
+  let present = 0;
+  for (const [objectName, relPath] of targets) {
+    const loaded = await readOptionalJson(rootAbs, relPath);
+    if (loaded.reason === "missing") continue;
+    present += 1;
+    docs[relPath] = loaded.ok ? loaded.value : null;
+    if (!loaded.ok) {
+      findings.push(
+        finding(
+          "contracts",
+          KIT_ERROR_KINDS.CONTRACT_PARSE_FAILED,
+          "SFC1001",
+          `${relPath} is not valid JSON`,
+          { path: relPath },
+        ),
+      );
+      continue;
+    }
+    const registration = findSchemaByObject(objectName);
+    const outcome = validateContractDocument(loaded.value, { schemaId: registration.$id });
+    if (!outcome.valid) {
+      findings.push(
+        finding(
+          "contracts",
+          "schema-validation-failed",
+          outcome.errorCode,
+          `${relPath} fails the registered ${objectName} schema: ${outcome.errors
+            .slice(0, 3)
+            .map((entry) => `${entry.instancePath || "/"} ${entry.message}`)
+            .join("; ")}`,
+          { path: relPath, schemaId: registration.$id },
+        ),
+      );
+    }
+  }
+  if (present === 0) {
+    findings.push(
+      finding(
+        "contracts",
+        KIT_ERROR_KINDS.CONTRACTS_MISSING,
+        "SFC2004",
+        "no contract documents found (expected skill-family.project-manifest.json and/or skill-family.managed-file-lock.json)",
+      ),
+    );
+  }
+}
+
+/** Contained read of a target-declared path: missing => null, escape => finding. */
+async function readManagedCandidate(rootAbs, rel, findings) {
+  try {
+    return await readFileContained(rootAbs, rel, { encoding: "utf8" });
+  } catch (cause) {
+    const kind = cause && cause.details ? cause.details.kind : null;
+    if (kind === "missing-resource") return null;
+    // Escaping lock entries are target-supplied data: report them, never follow them.
+    findings.push(
+      finding(
+        "drift",
+        kind ?? "uncontained-lock-path",
+        "SFC2004",
+        `lock entry path is not safely readable inside the target: ${rel} (kind: ${kind ?? "unknown"})`,
+        { path: rel },
+      ),
+    );
+    return { escaped: true };
+  }
+}
+
+async function checkDrift(rootAbs, findings) {
+  const loaded = await readOptionalJson(rootAbs, MANAGED_LOCK_PATH);
+  if (!loaded.ok) return null; // no lock => nothing to drift against
+  const lock = loaded.value;
+  const entries = Array.isArray(lock?.entries) ? lock.entries : [];
+  for (const entry of entries) {
+    const rel = typeof entry?.path === "string" ? normalizeRelPath(entry.path) : null;
+    const declaredHash = entry?.hash?.value;
+    if (!rel || typeof declaredHash !== "string" || !/^[0-9a-f]{64}$/.test(declaredHash)) {
+      continue; // malformed entries are reported by the contracts class
+    }
+    const text = await readManagedCandidate(rootAbs, rel, findings);
+    if (text === null) {
+      findings.push(
+        finding(
+          "drift",
+          KIT_ERROR_KINDS.MANAGED_FILE_MISSING,
+          "SFC2004",
+          `managed file declared in the lock does not exist: ${rel}`,
+          { path: rel },
+        ),
+      );
+      continue;
+    }
+    if (typeof text !== "string") continue; // escaping path already reported
+    const actual = digestBytes(Buffer.from(text, "utf8"));
+    if (actual !== declaredHash) {
+      findings.push(
+        finding(
+          "drift",
+          KIT_ERROR_KINDS.MANAGED_FILE_DRIFT,
+          "SFC2004",
+          `managed file drifted from its locked hash: ${rel} (lock=${declaredHash.slice(0, 12)}… actual=${actual.slice(0, 12)}…)`,
+          { path: rel },
+        ),
+      );
+    }
+  }
+  return lock;
+}
+
+async function checkClosure(rootAbs, lock, findings) {
+  if (!lock) return { digest: null, note: "no managed-file-lock present; closure check skipped" };
+  const resources = [
+    { path: MANAGED_LOCK_PATH, role: "input" },
+    ...(Array.isArray(lock.entries) ? lock.entries : [])
+      .filter((entry) => typeof entry?.path === "string")
+      .map((entry) => ({ path: normalizeRelPath(entry.path), role: "output" })),
+  ];
+  try {
+    const closure = await computeResourceClosure({ root: rootAbs, resources });
+    const missingOutputs = closure.resources.filter(
+      (resource) => resource.role === "output" && !resource.exists,
+    );
+    for (const missing of missingOutputs) {
+      findings.push(
+        finding(
+          "closure",
+          KIT_ERROR_KINDS.CLOSURE_INPUT_MISSING,
+          "SFC2004",
+          `closure output resource does not exist: ${missing.path}`,
+          { path: missing.path },
+        ),
+      );
+    }
+    return { digest: closure.digest, resourceCount: closure.resources.length };
+  } catch (cause) {
+    const kind =
+      cause && cause.details && cause.details.kind === "missing-resource"
+        ? KIT_ERROR_KINDS.CLOSURE_INPUT_MISSING
+        : "closure-failed";
+    findings.push(
+      finding(
+        "closure",
+        kind,
+        "SFC2004",
+        `resource closure could not be computed: ${cause && cause.message ? cause.message : "unknown"}`,
+      ),
+    );
+    return { digest: null };
+  }
+}
+
+async function checkVersion(docs, findings) {
+  const manifest = docs[PROJECT_MANIFEST_PATH];
+  const declared = manifest?.contracts?.version;
+  if (typeof declared !== "string") return { contractsVersion: null };
+  if (declared !== CONTRACTS_VERSION) {
+    findings.push(
+      finding(
+        "version",
+        KIT_ERROR_KINDS.CONTRACTS_VERSION_MISMATCH,
+        "SFC2004",
+        `project manifest declares contracts version ${declared}; this kit validates against ${CONTRACTS_VERSION}`,
+        { declared, expected: CONTRACTS_VERSION },
+      ),
+    );
+  }
+  return { contractsVersion: declared };
+}
+
+async function checkDocs(rootAbs, docs, findings) {
+  const readme = await readOptionalFile(rootAbs, "README.md");
+  if (readme === null || readme.trim().length === 0) {
+    findings.push(
+      finding(
+        "docs",
+        KIT_ERROR_KINDS.README_MISSING,
+        "SFC2004",
+        "README.md is missing or empty (documentation fact)",
+        { path: "README.md" },
+      ),
+    );
+  }
+  const packageJson = await readOptionalJson(rootAbs, "package.json");
+  const manifest = docs[PROJECT_MANIFEST_PATH];
+  if (packageJson.ok && manifest && typeof manifest?.project === "object") {
+    const packageName = packageJson.value?.name;
+    if (typeof packageName === "string") {
+      if (manifest.project.id !== packageName) {
+        findings.push(
+          finding(
+            "docs",
+            KIT_ERROR_KINDS.IDENTITY_MISMATCH,
+            "SFC2004",
+            `project manifest id "${manifest.project.id}" does not match package.json name "${packageName}"`,
+            { manifestId: manifest.project.id, packageName },
+          ),
+        );
+      }
+    }
+  }
+}
+
+async function checkGit(rootAbs, findings, allowGitSpawn) {
+  const git = await probeGitState(rootAbs, { allowSpawn: allowGitSpawn });
+  if (git.repository && git.headCommit === false) {
+    findings.push(
+      finding(
+        "git",
+        KIT_ERROR_KINDS.GIT_NO_COMMITS,
+        "SFC2004",
+        "the target is a git repository without any commit; history does not protect anything yet",
+      ),
+    );
+  }
+  if (git.repository && git.cleanState === false) {
+    findings.push(
+      finding(
+        "git",
+        KIT_ERROR_KINDS.GIT_DIRTY,
+        "SFC2004",
+        "the target has uncommitted changes; settle them before running write commands elsewhere",
+      ),
+    );
+  }
+  return git;
+}
+
+async function checkIdentity(rootAbs, docs, findings, profilesRoot) {
+  // Load identity record
+  const identityRecord = await loadIdentityRecord(rootAbs);
+
+  if (!identityRecord) {
+    findings.push(
+      finding(
+        "identity",
+        KIT_ERROR_KINDS.IDENTITY_RECORD_MISSING,
+        "SFC2004",
+        "identity record not found; cannot perform identity drift check",
+        { path: "skill-family.identity-record.json" },
+      ),
+    );
+    return null;
+  }
+
+  // Store for later use
+  docs["skill-family.identity-record.json"] = identityRecord;
+
+  // Validate against profile
+  if (profilesRoot) {
+    const profileValidation = await validateIdentityAgainstProfile(identityRecord, profilesRoot);
+    for (const f of profileValidation.findings) {
+      findings.push(
+        finding(
+          "identity",
+          f.kind,
+          f.code,
+          f.message,
+          { source: f.source, ...f },
+        ),
+      );
+    }
+  }
+
+  // Check identity drift
+  const driftReport = await checkIdentityDrift({ rootAbs, identityRecord });
+  for (const f of driftReport.findings) {
+    findings.push(
+      finding(
+        "identity",
+        f.kind,
+        f.code,
+        f.message,
+        { source: f.source, ...f },
+      ),
+    );
+  }
+
+  return identityRecord;
+}
+
+/**
+ * Runs all check classes over one target.
+ * Options: { root, allowGitSpawn, profilesRoot }.
+ * Returns the report document. Never writes anywhere; throws KitError only
+ * for unusable inputs (an unreadable target).
+ */
+export async function runChecks({ root, allowGitSpawn = true, only, profilesRoot } = {}) {
+  if (only !== undefined && !CHECK_CLASSES.includes(only)) {
+    throw invalidParamsError(`--only must be one of: ${CHECK_CLASSES.join(", ")}`, { value: only });
+  }
+  const rootAbs = await resolveTargetRoot(root ?? ".");
+  const findings = [];
+  const docs = {};
+
+  const classes = only === undefined ? CHECK_CLASSES : CHECK_CLASSES.filter((name) => name === only);
+  let closureInfo = { digest: null, note: "skipped" };
+  let git = null;
+  let versionInfo = { contractsVersion: null };
+  let identityRecord = null;
+
+  if (classes.includes("contracts")) await checkContracts(rootAbs, docs, findings);
+  if (classes.includes("drift")) {
+    const lock = await checkDrift(rootAbs, findings);
+    if (classes.includes("closure")) closureInfo = await checkClosure(rootAbs, lock, findings);
+  }
+  if (classes.includes("version")) versionInfo = await checkVersion(docs, findings);
+  if (classes.includes("docs")) await checkDocs(rootAbs, docs, findings);
+  if (classes.includes("git")) git = await checkGit(rootAbs, findings, allowGitSpawn);
+  if (classes.includes("identity")) identityRecord = await checkIdentity(rootAbs, docs, findings, profilesRoot);
+
+  const byClass = {};
+  for (const item of findings) {
+    byClass[item.class] = (byClass[item.class] ?? 0) + 1;
+  }
+
+  // The handwritten-managed classification fact is reported as data too, so
+  // consumers can see which entries would be write-protected.
+  const entries = await listTargetEntries(rootAbs);
+  const managedDeclarations = [];
+  const facts = await loadTargetFacts(rootAbs);
+  for (const rel of [...facts.managedSet].sort()) {
+    managedDeclarations.push({
+      path: rel,
+      handwrittenAlso: matchAnyGlob(facts.handwrittenPatterns, rel),
+    });
+  }
+
+  return {
+    kind: "skill-family.check-report",
+    schemaVersion: 1,
+    generatedBy: { tool: KIT_TOOL_NAME, version: KIT_VERSION },
+    target: { root: ".", entryCount: entries.length },
+    ok: findings.length === 0,
+    classes: CHECK_CLASSES.map((name) => ({
+      name,
+      ran: classes.includes(name),
+      findings: byClass[name] ?? 0,
+    })),
+    findings,
+    data: {
+      closure: closureInfo,
+      git,
+      version: versionInfo,
+      managedDeclarations,
+      identity: identityRecord ? {
+        record: identityRecord,
+        licensing: identityRecord.licensing,
+        authors: identityRecord.authors,
+      } : null,
+    },
+    policy:
+      "check is diagnosis only: it never writes, never fixes, and never calls git write commands; findings must be resolved by a human or an authorized generator",
+  };
+}

package/src/cli.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { bundledProfilesRoot } from "./licensing.mjs";
+import {
+  COMMAND_SIDE_EFFECTS,
+  KIT_EXIT_CODES,
+  REFUSED_MUTATION_FLAGS,
+  runCommand,
+  TOP_LEVEL_COMMANDS,
+  unknownCommandError,
+  invalidParamsError,
+  mutationModeError,
+} from "./index.mjs";
+
+/**
+ * skill-family-engineering-kit CLI.
+ *
+ * Exactly four top-level commands exist; there is no fifth. Exit codes are
+ * stable: 0 = ok/clean, 1 = findings (check), 2 = rejected/usage/mechanism
+ * error. Every refusal prints its registered SFC code and stable kind.
+ */
+
+const HELP_TEXT = `skill-family-engineering-kit —— 构建期工程工具包（恰好四个顶层命令）
+
+用法: node src/cli.mjs <command> [options]
+
+命令（四且仅四）:
+  scaffold     在空目录生成 Skill Family 项目骨架。
+               副作用: 只向空目标目录写入骨架文件（原子写、路径收容）；
+               非空或冲突目标被拒绝且不被触碰。
+  adopt-plan   严格只读地规划存量仓采用与迁移闭环。
+               副作用: 无 —— 不写任何文件（含临时文件），不运行 git 写命令，
+               不改名、不触碰远端；输出精确写集、冲突、风险、旧实现退出清单、
+               临时例外校验与迁移完成判定（JSON 到 stdout）。
+  projection   投影受管生成物。
+               副作用: 只写 manifest 授权且被目标声明为受管的路径；
+               未授权路径、手写文件与越界路径一律拒绝（拒绝时零写入）。
+  check        契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。
+               副作用: 无 —— 只诊断、绝不自动修复，git 仅只读探测。
+
+全局选项:
+  --root <dir>  目标工作区根目录（默认当前目录）
+  --help, -h    显示本帮助或单个命令的帮助
+
+退出码: 0 成功/无发现；1 check 有发现；2 拒绝/用法/机制错误。
+错误码复用 contracts 的 SFC* 体系（SFC2002/SFC2003/SFC2004 + 稳定 details.kind）。
+禁止项: git init/commit/push/tag、发布、删除、远端写入；不存在第五个顶层命令。
+`;
+
+function commandHelp(command) {
+  const sideEffect = COMMAND_SIDE_EFFECTS[command];
+  const details = {
+    scaffold: [
+      "选项:",
+      "  --root <dir>          目标目录（必须为空，或其父目录存在的不存在路径）",
+      "  --project-id <id>     kebab-case 项目 id（默认取目录名）",
+      "  --project-name <name> 人类可读项目名（默认同 id）",
+      "  --profile <id>        Profile id（默认 generic）",
+      "  --licensing-profile <id> 许可证 Profile id（默认 registry 第一个变体）",
+      "  --licensing-variant <id> 多变体 Profile 的必选变体 id",
+      "  --profiles-root <dir> 许可证 Profile 根目录",
+    ],
+    "adopt-plan": [
+      "选项:",
+      "  --root <dir>          目标工作区（默认当前目录）",
+      "  --project-id <id>     计划采用的项目 id（默认取目录名）",
+      "  --profile <id>        目标 Profile id（默认 generic）",
+      "  --licensing-profile <id> 许可证 Profile id（默认 registry 第一个变体）",
+      "  --licensing-variant <id> 多变体 Profile 的必选变体 id",
+      "  --profiles-root <dir> 许可证 Profile 根目录",
+      "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
+      "",
+      "  迁移闭环（FND-070）: 只读读取目标仓 skill-family.migration.json",
+      "  （旧实现退出清单 + 临时例外）；例外缺 owner/reason/deadline/",
+      "  migrationTarget 任一字段即计为冲突；到期例外不自动续期；",
+      "  旧实现未全部退出时完成判定恒为 false（双轨接入不算完成）。",
+    ],
+    projection: [
+      "选项:",
+      "  --root <dir>          目标工作区（默认当前目录）",
+      "  --manifest <relpath>  投影 manifest 相对路径（默认 skill-family.projection.json）",
+    ],
+    check: [
+      "选项:",
+      "  --root <dir>          目标工作区（默认当前目录）",
+      "  --only <class>        只运行一个诊断类: contracts|drift|closure|version|docs|git|identity",
+      "  --profiles-root <dir> 许可证 Profile 根目录",
+      "  --no-git-spawn        禁用只读 git status 探测，仅用文件系统事实",
+    ],
+  };
+  return [
+    `${command} —— ${sideEffect.summary}`,
+    `副作用: ${sideEffect.sideEffect}`,
+    "",
+    ...details[command],
+    "",
+    `退出码: ${sideEffect.exitCodes}`,
+  ].join("\n");
+}
+
+function printError(error) {
+  const code = error && error.code ? error.code : "SFC2004";
+  const kind = error && error.details && error.details.kind ? ` (${error.details.kind})` : "";
+  process.stderr.write(`[kit] ${code}${kind}: ${error && error.message ? error.message : String(error)}\n`);
+}
+
+function parseOptions(argv, spec) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (REFUSED_MUTATION_FLAGS.includes(arg)) {
+      throw mutationModeError(arg, spec.command);
+    }
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    const flagSpec = spec.flags[arg];
+    if (!flagSpec) {
+      throw invalidParamsError(`unknown option for '${spec.command}': ${arg}`, { flag: arg });
+    }
+    if (flagSpec.value) {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw invalidParamsError(`option ${arg} requires a value`, { flag: arg });
+      }
+      options[flagSpec.key] = value;
+    } else {
+      options[flagSpec.key] = true;
+    }
+  }
+  return options;
+}
+
+const COMMAND_SPECS = {
+  scaffold: {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--project-id": { key: "projectId", value: true },
+      "--project-name": { key: "projectName", value: true },
+      "--profile": { key: "profileId", value: true },
+      "--licensing-profile": { key: "licensingProfile", value: true },
+      "--licensing-variant": { key: "licensingVariant", value: true },
+      "--profiles-root": { key: "profilesRoot", value: true },
+    },
+  },
+  "adopt-plan": {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--project-id": { key: "projectId", value: true },
+      "--project-name": { key: "projectName", value: true },
+      "--profile": { key: "profileId", value: true },
+      "--licensing-profile": { key: "licensingProfile", value: true },
+      "--licensing-variant": { key: "licensingVariant", value: true },
+      "--profiles-root": { key: "profilesRoot", value: true },
+      "--no-git-spawn": { key: "noGitSpawn", value: false },
+    },
+  },
+  projection: {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--manifest": { key: "manifest", value: true },
+    },
+  },
+  check: {
+    flags: {
+      "--root": { key: "root", value: true },
+      "--only": { key: "only", value: true },
+      "--profiles-root": { key: "profilesRoot", value: true },
+      "--no-git-spawn": { key: "noGitSpawn", value: false },
+    },
+  },
+};
+
+export async function cliMain(argv) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    process.stdout.write(HELP_TEXT);
+    return KIT_EXIT_CODES.ok;
+  }
+  const command = argv[0];
+  if (!TOP_LEVEL_COMMANDS.includes(command)) {
+    printError(unknownCommandError(command));
+    return KIT_EXIT_CODES.rejected;
+  }
+
+  try {
+    const options = parseOptions(argv.slice(1), { command, flags: COMMAND_SPECS[command].flags });
+    if (options.help) {
+      process.stdout.write(`${commandHelp(command)}\n`);
+      return KIT_EXIT_CODES.ok;
+    }
+    const { exitCode, output } = await runCommand(command, {
+      root: options.root ?? ".",
+      projectId: options.projectId,
+      projectName: options.projectName,
+      profileId: options.profileId,
+      licensingProfile: options.licensingProfile,
+      licensingVariant: options.licensingVariant,
+      profilesRoot: options.profilesRoot ?? bundledProfilesRoot(),
+      manifest: options.manifest,
+      only: options.only,
+      allowGitSpawn: !options.noGitSpawn,
+    });
+    if (output !== undefined) {
+      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    }
+    return exitCode;
+  } catch (error) {
+    printError(error);
+    return KIT_EXIT_CODES.rejected;
+  }
+}
+
+// Direct-execution detection must survive symlinked package bins (pnpm
+// .bin shims): compare real paths, not the raw argv[1] URL.
+function isDirectExecution() {
+  if (process.argv[1] === undefined) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isDirectExecution()) {
+  cliMain(process.argv.slice(2)).then((code) => {
+    process.exit(code);
+  });
+}