@aron98/load-lock 1.4.0 → 1.6.0

package/dist/shared/protocol.d.ts

@@ -11,6 +11,9 @@
  *           the extra field (forward-compatible); newer daemons use it
  *           for the update handshake: a client strictly newer than the
  *           running daemon triggers a daemon self-restart (issue #34).
+ *           Since #52 the envelope also carries "clientRoot" (the client
+ *           copy's package root); the daemon records it as a known
+ *           runtime copy (runtimes.json). Also ignored by older daemons.
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}
@@ -139,6 +142,8 @@ export interface OwnerEntrySnapshot extends EntrySnapshot {
     permitToken?: string;
 }
 export interface JournalEntry {
+    /** Persisted format version of the writer (issue #51); absent before versioning. */
+    formatVersion?: number;
     requestId: string;
     pool: string;
     agentId: string;
@@ -438,3 +443,20 @@ export interface HolderDiag {
         note: string;
     };
 }
+export declare const HOOK_ONCE_DEFAULT_TTL_MS = 60000;
+export declare const HOOK_ONCE_MAX_TTL_MS: number;
+export interface HookOnceParams {
+    harness: string;
+    sessionId: string;
+    event: string;
+    /** Distinguishes legitimate repeats within one session (e.g. SessionStart source, offer token). */
+    occurrence?: string;
+    /** Key lifetime, ms (clamped to [1s, HOOK_ONCE_MAX_TTL_MS]); ignored with hold. */
+    ttlMs?: number;
+    /** Hold the key until this connection closes instead of a TTL. */
+    hold?: boolean;
+}
+export interface HookOnceResult {
+    /** True when the caller is the first for this key and should act. */
+    first: boolean;
+}

package/dist/shared/protocol.js

@@ -11,6 +11,9 @@
  *           the extra field (forward-compatible); newer daemons use it
  *           for the update handshake: a client strictly newer than the
  *           running daemon triggers a daemon self-restart (issue #34).
+ *           Since #52 the envelope also carries "clientRoot" (the client
+ *           copy's package root); the daemon records it as a known
+ *           runtime copy (runtimes.json). Also ignored by older daemons.
  * Response: {"id": <number>, "ok": true, "result": {...}}
  *           {"id": <number>, "ok": false, "error": {"code": "...", "message": "..."}}
  * Watch push: {"event": true, ...event fields...}
@@ -25,3 +28,15 @@ export class ProtocolError extends Error {
         this.details = details;
     }
 }
+// ---------------------------------------------------------------------------
+// hook_once (issue #54): daemon-side dedupe for duplicate hook wiring.
+// Loose hooks + plugin hooks (or two plugins) fire the same harness hook
+// more than once. Each hook handler first claims the key
+// (harness, sessionId, event, occurrence); only the first caller acts, the
+// rest exit 0 silently. Keys are in-memory only (never persisted, gone on
+// daemon restart) and expire after ttlMs — or, with hold, live exactly as
+// long as the calling connection (long-running await-offer watchers).
+// Daemons without the method answer `unknown method`; callers then act as
+// before (no dedupe).
+export const HOOK_ONCE_DEFAULT_TTL_MS = 60_000;
+export const HOOK_ONCE_MAX_TTL_MS = 10 * 60_000;

package/dist/shared/runtimes.d.ts

@@ -0,0 +1,41 @@
+export interface RuntimeCopy {
+    /** Real path of the copy's package root. */
+    path: string;
+    /** Version read from the copy's package.json (not from the client). */
+    version: string;
+    /** Epoch ms of the last handshake from this copy. */
+    lastSeen: number;
+}
+/** daemon.json contents (fields beyond pid/startedAt/socket since #52). */
+export interface DaemonInfo {
+    pid: number;
+    startedAt: number;
+    socket: string;
+    /** Package root the daemon runs from (since #52). */
+    packageRoot?: string;
+    /** Package version the daemon runs (since #52). */
+    version?: string;
+}
+/** Cap on remembered copies; the least recently seen are dropped first. */
+export declare const MAX_RUNTIMES = 32;
+export declare function runtimesPath(stateDir: string): string;
+/**
+ * Validate a package root: it must hold a package.json naming
+ * @aron98/load-lock with a string version. Returns the real path and the
+ * on-disk version, or null.
+ */
+export declare function inspectPackageRoot(root: string): {
+    path: string;
+    version: string;
+} | null;
+/** Known copies from the state dir, dropping entries whose path is gone. */
+export declare function loadRuntimes(stateDir: string): RuntimeCopy[];
+export declare function saveRuntimes(stateDir: string, copies: RuntimeCopy[]): void;
+/**
+ * Merge one sighting into the list (dedupe by real path, newest first,
+ * capped). Returns the new list, or null when the root is not a valid
+ * load-lock copy.
+ */
+export declare function mergeRuntime(copies: RuntimeCopy[], root: string, now: number): RuntimeCopy[] | null;
+/** daemon.json contents, or null when missing/unreadable. */
+export declare function readDaemonInfo(stateDir: string): DaemonInfo | null;

package/dist/shared/runtimes.js

@@ -0,0 +1,81 @@
+/**
+ * Runtime-copy bookkeeping (issue #52): which load-lock copies (package
+ * roots) have talked to this machine's daemon.
+ *
+ * The daemon records its own runtime in `daemon.json` and every copy seen
+ * via the client handshake (`clientRoot` in the request envelope) in
+ * `runtimes.json` next to it. Small entry points (skill, plugin launchers)
+ * and `doctor` read these to find an existing runtime without npx.
+ *
+ * Everything here is best-effort: unreadable/missing files yield empty
+ * lists, never a throw. A client's path hint is never trusted for the
+ * version — it is re-read from the copy's own package.json on disk.
+ */
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { PKG_NAME } from "./pkginfo.js";
+/** Cap on remembered copies; the least recently seen are dropped first. */
+export const MAX_RUNTIMES = 32;
+export function runtimesPath(stateDir) {
+    return join(stateDir, "runtimes.json");
+}
+/**
+ * Validate a package root: it must hold a package.json naming
+ * @aron98/load-lock with a string version. Returns the real path and the
+ * on-disk version, or null.
+ */
+export function inspectPackageRoot(root) {
+    try {
+        const real = realpathSync(root);
+        const pkg = JSON.parse(readFileSync(join(real, "package.json"), "utf8"));
+        if (pkg?.name !== PKG_NAME || typeof pkg.version !== "string")
+            return null;
+        return { path: real, version: pkg.version };
+    }
+    catch {
+        return null;
+    }
+}
+/** Known copies from the state dir, dropping entries whose path is gone. */
+export function loadRuntimes(stateDir) {
+    try {
+        const raw = JSON.parse(readFileSync(runtimesPath(stateDir), "utf8"));
+        const list = Array.isArray(raw?.copies) ? raw.copies : [];
+        return list.filter((c) => typeof c?.path === "string" &&
+            typeof c.version === "string" &&
+            typeof c.lastSeen === "number" &&
+            existsSync(join(c.path, "package.json")));
+    }
+    catch {
+        return [];
+    }
+}
+export function saveRuntimes(stateDir, copies) {
+    const path = runtimesPath(stateDir);
+    const tmp = join(stateDir, ".runtimes.json.tmp-" + process.pid);
+    writeFileSync(tmp, JSON.stringify({ copies }, null, 2) + "\n", { mode: 0o644 });
+    renameSync(tmp, path);
+}
+/**
+ * Merge one sighting into the list (dedupe by real path, newest first,
+ * capped). Returns the new list, or null when the root is not a valid
+ * load-lock copy.
+ */
+export function mergeRuntime(copies, root, now) {
+    const found = inspectPackageRoot(root);
+    if (!found)
+        return null;
+    const rest = copies.filter((c) => c.path !== found.path);
+    return [{ path: found.path, version: found.version, lastSeen: now }, ...rest]
+        .sort((a, b) => b.lastSeen - a.lastSeen)
+        .slice(0, MAX_RUNTIMES);
+}
+/** daemon.json contents, or null when missing/unreadable. */
+export function readDaemonInfo(stateDir) {
+    try {
+        return JSON.parse(readFileSync(join(stateDir, "daemon.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/shared/version.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Package root of THIS copy (the directory holding its package.json):
+ * dist/shared/version.js → <package root>. Sent in the request envelope as
+ * `clientRoot` and recorded by the daemon (issue #52).
+ */
+export declare function packageRoot(): string;
 /** Version of THIS copy of load-lock (the on-disk install running now). */
 export declare function packageVersion(): string;
 /**

package/dist/shared/version.js

@@ -13,6 +13,14 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 let cached;
+/**
+ * Package root of THIS copy (the directory holding its package.json):
+ * dist/shared/version.js → <package root>. Sent in the request envelope as
+ * `clientRoot` and recorded by the daemon (issue #52).
+ */
+export function packageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
 /** Version of THIS copy of load-lock (the on-disk install running now). */
 export function packageVersion() {
     if (cached === undefined) {
@@ -20,7 +28,7 @@ export function packageVersion() {
             // dist/shared/version.js → <package root>/package.json — resolves the
             // same way in the repo checkout, a global CLI install, and an
             // opencode cache copy. npm always ships package.json with the tarball.
-            const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+            const pkgPath = join(packageRoot(), "package.json");
             cached = String(JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0");
         }
         catch {

package/dist/test/ace-mcp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/ace-mcp.test.js

@@ -0,0 +1,157 @@
+/**
+ * Contract test for the ACE MCP artifact (issue #65): `ace/mcp/mcp.json`
+ * must validate against ACE's manifest schema, as found in the #64 spike,
+ * and the folder must pass ACE's file-level rules. Light: files only, no
+ * daemon. (`load-lock mcp` itself is exercised in mcp.test.ts.)
+ *
+ * Source of truth, copied verbatim below:
+ * https://github.com/TNG/ace/blob/b703410218833071800cc918cb95718e0404640a/backend/app/domain/kinds/mcp_manifest.schema.json
+ * Rules from the same revision: backend/app/domain/kinds/MCP.md (inline
+ * secrets), compliance_mcp_rule_checks_service.py (`_first_non_flag`,
+ * companion-file roots), artifact_import_zip_safety_service.py (forbidden
+ * names in a non-plugin bundle).
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ACE_MCP_DIR = join(REPO_ROOT, "ace", "mcp");
+const pkg = JSON.parse(readFileSync(join(REPO_ROOT, "package.json"), "utf8"));
+const ACE_MCP_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    required: ["name", "transport"],
+    properties: {
+        name: { type: "string", minLength: 1 },
+        description: { type: "string" },
+        transport: { type: "string", enum: ["stdio", "http", "sse"] },
+        command: { type: "string", minLength: 1 },
+        args: { type: "array", items: { type: "string" } },
+        env: { type: "object", additionalProperties: { type: "string" } },
+        cwd: { type: "string" },
+        companion_files: { type: "array", items: { type: "string" } },
+        url: { type: "string", format: "uri", pattern: "^https://" },
+        headers: { type: "object", additionalProperties: { type: "string" } },
+    },
+    additionalProperties: false,
+    oneOf: [
+        {
+            title: "Stdio (local) MCP",
+            properties: { transport: { const: "stdio" } },
+            required: ["transport", "command"],
+            not: { anyOf: [{ required: ["url"] }, { required: ["headers"] }] },
+        },
+        {
+            title: "HTTP/SSE (remote) MCP",
+            properties: { transport: { enum: ["http", "sse"] } },
+            required: ["transport", "url"],
+            not: {
+                anyOf: [
+                    { required: ["command"] },
+                    { required: ["args"] },
+                    { required: ["env"] },
+                    { required: ["cwd"] },
+                    { required: ["companion_files"] },
+                ],
+            },
+        },
+    ],
+};
+/**
+ * Minimal JSON Schema check covering exactly the keywords the ACE schema
+ * uses (`format` is annotation-only in 2020-12). Returns error paths.
+ */
+function validate(schema, v, path = "$") {
+    const errs = [];
+    const isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+    if (schema.type) {
+        const ok = schema.type === "array" ? Array.isArray(v) : schema.type === "object" ? isObj(v) : typeof v === schema.type;
+        if (!ok)
+            return [`${path}: expected ${schema.type}`];
+    }
+    if ("const" in schema && v !== schema.const)
+        errs.push(`${path}: expected ${JSON.stringify(schema.const)}`);
+    if (schema.enum && !schema.enum.includes(v))
+        errs.push(`${path}: not one of ${schema.enum.join("|")}`);
+    if (schema.minLength !== undefined && typeof v === "string" && v.length < schema.minLength)
+        errs.push(`${path}: too short`);
+    if (schema.pattern && typeof v === "string" && !new RegExp(schema.pattern, "u").test(v))
+        errs.push(`${path}: pattern`);
+    if (schema.items && Array.isArray(v))
+        v.forEach((x, i) => errs.push(...validate(schema.items, x, `${path}[${i}]`)));
+    if (isObj(v)) {
+        for (const k of schema.required ?? [])
+            if (!(k in v))
+                errs.push(`${path}: missing ${k}`);
+        for (const [k, x] of Object.entries(v)) {
+            if (schema.properties && k in schema.properties)
+                errs.push(...validate(schema.properties[k], x, `${path}.${k}`));
+            else if (schema.additionalProperties === false)
+                errs.push(`${path}.${k}: unknown field`);
+            else if (isObj(schema.additionalProperties))
+                errs.push(...validate(schema.additionalProperties, x, `${path}.${k}`));
+        }
+    }
+    if (schema.anyOf && !schema.anyOf.some((s) => validate(s, v, path).length === 0))
+        errs.push(`${path}: anyOf`);
+    if (schema.not && validate(schema.not, v, path).length === 0)
+        errs.push(`${path}: matches not`);
+    if (schema.oneOf) {
+        const n = schema.oneOf.filter((s) => validate(s, v, path).length === 0).length;
+        if (n !== 1)
+            errs.push(`${path}: matches ${n} oneOf branches`);
+    }
+    return errs;
+}
+/** ACE's `_first_non_flag`: the package the npx shim will fetch, shown to reviewers. */
+function firstNonFlag(args) {
+    return args.find((a) => !a.startsWith("-") && a !== "dlx");
+}
+const SECRET_KEY = /^(authorization|.*token|.*key|.*secret)$/i;
+const manifest = JSON.parse(readFileSync(join(ACE_MCP_DIR, "mcp.json"), "utf8"));
+test("ace mcp.json: validates against ACE's manifest schema", () => {
+    assert.deepEqual(validate(ACE_MCP_SCHEMA, manifest), []);
+});
+test("ace mcp.json: the validator rejects what ACE rejects", () => {
+    const ok = { name: "x", transport: "stdio", command: "npx" };
+    assert.deepEqual(validate(ACE_MCP_SCHEMA, ok), []);
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { ...ok, mode: "local" }), [], "unknown field (no `mode`)");
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { name: "x", transport: "stdio" }), [], "stdio without command");
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { ...ok, url: "https://x" }), [], "stdio with url");
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { ...ok, transport: "local" }), [], "bad transport");
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { ...ok, args: ["a", 1] }), [], "non-string arg");
+    assert.notDeepEqual(validate(ACE_MCP_SCHEMA, { ...ok, name: "" }), [], "empty name");
+});
+test("ace mcp.json: local npx server running `load-lock mcp` at the package.json pin", () => {
+    assert.equal(manifest.name, "load-lock");
+    assert.equal(manifest.transport, "stdio", "local only, never remote");
+    assert.equal(manifest.command, "npx");
+    assert.deepEqual(manifest.args, ["-y", `${pkg.name}@${pkg.version}`, "mcp"]);
+    // ACE's mcp_local_command_safe shows reviewers this as the fetched package.
+    assert.equal(firstNonFlag(manifest.args), `${pkg.name}@${pkg.version}`);
+    // npx runs the bin named after the unscoped package; it must be the CLI.
+    const unscoped = String(pkg.name).split("/").pop();
+    assert.equal(pkg.bin[unscoped], "dist/cli/main.js");
+    // `cwd` is dropped from ACE's install patch: never rely on it.
+    assert.equal(manifest.cwd, undefined);
+    for (const [k, v] of Object.entries(manifest.env ?? {})) {
+        if (SECRET_KEY.test(k))
+            assert.match(String(v), /\$\{[^}]+\}/, `env ${k} must be a \${VAR} placeholder`);
+    }
+});
+test("ace/mcp folder: only mcp.json + README, nothing ACE's bundle rules would flag", () => {
+    const files = readdirSync(ACE_MCP_DIR).sort();
+    assert.deepEqual(files, ["README.md", "mcp.json"]);
+    // companion_files roots (must match companion_files) and names forbidden in a non-plugin bundle.
+    for (const bad of ["bin", "scripts", "config", "references", ".claude-plugin", ".mcp.json", ".lsp.json", ".opencode"]) {
+        assert.ok(!files.includes(bad), bad);
+    }
+    assert.equal(manifest.companion_files, undefined);
+});
+test("ace mcp.json: pin is declared in scripts/check-pins.mjs", async () => {
+    const pins = (await import(pathToFileURL(join(REPO_ROOT, "scripts", "check-pins.mjs")).href));
+    assert.ok(pins.PINNED.some((e) => e.path === "ace/mcp/mcp.json" && e.kind === "spec"));
+    assert.deepEqual(pins.checkPins(REPO_ROOT, pkg.version), []);
+});

package/dist/test/ace-opencode.test.d.ts

@@ -0,0 +1 @@
+export {};