@jaybeeuu/agent-cortex 1.40.0 → 1.41.0

package/test/pi-installer.test.mjs

@@ -1,7 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtemp, mkdir, writeFile, rm, readFile, readdir, stat } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { mkdtemp, mkdir, writeFile, rm, readFile, readdir, stat, lstat, symlink } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { installPi } from "../bin/installers/pi.mjs";
@@ -63,10 +63,29 @@ async function writeFixture(fx, relPath, content) {
   await writeFile(p, content);
 }
 
-/** Seed a minimal but realistic package tree (agents + token-map + skills). */
+/** Template pi settings the fixture package ships (defaults the installer merges). */
+function defaultPiSettings() {
+  return {
+    packages: [{ source: "../../src/agent-cortex", skills: [] }, "npm:pi-web-access@0.10.7"],
+    defaultModel: "template/model",
+    theme: "dark",
+    tinyModel: { model: "template/tiny", maxNameLength: 40 },
+  };
+}
+
+function defaultPiKeybindings() {
+  return { "tui.input.newLine": ["shift+enter"] };
+}
+
+/** Seed a minimal but realistic package tree (agents + token-map + skills + pi templates). */
 async function seedPackage(fx, opts = {}) {
-  const { agents = {}, skills = {}, tokenMap: map, version } = opts;
+  const { agents = {}, skills = {}, tokenMap: map, version, packages } = opts;
   await writeFixture(fx, "token-map.json", JSON.stringify(map ?? tokenMap(version ? { version } : {})));
+  if (packages) {
+    await writeFixture(fx, "package.json", JSON.stringify({ name: "fixture", pi: { packages } }));
+  }
+  await writeFixture(fx, "pi/settings.json", JSON.stringify(opts.piSettings ?? defaultPiSettings(), null, 2));
+  await writeFixture(fx, "pi/keybindings.json", JSON.stringify(opts.piKeybindings ?? defaultPiKeybindings(), null, 2));
   for (const [name, def] of Object.entries(agents)) {
     await writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
     await writeFixture(
@@ -243,6 +262,105 @@ describe("installPi — agent composition", () => {
   });
 });
 
+// ─── Third-party package provisioning ────────────────────────────────────────
+
+describe("installPi — package provisioning", () => {
+  function recordingRunner() {
+    const calls = [];
+    return {
+      calls,
+      runInstall: async (source) => {
+        calls.push(source);
+        return { ok: true, error: null };
+      },
+    };
+  }
+
+  it("does not touch the pi package store unless provisioning is requested", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        packages: ["npm:pi-questions"],
+      });
+      const { calls, runInstall } = recordingRunner();
+
+      const result = await installPi({ root: fx.root, output: fx.output, runInstall });
+
+      assert.deepEqual(calls, []);
+      assert.equal(result.packages, null);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("installs the packages declared in the package manifest when enabled", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        packages: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+      });
+      const { calls, runInstall } = recordingRunner();
+
+      const result = await installPi({ root: fx.root, output: fx.output, provisionPackages: true, runInstall });
+
+      assert.deepEqual(calls, ["npm:pi-questions", "npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.packages.installed, ["npm:pi-questions", "npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.packages.failed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run reports the package plan without installing", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        packages: ["npm:pi-questions"],
+      });
+      const { calls, runInstall } = recordingRunner();
+
+      const result = await installPi({
+        root: fx.root,
+        output: fx.output,
+        provisionPackages: true,
+        dryRun: true,
+        runInstall,
+      });
+
+      assert.deepEqual(calls, []);
+      assert.deepEqual(result.packages.planned, ["npm:pi-questions"]);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("warns but still installs agents when a package install fails", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, {
+        agents: { alpha: { body: "# alpha" } },
+        packages: ["npm:pi-questions"],
+      });
+
+      const result = await installPi({
+        root: fx.root,
+        output: fx.output,
+        provisionPackages: true,
+        runInstall: async () => ({ ok: false, error: "offline" }),
+      });
+
+      assert.ok(await pathExists(join(fx.output, "agents", "alpha.agent.md")), "agents still installed");
+      assert.deepEqual(result.packages.failed, [{ source: "npm:pi-questions", error: "offline" }]);
+      assert.ok(result.warnings.some((w) => w.includes("npm:pi-questions")), "failure surfaced as a warning");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+});
+
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
 describe("installPi — skills", () => {
@@ -319,6 +437,227 @@ describe("installPi — output & dry-run", () => {
   });
 });
 
+// ─── Pi settings.json ────────────────────────────────────────────────────────
+
+describe("installPi — pi settings.json", () => {
+  it("writes a real settings.json with the repo path package and template keys", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      const settingsPath = join(fx.output, "settings.json");
+      assert.equal((await lstat(settingsPath)).isSymbolicLink(), false, "settings.json is a real file");
+      const settings = JSON.parse(await readFile(settingsPath, "utf-8"));
+
+      const repoEntry = settings.packages.find((p) => !(typeof p === "string" ? p : p.source).startsWith("npm:"));
+      assert.deepEqual(repoEntry.skills, [], "repo path package keeps the package filter shape");
+      assert.equal(resolve(dirname(settingsPath), repoEntry.source), fx.root, "repo path package resolves to the package root");
+      assert.ok(settings.packages.includes("npm:pi-web-access@0.10.7"), "template npm deps preserved");
+      assert.equal(settings.defaultModel, "template/model", "template key present");
+      assert.match(settings["//"], /GENERATED from pi\/settings\.json/);
+      assert.equal(result.settings.action, "written");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("preserves personal values and unknown keys while filling template defaults", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await writeFixture(
+        fx,
+        "out/settings.json",
+        JSON.stringify({
+          defaultModel: "personal/model",
+          theme: "light",
+          personalOnly: { nested: true },
+          tinyModel: { model: "personal/tiny" },
+        }),
+      );
+
+      await installPi({ root: fx.root, output: fx.output });
+
+      const settings = JSON.parse(await readFile(join(fx.output, "settings.json"), "utf-8"));
+      assert.equal(settings.defaultModel, "personal/model", "personal value wins over the template default");
+      assert.equal(settings.theme, "light", "personal value wins over the template default");
+      assert.deepEqual(settings.personalOnly, { nested: true }, "unknown key preserved");
+      assert.equal(settings.tinyModel.model, "personal/tiny", "nested personal leaf retained");
+      assert.equal(settings.tinyModel.maxNameLength, 40, "nested template default filled in");
+      assert.ok(
+        settings.packages.some((p) => !(typeof p === "string" ? p : p.source).startsWith("npm:")),
+        "packages stays CLI-managed",
+      );
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("replaces a legacy symlink with a real managed file", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await mkdir(fx.output, { recursive: true });
+      await symlink(join(fx.root, "pi", "settings.json"), join(fx.output, "settings.json"));
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.settings.action, "removed-symlink");
+      const settingsPath = join(fx.output, "settings.json");
+      assert.equal((await lstat(settingsPath)).isSymbolicLink(), false, "symlink replaced by a real file");
+      const settings = JSON.parse(await readFile(settingsPath, "utf-8"));
+      assert.ok(settings.packages.length > 0, "managed packages written");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("re-running leaves settings.json unchanged", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await installPi({ root: fx.root, output: fx.output });
+      const first = await readFile(join(fx.output, "settings.json"), "utf-8");
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.settings.action, "unchanged");
+      assert.equal(await readFile(join(fx.output, "settings.json"), "utf-8"), first);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run plans the settings write without touching the filesystem", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = await installPi({ root: fx.root, output: fx.output, dryRun: true });
+
+      assert.equal(result.settings.action, "would-write");
+      assert.equal(await pathExists(join(fx.output, "settings.json")), false, "no file written in dry-run");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run reports would-remove-symlink for a legacy symlink", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await mkdir(fx.output, { recursive: true });
+      const link = join(fx.output, "settings.json");
+      await symlink(join(fx.root, "pi", "settings.json"), link);
+
+      const result = await installPi({ root: fx.root, output: fx.output, dryRun: true });
+
+      assert.equal(result.settings.action, "would-remove-symlink");
+      assert.equal(result.settings.removedSymlink, true);
+      assert.equal((await lstat(link)).isSymbolicLink(), true, "symlink untouched in dry-run");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+});
+
+// ─── Pi keybindings.json ─────────────────────────────────────────────────────
+
+describe("installPi — pi keybindings.json", () => {
+  it("writes the template bindings as a real generated file", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      const keybindingsPath = join(fx.output, "keybindings.json");
+      assert.equal((await lstat(keybindingsPath)).isSymbolicLink(), false, "keybindings.json is a real file");
+      const keybindings = JSON.parse(await readFile(keybindingsPath, "utf-8"));
+      assert.deepEqual(keybindings["tui.input.newLine"], ["shift+enter"], "template bindings copied");
+      assert.match(keybindings["//"], /GENERATED from pi\/keybindings\.json/);
+      assert.equal(result.keybindings.action, "written");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("leaves a user-modified keybindings file alone", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await writeFixture(
+        fx,
+        "out/keybindings.json",
+        JSON.stringify({ "tui.input.newLine": ["ctrl+j"] }, null, 2),
+      );
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.keybindings.action, "skipped");
+      const keybindings = JSON.parse(await readFile(join(fx.output, "keybindings.json"), "utf-8"));
+      assert.deepEqual(keybindings["tui.input.newLine"], ["ctrl+j"], "user edit preserved");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("refreshes an unmodified install when the template changes", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await installPi({ root: fx.root, output: fx.output });
+      await writeFixture(
+        fx,
+        "pi/keybindings.json",
+        JSON.stringify({ "tui.input.newLine": ["ctrl+j"] }, null, 2),
+      );
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.keybindings.action, "written");
+      const keybindings = JSON.parse(await readFile(join(fx.output, "keybindings.json"), "utf-8"));
+      assert.deepEqual(keybindings["tui.input.newLine"], ["ctrl+j"], "updated template applied");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("replaces a legacy symlink with a real file", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await mkdir(fx.output, { recursive: true });
+      await symlink(join(fx.root, "pi", "keybindings.json"), join(fx.output, "keybindings.json"));
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.keybindings.action, "removed-symlink");
+      assert.equal((await lstat(join(fx.output, "keybindings.json"))).isSymbolicLink(), false);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("re-running leaves keybindings.json unchanged", async () => {
+    const fx = await makeFixture();
+    try {
+      await seedPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await installPi({ root: fx.root, output: fx.output });
+      const first = await readFile(join(fx.output, "keybindings.json"), "utf-8");
+
+      const result = await installPi({ root: fx.root, output: fx.output });
+
+      assert.equal(result.keybindings.action, "unchanged");
+      assert.equal(await readFile(join(fx.output, "keybindings.json"), "utf-8"), first);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+});
+
 // ─── Integration against the real repo ───────────────────────────────────────
 
 describe("installPi — real repo integration", () => {

package/test/pi-packages.test.mjs

@@ -0,0 +1,295 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  loadRequiredPackages,
+  npmSourceName,
+  planPackageInstalls,
+  provisionPiPackages,
+  runPiInstall,
+} from "../lib/pi-packages.mjs";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+async function makePiRoot({ declared = [], installed = [], settingsRaw } = {}) {
+  const root = await mkdtemp(join(tmpdir(), "pi-packages-"));
+  if (settingsRaw !== undefined) {
+    await writeFile(join(root, "settings.json"), settingsRaw);
+  } else if (declared.length > 0) {
+    await writeFile(join(root, "settings.json"), JSON.stringify({ packages: declared }));
+  }
+  for (const name of installed) {
+    await mkdir(join(root, "npm", "node_modules", name), { recursive: true });
+  }
+  return { root, cleanup: async () => rm(root, { recursive: true, force: true }) };
+}
+
+/** A runner that records every source it is asked to install. */
+function recordingRunner({ results = {} } = {}) {
+  const calls = [];
+  const runner = async (source) => {
+    calls.push(source);
+    return results[source] ?? { ok: true, error: null };
+  };
+  return { runner, calls };
+}
+
+/** Run `fn` with PATH set to `pathValue`, restoring the previous PATH afterwards. */
+async function withPath(pathValue, fn) {
+  const original = process.env.PATH;
+  process.env.PATH = pathValue;
+  try {
+    return await fn();
+  } finally {
+    process.env.PATH = original;
+  }
+}
+
+/** Write an executable `pi` stub with the given shell body; returns its dir and cleanup. */
+async function makePiStub(body) {
+  const dir = await mkdtemp(join(tmpdir(), "pi-stub-"));
+  const file = join(dir, "pi");
+  await writeFile(file, `#!/bin/sh\n${body}\n`);
+  await chmod(file, 0o755);
+  return { dir, cleanup: async () => rm(dir, { recursive: true, force: true }) };
+}
+
+/** A directory with nothing on PATH, so any external command lookup fails. */
+async function makeEmptyPathDir() {
+  const dir = await mkdtemp(join(tmpdir(), "pi-stub-empty-"));
+  return { dir, cleanup: async () => rm(dir, { recursive: true, force: true }) };
+}
+
+// ─── Manifest ────────────────────────────────────────────────────────────────
+
+describe("loadRequiredPackages", () => {
+  it("reads the declared pi packages from the package manifest", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-packages-manifest-"));
+    try {
+      await writeFile(
+        join(root, "package.json"),
+        JSON.stringify({ name: "x", pi: { extensions: ["./extensions"], packages: ["npm:pi-questions"] } }),
+      );
+      assert.deepEqual(await loadRequiredPackages(root), ["npm:pi-questions"]);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("returns no packages when the manifest does not declare any", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-packages-manifest-"));
+    try {
+      await writeFile(join(root, "package.json"), JSON.stringify({ name: "x", pi: { skills: ["./skills"] } }));
+      assert.deepEqual(await loadRequiredPackages(root), []);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── Source parsing ──────────────────────────────────────────────────────────
+
+describe("npmSourceName", () => {
+  it("extracts the package name from npm sources, including scoped and pinned specs", () => {
+    assert.equal(npmSourceName("npm:pi-questions"), "pi-questions");
+    assert.equal(npmSourceName("npm:pi-web-access@0.10.7"), "pi-web-access");
+    assert.equal(npmSourceName("npm:@scope/pkg@1.2.3"), "@scope/pkg");
+  });
+
+  it("returns null for non-npm sources it cannot verify locally", () => {
+    assert.equal(npmSourceName("git:github.com/user/repo"), null);
+    assert.equal(npmSourceName("./local/path"), null);
+  });
+});
+
+// ─── Install plan ────────────────────────────────────────────────────────────
+
+describe("planPackageInstalls", () => {
+  it("plans nothing when every required package is declared and installed", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-questions"], {
+        declaredSources: ["npm:pi-questions"],
+        installedNames: ["pi-questions"],
+      }),
+      [],
+    );
+  });
+
+  it("plans a package that is declared but not installed", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-web-access@0.10.7"], {
+        declaredSources: ["npm:pi-web-access@0.10.7"],
+        installedNames: [],
+      }),
+      ["npm:pi-web-access@0.10.7"],
+    );
+  });
+
+  it("plans a package that is installed but not declared, so pi will load it", () => {
+    assert.deepEqual(
+      planPackageInstalls(["npm:pi-questions"], {
+        declaredSources: [],
+        installedNames: ["pi-questions"],
+      }),
+      ["npm:pi-questions"],
+    );
+  });
+});
+
+// ─── Provisioning ────────────────────────────────────────────────────────────
+
+describe("runPiInstall", () => {
+  it("degrades to a result when the pi CLI is not on PATH", async () => {
+    const empty = await makeEmptyPathDir();
+    try {
+      const result = await withPath(empty.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: false, error: "pi CLI not found on PATH" });
+    } finally {
+      await empty.cleanup();
+    }
+  });
+
+  it("maps a successful pi install to ok", async () => {
+    const stub = await makePiStub("exit 0");
+    try {
+      const result = await withPath(stub.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: true, error: null });
+    } finally {
+      await stub.cleanup();
+    }
+  });
+
+  it("maps a failing pi install to its stderr", async () => {
+    const stub = await makePiStub('echo "offline: no registry" >&2\nexit 1');
+    try {
+      const result = await withPath(stub.dir, () => runPiInstall("npm:pi-questions"));
+      assert.deepEqual(result, { ok: false, error: "offline: no registry" });
+    } finally {
+      await stub.cleanup();
+    }
+  });
+});
+
+describe("provisionPiPackages", () => {
+  it("installs missing packages and skips the ones already present", async () => {
+    const fx = await makePiRoot({ declared: ["npm:pi-questions"], installed: ["pi-questions"] });
+    try {
+      const { runner, calls } = await recordingRunner();
+
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+
+      assert.deepEqual(calls, ["npm:pi-web-access@0.10.7"], "only the missing package is installed");
+      assert.deepEqual(result.installed, ["npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.failed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("is idempotent — a second run with everything present installs nothing", async () => {
+    const fx = await makePiRoot({
+      declared: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+      installed: ["pi-questions", "pi-web-access"],
+    });
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+      assert.deepEqual(calls, []);
+      assert.deepEqual(result.installed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("reports a failed install and continues with the rest", async () => {
+    const fx = await makePiRoot();
+    try {
+      const warnings = [];
+      const { runner, calls } = await recordingRunner({
+        results: { "npm:pi-questions": { ok: false, error: "offline" } },
+      });
+
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions", "npm:pi-web-access@0.10.7"],
+        piRoot: fx.root,
+        runInstall: runner,
+        warn: (msg) => warnings.push(msg),
+      });
+
+      assert.deepEqual(calls, ["npm:pi-questions", "npm:pi-web-access@0.10.7"], "failure does not abort the rest");
+      assert.deepEqual(result.installed, ["npm:pi-web-access@0.10.7"]);
+      assert.deepEqual(result.failed, [{ source: "npm:pi-questions", error: "offline" }]);
+      assert.ok(warnings.some((w) => w.includes("npm:pi-questions")), "failure is surfaced as a warning");
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("uses the pi CLI runner by default and warns when it is missing", async () => {
+    const fx = await makePiRoot();
+    const empty = await makeEmptyPathDir();
+    try {
+      const warnings = [];
+      const result = await withPath(empty.dir, () =>
+        provisionPiPackages({
+          required: ["npm:pi-questions"],
+          piRoot: fx.root,
+          warn: (msg) => warnings.push(msg),
+        }),
+      );
+
+      assert.deepEqual(result.failed, [{ source: "npm:pi-questions", error: "pi CLI not found on PATH" }]);
+      assert.ok(
+        warnings.some((w) => w.includes("pi CLI not found on PATH")),
+        "missing CLI is surfaced as a warning, not a thrown error",
+      );
+    } finally {
+      await empty.cleanup();
+      await fx.cleanup();
+    }
+  });
+
+  it("dry-run reports the plan without installing anything", async () => {
+    const fx = await makePiRoot();
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions"],
+        piRoot: fx.root,
+        runInstall: runner,
+        dryRun: true,
+      });
+      assert.deepEqual(calls, []);
+      assert.deepEqual(result.planned, ["npm:pi-questions"]);
+      assert.deepEqual(result.installed, []);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+
+  it("treats an unreadable settings file as no declarations rather than failing the install", async () => {
+    const fx = await makePiRoot({ settingsRaw: "{ not json" });
+    try {
+      const { runner, calls } = await recordingRunner();
+      const result = await provisionPiPackages({
+        required: ["npm:pi-questions"],
+        piRoot: fx.root,
+        runInstall: runner,
+      });
+      assert.deepEqual(calls, ["npm:pi-questions"], "still attempts the install");
+      assert.deepEqual(result.installed, ["npm:pi-questions"]);
+    } finally {
+      await fx.cleanup();
+    }
+  });
+});

package/token-map.README.md

@@ -131,8 +131,10 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
   and `agent-cortex install copilot` run.
 - `bin/installers/claude.mjs` — the single Claude generator: plain
   `agent-cortex install claude` materialises the plugin into `~/.agent-cortex/claude`
-  with token-substituted skills and registers it with Claude Code; `--output <dir>` is the
-  generate-only form (tests/CI structural checks). The repo commits no `claude/` output.
+  with token-substituted skills, merges the committed `claude/settings.json` into
+  `~/.claude/settings.json`, and registers it with Claude Code; `--output <dir>` is the
+  generate-only form (tests/CI structural checks). The only committed `claude/` file is the
+  settings template.
 - `bin/installers/pi.mjs` — the pi harness installer (`agent-cortex install pi`), an
   install-time consumer of the map's contract.
 - `lib/cli.mjs` — `SUPPORTED_HARNESSES`, the install command surface the harness ids come