@jaybeeuu/agent-cortex 1.40.0 → 1.41.1

package/bin/installers/claude.mjs

@@ -1,8 +1,9 @@
 // Install-time generator + registrar for the Claude Code plugin. A plain
 // `agent-cortex install claude` MATERIALISES the plugin into a home-scoped
-// directory (~/.agent-cortex/claude); there is no committed claude/ output in
-// the repo to regenerate — claude-extras/ and the gitignored $HOME target are
-// the only stores. The materialised plugin is:
+// directory (~/.agent-cortex/claude) and merges the committed
+// claude/settings.json template into ~/.claude/settings.json; the generated
+// plugin subtree is never committed — only that template, claude-extras/, and
+// the gitignored $HOME target are stores. The materialised plugin is:
 //
 //   <output>/.claude-plugin/plugin.json     plugin manifest (version tracks the
 //                                           package — never stale)
@@ -52,12 +53,13 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { readFile, writeFile, mkdir, rm, copyFile, stat, readdir, chmod } from "node:fs/promises";
+import { readFile, writeFile, mkdir, rm, copyFile, stat, readdir, chmod, rename, lstat } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { join, dirname, basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens } from "../../scripts/lib/compose-agent.mjs";
+import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = join(MODULE_DIR, "..", "..");
@@ -69,6 +71,18 @@ const PACKAGE_ROOT = join(MODULE_DIR, "..", "..");
 // os.homedir() honours $HOME on POSIX).
 const DEFAULT_OUTPUT = join(homedir(), ".agent-cortex", "claude");
 
+// Claude Code's user settings file: the default install merges the committed
+// claude/settings.json template into it. `--output` leaves it alone; an
+// explicit settingsPath is the programmatic (test/CI) seam that requests it.
+const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+
+// The committed user-settings template.
+const SETTINGS_TEMPLATE = "claude/settings.json";
+
+// The only keys the installer owns outright: everything else in the live file
+// is personal config the merge must preserve.
+const SETTINGS_OWNED_KEYS = ["enabledPlugins", "extraKnownMarketplaces"];
+
 // The token-map contract version this installer implements (token-map.json
 // "version" field). A higher map version is rejected: the contract must be
 // extended before this installer can trust it.
@@ -89,22 +103,6 @@ const SKILL_EXCLUDE = new Set(["ralph", "run-pipeline-stage"]);
 
 const NAME_PREFIX = "agent-cortex:";
 
-async function isFile(p) {
-  try {
-    return (await stat(p)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-async function isDirectory(p) {
-  try {
-    return (await stat(p)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 function byName(a, b) {
   return a.localeCompare(b);
 }
@@ -301,6 +299,141 @@ async function buildHandAuthored(root) {
   return items;
 }
 
+// ─── Claude user settings ────────────────────────────────────────────────────
+
+/**
+ * Materialise ~/.claude/settings.json from the committed claude/settings.json
+ * template with merge-keep-personal semantics (the same contract as the pi
+ * installer's installSettings):
+ *
+ *   - template keys fill in defaults the live file lacks; every value already
+ *     present in the live file wins (deeply), and unknown keys are preserved,
+ *     so personal config survives re-install;
+ *   - `enabledPlugins` and `extraKnownMarketplaces` are CLI-owned: they are
+ *     rewritten from the template outright. `permissions`, `hooks`, `env`,
+ *     `statusLine` and every other key are never touched.
+ */
+async function installSettings({ root, target, dryRun, warn }) {
+  const template = await readTemplateJson(join(root, SETTINGS_TEMPLATE), warn);
+  if (template === null) return null;
+
+  const merged = mergeSettings(template, await readJsonObject(target, warn));
+  for (const key of SETTINGS_OWNED_KEYS) {
+    if (key in template) merged[key] = template[key];
+    else delete merged[key];
+  }
+
+  const content = `${JSON.stringify(merged, null, 2)}\n`;
+  return writeManagedJson({ target, content, dryRun });
+}
+
+/**
+ * Merge the committed template over the live file. Template keys fill in
+ * defaults, live values win (deeply), and keys the template does not know about
+ * are preserved — re-installing never discards personal or Claude-written config.
+ */
+function mergeSettings(template, existing) {
+  const merged = {};
+  for (const key of Object.keys(template)) {
+    const templateValue = template[key];
+    const existingValue = existing[key];
+    if (isPlainObject(templateValue) && isPlainObject(existingValue)) {
+      merged[key] = mergeSettings(templateValue, existingValue);
+    } else {
+      merged[key] = key in existing ? existingValue : templateValue;
+    }
+  }
+  for (const key of Object.keys(existing)) {
+    if (!(key in merged)) merged[key] = existing[key];
+  }
+  return merged;
+}
+
+/**
+ * Write the managed settings file. A legacy symlink is replaced with a real
+ * file by writing a sibling temp file and renaming it over the target — rename
+ * replaces the link itself, so the committed template is never written through.
+ * Returns the action taken so the CLI can report the plan (dry-run included).
+ */
+async function writeManagedJson({ target, content, dryRun }) {
+  const symlink = await isSymlink(target);
+  const current = await readFileMaybe(target);
+
+  if (dryRun) {
+    return {
+      path: target,
+      action: symlink ? "would-remove-symlink" : current === content ? "unchanged" : "would-write",
+      removedSymlink: symlink,
+    };
+  }
+  if (!symlink && current === content) {
+    return { path: target, action: "unchanged", removedSymlink: false };
+  }
+
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+  try {
+    await writeFile(tmp, content);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+  return { path: target, action: symlink ? "removed-symlink" : "written", removedSymlink: symlink };
+}
+
+async function readTemplateJson(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) {
+    warn(`no ${filePath} template in the package — skipping`);
+    return null;
+  }
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) throw new Error(`${filePath} is not a JSON object`);
+  return parsed;
+}
+
+async function readJsonObject(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) return {};
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) {
+    warn(`${filePath} is not a JSON object — ignoring its contents`);
+    return {};
+  }
+  return parsed;
+}
+
+function tryParseJsonObject(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readFileMaybe(filePath) {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function isSymlink(filePath) {
+  try {
+    return (await lstat(filePath)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Generate the Claude Code plugin subtree.
  *
@@ -313,14 +446,19 @@ async function buildHandAuthored(root) {
  * @param {string} [options.pluginRoot]  Override plugin_root used for {{PATH:...}} resolution
  *                                       (default: token-map.json's claude value)
  * @param {boolean} [options.dryRun]     Plan and report without writing anything.
+ * @param {string} [options.settingsPath] Claude user-settings target
+ *                                       (default ~/.claude/settings.json). Passing it
+ *                                       explicitly materialises settings even with
+ *                                       --output — the test/CI seam.
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`.
  * @returns {{ output: string, marketplaceRoot: string|null, manifestPath: string|null,
  *             marketplaceManifest: object|null, agents: string[], natives: string[],
  *             skills: {names: string[], md: number, files: number, dir: string},
  *             hooks: boolean, hookFiles: string[], handAuthored: string[],
+ *             settings: {path: string, action: string, removedSymlink: boolean}|null,
  *             warnings: string[], dryRun: boolean }}
  */
-export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = false, pluginRoot, warn = DEFAULT_WARN } = {}) {
+export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = false, pluginRoot, settingsPath, warn = DEFAULT_WARN } = {}) {
   const tokenMap = await loadTokenMap(root);
   if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
     throw new Error(
@@ -360,6 +498,15 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     await mkdir(out, { recursive: true });
   }
 
+  // The default install owns ~/.claude/settings.json; --output is the
+  // generate-only form and leaves the user's Claude config alone. An explicit
+  // settingsPath requests the write regardless (the test/CI seam).
+  const settingsTarget = settingsPath ?? DEFAULT_SETTINGS_PATH;
+  const settings =
+    isDefaultInstall || settingsPath !== undefined
+      ? await installSettings({ root, target: settingsTarget, dryRun, warn: warnSink })
+      : null;
+
   const agents = await buildAgents(root);
   const natives = await buildNatives(root, join(root, "agents-native"));
   const skillOut = join(out, "skills");
@@ -382,6 +529,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     hooks: hooksJson !== null,
     hookFiles: hookFiles.map((f) => f.rel),
     handAuthored: handAuthored.map((f) => f.rel),
+    settings,
     warnings,
     dryRun,
   };
@@ -402,10 +550,12 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
       console.log(`  hook scripts: ${summary.hookFiles.join(", ")} (bundled into ${join(out, "hooks")}/)`);
     if (summary.handAuthored.length)
       console.log(`  hand-authored files: ${summary.handAuthored.join(", ")} (copied from repo claude-extras/)`);
+    if (summary.settings) console.log(`  settings → ${summary.settings.path} (${summary.settings.action})`);
     return summary;
   }
 
   // Write phase — the cleanup before buildSkills already cleared stale children.
+  if (settings) console.log(`Materialised Claude settings → ${settings.path} (${settings.action})`);
   const agentOut = join(out, "agents");
   await mkdir(agentOut, { recursive: true });
   for (const { file, content } of [...agents.files, ...natives]) {

package/bin/installers/copilot.mjs

@@ -30,30 +30,15 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { writeFile, mkdir, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
+import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
 
-async function isDirectory(p) {
-  try {
-    return (await stat(p)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function isFile(p) {
-  try {
-    return (await stat(p)).isFile();
-  } catch {
-    return false;
-  }
-}
-
 function byName(a, b) {
   return a.localeCompare(b);
 }

package/bin/installers/pi.mjs

@@ -4,6 +4,8 @@
 //
 //   <output>/agents/<slug>.agent.md   composed agents (default ~/.pi/agent/agents)
 //   <output>/skills/<group>/<name>/   token-substituted skill copies (default ~/.pi/agent/skills)
+//   <output>/settings.json            merged pi settings — CLI owns `packages` (default ~/.pi/agent/settings.json)
+//   <output>/keybindings.json         generated pi keybindings (default ~/.pi/agent/keybindings.json)
 //
 // Composition per the token-map.json contract:
 //   1. {{SECTION:name}} is resolved from the agent's pi/<name>.md section file
@@ -19,17 +21,26 @@
 // Skill markdown files get the same TOOL/PATH substitution so pi never serves
 // literal token syntax; other skill files are copied verbatim.
 //
-// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which pi
-// loads before package skills, so the substituted copies shadow the raw package
-// skills of the same name (pi dedupes by name, user wins).
+// Skills install into ~/.pi/agent/skills (pi's user-global skill dir), which is
+// the sole pi skill source: the checkout's raw package skills are not loaded
+// locally because pi/settings.json registers agent-cortex with an object-form
+// packages filter { source, "skills": [] } (extensions stay enabled). The
+// filter exists so pi never sees the raw, un-substituted package skills and
+// reports a name collision per skill (pi warns on collisions, user dir wins).
+// Consumers who install the npm package without that filter still rely on pi's
+// shadowing order (user dir loads before package skills). Re-run this installer
+// after any skill edit so the substituted copy in the user dir stays in sync.
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { readFile, writeFile, mkdir, copyFile, readdir, stat } from "node:fs/promises";
-import { join, dirname } from "node:path";
+import { readFile, writeFile, mkdir, copyFile, readdir, lstat, rename, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join, dirname, basename, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
+import { loadRequiredPackages, provisionPiPackages } from "../../lib/pi-packages.mjs";
+import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const PI = "pi";
 
@@ -41,23 +52,17 @@ const CONTRACT_VERSION = 1;
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const DEFAULT_OUTPUT = join(homedir(), ".pi", "agent");
 
-const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
+const SETTINGS_TEMPLATE = "pi/settings.json";
+const KEYBINDINGS_TEMPLATE = "pi/keybindings.json";
 
-async function isDirectory(p) {
-  try {
-    return (await stat(p)).isDirectory();
-  } catch {
-    return false;
-  }
-}
+// pi parses settings.json / keybindings.json with a bare JSON.parse (see pi's
+// SettingsManager / KeybindingsManager), so JSONC comments are not an option —
+// a `//` line would make the file unreadable. The GENERATED marker therefore
+// lives in a top-level "//" key, the conventional JSON comment stand-in, which
+// pi ignores on load and preserves on write.
+const GENERATED_KEY = "//";
 
-async function isFile(p) {
-  try {
-    return (await stat(p)).isFile();
-  } catch {
-    return false;
-  }
-}
+const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
 
 /**
  * Install the agent-cortex pi harness into the pi runtime.
@@ -70,8 +75,18 @@ async function isFile(p) {
  * @param {boolean} [options.dryRun]     Compute and report without writing anything
  * @param {string} [options.pluginRoot]  Override plugin_root used for {{PATH:...}}
  *                                       resolution (default: token-map pi value)
+ * @param {boolean} [options.provisionPackages]  Install the third-party pi packages
+ *                                       declared in the package manifest (package.json
+ *                                       pi.packages) into the pi user scope — e.g.
+ *                                       pi-questions (ask_questions) and pi-web-access
+ *                                       (fetch_content). Off by default; `agent-cortex
+ *                                       install pi` turns it on for a real install.
+ * @param {(source: string) => Promise<{ok: boolean, error: string | null}>} [options.runInstall]
+ *                                       Installer for one package source (default: pi install)
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`
  * @returns {{ agents: {name:string, filePath:string}[], skills: {skills:number, md:number, files:number, dir:string},
+ *             packages: {planned:string[], installed:string[], failed:{source:string, error:string}[]} | null,
+ *             settings: ManagedFileResult|null, keybindings: ManagedFileResult|null,
  *             warnings: string[], dryRun: boolean, agentsDir: string, skillsDir: string }}
  */
 export async function installPi(options = {}) {
@@ -97,8 +112,22 @@ export async function installPi(options = {}) {
 
   const agents = await installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
   const skills = await installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+  const config = await installConfig({ root, output, dryRun, warn });
+
+  // Third-party packages give the composed agents their pi tools (ask_questions
+  // from pi-questions, fetch_content from pi-web-access). They are declared in
+  // the package manifest and only provisioned on a real install.
+  const packages = options.provisionPackages
+    ? await provisionPiPackages({
+        required: await loadRequiredPackages(root),
+        piRoot: output,
+        dryRun,
+        runInstall: options.runInstall,
+        warn,
+      })
+    : null;
 
-  return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
+  return { agents, skills, packages, ...config, warnings, dryRun, agentsDir, skillsDir };
 }
 
 // ─── Agents ──────────────────────────────────────────────────────────────────
@@ -197,4 +226,214 @@ async function copyTree(src, dest, transform, dryRun) {
     }
   }
   return { md, files };
-}
+}
+// ─── Pi config files ─────────────────────────────────────────────────────────
+
+/**
+ * Materialise the pi config files into the agent dir.
+ *
+ * `settings.json` is merged: the committed template supplies defaults for keys
+ * the live file lacks, while every value already present in the live file wins,
+ * so personal config (and anything pi itself wrote) survives re-install. The
+ * one key the CLI owns outright is `packages`: it is rewritten from the
+ * template with the repo path entry resolved against the target settings file.
+ *
+ * `keybindings.json` follows a checksum rule: a missing file or a legacy
+ * symlink is materialised from the template, an unmodified install is refreshed
+ * when the template changes, and a file edited after install is left untouched.
+ */
+async function installConfig({ root, output, dryRun, warn }) {
+  return {
+    settings: await installSettings({ root, output, dryRun, warn }),
+    keybindings: await installKeybindings({ root, output, dryRun, warn }),
+  };
+}
+
+async function installSettings({ root, output, dryRun, warn }) {
+  const template = await readTemplateJson(join(root, SETTINGS_TEMPLATE), warn);
+  if (template === null) return null;
+
+  const target = join(output, "settings.json");
+  const merged = mergeSettings(template, await readJsonObject(target, warn));
+  merged.packages = resolvePackages(template.packages, root, dirname(target));
+  delete merged[GENERATED_KEY];
+
+  const content = `${JSON.stringify(
+    { [GENERATED_KEY]: generatedMarker(SETTINGS_TEMPLATE), ...merged },
+    null,
+    2,
+  )}\n`;
+  return writeManagedJson({ target, content, dryRun });
+}
+
+async function installKeybindings({ root, output, dryRun, warn }) {
+  const template = await readTemplateJson(join(root, KEYBINDINGS_TEMPLATE), warn);
+  if (template === null) return null;
+
+  const target = join(output, "keybindings.json");
+  const content = `${JSON.stringify(
+    { [GENERATED_KEY]: generatedMarker(KEYBINDINGS_TEMPLATE, checksum(template)), ...template },
+    null,
+    2,
+  )}\n`;
+
+  const current = await readFileMaybe(target);
+  if (current !== null && !(await isSymlink(target)) && current !== content) {
+    const parsed = tryParseJsonObject(current);
+    // An install we wrote carries the checksum it recorded; a body that no
+    // longer matches was edited by hand and must not be clobbered. A body
+    // byte-identical to the template is a legacy copy and safe to refresh.
+    const recorded = parsed === null ? null : readRecordedChecksum(parsed[GENERATED_KEY]);
+    const unmodified = parsed !== null && (checksum(parsed) === checksum(template) || recorded === checksum(parsed));
+    if (!unmodified) {
+      warn(`${target} was modified after install — leaving it untouched (delete it to re-adopt the template)`);
+      return { path: target, action: "skipped", removedSymlink: false };
+    }
+  }
+  return writeManagedJson({ target, content, dryRun });
+}
+
+/** Human-readable marker written as the `//` key of every generated config file. */
+function generatedMarker(from, templateChecksum) {
+  const base = `GENERATED from ${from} by \`agent-cortex install pi\` — DO NOT EDIT; re-run the installer to update.`;
+  return templateChecksum ? `${base} template-checksum:${templateChecksum}` : base;
+}
+
+/** SHA-256 of a config body with the generated marker stripped, so it is stable across writes. */
+function checksum(obj) {
+  const { [GENERATED_KEY]: _marker, ...body } = obj;
+  return createHash("sha256").update(JSON.stringify(body, null, 2)).digest("hex");
+}
+
+function readRecordedChecksum(marker) {
+  if (typeof marker !== "string") return null;
+  const match = /template-checksum:([0-9a-f]{64})/.exec(marker);
+  return match ? match[1] : null;
+}
+
+/**
+ * Merge the committed template over the live file. Template keys fill in
+ * defaults, live values win (deeply), and keys the template does not know about
+ * are preserved — re-installing never discards personal or pi-written config.
+ */
+function mergeSettings(template, existing) {
+  const merged = {};
+  for (const key of Object.keys(template)) {
+    const templateValue = template[key];
+    const existingValue = existing[key];
+    if (isPlainObject(templateValue) && isPlainObject(existingValue)) {
+      merged[key] = mergeSettings(templateValue, existingValue);
+    } else {
+      merged[key] = key in existing ? existingValue : templateValue;
+    }
+  }
+  for (const key of Object.keys(existing)) {
+    if (!(key in merged)) merged[key] = existing[key];
+  }
+  return merged;
+}
+
+/**
+ * Build the CLI-managed packages list: the template entries with the repo path
+ * package resolved relative to the target settings file. pi resolves user-scope
+ * local package paths against its agent dir, so this keeps the checkout (or npm
+ * install) registered wherever the settings file lands.
+ */
+function resolvePackages(packages, root, settingsDir) {
+  if (!Array.isArray(packages)) return packages;
+  const repoSource = relative(settingsDir, root) || ".";
+  let resolved = false;
+  const out = packages.map((entry) => {
+    const source = typeof entry === "string" ? entry : entry?.source;
+    if (resolved || typeof source !== "string" || source.startsWith("npm:")) return entry;
+    resolved = true;
+    return typeof entry === "string" ? repoSource : { ...entry, source: repoSource };
+  });
+  if (!resolved) out.unshift({ source: repoSource, skills: [] });
+  return out;
+}
+
+/**
+ * Write a managed config file. A legacy symlink is replaced with a real file by
+ * writing a sibling temp file and renaming it over the target — rename replaces
+ * the link itself, so the repo template is never written through. Returns the
+ * action taken so the CLI can report the plan (dry-run included).
+ */
+async function writeManagedJson({ target, content, dryRun }) {
+  const symlink = await isSymlink(target);
+  const current = await readFileMaybe(target);
+
+  if (dryRun) {
+    return {
+      path: target,
+      action: symlink ? "would-remove-symlink" : current === content ? "unchanged" : "would-write",
+      removedSymlink: symlink,
+    };
+  }
+  if (!symlink && current === content) {
+    return { path: target, action: "unchanged", removedSymlink: false };
+  }
+
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+  try {
+    await writeFile(tmp, content);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm(tmp, { force: true });
+    throw err;
+  }
+  return { path: target, action: symlink ? "removed-symlink" : "written", removedSymlink: symlink };
+}
+
+async function readTemplateJson(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) {
+    warn(`no ${filePath} template in the package — skipping`);
+    return null;
+  }
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) throw new Error(`${filePath} is not a JSON object`);
+  return parsed;
+}
+
+async function readJsonObject(filePath, warn) {
+  const raw = await readFileMaybe(filePath);
+  if (raw === null) return {};
+  const parsed = tryParseJsonObject(raw);
+  if (parsed === null) {
+    warn(`${filePath} is not a JSON object — ignoring its contents`);
+    return {};
+  }
+  return parsed;
+}
+
+function tryParseJsonObject(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readFileMaybe(filePath) {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function isSymlink(filePath) {
+  try {
+    return (await lstat(filePath)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}

package/claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "enabledPlugins": {},
+  "extraKnownMarketplaces": {}
+}