@salaros/ai-harness 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salaros/ai-harness",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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"

package/scripts/update-harness.js

@@ -340,8 +340,9 @@ function policies(templateDir) {
 // the docs site is the case, useful to some projects and dead weight in the rest.
 // `wants` answers whether the run asked for an optional part, so the table's meaning does not depend
 // on the process's own argv and a test can ask what a repo would get either way.
+const rowFor = (rows, file) => rows.find(r => r.path.endsWith("/") ? file.startsWith(r.path) : file === r.path);
 function policyFor(rows, file, wants) {
-    const row = rows.find(r => r.path.endsWith("/") ? file.startsWith(r.path) : file === r.path);
+    const row = rowFor(rows, file);
     if (!row) return "merge";               // anything the upstream ships and nobody classified is harness
     if (!row.policy.startsWith("optional:")) return row.policy;
     return wants(row.policy.slice("optional:".length)) ? "seed" : "template";
@@ -402,12 +403,31 @@ function threeWay(base, ours, theirs) {
         fs.writeFileSync(f("base"), base);
         fs.writeFileSync(f("ours"), ours);
         fs.writeFileSync(f("theirs"), theirs);
-        const r = lib.run("git", ["merge-file", "-L", "yours", "-L", "upstream (base)", "-L", "upstream (new)",
+        const r = lib.run("git", ["merge-file", "--diff3", "-L", "yours", "-L", "upstream (base)", "-L", "upstream (new)",
             f("ours"), f("base"), f("theirs")]);
-        return { text: fs.readFileSync(f("ours"), "utf8"), conflicts: r.status > 0, failed: r.status < 0 };
+        if (r.status < 0) return { text: "", conflicts: false, failed: true };
+        return settleDropped(fs.readFileSync(f("ours"), "utf8"));
     } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
+// The conflicts of a --diff3 merge, each settled or written the way this script always has: the
+// project's side and the upstream's, no base. A conflict whose project side shares no line with the
+// base is a section the project dropped or replaced with its own, as a project does with the harness's
+// part of .gitignore, and it stays dropped: the upstream's edit is to text the project no longer has.
+// A conflict with an empty base is both sides adding at one place, and stays a conflict.
+function settleDropped(text) {
+    const HUNK = /^<{7} yours\n([\s\S]*?)^\|{7} upstream \(base\)\n([\s\S]*?)^={7}\n([\s\S]*?)^>{7} upstream \(new\)\n/gm;
+    const lines = s => s.split("\n").map(l => l.trim()).filter(Boolean);
+    let conflicts = 0;
+    const out = text.replace(HUNK, (all, ours, base, theirs) => {
+        const was = new Set(lines(base));
+        if (was.size && !lines(ours).some(l => was.has(l))) return ours;
+        conflicts++;
+        return `<<<<<<< yours\n${ours}=======\n${theirs}>>>>>>> upstream (new)\n`;
+    });
+    return { text: out, conflicts: conflicts > 0, failed: false };
+}
+
 // Git checks a repo out with the platform's line endings, so a Windows working copy holds CRLF where
 // the upstream stores LF. Compared raw, every line of every file reads as changed: a copy nobody
 // touched reports as edited, and a real edit is buried in a whole-file conflict nobody can read. So
@@ -468,9 +488,12 @@ function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recover
     let from = hasBase ? baseText() : null;
     if (from === null && policy === "reconcile") from = recoverBase(ours);
     if (from === null && policy === "reconcile") from = "";
+    // A union table merges by row whether or not there is a base, and even an untouched copy goes
+    // through that merge: it may hold a row the upstream dropped and the project still needs.
+    if (from === null && policy === "union") from = "";
     if (from === null) return keep;
 
-    if (ours === from) return { outcome: "written", bucket: "written", text: asFound(theirs, crlf) };
+    if (ours === from && policy !== "union") return { outcome: "written", bucket: "written", text: asFound(theirs, crlf) };
     const merged = merge(from, ours, theirs);
     if (merged.failed) return { outcome: "yours, merge failed", bucket: "kept", text: null };
     const result = asFound(merged.text, crlf);
@@ -482,6 +505,31 @@ function decideText({ policy, raw, theirs, hasBase, adopt }, { baseText, recover
     return { outcome: "merged", bucket: "merged", text: result };
 }
 
+// A union table, merged row by row rather than line by line: a row is keyed by its first
+// tab-separated column, and the table is a set of them, so there is nothing to conflict over.
+// The upstream's comments and order come first. Each of its rows is the project's where only the
+// project changed it, or where both did, and the upstream's otherwise; a row the project deleted
+// stays deleted. Every row of the project's the upstream lacks follows, whether the project added it
+// or the upstream dropped it: the licence of a skill the upstream stopped shipping is still needed
+// here, because the skills merge keeps the skill. All three texts are LF; `base` is null without a
+// receipt, and then the project's copy of a row wins.
+function mergeRows(base, ours, theirs) {
+    const rows = text => new Map((text || "").split("\n").filter(l => l.trim() && !l.startsWith("#")).map(l => [l.split("\t")[0], l]));
+    const was = rows(base), mine = rows(ours), up = rows(theirs);
+    const out = [];
+    for (const line of theirs.split("\n")) {
+        const key = line.split("\t")[0];
+        if (!line.trim() || line.startsWith("#") || !up.has(key)) { out.push(line); continue; }
+        const o = mine.get(key), b = was.get(key);
+        if (o === undefined) { if (b === undefined) out.push(line); continue; }
+        out.push(o === b ? line : o);
+    }
+    const extra = [...mine].filter(([key]) => !up.has(key)).map(([, line]) => line);
+    if (!extra.length) return out.join("\n");
+    while (out.length && out[out.length - 1] === "") out.pop();
+    return [...out, ...extra, ""].join("\n");
+}
+
 // ---------------------------------------------------------------- the plan
 //
 // Everything a run will do to the target, decided before anything is written: an install rewrites
@@ -516,8 +564,13 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
     }
     // --adopt is how a repo whose harness files are wrong gets them replaced, and the commonest way to
     // reach that state is an install that wrote the receipt and kept a stale harness. So the run stays
-    // open at the recorded commit, and main() answers "nothing to update" only without --adopt.
-    if (previous && base === head) notices.push(`harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`);
+    // open at the recorded commit, and main() answers "nothing to update" only without --adopt. An
+    // optional part asked for by its flag keeps it open too, and then only that part has anything to do.
+    if (previous && base === head) {
+        notices.push(options.adopt
+            ? `harness is already at ${head.slice(0, 8)} (${ref}); --adopt takes every harness file again anyway`
+            : `harness is already at ${head.slice(0, 8)} (${ref}); installing only the optional part(s) asked for`);
+    }
 
     // A repo carrying a harness from before harness-lock.json existed. Without a base the rule below
     // keeps every file that is already there, which protects the project's work and also preserves
@@ -576,7 +629,12 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
         // does not have names something that was never there.
         if (policy === "skip") { line(exists ? "yours" : "absent", exists ? "skipped" : null); continue; }
         if (policy === "seed") {
+            // A seed file the recorded commit already shipped was laid down then, so its absence is
+            // the project deleting it, and it stays deleted. An optional part is the exception: its
+            // flag is the project asking for it now, whatever an earlier run left out.
+            const asked = (rowFor(rows, file) || { policy: "" }).policy.startsWith("optional:");
             if (exists) line("yours", "kept");
+            else if (!asked && base !== null && upstream.blob(base, file) !== null) line("deleted here", null);
             else line("created", "seeded", { write: theirs });
             continue;
         }
@@ -589,22 +647,30 @@ function plan({ upstream, target, rows, head, ref, previous, options, stamp = {}
             : decideText({ policy, raw: held, theirs, hasBase, adopt: options.adopt }, {
                 baseText: () => upstream.blob(base, file),
                 recoverBase: ours => recoverBase(upstream, file, ours),
-                merge: threeWay,
+                // A union table has no lines to conflict over, and no base means the project's rows win.
+                merge: policy === "union"
+                    ? (from, ours, up) => ({ text: mergeRows(from, ours, up), conflicts: false, failed: false })
+                    : threeWay,
             });
         line(outcome, bucket, text === null ? {} : { write: text });
     }
 
     add({ phase: "skeletons a project starts with" });
     const hasIntent = target.exists(projectFacts.INTENT);
+    // The receipt lists the skeletons its run knew, so one missing on an update is one the project
+    // deleted, and it stays deleted; a skeleton added since still arrives. A receipt from before the
+    // list is taken to know them all, which every install since the skeletons began has laid down.
+    const known = new Set(previous && base !== null ? previous.skeletons || Object.keys(SKELETONS) : []);
     for (const [file, lines] of Object.entries(SKELETONS)) {
         if (target.exists(file)) add({ file, policy: "seed", mode: "100644", outcome: "yours", bucket: null });
+        else if (known.has(file)) add({ file, policy: "seed", mode: "100644", outcome: "deleted here", bucket: null });
         else add({ file, policy: "seed", mode: "100644", outcome: "created", bucket: "seeded", write: skeletonLines(file, lines, hasIntent).join("\n") });
     }
 
     add({ phase: "skills, merged by name" });
     entries.push(...planSkills(upstream, target, head, skills));
 
-    add({ file: LOCK, silent: true, write: JSON.stringify({ template: TEMPLATE, ref, commit: head, ...stamp }, null, 2) + "\n" });
+    add({ file: LOCK, silent: true, write: JSON.stringify({ template: TEMPLATE, ref, commit: head, ...stamp, skeletons: Object.keys(SKELETONS) }, null, 2) + "\n" });
     return { entries, notices, base };
 }
 
@@ -800,6 +866,13 @@ function report({ entries, base, head, ref, target, check, options }) {
 
 // ---------------------------------------------------------------- the run
 
+// Whether the run has nothing to do: the receipt already names the upstream's head, and neither
+// --adopt nor the flag of an optional part asks for more. The first --astro-docs usually comes after
+// the harness is current, so an optional part is something to install even at the recorded commit.
+function upToDate(previous, head, options, optional) {
+    return !!previous && previous.commit === head && !options.adopt && !optional.some(name => options.wants(name));
+}
+
 // Returns the exit code, and throws Stop for a run that could not start.
 function main(args) {
     const options = parseOptions(args);
@@ -821,7 +894,7 @@ function main(args) {
         const unknown = unknownArgs(args, optional);
         if (unknown.length) fail(`unknown argument(s): ${unknown.join(" ")}. Nothing was written; run with --help for the options.`);
         const head = at(templateDir, ["rev-parse", "HEAD"]).output.trim();
-        if (previous && previous.commit === head && !options.adopt) {
+        if (upToDate(previous, head, options, optional)) {
             say(`harness is already at ${head.slice(0, 8)} (${ref}); nothing to update`);
             return 0;
         }
@@ -848,7 +921,7 @@ function main(args) {
 // The plan and the decisions under it, so the suite can put a case in and read the answer out rather
 // than building a git checkout to reach one branch. apply() is here for its dry run, which prints and
 // writes nothing; main() writes to somebody's repository and is reached through the command line.
-module.exports = { installerStamp, unknownArgs, mistypedArgs, usage, parseOptions, policyFor, plan, apply, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
+module.exports = { installerStamp, upToDate, mergeRows, settleDropped, unknownArgs, mistypedArgs, usage, parseOptions, policyFor, plan, apply, decideText, decideBinary, lineCounts, overlap, NEAREST, skeletonLines };
 
 if (require.main === module) {
     try { process.exitCode = main(process.argv.slice(2)); }