portable-agent-layer 0.9.0 → 0.11.0

package/src/targets/claude/install.ts

@@ -1,20 +1,23 @@
 /**
  * PAL — Claude Code target installer (TypeScript)
- * Merges hooks into existing settings.json (never overwrites).
- * Copies skills additively. Generates CLAUDE.md from TELOS.
+ * Merges settings template into existing settings.json (never overwrites).
+ * Copies skills, agents, and PAL docs. Generates CLAUDE.md from TELOS.
  */
 
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
-import { palHome, palPkg, platform } from "../../hooks/lib/paths";
+import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import {
   copyAgents,
+  copyPalDocs,
   copySkills,
   countAgents,
   countMd,
   countSkills,
+  loadSettingsTemplate,
   log,
+  mergeSettings,
   readJson,
   writeJson,
 } from "../lib";
@@ -35,96 +38,13 @@ const backup = `${SETTINGS}.bak.${Date.now()}`;
 copyFileSync(SETTINGS, backup);
 log.info("Backed up settings.json");
 
-// --- Build hooks payload ---
-const hooksPayload = {
-  hooks: {
-    SessionStart: [
-      {
-        matcher: "",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/LoadContext.ts` },
-        ],
-      },
-    ],
-    UserPromptSubmit: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/UserPromptOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-    PreToolUse: [
-      {
-        matcher: "Bash|Write|Edit",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/SecurityValidator.ts`,
-          },
-        ],
-      },
-      {
-        matcher: "Skill",
-        hooks: [
-          { type: "command", command: `bun run ${PKG_ROOT}/src/hooks/SkillGuard.ts` },
-        ],
-      },
-    ],
-    Stop: [
-      {
-        matcher: "",
-        hooks: [
-          {
-            type: "command",
-            command: `bun run ${PKG_ROOT}/src/hooks/StopOrchestrator.ts`,
-          },
-        ],
-      },
-    ],
-  },
-};
+// --- Load template and merge into existing settings ---
+const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(SETTINGS, {});
+const merged = mergeSettings(existing, template);
 
-// --- Merge hooks additively (deduplicate by command) ---
-type HookEntry = { matcher: string; hooks: Array<{ type: string; command: string }> };
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
-
-const settings = readJson<Settings>(SETTINGS, {});
-if (!settings.hooks) settings.hooks = {};
-
-for (const [event, entries] of Object.entries(hooksPayload.hooks)) {
-  const existing = settings.hooks[event] ?? [];
-  for (const entry of entries) {
-    const cmd = entry.hooks[0]?.command;
-    const alreadyPresent = existing.some((e) => e.hooks?.[0]?.command === cmd);
-    if (!alreadyPresent) existing.push(entry);
-  }
-  settings.hooks[event] = existing;
-}
-
-// --- Add PAL tool permissions (auto-allow ai: scripts) ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (!s.permissions) s.permissions = {};
-if (!s.permissions.allow) s.permissions.allow = [];
-const aiTools = [
-  "ai:entity-save",
-  "ai:fyzz-api",
-  "ai:pdf-download",
-  "ai:youtube-analyze",
-];
-for (const tool of aiTools) {
-  const perm = `Bash(bun run ${tool} *)`;
-  if (!s.permissions.allow.includes(perm)) {
-    s.permissions.allow.push(perm);
-  }
-}
-
-writeJson(SETTINGS, settings);
-log.success("Merged hooks into settings.json");
+writeJson(SETTINGS, merged);
+log.success("Merged PAL settings into settings.json");
 
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
@@ -133,13 +53,16 @@ copySkills(skillsDir);
 // --- Copy agents ---
 copyAgents();
 
+// --- Copy PAL system docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+
 // --- Generate ~/.claude/AGENTS.md and symlink ~/.claude/CLAUDE.md → AGENTS.md ---
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md (→ ~/.claude/CLAUDE.md symlink)");
 
 log.success("Claude Code installation complete");
 console.log("");
-log.info(`Hooks: 5 (SessionStart, UserPromptSubmit, PreToolUse×2, Stop)`);
 log.info(`Skills: ${countSkills()}`);
 log.info(`Agents: ${countAgents()}`);
 log.info(`TELOS: ${countMd(resolve(palHome(), "telos"))} files`);

package/src/targets/claude/uninstall.ts

@@ -1,14 +1,23 @@
 /**
  * PAL — Claude Code uninstaller (TypeScript)
- * Removes PAL hooks, skills, and env from settings.json.
+ * Removes exactly what the settings template added, plus skills, agents, and PAL docs.
  */
 
 import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
-import { palPkg, platform } from "../../hooks/lib/paths";
-import { log, readJson, removeAgents, removeSkills, writeJson } from "../lib";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  loadSettingsTemplate,
+  log,
+  readJson,
+  removeAgents,
+  removePalDocs,
+  removeSkills,
+  unmergeSettings,
+  writeJson,
+} from "../lib";
 
-const PKG_ROOT = palPkg();
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CLAUDE_DIR = platform.claudeDir();
 const SETTINGS = resolve(CLAUDE_DIR, "settings.json");
 
@@ -21,50 +30,13 @@ if (!existsSync(SETTINGS)) {
 copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
 log.info("Backed up settings.json");
 
-// --- Remove PAL hooks ---
-type HookEntry = {
-  matcher?: string;
-  hooks?: Array<{ command?: string }>;
-  command?: string;
-};
-type Settings = { hooks?: Record<string, HookEntry[]>; env?: Record<string, string> };
+// --- Load template and unmerge from existing settings ---
+const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(SETTINGS, {});
+const cleaned = unmergeSettings(existing, template);
 
-const settings = readJson<Settings>(SETTINGS, {});
-
-if (settings.hooks) {
-  for (const [event, entries] of Object.entries(settings.hooks)) {
-    settings.hooks[event] = entries.filter((entry) => {
-      // New format: { matcher, hooks: [{ command }] }
-      if (entry.hooks) return !entry.hooks.some((h) => h.command?.includes(PKG_ROOT));
-      // Old flat format: { type, command }
-      if (entry.command) return !entry.command.includes(PKG_ROOT);
-      return true;
-    });
-    if (settings.hooks[event].length === 0) delete settings.hooks[event];
-  }
-  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-}
-
-// --- Remove env ---
-if (settings.env) {
-  // Clean up env vars
-  delete settings.env.PAL_DIR;
-  if (Object.keys(settings.env).length === 0) delete settings.env;
-}
-
-// --- Remove PAL tool permissions ---
-type SettingsWithPermissions = Settings & { permissions?: { allow?: string[] } };
-const s = settings as SettingsWithPermissions;
-if (s.permissions?.allow) {
-  s.permissions.allow = s.permissions.allow.filter(
-    (p) => !p.includes(PKG_ROOT) && !p.startsWith("Bash(bun run ai:")
-  );
-  if (s.permissions.allow.length === 0) delete s.permissions.allow;
-  if (Object.keys(s.permissions).length === 0) delete s.permissions;
-}
-
-writeJson(SETTINGS, settings);
-log.success("Removed PAL hooks and env from settings.json");
+writeJson(SETTINGS, cleaned);
+log.success("Removed PAL settings from settings.json");
 
 // --- Remove PAL skills ---
 const removed = removeSkills(resolve(CLAUDE_DIR, "skills"));
@@ -82,6 +54,9 @@ if (removedAgents.length > 0) {
   log.info("No PAL agents found");
 }
 
+// --- Remove PAL system docs ---
+removePalDocs();
+
 // --- Remove AGENTS.md and CLAUDE.md symlink ---
 const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
 const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");

package/src/targets/lib.ts

@@ -41,6 +41,101 @@ export function writeJson(path: string, data: unknown): void {
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
 
+// --- Settings template merge/unmerge ---
+
+type HookEntry = { matcher?: string; hooks?: Array<{ type: string; command: string }> };
+type Settings = Record<string, unknown> & {
+  hooks?: Record<string, HookEntry[]>;
+  permissions?: { allow?: string[]; deny?: string[]; ask?: string[] };
+};
+
+/**
+ * Load a settings template, replacing {{PKG_ROOT}} with the actual path.
+ */
+export function loadSettingsTemplate(templatePath: string, pkgRoot: string): Settings {
+  const raw = readFileSync(templatePath, "utf-8");
+  const resolved = raw.replaceAll("{{PKG_ROOT}}", pkgRoot);
+  return JSON.parse(resolved) as Settings;
+}
+
+/**
+ * Merge a PAL settings template into existing settings.
+ * - hooks: deduplicate by command string
+ * - permissions.allow: deduplicate by value
+ * - other keys: template values are added if not already present
+ */
+export function mergeSettings(existing: Settings, template: Settings): Settings {
+  const result = { ...existing };
+
+  // Merge hooks (deduplicate by command)
+  if (template.hooks) {
+    if (!result.hooks) result.hooks = {};
+    for (const [event, entries] of Object.entries(template.hooks)) {
+      const current = result.hooks[event] ?? [];
+      for (const entry of entries) {
+        const cmd = entry.hooks?.[0]?.command;
+        if (cmd && !current.some((e) => e.hooks?.[0]?.command === cmd)) {
+          current.push(entry);
+        }
+      }
+      result.hooks[event] = current;
+    }
+  }
+
+  // Merge permissions.allow (deduplicate)
+  if (template.permissions?.allow) {
+    if (!result.permissions) result.permissions = {};
+    if (!result.permissions.allow) result.permissions.allow = [];
+    for (const perm of template.permissions.allow) {
+      if (!result.permissions.allow.includes(perm)) {
+        result.permissions.allow.push(perm);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove everything a PAL settings template added from existing settings.
+ * - hooks: remove entries whose command matches any template command
+ * - permissions.allow: remove entries that appear in the template
+ * - cleans up empty arrays/objects
+ */
+export function unmergeSettings(existing: Settings, template: Settings): Settings {
+  const result = { ...existing };
+
+  // Collect all PAL hook commands from template
+  if (template.hooks && result.hooks) {
+    const palCommands = new Set<string>();
+    for (const entries of Object.values(template.hooks)) {
+      for (const entry of entries) {
+        const cmd = entry.hooks?.[0]?.command;
+        if (cmd) palCommands.add(cmd);
+      }
+    }
+
+    for (const [event, entries] of Object.entries(result.hooks)) {
+      result.hooks[event] = entries.filter((e) => {
+        const cmd = e.hooks?.[0]?.command;
+        return !cmd || !palCommands.has(cmd);
+      });
+      if (result.hooks[event].length === 0) delete result.hooks[event];
+    }
+    if (Object.keys(result.hooks).length === 0) delete result.hooks;
+  }
+
+  // Remove PAL permissions
+  if (template.permissions?.allow && result.permissions?.allow) {
+    const palPerms = new Set(template.permissions.allow);
+    result.permissions.allow = result.permissions.allow.filter((p) => !palPerms.has(p));
+    if (result.permissions.allow.length === 0) delete result.permissions.allow;
+    if (Object.keys(result.permissions).length === 0) delete result.permissions;
+  }
+
+  return result;
+}
+
 // --- TELOS scaffolding ---
 
 /** Copy template files into telos/ without overwriting existing ones */
@@ -60,14 +155,65 @@ export function scaffoldTelos(): void {
   }
 }
 
+// --- PAL docs (modular context routing files) ---
+
+const PAL_DOCS_DIR = resolve(platform.agentsDir(), "PAL");
+
+/**
+ * Install PAL system docs into ~/.agents/PAL/.
+ * Always overwrites — these are engine-managed, not user-editable.
+ */
+export function copyPalDocs(): number {
+  const srcDir = assets.palDocs();
+  if (!existsSync(srcDir)) return 0;
+
+  mkdirSync(PAL_DOCS_DIR, { recursive: true });
+  let count = 0;
+
+  for (const file of readdirSync(srcDir).filter((f) => f.endsWith(".md"))) {
+    const src = resolve(srcDir, file);
+    const dst = resolve(PAL_DOCS_DIR, file);
+    copyFileSync(src, dst);
+    count++;
+  }
+
+  // Symlink ~/.agents/PAL/telos and ~/.agents/PAL/memory → <palHome>/...
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  ensureSymlink(resolve(PAL_DOCS_DIR, "telos"), resolve(palHome(), "telos"), linkType);
+  ensureSymlink(resolve(PAL_DOCS_DIR, "memory"), resolve(palHome(), "memory"), linkType);
+
+  return count;
+}
+
+/** Remove PAL system docs from ~/.agents/PAL/ */
+export function removePalDocs(): void {
+  if (!existsSync(PAL_DOCS_DIR)) return;
+  for (const file of readdirSync(PAL_DOCS_DIR).filter((f) => f.endsWith(".md"))) {
+    try {
+      unlinkSync(resolve(PAL_DOCS_DIR, file));
+    } catch {
+      /* gone */
+    }
+  }
+  try {
+    rmSync(PAL_DOCS_DIR, { recursive: true });
+    log.info("Removed ~/.agents/PAL/");
+  } catch {
+    /* gone */
+  }
+}
+
 // --- Skills ---
 
 const AGENTS_SKILLS_DIR = resolve(platform.agentsDir(), "skills");
 
 /**
- * Install PAL skills into the shared ~/.agents/skills/<name>/SKILL.md standard,
- * then symlink ~/.claude/skills/<name> → ../../.agents/skills/<name>.
- * Additive — skips skills already installed.
+ * Install PAL skills by symlinking:
+ *   ~/.agents/skills/<name> → <repo>/assets/skills/<name>  (source of truth)
+ *   ~/.claude/skills/<name> → ~/.agents/skills/<name>       (Claude Code discovery)
+ *
+ * Symlinks mean tools inside skills can import from the repo (src/hooks/lib/*)
+ * and everything resolves naturally. Additive — skips skills already installed.
  */
 export function copySkills(claudeSkillsDir: string): number {
   const skillsDir = assets.skills();
@@ -75,69 +221,65 @@ export function copySkills(claudeSkillsDir: string): number {
 
   mkdirSync(AGENTS_SKILLS_DIR, { recursive: true });
   mkdirSync(claudeSkillsDir, { recursive: true });
+  const linkType = process.platform === "win32" ? "junction" : "dir";
   let count = 0;
 
-  for (const file of readdirSync(skillsDir).filter((f) => f.endsWith(".md"))) {
-    const name = file.replace(/\.md$/, "");
-    const src = resolve(skillsDir, file);
-    const agentSkillDir = resolve(AGENTS_SKILLS_DIR, name);
-    const agentSkillFile = resolve(agentSkillDir, "SKILL.md");
+  for (const name of readdirSync(skillsDir)) {
+    const srcDir = resolve(skillsDir, name);
+    if (!existsSync(resolve(srcDir, "SKILL.md"))) continue;
+
+    // ~/.agents/skills/<name> → <repo>/assets/skills/<name>
+    const agentLink = resolve(AGENTS_SKILLS_DIR, name);
+    ensureSymlink(agentLink, srcDir, linkType);
+
+    // ~/.claude/skills/<name> → ~/.agents/skills/<name>
     const claudeLink = resolve(claudeSkillsDir, name);
+    ensureSymlink(claudeLink, agentLink, linkType);
 
-    // Install into ~/.agents/skills/<name>/SKILL.md
-    if (!existsSync(agentSkillFile)) {
-      mkdirSync(agentSkillDir, { recursive: true });
-      copyFileSync(src, agentSkillFile);
-      log.info(`Added skill: ${name}`);
-      count++;
-    } else {
-      log.warn(`Skill exists, skipping: ${name}`);
-    }
+    log.info(`Linked skill: ${name}`);
+    count++;
+  }
+  return count;
+}
 
-    // Create ~/.claude/skills/<name> symlink if missing or not a symlink
-    // Use 'junction' on Windows (no admin required), 'dir' symlink on Unix
-    const linkType = process.platform === "win32" ? "junction" : "dir";
+/** Create or update a symlink/junction, replacing any non-symlink entry. */
+function ensureSymlink(link: string, target: string, type: "dir" | "junction"): void {
+  try {
+    const st = lstatSync(link);
+    if (st.isSymbolicLink()) return; // already a symlink, leave it
+    rmSync(link, { recursive: true, force: true });
+  } catch {
+    // doesn't exist or broken — clean up just in case
     try {
-      const st = lstatSync(claudeLink);
-      if (!st.isSymbolicLink()) {
-        rmSync(claudeLink, { recursive: true, force: true });
-        symlinkSync(`../../.agents/skills/${name}`, claudeLink, linkType);
-      }
+      rmSync(link, { recursive: true, force: true });
     } catch {
-      // Entry might exist but lstatSync failed (broken symlink/junction on Windows)
-      try {
-        rmSync(claudeLink, { recursive: true, force: true });
-      } catch {
-        /* gone */
-      }
-      symlinkSync(`../../.agents/skills/${name}`, claudeLink, linkType);
+      /* gone */
     }
   }
-  return count;
+  symlinkSync(target, link, type);
 }
 
-/** Remove PAL skills from ~/.agents/skills/ and their symlinks from ~/.claude/skills/ */
+/** Remove PAL skill symlinks from ~/.agents/skills/ and ~/.claude/skills/ */
 export function removeSkills(claudeSkillsDir: string): string[] {
   const skillsDir = assets.skills();
   if (!existsSync(skillsDir)) return [];
 
   const removed: string[] = [];
-  for (const file of readdirSync(skillsDir).filter((f) => f.endsWith(".md"))) {
-    const name = file.replace(/\.md$/, "");
+  for (const name of readdirSync(skillsDir)) {
+    if (!existsSync(resolve(skillsDir, name, "SKILL.md"))) continue;
 
-    const agentSkillDir = resolve(AGENTS_SKILLS_DIR, name);
-    if (existsSync(agentSkillDir)) {
-      rmSync(agentSkillDir, { recursive: true });
-      removed.push(name);
-      log.info(`Removed skill: ${name}`);
-    }
-
-    const claudeLink = resolve(claudeSkillsDir, name);
-    try {
-      unlinkSync(claudeLink);
-    } catch {
-      /* already gone */
+    for (const link of [
+      resolve(AGENTS_SKILLS_DIR, name),
+      resolve(claudeSkillsDir, name),
+    ]) {
+      try {
+        unlinkSync(link);
+      } catch {
+        /* already gone */
+      }
     }
+    removed.push(name);
+    log.info(`Removed skill: ${name}`);
   }
   return removed;
 }

package/src/targets/opencode/install.ts

@@ -7,7 +7,14 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { palPkg, platform } from "../../hooks/lib/paths";
-import { copyAgentsForOpencode, copySkills, countSkills, log, writeJson } from "../lib";
+import {
+  copyAgentsForOpencode,
+  copyPalDocs,
+  copySkills,
+  countSkills,
+  log,
+  writeJson,
+} from "../lib";
 
 const PKG_ROOT = palPkg();
 const OC_GLOBAL_DIR = platform.opencodeDir();
@@ -53,7 +60,11 @@ log.success("Installed skills to ~/.agents/skills/");
 const ocAgentsDir = resolve(OC_GLOBAL_DIR, "agents");
 copyAgentsForOpencode(ocAgentsDir);
 
-// --- 5. Generate ~/.config/opencode/AGENTS.md ---
+// --- 5. Copy PAL system docs ---
+const palDocsCount = copyPalDocs();
+log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+
+// --- 6. Generate ~/.config/opencode/AGENTS.md ---
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md");
 

package/src/targets/opencode/uninstall.ts

@@ -6,7 +6,7 @@
 import { unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform } from "../../hooks/lib/paths";
-import { log, removeAgentsFromOpencode, removeSkills } from "../lib";
+import { log, removeAgentsFromOpencode, removePalDocs, removeSkills } from "../lib";
 
 const OC_GLOBAL_DIR = platform.opencodeDir() || "";
 
@@ -38,6 +38,9 @@ if (removedAgents.length > 0)
     `Removed ${removedAgents.length} opencode agent(s): ${removedAgents.join(", ")}`
   );
 
+// --- Remove PAL system docs ---
+removePalDocs();
+
 // --- Remove AGENTS.md and CLAUDE.md symlink ---
 const agentsMd = resolve(OC_GLOBAL_DIR, "AGENTS.md");
 const claudeMd = resolve(PAL_CLAUDE_DIR, "CLAUDE.md");