create-yss-spec 3.5.2 → 3.5.4

package/template/.agents/skills/llm-wiki/scripts/core.mjs

@@ -0,0 +1,262 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, writeFile, rename, lstat, realpath, mkdir, access } from "node:fs/promises";
+import path from "node:path";
+const STATES = ["current", "stale", "missing", "unverified", "archived"];
+const INFRA = /* @__PURE__ */ new Set(["index.md", "log.md", "claude.md", "agents.md", "soul.md", "concept-table.md"]);
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const json = (value) => `${JSON.stringify(value, null, 2)}
+`;
+class WikiError extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+  }
+}
+function fail(code, message) {
+  throw new WikiError(code, message);
+}
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw e;
+  }
+}
+async function digestFile(file) {
+  try {
+    return sha256(await readFile(file));
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+function inside(root, target) {
+  const r = path.relative(root, target);
+  return r === "" || !r.startsWith(`..${path.sep}`) && r !== ".." && !path.isAbsolute(r);
+}
+async function safePath(root, ref, { write = false } = {}) {
+  if (typeof ref !== "string" || !ref || ref.includes("\\") || ref.includes("\0") || path.isAbsolute(ref) || ref.split("/").some((x) => ["..", ".", ""].includes(x))) fail("PATH_INVALID", String(ref));
+  const base = path.resolve(root), target = path.resolve(base, ref);
+  if (!inside(base, target) || target === base) fail("PATH_ESCAPE", ref);
+  let baseReal;
+  try {
+    baseReal = await realpath(base);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const parent = path.dirname(base);
+    baseReal = path.join(await realpath(parent), path.basename(base));
+  }
+  let current = base;
+  for (const part of ref.split("/")) {
+    current = path.join(current, part);
+    let st;
+    try {
+      st = await lstat(current);
+    } catch (e) {
+      if (e.code === "ENOENT") continue;
+      throw e;
+    }
+    if (st.isSymbolicLink() && write) fail("SYMLINK_WRITE", ref);
+    let resolved;
+    try {
+      resolved = await realpath(current);
+    } catch {
+      fail("PATH_ESCAPE", `unresolved symlink ${ref}`);
+    }
+    if (!inside(baseReal, resolved)) fail("PATH_ESCAPE", ref);
+  }
+  return target;
+}
+async function atomicWrite(file, content) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  await writeFile(temp, content, { flag: "wx" });
+  await rename(temp, file);
+}
+function frontmatter(text) {
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return { humanOwned: false, body: text, fields: {} };
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) fail("FRONTMATTER_INVALID", "unterminated header");
+  const fields = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const pair = line.match(/^([\w-]+):\s*(.*?)\s*$/);
+    if (!pair) fail("FRONTMATTER_INVALID", "use flat scalar fields");
+    if (Object.hasOwn(fields, pair[1])) fail("FRONTMATTER_INVALID", `duplicate ${pair[1]}`);
+    fields[pair[1]] = pair[2];
+  }
+  if (fields["human-owned"] !== void 0 && !["true", "false"].includes(fields["human-owned"])) fail("FRONTMATTER_INVALID", "human-owned must be a boolean");
+  return { humanOwned: fields["human-owned"] === "true", fields, body: text.slice(m[0].length) };
+}
+function sourceSection(text) {
+  return text.match(/^##\s+来源\s*\r?\n([\s\S]*)/m)?.[1]?.trim() || "";
+}
+function ownership(article, text) {
+  const fm = frontmatter(text);
+  return { protected: article.humanOwned === true || fm.humanOwned, conflict: article.humanOwned !== void 0 && fm.fields["human-owned"] !== void 0 && article.humanOwned !== fm.humanOwned };
+}
+const array = (v) => Array.isArray(v);
+const unique = (v) => new Set(v).size === v.length;
+const digest = (v) => v === null || /^[a-f0-9]{64}$/.test(v);
+function validateManifest(m) {
+  const errors = [];
+  const check = (ok, code, detail) => {
+    if (!ok) errors.push(`${code}: ${detail}`);
+  };
+  if (!m || typeof m !== "object" || array(m)) return ["MANIFEST_INVALID: expected object"];
+  check([1, 2].includes(m.schemaVersion), "SCHEMA_UNSUPPORTED", m.schemaVersion);
+  check(m.profile === void 0 && m.schemaVersion === 1 || ["mixed", "documents", "code"].includes(m.profile), "PROFILE_INVALID", m.profile);
+  if (!array(m.sources) || !array(m.articles)) return [...errors, "MANIFEST_INVALID: sources and articles must be arrays"];
+  for (const [group, rows] of [["source", m.sources], ["article", m.articles]]) {
+    check(rows.every((x) => x && typeof x.id === "string" && x.id.trim() && (group === "source" || !/[\[\]#|/\\]/.test(x.id))), "ID_INVALID", group);
+    check(unique(rows.map((x) => x?.id)), "DUPLICATE_ID", group);
+  }
+  const sources = new Set(m.sources.map((x) => x?.id)), articles = new Set(m.articles.map((x) => x?.id));
+  check(unique(m.articles.map((x) => x?.file)), "DUPLICATE_FILE", "articles");
+  for (const s of m.sources) {
+    if (!s || typeof s !== "object") continue;
+    check(["document", "derived", "code-surface"].includes(s.kind), "SOURCE_KIND", s.id);
+    if (s.kind === "code-surface") check(typeof s.livePath === "string" && s.livePath.length > 0, "LIVE_PATH_REQUIRED", s.id);
+    check(!(m.profile === "documents" && s.kind === "code-surface"), "PROFILE KIND", s.id + " code-surface");
+    check(s.kind === "code-surface" ? s.rawPath == null : typeof s.rawPath === "string" && s.rawPath.length > 0, s.kind === "code-surface" ? "RAW PATH FORBIDDEN" : "RAW PATH REQUIRED", s.id);
+    if (s.kind === "derived") {
+      if (m.schemaVersion === 2 && s.extract?.kind === "prose-note") check(typeof s.extract.rules === "string" && s.extract.rules.length > 0 && s.extract.inputDigests && typeof s.extract.inputDigests === "object", "EXTRACT_RULES", s.id);
+      check(!!s.extract?.kind, "EXTRACT REQUIRED", s.id);
+      if (s.extract?.kind) check(["skill-names", "heading-list", "prose-note"].includes(s.extract.kind), "EXTRACT KIND", `${s.id} ${s.extract.kind}`);
+      if (m.schemaVersion === 2) {
+        check(typeof s.extract?.version === "string" && !!s.extract.version, "EXTRACT_VERSION", s.id);
+        check(array(s.extract?.inputs) && s.extract.inputs.length > 0 && unique(s.extract.inputs), "EXTRACT_INPUTS", s.id);
+      }
+    }
+    if (s.status !== void 0) check(STATES.includes(s.status), "STATUS_INVALID", s.id);
+    if (m.schemaVersion === 2) {
+      for (const k of ["originalDigest", "effectiveDigest", "rawDigest"]) check(Object.hasOwn(s, k) && digest(s[k]), "DIGEST_INVALID", `${s.id}.${k}`);
+      check(typeof s.location === "string" && s.location.length > 0, "LOCATION_REQUIRED", s.id);
+    }
+  }
+  for (const a of m.articles) {
+    if (!a || typeof a !== "object") continue;
+    check(a.file === `wiki/${a.id}.md` && !INFRA.has(`${a.id}.md`.toLowerCase()), "MANIFEST ID MISMATCH", a.id);
+    check(array(a.sourceIds) && unique(a.sourceIds), "SOURCE_REFS_INVALID", a.id);
+    check(array(a.sourceIds) && (a.sourceIds.length > 0 || array(a.dependsOnArticles) && a.dependsOnArticles.length > 0), "EMPTY_SOURCE_REFS", a.id);
+    for (const id of array(a.sourceIds) ? a.sourceIds : []) check(sources.has(id), "UNKNOWN SOURCE ID", `${a.id} -> ${id}`);
+    if (a.dependsOnArticles !== void 0) check(array(a.dependsOnArticles) && unique(a.dependsOnArticles), "DEPENDENCIES_INVALID", a.id);
+    for (const id of array(a.dependsOnArticles) ? a.dependsOnArticles : []) check(articles.has(id), "UNKNOWN_ARTICLE_ID", `${a.id} -> ${id}`);
+    if (a.aliases !== void 0) check(array(a.aliases) && a.aliases.every((x) => typeof x === "string" && x.trim()), "ALIASES_INVALID", a.id);
+    if (a.humanOwned !== void 0) check(typeof a.humanOwned === "boolean", "OWNERSHIP_INVALID", a.id);
+    if (a.verification !== void 0 && a.verification !== null) check(a.verification && typeof a.verification === "object" && array(a.verification.evidence) && a.verification.evidence.every((e) => e && typeof e === "object" && sources.has(e.sourceId) && ["general", "critical"].includes(e.risk) && typeof e.claim === "string" && e.claim.length > 0 && digest(e.excerptDigest) && e.excerptDigest !== null && typeof e.inputPath === "string" && Number.isInteger(e.startLine) && e.startLine > 0 && Number.isInteger(e.endLine) && e.endLine >= e.startLine) && digest(a.verification.articleDigest) && a.verification.articleDigest !== null, "EVIDENCE_INVALID", a.id);
+    if (a.status !== void 0) check(STATES.includes(a.status), "STATUS_INVALID", a.id);
+    if (m.schemaVersion === 2) {
+      check(digest(a.articleDigest) && Object.hasOwn(a, "articleDigest"), "DIGEST_INVALID", a.id);
+      check(a.compiledFrom && typeof a.compiledFrom === "object" && !array(a.compiledFrom), "COMPILED_FROM_INVALID", a.id);
+      for (const [id, binding] of Object.entries(a.compiledFrom || {})) {
+        check(sources.has(id) && binding && digest(binding.effectiveDigest) && binding.effectiveDigest !== null, "COMPILED_FROM_INVALID", `${a.id}:${id}`);
+      }
+    }
+  }
+  if (errors.length === 0) {
+    try {
+      for (const a of m.articles) sourceClosure(m, a.id);
+    } catch (e) {
+      errors.push(e.message);
+    }
+  }
+  if (m.feedback !== void 0) {
+    check(array(m.feedback), "FEEDBACK_INVALID", "expected array");
+    if (array(m.feedback)) {
+      check(unique(m.feedback.map((f) => f?.id)), "DUPLICATE_ID", "feedback");
+      for (const f of m.feedback) {
+        if (!f || typeof f !== "object") {
+          errors.push("FEEDBACK_INVALID: expected object");
+          continue;
+        }
+        check(typeof f.id === "string" && f.id.length > 0 && articles.has(f.articleId) && digest(f.targetDigest) && f.targetDigest !== null && typeof f.issue === "string" && f.issue.trim() && f.locator && typeof f.locator.quote === "string" && f.locator.quote.length > 0, "FEEDBACK_INVALID", f.id);
+        check(["open", "accepted", "partial", "rejected", "deferred"].includes(f.status), "FEEDBACK_STATUS", f.id);
+      }
+    }
+  }
+  return errors;
+}
+function sourceClosure(m, id, trail = []) {
+  if (trail.includes(id)) fail("DEPENDENCY_CYCLE", [...trail, id].join(" -> "));
+  const a = m.articles.find((x) => x.id === id);
+  if (!a) fail("UNKNOWN_ARTICLE_ID", id);
+  return [.../* @__PURE__ */ new Set([...a.sourceIds || [], ...(a.dependsOnArticles || []).flatMap((dep) => sourceClosure(m, dep, [...trail, id]))])].sort();
+}
+async function checkPaths(m, { wikiRoot, repoRoot }) {
+  for (const s of m.sources) {
+    for (const ref of [s.livePath, ...s.extract?.inputs || []].filter(Boolean)) await safePath(repoRoot, ref);
+    if (s.rawPath) await safePath(wikiRoot, s.rawPath);
+  }
+  for (const a of m.articles) await safePath(wikiRoot, a.file);
+}
+async function loadManifest(wikiRoot, { repoRoot = process.cwd(), validate = true } = {}) {
+  const m = JSON.parse(await readFile(await safePath(wikiRoot, ".wiki-manifest.json"), "utf8"));
+  if (validate) {
+    const errors = validateManifest(m);
+    if (errors.length) fail("MANIFEST_INVALID", errors.join("\n"));
+    await checkPaths(m, { wikiRoot, repoRoot });
+  }
+  return m;
+}
+async function transactionState(wikiRoot, { reader } = {}) {
+  // A writer claims the lock before replacing an earlier finalized journal.
+  // That interval must also block readers.
+  if (await exists(await safePath(wikiRoot, ".wiki-lock"))) return { state: "locked", incomplete: true };
+  const file = await safePath(wikiRoot, ".wiki-transaction.json");
+  if (!await exists(file)) return { state: "none" };
+  const j = JSON.parse(reader ? (await reader(file)).toString() : await readFile(file, "utf8"));
+  return { id: j.id, state: j.phase, incomplete: !["finalized", "aborted"].includes(j.phase) };
+}
+async function assertReadable(wikiRoot, reader) {
+  const tx = await transactionState(wikiRoot, { reader });
+  if (tx.incomplete || tx.state === "locked") fail("TRANSACTION_INCOMPLETE", "explicit resume or abort required; query never recovers");
+  return tx;
+}
+function cliError(e) {
+  process.stderr.write(`${JSON.stringify({ ok: false, code: e.code || "EXECUTION_ERROR", message: e.message })}
+`);
+  process.exitCode = 2;
+}
+function args(argv, commands = []) {
+  const result = { command: commands.length ? argv.shift() : void 0, repo: process.cwd() };
+  if (commands.length && !commands.includes(result.command)) fail("USAGE", commands.join("|"));
+  while (argv.length) {
+    const a = argv.shift();
+    if (a === "--apply" || a === "--structure-only") {
+      result[a.slice(2)] = true;
+    } else if (a.startsWith("--")) {
+      if (!argv.length || argv[0].startsWith("--")) fail("USAGE", `value required ${a}`);
+      const key = a.slice(2);
+      if (key === "candidate") (result.candidates ??= []).push(argv.shift());
+      else result[key] = argv.shift();
+    } else if (!result.wiki) result.wiki = a;
+    else fail("USAGE", a);
+  }
+  return result;
+}
+export {
+  INFRA,
+  STATES,
+  WikiError,
+  args,
+  assertReadable,
+  atomicWrite,
+  checkPaths,
+  cliError,
+  digestFile,
+  exists,
+  fail,
+  frontmatter,
+  json,
+  loadManifest,
+  ownership,
+  safePath,
+  sha256,
+  sourceClosure,
+  sourceSection,
+  transactionState,
+  validateManifest
+};

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

@@ -2,15 +2,27 @@
 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"]);
-
+import { safePath, cliError } from "./core.mjs";
+const EXTRACT_KINDS = Object.freeze(["skill-names", "heading-list", "prose-note"]);
+function extractHeadings(text, input = "") {
+  const lines = [`# heading-list${input ? `: ${input}` : ""}`, ""];
+  let fence = null;
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1][0];
+      else if (fence === marker[1][0]) fence = null;
+      continue;
+    }
+    if (!fence && /^#{1,6}\s+\S/.test(line)) lines.push(`- L${index + 1}: ${line.trim()}`);
+  }
+  return lines.join("\n") + "\n";
+}
 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) {
+function extractSkillNames(lock) {
   if (!lock || typeof lock !== "object" || Array.isArray(lock)) {
     throw new TypeError("skill-names input must be a lock object");
   }
@@ -27,9 +39,9 @@ export function extractSkillNames(lock) {
       lines.push("");
     }
   }
-  return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+  return `${lines.join("\n").replace(/\n+$/, "")}
+`;
 }
-
 async function main(argv = process.argv.slice(2)) {
   const kind = argv[0];
   let input;
@@ -38,18 +50,23 @@ async function main(argv = process.argv.slice(2)) {
     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>");
+  if (!["skill-names", "heading-list"].includes(kind) || !input || !output) {
+    throw new Error("usage: extract.mjs skill-names|heading-list --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`);
+  const inputFile = await safePath(process.cwd(), input);
+  const outputFile = await safePath(process.cwd(), output, { write: true });
+  const content = await readFile(inputFile, "utf8");
+  const text = kind === "skill-names" ? extractSkillNames(JSON.parse(content)) : extractHeadings(content, input);
+  await mkdir(path.dirname(outputFile), { recursive: true });
+  await writeFile(outputFile, text, "utf8");
+  process.stdout.write(`${output}
+`);
 }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main().catch((error) => {
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = 2;
-  });
+  main().catch(cliError);
 }
+export {
+  EXTRACT_KINDS,
+  extractHeadings,
+  extractSkillNames
+};

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

@@ -1,21 +1,20 @@
 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" },
+        alpha: { effectiveHash: "bbb" }
       },
       platform: {
         ".codex/skills": {
           "product-design": { effectiveHash: "ccc" },
-          "data-analytics": { effectiveHash: "ddd" },
-        },
-      },
-    },
+          "data-analytics": { effectiveHash: "ddd" }
+        }
+      }
+    }
   });
   assert.match(text, /## shared/);
   assert.match(text, /## platform/);
@@ -24,11 +23,9 @@ test("skill-names lists shared and platform keys, sorted, without hashes", () =>
   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/.agents/skills/llm-wiki/scripts/feedback.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadManifest, safePath, sha256, json, fail, args, cliError, assertReadable } from "./core.mjs";
+import { createPlan, applyPlan } from "./transaction.mjs";
+async function feedbackPlan({ wikiRoot, repoRoot = process.cwd(), request }) {
+  await assertReadable(wikiRoot);
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  if (manifest.schemaVersion !== 2) fail("MIGRATION_REQUIRED", "feedback requires v2");
+  manifest.feedback ||= [];
+  const a = manifest.articles.find((a2) => a2.id === request.articleId);
+  if (!a) fail("UNKNOWN_ARTICLE_ID", request.articleId);
+  const text = await readFile(await safePath(wikiRoot, a.file), "utf8"), digest = sha256(text), existing = manifest.feedback.find((f) => f.id === request.id);
+  if (!request.id || !request.issue || !request.locator?.quote) fail("FEEDBACK_INVALID", "id, issue and quoted locator required");
+  if (request.targetDigest !== digest) fail("FEEDBACK_REANCHOR_REQUIRED", "target changed; locate quoted text on current version");
+  const index = text.indexOf(request.locator.quote);
+  if (index < 0 || text.indexOf(request.locator.quote, index + 1) >= 0) fail("FEEDBACK_REANCHOR_REQUIRED", "quote must match exactly once");
+  const state = request.status || "open";
+  if (!["open", "accepted", "partial", "rejected", "deferred"].includes(state)) fail("FEEDBACK_INVALID", "status");
+  const record = { id: request.id, articleId: a.id, targetDigest: digest, locator: { quote: request.locator.quote, startLine: text.slice(0, index).split("\n").length }, issue: request.issue, status: state, history: existing?.history || [] };
+  if (existing && existing.articleId !== a.id) fail("FEEDBACK_ID_CONFLICT", request.id);
+  if (["accepted", "partial"].includes(state)) {
+    const r = request.resolution;
+    if (!existing || !r?.transactionId || r.beforeDigest !== existing.targetDigest || r.afterDigest !== digest || r.beforeDigest === r.afterDigest || !r.note) fail("FEEDBACK_EVIDENCE_REQUIRED", "actual change and verification required");
+    const j = JSON.parse(await readFile(await safePath(wikiRoot, `.wiki-staging/${r.transactionId}/completed.json`), "utf8"));
+    if (j.phase !== "finalized" || !j.writes?.some((w) => w.path === a.file && w.before === r.beforeDigest && w.after === r.afterDigest) || a.verification?.articleDigest !== digest) fail("FEEDBACK_EVIDENCE_REQUIRED", "completed article modification and verified compilation required");
+    record.resolution = r;
+  } else if (state !== "open") {
+    if (!request.resolution?.note) fail("FEEDBACK_EVIDENCE_REQUIRED", "disposition reason required");
+    record.resolution = request.resolution;
+  }
+  const comparable = (f) => JSON.stringify({ ...f, history: void 0 });
+  if (existing && comparable(existing) === comparable(record)) return { duplicate: true, id: record.id };
+  if (existing && existing.status === "open" && state === "open" && existing.issue !== record.issue) fail("FEEDBACK_ID_CONFLICT", "existing feedback differs");
+  record.history = [...record.history, { at: request.at || (/* @__PURE__ */ new Date()).toISOString(), status: state, targetDigest: digest }];
+  if (existing) manifest.feedback[manifest.feedback.indexOf(existing)] = record;
+  else manifest.feedback.push(record);
+  return createPlan({ wikiRoot, repoRoot, request: { operation: "feedback", manifest, authorization: { confirmed: request.confirmed === true, paths: [".wiki-manifest.json", "wiki/log.md"] } } });
+}
+async function main() {
+  const a = args(process.argv.slice(2));
+  if (!a.wiki || !a.request) fail("USAGE", "--wiki --request [--apply]");
+  const options = { wikiRoot: path.resolve(a.repo, a.wiki), repoRoot: path.resolve(a.repo) };
+  const plan = await feedbackPlan({ ...options, request: JSON.parse(await readFile(a.request, "utf8")) });
+  process.stdout.write(json(a.apply && !plan.duplicate ? await applyPlan({ ...options, plan }) : plan));
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) main().catch(cliError);
+export {
+  feedbackPlan
+};

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

@@ -1,174 +1,46 @@
 #!/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;
-  });
-}
+import { sha256, exists, loadManifest, args, cliError, transactionState } from "./core.mjs";
+import { observeSource, inspectArticles } from "./sources.mjs";
+const resolveWikiRoot = (arg, cwd = process.cwd()) => {
+  if (!arg) throw new Error("missing --wiki");
+  return path.resolve(cwd, arg);
+};
+const manifestPath = (root) => path.join(root, ".wiki-manifest.json");
+const normalizeLivePath = (p) => String(p || "").replace(/\\/g, "/").replace(/^\.\/+/, "");
+function unmappedCandidates(sources, candidates = []) {
+  const mapped = new Set(sources.map((s) => normalizeLivePath(s.livePath)));
+  return [...new Set(candidates.map(normalizeLivePath).filter((p) => p && !mapped.has(p)))];
+}
+async function hashSources({ wikiRoot, repoRoot = process.cwd() }) {
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  const observations = [];
+  for (const s of manifest.sources) observations.push(await observeSource(s, { wikiRoot, repoRoot }));
+  return { manifest, observations, hashed: observations.length, missing: observations.filter((s) => s.state === "missing").map((s) => s.id), readOnly: true, transaction: await transactionState(wikiRoot) };
+}
+async function drift({ wikiRoot, repoRoot = process.cwd(), candidates = [], articleIds, reader }) {
+  const manifest = await loadManifest(wikiRoot, { repoRoot });
+  const report = await inspectArticles(manifest, { wikiRoot, repoRoot, articleIds, reader });
+  const select = (state) => report.sourceStates.filter((s) => s.state === state).map((s) => s.id);
+  return { changed: select("stale"), missing: select("missing"), unchanged: select("current"), unverified: select("unverified"), archived: select("archived"), articles: report.articleStates.filter((a) => a.state !== "current" && a.state !== "archived").map((a) => a.id), unmapped: unmappedCandidates(manifest.sources, candidates), humanOwned: report.articleStates.filter((a) => a.humanOwned).map((a) => a.id), ...report };
+}
+async function main() {
+  const a = args(process.argv.slice(2), ["hash", "drift", "status"]);
+  const options = { wikiRoot: resolveWikiRoot(a.wiki, a.repo), repoRoot: path.resolve(a.repo), candidates: a.candidates };
+  const result = a.command === "hash" ? await hashSources(options) : await drift(options);
+  if (a.command === "hash") delete result.manifest;
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) main().catch(cliError);
+export {
+  drift,
+  exists,
+  hashSources,
+  loadManifest,
+  manifestPath,
+  normalizeLivePath,
+  resolveWikiRoot,
+  sha256,
+  unmappedCandidates
+};