@dombaras/agent-harness 0.1.5 → 0.1.7

package/README.md

@@ -123,6 +123,19 @@ npx @dombaras/agent-harness update --target /path/to/project
   modified harness files. Your unrelated uncommitted work is never staged.
   - `--no-commit` to skip commit+push, `--no-push` to commit but not push.
   - `init` never commits.
+  - Harness-owned paths are **force-added**, so a project that gitignores deployment
+    artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the
+    harness commit instead of a raw `git add` failure that silently skips it — force-added
+    files are called out in the summary.
+- **`[Nothing-to-Update]` confirmation**: if the target is already at this CLI's version and no
+  harness-owned file changed, `update` says so explicitly, writes nothing, and makes no commit —
+  a no-op is never mistaken for a sync and never churns `.harness.json`.
+- **Downgrade guard**: `update` refuses to run on a target whose deployed harness is NEWER than
+  this CLI (e.g. deployed from a local checkout that was never published) and tells you to publish
+  that version first.
+- **Published-version check**: if this CLI's version is not the latest `dist-tags.latest` on npm,
+  `update` warns you — catches the "bumped the version and updated a project from a local
+  checkout, but never published" gap before it silently forks the projects.
 - **Non-destructive**: if a harness-owned file was modified locally since the
   last deploy (tracked by checksum in `.harness.json`), it is backed up to
   `.harness-backup/<timestamp>/` before overwrite.

package/bin/agent-harness.js

@@ -210,9 +210,12 @@ function isGitRepo(target) {
 // project's next session never sees "unexplained" modified harness files. Scoped
 // to this run's changed harness files (never `git add -A`) so unrelated uncommitted
 // work is NEVER swept in. Memory/backup files are excluded (project data / rollback).
-// Returns { committed:boolean, staged:string[], skipped:string[], pushed:boolean|null }.
+// Harness-owned paths are force-added (`-f`): target projects often gitignore
+// .agents/ .opencode/ AGENTS.md (inherited from the harness's own .gitignore), and
+// a plain `git add` would fail on the first ignored path and commit NOTHING.
+// Returns { committed:boolean, staged:string[], skipped:string[], pushed:boolean|null, forceAdded:string[] }.
 function commitHarnessChanges(target, changedRels, opts) {
-  const out = { committed: false, staged: [], skipped: [], pushed: null };
+  const out = { committed: false, staged: [], skipped: [], pushed: null, forceAdded: [] };
   if (!opts.commit) return out;
   if (!isGitRepo(target)) {
     out.skipped.push("not a git repo");
@@ -222,9 +225,13 @@ function commitHarnessChanges(target, changedRels, opts) {
     out.skipped.push("no harness files changed");
     return out;
   }
-  const addR = runGit(target, ["add", "--", ...changedRels]);
+  const ignored = runGit(target, ["check-ignore", ...changedRels]);
+  if (ignored.ok && ignored.out) {
+    out.forceAdded = ignored.out.split(/\r?\n/).filter(Boolean).map(relKey);
+  }
+  const addR = runGit(target, ["add", "-f", "--", ...changedRels]);
   if (!addR.ok) {
-    out.skipped.push("git add failed: " + addR.err);
+    out.skipped.push("git add failed: " + firstGitErrorLine(addR.err));
     return out;
   }
   const diffCached = runGit(target, ["diff", "--cached", "--name-only"]);
@@ -238,7 +245,7 @@ function commitHarnessChanges(target, changedRels, opts) {
   const message = `chore(harness): @dombaras/agent-harness ${prior}${PKG.version}`;
   const commitR = runGit(target, ["commit", "-m", message]);
   if (!commitR.ok) {
-    out.skipped.push("commit failed: " + commitR.err);
+    out.skipped.push("commit failed: " + firstGitErrorLine(commitR.err));
     return out;
   }
   out.committed = true;
@@ -247,7 +254,7 @@ function commitHarnessChanges(target, changedRels, opts) {
     if (hasRemote) {
       const pushR = runGit(target, ["push", "origin", "HEAD"]);
       out.pushed = pushR.ok;
-      if (!pushR.ok) out.skipped.push("push failed: " + pushR.err);
+      if (!pushR.ok) out.skipped.push("push failed: " + firstGitErrorLine(pushR.err));
     } else {
       out.skipped.push("no git remote to push");
     }
@@ -255,6 +262,16 @@ function commitHarnessChanges(target, changedRels, opts) {
   return out;
 }
 
+/* Pull the first real error line out of git's stderr, dropping the LF/CRLF
+ * warnings and `hint:` noise that bury the actual message. */
+function firstGitErrorLine(err) {
+  const line = String(err || "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l && !/^warning:/i.test(l) && !/^hint:/i.test(l));
+  return line || "git command failed";
+}
+
 // ---------------------------------------------------------------- deploy
 
 function backup(target, rel, content) {
@@ -274,6 +291,17 @@ async function deploy(target, opts) {
   }
   const VARIABLES = { PROJECT_NAME: projectName, PROJECT_DOMAIN: projectDomain };
 
+  // Refuse to downgrade: the target's deployed harness is newer than this CLI.
+  // This is how the "I updated from a local checkout that I never published"
+  // mistake surfaces instead of silently writing older templates over a newer
+  // deployment (and auto-committing that regression).
+  if (isUpdate && existing.version && compareVersions(existing.version, PKG.version) > 0) {
+    throw new Error(
+      `"${projectName}" has harness v${existing.version} — NEWER than this CLI (v${PKG.version}). ` +
+        `Not downgrading. Publish v${existing.version} (or this CLI) so \`update\` can re-sync from the registry.`
+    );
+  }
+
   const previousFiles = existing.files || {};
   const actions = [];
   const manifest = {};
@@ -349,6 +377,16 @@ async function deploy(target, opts) {
     }
   }
 
+  // Nothing-to-update detection: an update that made no effective change to any
+  // harness-owned file and was already running this exact version is a no-op —
+  // report it clearly instead of printing a zero-delta "Updated", and leave the
+  // target byte-for-byte untouched (no .harness.json timestamp churn, no commit).
+  const changedRelsAll = actions
+    .filter((a) => ["create", "overwrite", "overwrite (backup)", "merge"].includes(a.kind))
+    .map((a) => a.rel);
+  const nothingToUpdate =
+    !!isUpdate && changedRelsAll.length === 0 && compareVersions(existing.version || "0", PKG.version) === 0;
+
   const config = {
     version: PKG.version,
     projectName,
@@ -357,22 +395,13 @@ async function deploy(target, opts) {
     updatedAt: new Date().toISOString(),
     files: manifest,
   };
-  if (!dryRun) {
+  if (!dryRun && !nothingToUpdate) {
     fs.writeFileSync(path.join(target, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
   }
 
-  // Nothing-to-update detection: an update that made no effective change to any
-  // harness-owned file and was already running this exact version is a no-op —
-  // still report it clearly instead of printing a zero-delta "Updated".
-  const changedRelsAll = actions
-    .filter((a) => ["create", "overwrite", "overwrite (backup)", "merge"].includes(a.kind))
-    .map((a) => a.rel);
-  const nothingToUpdate =
-    !!isUpdate && changedRelsAll.length === 0 && compareVersions(existing.version || "0", PKG.version) === 0;
-
   // Auto-commit only this run's changed harness-owned files (update only).
   let commitResult = null;
-  if (isUpdate && !dryRun) {
+  if (isUpdate && !dryRun && !nothingToUpdate) {
     const changedRels = changedRelsAll.filter(
       (r) => !r.startsWith(".agents/memory/") && !r.startsWith(".harness-backup/")
     );
@@ -404,10 +433,22 @@ function summarize(actions) {
 
 function printSummary(result, isUpdate) {
   const { projectName, actions, dryRun } = result;
+
+  if (isUpdate && result.nothingToUpdate) {
+    console.log(
+      `\n[Nothing-to-Update] agent-harness v${PKG.version}: "${projectName}" is already at ` +
+        `v${result.priorVersion || PKG.version} and no harness-owned file changed.`
+    );
+    return;
+  }
+
   const verb = isUpdate
     ? (dryRun ? "Would update" : "Updated")
     : (dryRun ? "Would initialize" : "Initialized");
   console.log(`\nagent-harness v${PKG.version} ${verb.toLowerCase()} "${projectName}"` + (dryRun ? " (dry run)" : ""));
+  if (isUpdate && result.priorVersion && result.priorVersion !== PKG.version) {
+    console.log(`  harness: v${result.priorVersion} -> v${PKG.version}`);
+  }
   for (const a of actions) console.log(`  [${a.kind}] ${a.rel}`);
   const counts = summarize(actions);
   console.log(
@@ -417,6 +458,22 @@ function printSummary(result, isUpdate) {
   );
 }
 
+/* Best-effort warning: when this CLI's version is not the latest published on
+ * the registry, flag it. This catches the "bumped + ran update from a local
+ * checkout, but never published" silent gap. */
+function printUnpublishedWarning() {
+  const published = publishedLatestVersion();
+  if (published == null || published === "" || published === PKG.version) return;
+  const cmp = compareVersions(PKG.version, published);
+  if (cmp <= 0) return;
+  console.log(
+    `\n  WARNING: this CLI is v${PKG.version}, but the latest version published on ` +
+      `npm is v${published}. If you ran this from a local checkout, the changes were ` +
+      `NOT published — Publish first, then \`update\` other projects, or they will ` +
+      `branch off an older harness.`
+  );
+}
+
 function printNextSteps() {
   console.log("  Next steps:");
   console.log("   1. Fill in `.agents/memory/domain-map.md`, `.agents/memory/stack-versions.md`,");
@@ -487,6 +544,7 @@ async function update(target, flags) {
     push: !flags["--no-commit"] && !flags["--no-push"],
   });
   printSummary(result, true);
+  printUnpublishedWarning();
   printCommitResult(result);
 }
 
@@ -496,6 +554,12 @@ function printCommitResult(result) {
   console.log("");
   if (c.committed) {
     console.log("  committed harness files: " + c.staged.join(", "));
+    if (c.forceAdded.length) {
+      console.log(
+        "  force-added (gitignored in this project, but harness-owned): " +
+          c.forceAdded.join(", ")
+      );
+    }
     console.log(
       c.pushed === true
         ? "  pushed to origin."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"