create-yss-spec 2.1.10 → 2.1.13

package/template/.hermes/skills/llm-wiki/scripts/extract.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const EXTRACT_KINDS = Object.freeze(["skill-names", "heading-list", "prose-note"]);
+
+function namesOf(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  return Object.keys(value).sort((a, b) => a.localeCompare(b));
+}
+
+export function extractSkillNames(lock) {
+  if (!lock || typeof lock !== "object" || Array.isArray(lock)) {
+    throw new TypeError("skill-names input must be a lock object");
+  }
+  const shared = namesOf(lock.skills?.shared);
+  const platform = lock.skills?.platform && typeof lock.skills.platform === "object" ? lock.skills.platform : {};
+  const lines = ["# skills-lock names", "", "Derived names only. Do not copy hashes, paths, or the lock file.", "", "## shared", ""];
+  for (const name of shared) lines.push(`- \`${name}\``);
+  const roots = namesOf(platform);
+  if (roots.length) {
+    lines.push("", "## platform", "");
+    for (const root of roots) {
+      lines.push(`### \`${root}\``, "");
+      for (const name of namesOf(platform[root])) lines.push(`- \`${name}\``);
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const kind = argv[0];
+  let input;
+  let output;
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === "--in") input = argv[++i];
+    else if (argv[i] === "--out") output = argv[++i];
+  }
+  if (kind !== "skill-names" || !input || !output) {
+    throw new Error("usage: extract.mjs skill-names --in <lock.json> --out <raw.md>");
+  }
+  const text = extractSkillNames(JSON.parse(await readFile(input, "utf8")));
+  await mkdir(path.dirname(output), { recursive: true });
+  await writeFile(output, text, "utf8");
+  process.stdout.write(`${output}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/template/.hermes/skills/llm-wiki/scripts/extract.test.mjs

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EXTRACT_KINDS, extractSkillNames } from "./extract.mjs";
+
+test("skill-names lists shared and platform keys, sorted, without hashes", () => {
+  const text = extractSkillNames({
+    skills: {
+      shared: {
+        zeta: { effectiveHash: "aaa", skillPath: "hidden" },
+        alpha: { effectiveHash: "bbb" },
+      },
+      platform: {
+        ".codex/skills": {
+          "product-design": { effectiveHash: "ccc" },
+          "data-analytics": { effectiveHash: "ddd" },
+        },
+      },
+    },
+  });
+  assert.match(text, /## shared/);
+  assert.match(text, /## platform/);
+  assert.ok(text.indexOf("`alpha`") < text.indexOf("`zeta`"));
+  assert.ok(text.indexOf("`data-analytics`") < text.indexOf("`product-design`"));
+  assert.doesNotMatch(text, /aaa|bbb|ccc|ddd|skillPath|effectiveHash/);
+  assert.doesNotMatch(text, /"version"|canonicalRoot/);
+});
+
+test("skill-names rejects a whole-file dump of a non-object", () => {
+  assert.throws(() => extractSkillNames("not-json-object"), /lock object/);
+});
+
+test("declared extract kinds stay the documented set", () => {
+  assert.deepEqual([...EXTRACT_KINDS], ["skill-names", "heading-list", "prose-note"]);
+});

package/template/.hermes/skills/llm-wiki/scripts/inventory.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { readFile, writeFile, access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MANIFEST = ".wiki-manifest.json";
+
+export function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+export function resolveWikiRoot(wikiArg, cwd = process.cwd()) {
+  if (!wikiArg) throw new Error("missing --wiki <wiki-root>");
+  return path.resolve(cwd, wikiArg);
+}
+
+export function manifestPath(wikiRoot) {
+  return path.join(wikiRoot, MANIFEST);
+}
+
+export async function loadManifest(wikiRoot) {
+  const file = manifestPath(wikiRoot);
+  const raw = await readFile(file, "utf8");
+  return JSON.parse(raw);
+}
+
+export async function saveManifest(wikiRoot, manifest) {
+  const file = manifestPath(wikiRoot);
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return file;
+}
+
+export async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function gitCommit(repoRoot) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export async function hashSources({ wikiRoot, repoRoot, now = new Date().toISOString() }) {
+  const manifest = await loadManifest(wikiRoot);
+  const missing = [];
+  for (const source of manifest.sources || []) {
+    if (!source.livePath) {
+      source.sha256 = "";
+      continue;
+    }
+    const live = path.resolve(repoRoot, source.livePath);
+    if (!(await exists(live))) {
+      missing.push(source.id);
+      source.sha256 = "";
+      continue;
+    }
+    source.sha256 = sha256(await readFile(live));
+  }
+  manifest.compiledAt = now;
+  manifest.gitCommit = gitCommit(repoRoot);
+  await saveManifest(wikiRoot, manifest);
+  return { manifest, missing };
+}
+
+export function normalizeLivePath(livePath) {
+  return String(livePath || "").replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+
+export function unmappedCandidates(sources, candidates = []) {
+  const mapped = new Set(
+    (sources || []).map((source) => normalizeLivePath(source.livePath)).filter(Boolean),
+  );
+  const unmapped = [];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const livePath = normalizeLivePath(candidate);
+    if (!livePath || mapped.has(livePath) || seen.has(livePath)) continue;
+    seen.add(livePath);
+    unmapped.push(livePath);
+  }
+  return unmapped;
+}
+
+export async function drift({ wikiRoot, repoRoot, candidates = [] }) {
+  const manifest = await loadManifest(wikiRoot);
+  const changed = [];
+  const missing = [];
+  const unchanged = [];
+  for (const source of manifest.sources || []) {
+    if (!source.livePath) {
+      unchanged.push(source.id);
+      continue;
+    }
+    const live = path.resolve(repoRoot, source.livePath);
+    if (!(await exists(live))) {
+      missing.push(source.id);
+      continue;
+    }
+    const current = sha256(await readFile(live));
+    if (current !== source.sha256) changed.push(source.id);
+    else unchanged.push(source.id);
+  }
+  const hit = new Set([...changed, ...missing]);
+  const articles = [];
+  const humanOwned = [];
+  for (const article of manifest.articles || []) {
+    const impacted = (article.sourceIds || []).some((id) => hit.has(id));
+    if (!impacted) continue;
+    articles.push(article.id);
+    if (article.humanOwned === true) humanOwned.push(article.id);
+  }
+  return {
+    changed,
+    missing,
+    unchanged,
+    articles,
+    unmapped: unmappedCandidates(manifest.sources, candidates),
+    humanOwned,
+  };
+}
+
+function parseArgs(argv) {
+  const args = { command: argv[0], wiki: null, repo: process.cwd(), candidates: [] };
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === "--wiki") args.wiki = argv[++i];
+    else if (argv[i] === "--repo") args.repo = argv[++i];
+    else if (argv[i] === "--candidate") args.candidates.push(argv[++i]);
+    else if (!args.wiki && !argv[i].startsWith("-")) args.wiki = argv[i];
+  }
+  return args;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.command || !["hash", "drift", "status"].includes(args.command)) {
+    throw new Error(
+      "usage: inventory.mjs hash|drift|status --wiki <wiki-root> [--repo <repo-root>] [--candidate <livePath>]",
+    );
+  }
+  const wikiRoot = resolveWikiRoot(args.wiki, args.repo);
+  const repoRoot = path.resolve(args.repo);
+  if (!(await exists(manifestPath(wikiRoot)))) {
+    throw new Error(`manifest not found: ${manifestPath(wikiRoot)}`);
+  }
+  if (args.command === "hash") {
+    const result = await hashSources({ wikiRoot, repoRoot });
+    process.stdout.write(
+      `${JSON.stringify({ hashed: (result.manifest.sources || []).length, missing: result.missing }, null, 2)}\n`,
+    );
+    if (result.missing.length) process.exitCode = 1;
+    return;
+  }
+  const report = await drift({ wikiRoot, repoRoot, candidates: args.candidates });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/template/.hermes/skills/llm-wiki/scripts/inventory.test.mjs

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { drift, hashSources, sha256, unmappedCandidates } from "./inventory.mjs";
+
+const inventoryCli = fileURLToPath(new URL("./inventory.mjs", import.meta.url));
+
+async function seed() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-inv-"));
+  const wiki = path.join(repo, "wiki-root");
+  await mkdir(path.join(wiki, "raw"), { recursive: true });
+  const liveRel = "docs/api.md";
+  const live = path.join(repo, liveRel);
+  await mkdir(path.dirname(live), { recursive: true });
+  await writeFile(live, "v1\n", "utf8");
+  await writeFile(
+    path.join(wiki, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      wikiRoot: "wiki-root",
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: liveRel,
+          rawPath: "raw/api.md",
+          sha256: "",
+          role: "copy",
+        },
+      ],
+      articles: [
+        { id: "API契约", file: "wiki/API契约.md", sourceIds: ["api.md"], humanOwned: false },
+        { id: "人工页", file: "wiki/人工页.md", sourceIds: ["api.md"], humanOwned: true },
+      ],
+    }),
+    "utf8",
+  );
+  return { repo, wiki, live, liveRel };
+}
+
+test("hash-sources fills sha256; drift is empty until live file changes", async () => {
+  const { repo, wiki, live } = await seed();
+  const hashed = await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  assert.equal(hashed.missing.length, 0);
+  assert.equal(hashed.manifest.sources[0].sha256, sha256(Buffer.from("v1\n")));
+  const clean = await drift({ wikiRoot: wiki, repoRoot: repo });
+  assert.deepEqual(clean.changed, []);
+  assert.deepEqual(clean.articles, []);
+  await writeFile(live, "v2\n", "utf8");
+  const dirty = await drift({ wikiRoot: wiki, repoRoot: repo });
+  assert.deepEqual(dirty.changed, ["api.md"]);
+  assert.deepEqual(dirty.articles, ["API契约", "人工页"]);
+  assert.deepEqual(dirty.humanOwned, ["人工页"]);
+  assert.deepEqual(dirty.unmapped, []);
+});
+
+test("unmapped candidates are listed without scanning the tree", () => {
+  const sources = [{ livePath: "docs/api.md" }];
+  assert.deepEqual(unmappedCandidates(sources, ["docs/api.md", "docs/new.md", "./docs/new.md"]), [
+    "docs/new.md",
+  ]);
+});
+
+test("drift CLI exits 0 when sources changed and prints JSON", async () => {
+  const { repo, wiki, live } = await seed();
+  await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  await writeFile(live, "v2\n", "utf8");
+  const ran = spawnSync(process.execPath, [inventoryCli, "drift", "--wiki", wiki, "--repo", repo], {
+    encoding: "utf8",
+  });
+  assert.equal(ran.status, 0, ran.stderr);
+  const report = JSON.parse(ran.stdout);
+  assert.deepEqual(report.changed, ["api.md"]);
+  assert.deepEqual(report.articles, ["API契约", "人工页"]);
+  assert.deepEqual(report.humanOwned, ["人工页"]);
+  assert.deepEqual(report.unmapped, []);
+});
+
+test("status CLI exits 0 and lists unmapped candidates", async () => {
+  const { repo, wiki, live } = await seed();
+  await hashSources({ wikiRoot: wiki, repoRoot: repo, now: "2026-01-01T00:00:00Z" });
+  await writeFile(live, "v2\n", "utf8");
+  const ran = spawnSync(
+    process.execPath,
+    [inventoryCli, "status", "--wiki", wiki, "--repo", repo, "--candidate", "docs/extra.md"],
+    { encoding: "utf8" },
+  );
+  assert.equal(ran.status, 0, ran.stderr);
+  const report = JSON.parse(ran.stdout);
+  assert.deepEqual(report.changed, ["api.md"]);
+  assert.deepEqual(report.unmapped, ["docs/extra.md"]);
+  assert.deepEqual(report.humanOwned, ["人工页"]);
+});

package/template/.hermes/skills/llm-wiki/scripts/lint-wikilinks.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXTRACT_KINDS } from "./extract.mjs";
+import { exists, sha256 } from "./inventory.mjs";
+
+export const INFRA = new Set([
+  "index.md",
+  "log.md",
+  "claude.md",
+  "agents.md",
+  "soul.md",
+  "concept-table.md",
+]);
+const WIKILINK_RE = /\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g;
+const SOURCE_HEADING_RE = /^##\s+来源\s*$/m;
+const H1_RE = /^#\s+(.+?)\s*$/m;
+
+export function articlesDir(wikiRoot) {
+  return path.join(wikiRoot, "wiki");
+}
+
+export function extractLinks(text) {
+  const ids = [];
+  const invalid = [];
+  WIKILINK_RE.lastIndex = 0;
+  let match;
+  while ((match = WIKILINK_RE.exec(text))) {
+    const target = match[1].trim();
+    if (!target) continue;
+    if (target.startsWith("../") || target.includes("/")) {
+      invalid.push(target);
+      continue;
+    }
+    ids.push(target);
+  }
+  return { ids, invalid };
+}
+
+export async function lintWiki(wikiRoot, { repoRoot = process.cwd() } = {}) {
+  const dir = articlesDir(wikiRoot);
+  if (!(await exists(path.join(dir, "index.md")))) {
+    return { ok: false, errors: [`missing ${path.join(dir, "index.md")}`], counts: {} };
+  }
+  const names = (await readdir(dir)).filter((name) => name.endsWith(".md"));
+  const articleFiles = names.filter((name) => !INFRA.has(name.toLowerCase()));
+  const articleIds = new Set(articleFiles.map((name) => name.slice(0, -3)));
+  const errors = [];
+  let linkCount = 0;
+
+  const indexText = await readFile(path.join(dir, "index.md"), "utf8");
+  const indexLinks = extractLinks(indexText);
+  linkCount += indexLinks.ids.length;
+  for (const target of indexLinks.invalid) errors.push(`CROSS-WIKI (index): [[${target}]]`);
+  const indexed = new Set();
+  for (const id of indexLinks.ids) {
+    indexed.add(id);
+    if (!articleIds.has(id)) errors.push(`MISSING (index): [[${id}]]`);
+  }
+
+  for (const file of articleFiles) {
+    const id = file.slice(0, -3);
+    const text = await readFile(path.join(dir, file), "utf8");
+    const heading = text.match(H1_RE);
+    if (!heading || heading[1] !== id) errors.push(`H1 MISMATCH: ${file} expected # ${id}`);
+    if (!SOURCE_HEADING_RE.test(text)) errors.push(`NO SOURCE SECTION: ${file}`);
+    if (!indexed.has(id)) errors.push(`ORPHAN: ${file}`);
+    const links = extractLinks(text);
+    for (const target of links.invalid) errors.push(`CROSS-WIKI: ${file} -> [[${target}]]`);
+    for (const target of links.ids) {
+      linkCount += 1;
+      if (!articleIds.has(target)) errors.push(`MISSING: ${file} -> [[${target}]]`);
+    }
+  }
+
+  const manifestFile = path.join(wikiRoot, ".wiki-manifest.json");
+  if (await exists(manifestFile)) {
+    const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+    const sourceById = new Map();
+    for (const source of manifest.sources || []) {
+      if (source?.id) sourceById.set(source.id, source);
+    }
+    const listedFiles = new Set();
+    for (const article of manifest.articles || []) {
+      const rel = path.posix.normalize(article.file || "");
+      listedFiles.add(rel);
+      const expectedId = path.posix.basename(rel, ".md");
+      if (article.id !== expectedId) {
+        errors.push(`MANIFEST ID MISMATCH: ${article.file} id=${article.id} expected ${expectedId}`);
+      }
+      const file = path.resolve(wikiRoot, article.file);
+      if (!(await exists(file))) errors.push(`MANIFEST ARTICLE MISSING: ${article.file}`);
+      for (const sourceId of article.sourceIds || []) {
+        if (!sourceById.has(sourceId)) {
+          errors.push(`UNKNOWN SOURCE ID: ${article.id} -> ${sourceId}`);
+        }
+      }
+    }
+    for (const file of articleFiles) {
+      const rel = path.posix.join("wiki", file);
+      if (!listedFiles.has(rel)) errors.push(`UNLISTED ARTICLE: ${file}`);
+    }
+    for (const source of manifest.sources || []) {
+      if (manifest.profile === "documents" && source.kind === "code-surface") {
+        errors.push(`PROFILE KIND: documents forbids code-surface (${source.id})`);
+      }
+      if (source.kind === "document" || source.kind === "derived") {
+        if (!source.rawPath) {
+          errors.push(`RAW PATH REQUIRED: ${source.id} (${source.kind})`);
+        } else {
+          const raw = path.resolve(wikiRoot, source.rawPath);
+          if (!(await exists(raw))) errors.push(`RAW MISSING: ${source.id} (${source.rawPath})`);
+        }
+      }
+      if (source.kind === "derived") {
+        const extractKind = source.extract?.kind;
+        if (!extractKind) errors.push(`EXTRACT REQUIRED: ${source.id}`);
+        else if (!EXTRACT_KINDS.includes(extractKind)) {
+          errors.push(`EXTRACT KIND: ${source.id} (${extractKind})`);
+        }
+      }
+      if (source.kind === "code-surface" && source.rawPath != null) {
+        errors.push(`RAW PATH FORBIDDEN: ${source.id} (code-surface)`);
+      }
+      if (!source.livePath) continue;
+      const live = path.resolve(repoRoot, source.livePath);
+      if (!(await exists(live))) {
+        errors.push(`MANIFEST SOURCE MISSING: ${source.id} (${source.livePath})`);
+        continue;
+      }
+      const current = sha256(await readFile(live));
+      if (!source.sha256 || current !== source.sha256) {
+        errors.push(`STALE HASH: ${source.id} (${source.livePath})`);
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    counts: { articles: articleFiles.length, links: linkCount },
+  };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let wikiArg;
+  let repoRoot = process.cwd();
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--repo") repoRoot = argv[++i];
+    else if (!wikiArg && !argv[i].startsWith("-")) wikiArg = argv[i];
+  }
+  repoRoot = path.resolve(repoRoot);
+  if (!wikiArg) {
+    throw new Error("usage: lint-wikilinks.mjs <wiki-root> [--repo <repo-root>]");
+  }
+  const wikiRoot = path.resolve(repoRoot, wikiArg);
+  const result = await lintWiki(wikiRoot, { repoRoot });
+  for (const error of result.errors) process.stdout.write(`${error}\n`);
+  process.stdout.write(
+    `校验完成：${result.counts.articles || 0} 篇文章，${result.counts.links || 0} 条 wikilink\n`,
+  );
+  if (result.ok) process.stdout.write("通过：所有 wikilink / 来源 / 索引检查通过\n");
+  else {
+    process.stdout.write(
+      "失败：存在缺失的 wikilink、孤儿页、来源小节、跨路径链接、H1 或 manifest 闭合问题\n",
+    );
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  });
+}