portable-agent-layer 0.10.0 → 0.11.0

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");