@salaros/ai-harness 0.2.10 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.2.10",
+  "version": "0.3.1",
   "description": "Installs and updates the agent harness from its upstream repository: hooks, skills, agents and the documentation chain, merged into an existing repository without touching its own work.",
   "bin": {
     "ai-harness": "scripts/update-harness.js"
@@ -8,6 +8,8 @@
   "files": [
     "scripts/update-harness.js",
     "scripts/lib.js",
+    "scripts/project-facts.js",
+    "scripts/repo-view.js",
     "README.md",
     "LICENSE"
   ],

package/scripts/README.md

@@ -17,11 +17,13 @@ part of the product.
 
 - One task per script, named after what it does (`githooks-init.js`,
   `build.js`, `release.js`); Node, so they run the same on every OS.
-- Scripts are safe to run from any working directory — each resolves the
-  repository root from its own location, or from `--root=<dir>` when given
-  (`lib.root()`; `lib.args()` is the arguments without that flag). The
-  suite uses the flag to run a script against a temporary repo, and a script
-  that calls another passes its own root along.
+- Scripts are safe to run from any working directory — every script and hook
+  asks `lib.root()` which repo it is about, and gets one answer: `--root=<dir>`
+  when given, then the harness's project-dir variable
+  (`CLAUDE_PROJECT_DIR` and its Cursor and Gemini equivalents), then the
+  checkout the file sits in (`lib.args()` is the arguments without the flag).
+  The suite uses the flag to run a script against a temporary repo, and a
+  script that calls another passes its own root along.
 - A script run as a command may `chdir` there (`lib.chdirRoot()`). A script
   another script requires takes the root as its first argument and resolves
   against it (`lib.root()` at the entry point, `path.resolve(root, …)`
@@ -36,6 +38,15 @@ part of the product.
   and hand over to `githook.js <hook>`. Nothing else belongs in them: a
   decision made in the shell is one no test can reach, and the suite asserts
   the shape.
+- A script is a thin shell around its decisions. Parsing, merging,
+  formatting and the summary it prints go in a pure module the suite tests;
+  the script only reads, writes and reports, for the same reason the hooks
+  above hold no logic.
+- What two scripts share lives in one module here instead of a copy in each,
+  so the callers cannot drift: a threshold, a list, or a whole step, the way
+  `lib.js` holds root resolution and argument parsing for every script. When
+  several scripts do one job for different sources, a runner owns the common
+  steps and each script brings only its source and its rules.
 - Scripts must be idempotent where possible — running them twice should not
   break anything.
   

package/scripts/lib.js

@@ -4,7 +4,7 @@
 // which requires this file rather than the other way around, so scripts/ never reaches into the
 // harness-specific folder.
 //   const lib = require("./lib");
-//   const root = lib.root();                 // the repo root: --root=<dir> if given, else one level above this file
+//   const root = lib.root();                 // the repo root (precedence below)
 //   const root = lib.chdirRoot();            // the same, and cd there
 //   const [cmd, ...rest] = lib.args();       // the command line, without --root=<dir>
 //   lib.stdin()                              // everything on stdin, or "" if there is none
@@ -15,21 +15,50 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
-// Every script under scripts/ resolves the repo root once, on its command line, and a script run as
-// a command chdirs there so its relative paths (SKILL.md files, README.md, stacks.tsv) work no matter
-// where it was invoked from. A script another script requires takes the root as an argument and
-// resolves against it: chdir is a process-wide effect, so a library that moves the working directory
-// moves it for its caller too.
-// The root is the repo this file sits in, unless the command was given --root=<dir>. That flag is
-// how a check reaches a repo other than its own checkout: the suite points a case at a throwaway
-// directory rather than planting files in the tree it runs in, and the installer checks a target
-// with the upstream's copy of a script. One token, so an argument parser that skips "--" flags skips
-// it too.
+// Which repo an entry point is about, in one precedence every script and hook follows:
+//   1. --root=<dir> on the command line, the explicit answer
+//   2. CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR or GEMINI_PROJECT_DIR, the harness's answer
+//   3. the checkout this file sits in
+// The flag is how a check reaches a repo other than its own checkout: the suite points a case at a
+// throwaway directory rather than planting files in the tree it runs in, and the installer checks a
+// target with the upstream's copy of a script. One token, so an argument parser that skips "--"
+// flags skips it too. The variables are how a harness says which project it is editing, which is
+// not always the checkout a hook file sits in. A variable naming another checkout is honoured and
+// reported on stderr; one naming nothing that exists is ignored and reported.
+// A script run as a command chdirs to the root so its relative paths (SKILL.md files, README.md,
+// stacks.tsv) work wherever it was invoked from. A script another script requires takes the root as
+// an argument and resolves against it: chdir is a process-wide effect, so a library that moves the
+// working directory moves it for its caller too.
 const ROOT_FLAG = "--root=";
-const root = () => {
-    const given = process.argv.slice(2).find(a => a.startsWith(ROOT_FLAG));
-    return path.resolve(given ? given.slice(ROOT_FLAG.length) : path.join(__dirname, ".."));
+const ROOT_ENV_VARS = ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "GEMINI_PROJECT_DIR"];
+const CHECKOUT = path.resolve(__dirname, "..");
+
+const win = process.platform === "win32";
+const warn = msg => process.stderr.write(`harness: ${msg}\n`);
+const same = (a, b) => win ? a.toLowerCase() === b.toLowerCase() : a === b;
+// Git Bash reports C:\x as /c/x; Windows APIs may prefix \\?\. Bring both to a form path can resolve.
+const fix = p => {
+    let s = String(p).replace(/^\\\\\?\\/, "");
+    if (win) { const m = s.match(/^\/([a-zA-Z])(?:\/(.*))?$/); if (m) s = `${m[1].toUpperCase()}:/${m[2] || ""}`; }
+    return s;
 };
+const real = p => { try { return fs.realpathSync(p); } catch { return p; } };
+
+function root() {
+    const given = process.argv.slice(2).find(a => a.startsWith(ROOT_FLAG));
+    if (given) return path.resolve(fix(given.slice(ROOT_FLAG.length)));
+    const here = real(CHECKOUT);
+    for (const v of ROOT_ENV_VARS) {
+        const val = process.env[v];
+        if (!val) continue;
+        const dir = path.resolve(fix(val));
+        let st; try { st = fs.statSync(dir); } catch { }
+        if (!st || !st.isDirectory()) { warn(`${v} is not a directory; using the checkout this file lives in`); break; }
+        if (!same(real(dir), here)) warn(`${v} (${dir}) is not the checkout this file lives in (${here}); using ${v}`);
+        return dir;
+    }
+    return here;
+}
 const args = () => process.argv.slice(2).filter(a => !a.startsWith(ROOT_FLAG));
 
 function chdirRoot() {
@@ -55,4 +84,4 @@ function readTsv(file) {
         .map(l => l.split("\t"));
 }
 
-module.exports = { root, args, ROOT_FLAG, chdirRoot, stdin, run, node, shell, readTsv };
+module.exports = { root, args, ROOT_FLAG, ROOT_ENV_VARS, CHECKOUT, chdirRoot, fix, warn, stdin, run, node, shell, readTsv };

package/scripts/project-facts.js

@@ -0,0 +1,113 @@
+// scripts/project-facts.js
+// The one reader of a project's facts: the labelled lines of MEMORY.md, and the name and purpose an
+// INTENT.md gives in its "## Product" section. The initialisation gate, the commit-message check,
+// docs-check, the docs portal and the installer's MEMORY.md skeleton all ask this module, so a line
+// one of them counts as present is present to every one of them, and a placeholder one of them
+// treats as unanswered is unanswered everywhere.
+// Shipped in the npm package beside update-harness.js and lib.js, because the installer builds its
+// skeleton from FACTS, so the installer must not require anything else from scripts/.
+// Usage:
+//   const facts = require("./project-facts");
+//   const f = facts.readFactsAt(root);           // { Name, Purpose, Requirements, ... }
+//   f["Issue tracker"]                            // null: no line; "": unanswered; else the value
+//   facts.unanswered(f)                           // the required labels with no answer
+const fs = require("fs");
+const path = require("path");
+
+const MEMORY = "MEMORY.md";
+const INTENT = "INTENT.md";
+
+// Every fact, in the order MEMORY.md lists them. `required` facts gate initialisation; the rest are
+// read by the skills that need them and never block. `intent` marks the two an INTENT.md owns.
+// `Issue tracker` is optional because a tracker is a choice rather than a property of the code,
+// `Frontend` because a service or a library has no UI, and `Prose language` because a missing line
+// already means English.
+const FACTS = [
+    { label: "Name", required: true, intent: true, placeholder: "<name>" },
+    { label: "Purpose", required: true, intent: true, placeholder: "<purpose>" },
+    { label: "Prose language", required: false, placeholder: "<prose language>" },
+    { label: "Requirements", required: true, placeholder: "<requirements>" },
+    { label: "Unit type", required: true, placeholder: "<unit type>" },
+    { label: "Language", required: true, placeholder: "<language>" },
+    { label: "Runtime / package manager", required: true, placeholder: "<runtime>" },
+    { label: "Frontend", required: false, placeholder: "<framework>" },
+    { label: "Issue tracker", required: false, placeholder: "<tracker>" },
+];
+
+// INTENT.md (https://www.intentdocs.com/intent-md): the product's intent, one per product, at the
+// root. Optional, so the harness neither ships nor requires one. Given its text, returns whether the
+// "# INTENT.md" title is there, the product's bold name and the prose describing it from
+// "## Product" (null when the section is missing), and whether "## MVP stories" is there; that heading
+// may run on, as in "## MVP stories — build these first". docs-check holds the file to these sections.
+function readIntent(text) {
+    const lines = text.split(/\r?\n/);
+    const h1 = lines.find(l => /^#\s/.test(l));
+    const section = name => {
+        const start = lines.findIndex(l => new RegExp(`^##\\s+${name}\\b`, "i").test(l));
+        if (start < 0) return null;
+        const end = lines.findIndex((l, i) => i > start && /^#{1,2}\s/.test(l));
+        return lines.slice(start + 1, end < 0 ? lines.length : end).join("\n").trim();
+    };
+    const body = section("Product");
+    let product = null;
+    if (body !== null) {
+        const bold = body.match(/\*\*([^*]+)\*\*/);
+        product = {
+            name: bold ? bold[1].trim().replace(/[:.]+$/, "").trim() : "",
+            purpose: body.replace(/\*\*[^*]+\*\*/, "").replace(/^[\s:.,—–-]+/, "").replace(/\s+/g, " ").trim(),
+        };
+    }
+    return { title: !!h1 && h1.trim() === "# INTENT.md", product, stories: section("MVP stories") !== null };
+}
+
+// A fact's line: a `-` or `*` bullet, then the label in bold with its colon inside or after the bold
+// (`- **Name:** Acme`, `* **Name**: Acme`). An unbolded line is prose that happens to start with the
+// word, so it is not a fact. The value is null when no line carries the label.
+function lineValue(text, label) {
+    if (text === null) return null;
+    const escaped = label.replace(/[/.*+?^${}()|[\]\\]/g, "\\$&");
+    const m = text.match(new RegExp(`^\\s*[-*]\\s*\\*\\*${escaped}(?::\\*\\*|\\*\\*:)[ \\t]*(.*)$`, "mi"));
+    return m ? m[1].trim() : null;
+}
+
+// A value is unanswered when nothing is left once every <placeholder> is removed: `<language>` and
+// `<language> <version>` are the template, `C#` and `see <link> in docs/` are answers, kept whole.
+const answer = value => value.replace(/<[^>]*>/g, "").trim() ? value : "";
+
+// Every fact, from the texts of MEMORY.md and INTENT.md, each null when that file is absent. A label
+// maps to null when nothing gives it, "" when it is unanswered, and the trimmed value otherwise.
+// With an INTENT.md, Name and Purpose come from its "## Product" alone: a MEMORY.md line for either
+// is ignored, so a stale copy there never stands in for the product's own words.
+function readFacts({ memory = null, intent = null } = {}) {
+    const product = intent === null ? null : readIntent(intent).product;
+    const facts = {};
+    for (const { label, intent: owned } of FACTS) {
+        const raw = owned && intent !== null
+            ? (product ? product[label.toLowerCase()] : null)
+            : lineValue(memory, label);
+        facts[label] = raw === null ? null : answer(raw);
+    }
+    return facts;
+}
+
+// readFacts() for the files on disk under a root. A reader holding the texts some other way, such as
+// docs-check through a repo view, calls readFacts() with them instead.
+function readFactsAt(root) {
+    const read = file => {
+        const at = path.resolve(root, file);
+        return fs.existsSync(at) ? fs.readFileSync(at, "utf8") : null;
+    };
+    return readFacts({ memory: read(MEMORY), intent: read(INTENT) });
+}
+
+// The required labels readFacts() found no answer for, in FACTS order.
+const unanswered = facts => FACTS.filter(f => f.required && !facts[f.label]).map(f => f.label);
+
+// MEMORY.md's fact lines as the installer lays them down, every one a placeholder. Beside an
+// INTENT.md, Name and Purpose give way to a line saying where they are.
+function skeleton(hasIntent) {
+    const lines = FACTS.filter(f => !(hasIntent && f.intent)).map(f => `- **${f.label}:** ${f.placeholder}`);
+    return hasIntent ? [`The name and purpose are in \`${INTENT}\`, under \`## Product\`.`, "", ...lines] : lines;
+}
+
+module.exports = { FACTS, MEMORY, INTENT, readFacts, readFactsAt, unanswered, readIntent, skeleton };

package/scripts/repo-view.js

@@ -0,0 +1,101 @@
+// scripts/repo-view.js
+// A repo as a check reads it: four questions about repo-relative paths, answered from the working
+// tree, from Git's index, or from a map a test builds. A check that takes a view reads what a
+// commit will record as easily as what is on disk, and a test hands it the files it is about
+// instead of building a tree or pointing it at a file that does not exist.
+//   exists(rel)   a file, or a folder holding one
+//   isFile(rel)   a file
+//   read(rel)     its text, or null when there is none
+//   list(rel)     the names directly inside a folder, sorted; [] when there is none
+// Paths are repo-relative with forward slashes. Nothing here writes, prints or exits.
+// indexModes() is the one reader of `git ls-files -s`: the mode Git records is how the harness
+// tells a symlink (120000) and an executable (100755) from a plain file.
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// stdout alone and untrimmed, since a blob's trailing newline is part of its text.
+const git = (dir, args) => spawnSync("git", ["-c", "core.quotepath=off", ...args], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+
+const norm = rel => path.posix.normalize(String(rel).split(path.sep).join("/")).replace(/^\.\/?$|\/+$/g, "");
+
+// Every path Git's index holds in `dir`, optionally under `paths` (pathspecs), as
+// { file, mode, object, link, exec }. null when `dir` is not a git checkout.
+function indexModes(dir, paths = []) {
+    const r = git(dir, ["ls-files", "-s", "-z", ...(paths.length ? ["--", ...paths] : [])]);
+    if (r.status !== 0) return null;
+    return r.stdout.split("\0").filter(Boolean).map(entry => {
+        const [meta, file] = entry.split("\t");
+        const [mode, object] = meta.split(" ");
+        return { file, mode, object, link: mode === "120000", exec: mode === "100755" };
+    });
+}
+
+// A view over a set of files known up front, each read on first use. Folders are whatever the
+// paths imply, which is all an index or a map has of them.
+function filesView(loaders) {
+    const cache = new Map();
+    const under = rel => rel ? rel + "/" : "";
+    return {
+        exists: rel => { rel = norm(rel); return loaders.has(rel) || [...loaders.keys()].some(f => f.startsWith(under(rel))); },
+        isFile: rel => loaders.has(norm(rel)),
+        read: rel => {
+            rel = norm(rel);
+            if (!loaders.has(rel)) return null;
+            if (!cache.has(rel)) cache.set(rel, loaders.get(rel)());
+            return cache.get(rel);
+        },
+        list: rel => {
+            const prefix = under(norm(rel));
+            const names = new Set([...loaders.keys()].filter(f => f.startsWith(prefix)).map(f => f.slice(prefix.length).split("/")[0]));
+            return [...names].sort();
+        },
+    };
+}
+
+// The files on disk under `root`. A path outside it resolves as it stands, which is what a cited
+// `../` path means.
+function worktree(root) {
+    const at = rel => path.resolve(root, String(rel));
+    const stat = rel => { try { return fs.statSync(at(rel)); } catch { return null; } };
+    return {
+        exists: rel => !!stat(rel),
+        isFile: rel => !!(stat(rel) || { isFile: () => false }).isFile(),
+        read: rel => { const s = stat(rel); return s && s.isFile() ? fs.readFileSync(at(rel), "utf8") : null; },
+        list: rel => { const s = stat(rel); return s && s.isDirectory() ? fs.readdirSync(at(rel)).sort() : []; },
+    };
+}
+
+// Git's index at `root`, limited to `paths` when given: what the next commit records, and nothing
+// the working tree holds besides. Throws when `root` is not a git checkout, since an index nobody
+// could read is not an empty one.
+function index(root, paths = []) {
+    const rows = indexModes(root, paths);
+    if (!rows) throw new Error(`could not read the git index in ${root}`);
+    const blob = object => {
+        const r = git(root, ["cat-file", "blob", object]);
+        if (r.status !== 0) throw new Error(`could not read blob ${object}: ${r.stderr}`);
+        return r.stdout;
+    };
+    return filesView(new Map(rows.map(row => [row.file, () => blob(row.object)])));
+}
+
+// What a commit will record for `paths`, and the working tree for everything else. Each of `paths`
+// is read from the index when the index holds anything under it, and from the disk when it holds
+// nothing: a repo that keeps one of them untracked still gets a meaningful answer.
+function staged(root, paths) {
+    const idx = index(root, paths), disk = worktree(root);
+    const owner = rel => { rel = norm(rel); return paths.map(norm).find(p => rel === p || rel.startsWith(p + "/")); };
+    const pick = rel => { const p = owner(rel); return p !== undefined && idx.exists(p) ? idx : disk; };
+    return {
+        exists: rel => pick(rel).exists(rel),
+        isFile: rel => pick(rel).isFile(rel),
+        read: rel => pick(rel).read(rel),
+        list: rel => pick(rel).list(rel),
+    };
+}
+
+// The files a test names, path -> text, and nothing else.
+const fromMap = files => filesView(new Map(Object.entries(files).map(([f, text]) => [norm(f), () => text])));
+
+module.exports = { worktree, index, staged, fromMap, indexModes };