@holmes-lab/holmes-kit 0.10.1 → 0.12.0

package/dist/holmes/update/upgrade-plan.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_AUTO_REPIN_ENV = void 0;
+exports.planUpgrade = planUpgrade;
+exports.repinDecision = repinDecision;
+// @implements A-SPEC-543.2
+const update_notice_1 = require("./update-notice");
+/**
+ * @implements A-SPEC-543.2
+ * Pure: decide whether an upgrade runs and what it touches. Unknown latest is a noop (silence is not
+ * an install), and so is an equal or OLDER latest — upgrade never plans a downgrade. A 'run' plan
+ * carries the registry's workspaces verbatim as the re-pin list; an empty list is still a valid run
+ * (install-only, first machine).
+ */
+function planUpgrade(a) {
+    if (a.latest === null) {
+        return { kind: 'noop', reason: 'latest version unknown (registry unreachable and no cache) — nothing to plan' };
+    }
+    if ((0, update_notice_1.compareSemver)(a.latest, a.current) <= 0) {
+        return { kind: 'noop', reason: `already up to date (current ${a.current}, latest ${a.latest})` };
+    }
+    return { kind: 'run', current: a.current, latest: a.latest, installMode: a.installMode, repins: a.registry.workspaces };
+}
+/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
+exports.NO_AUTO_REPIN_ENV = 'HOLMES_NO_AUTO_REPIN';
+/**
+ * @implements A-SPEC-543.3
+ * Pure: should a session auto re-pin this workspace's derived artifacts? Only when the pin is a real
+ * version, the installed package is strictly NEWER (forward-only — never a downgrade or a match), and
+ * the operator has not opted out. The install was the user's explicit choice; this completes it at
+ * the workspace level. A decision always says why.
+ */
+function repinDecision(a) {
+    const optOut = a.env[exports.NO_AUTO_REPIN_ENV];
+    if (typeof optOut === 'string' && optOut !== '') {
+        return { repin: false, reason: `${exports.NO_AUTO_REPIN_ENV} set — auto re-pin disabled` };
+    }
+    if (a.pinned === null) {
+        return { repin: false, reason: 'workspace pin unreadable — no re-pin on an unknown pin' };
+    }
+    if ((0, update_notice_1.compareSemver)(a.installed, a.pinned) > 0) {
+        return { repin: true, reason: `installed ${a.installed} is newer than pin ${a.pinned} — re-pin forward` };
+    }
+    return { repin: false, reason: `pin ${a.pinned} is up to date with installed ${a.installed} — no re-pin` };
+}

package/dist/holmes/update/workspaces.d.ts

@@ -0,0 +1,35 @@
+/** One wired workspace, as the registry answers "what is wired NOW" (not a history). */
+export interface WorkspaceEntry {
+    target: string;
+    agents: string[];
+    version: string;
+    ts: string;
+}
+export interface Registry {
+    version: 1;
+    workspaces: WorkspaceEntry[];
+}
+export declare const EMPTY_REGISTRY: Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Parse the registry file's content. `null` (absent), broken JSON, or a wrong shape all yield the
+ * empty registry — best-effort by design: a broken registry restarts empty rather than ever breaking
+ * wiring (the recorder that feeds it is swallowed too).
+ */
+export declare function readRegistry(raw: string | null): Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Pure: replace the entry whose `target` matches (path-identity dedup — the registry answers what is
+ * wired NOW), append otherwise, preserve order, never mutate the inputs.
+ */
+export declare function mergeWorkspaceEntry(reg: Registry, entry: WorkspaceEntry): Registry;
+/**
+ * @implements A-SPEC-543.1
+ * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
+ * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ */
+export declare function recordWorkspace(home: string, entry: WorkspaceEntry, io?: {
+    read: (p: string) => string;
+    write: (p: string, c: string) => void;
+    mkdir: (p: string) => void;
+}): boolean;

package/dist/holmes/update/workspaces.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_REGISTRY = void 0;
+exports.readRegistry = readRegistry;
+exports.mergeWorkspaceEntry = mergeWorkspaceEntry;
+exports.recordWorkspace = recordWorkspace;
+// @implements A-SPEC-543.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.EMPTY_REGISTRY = { version: 1, workspaces: [] };
+/**
+ * @implements A-SPEC-543.1
+ * Parse the registry file's content. `null` (absent), broken JSON, or a wrong shape all yield the
+ * empty registry — best-effort by design: a broken registry restarts empty rather than ever breaking
+ * wiring (the recorder that feeds it is swallowed too).
+ */
+function readRegistry(raw) {
+    if (raw === null)
+        return { version: 1, workspaces: [] };
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed?.workspaces))
+            return { version: 1, workspaces: [] };
+        const workspaces = parsed.workspaces.filter((w) => !!w && typeof w.target === 'string'
+            && Array.isArray(w.agents)
+            && typeof w.version === 'string'
+            && typeof w.ts === 'string');
+        return { version: 1, workspaces };
+    }
+    catch {
+        return { version: 1, workspaces: [] };
+    }
+}
+/**
+ * @implements A-SPEC-543.1
+ * Pure: replace the entry whose `target` matches (path-identity dedup — the registry answers what is
+ * wired NOW), append otherwise, preserve order, never mutate the inputs.
+ */
+function mergeWorkspaceEntry(reg, entry) {
+    const replaced = reg.workspaces.some((w) => w.target === entry.target);
+    return {
+        version: 1,
+        workspaces: replaced
+            ? reg.workspaces.map((w) => (w.target === entry.target ? entry : w))
+            : [...reg.workspaces, entry],
+    };
+}
+/**
+ * @implements A-SPEC-543.1
+ * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
+ * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ */
+function recordWorkspace(home, entry, io = {
+    read: (p) => fs.readFileSync(p, 'utf8'),
+    write: (p, c) => fs.writeFileSync(p, c),
+    mkdir: (p) => { fs.mkdirSync(p, { recursive: true }); },
+}) {
+    try {
+        const dir = path.join(home, '.holmes');
+        const file = path.join(dir, 'workspaces.json');
+        let raw = null;
+        try {
+            raw = io.read(file);
+        }
+        catch {
+            raw = null;
+        }
+        const merged = mergeWorkspaceEntry(readRegistry(raw), entry);
+        io.mkdir(dir);
+        io.write(file, `${JSON.stringify(merged, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",