portable-agent-layer 0.10.0 → 0.12.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,82 @@ export function scaffoldTelos(): void {
   }
 }
 
+// --- PAL settings scaffolding ---
+
+/** Copy pal-settings.json template to memory/ without overwriting */
+export function scaffoldPalSettings(): void {
+  const src = resolve(assets.skills(), "..", "templates", "pal-settings.json");
+  if (!existsSync(src)) return;
+
+  const memDir = resolve(palHome(), "memory");
+  mkdirSync(memDir, { recursive: true });
+
+  const dst = resolve(memDir, "pal-settings.json");
+  if (!existsSync(dst)) {
+    copyFileSync(src, dst);
+    log.info("Created pal-settings.json from template");
+  }
+}
+
+// --- 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 +238,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");

package/assets/templates/STEERING-RULES.md

@@ -1,23 +0,0 @@
-## Steering Rules
-
-Behavioral directives — act on these, don't just know them.
-
-**Surgical fixes only.** When debugging, make precise corrections to the broken behavior. Never delete or rearchitect components as a fix. If you believe a component is the root cause, explain your reasoning and ask before removing it.
-
-**Never assert without verification.** Don't say something "is" a certain way unless you've verified it with your tools. After making changes, verify the result before claiming success. Evidence required — tests, diffs, tool output. Never "Done!" without proof.
-
-**First principles over bolt-ons.** Most problems are symptoms. Understand → Simplify → Reduce → Add (last resort). Don't accrue technical debt through band-aid solutions.
-
-**Read before modifying.** Understand existing code, imports, and patterns before suggesting changes.
-
-**One change when debugging.** Isolate, verify, proceed. Don't change multiple things at once.
-
-**Minimal scope.** Only change what was asked. No bonus refactoring, no extra cleanup, no unsolicited improvements.
-
-**Ask before destructive actions.** Deletes, force pushes, production deploys — always ask first.
-
-**Plan means stop.** "Create a plan" = present and STOP. No execution without approval.
-
-**Error recovery.** When told you did something wrong — review the session, identify the violation, fix it, then explain what happened and capture the learning. Don't ask "What did I do wrong?"
-
-**Act on what you know.** When tracked opinions or relationship notes reveal user preferences, apply them to your behavior. If you know the user prefers concise responses, be concise. If they prefer manual commits, never offer to commit.

package/assets/templates/telos/IDENTITY.md

@@ -1,4 +0,0 @@
-# AI Identity
-
-<!-- The name and identity of your personal AI assistant. -->
-

package/src/cli/install.ts

@@ -1,86 +0,0 @@
-/**
- * PAL — main installer entry point (TypeScript)
- * Usage: bun run install.ts [--claude] [--opencode] [--all]
- * Default: installs for both targets.
- */
-
-import { ensureSetupState, isSetupComplete } from "../hooks/lib/setup";
-import { log, scaffoldTelos } from "../targets/lib";
-
-// --- Parse args ---
-const args = process.argv.slice(2);
-let installClaude = false;
-let installOpencode = false;
-
-if (args.length === 0) {
-  installClaude = true;
-  installOpencode = true;
-}
-
-for (const arg of args) {
-  if (arg === "--claude") installClaude = true;
-  else if (arg === "--opencode") installOpencode = true;
-  else if (arg === "--all") {
-    installClaude = true;
-    installOpencode = true;
-  } else if (arg === "--help" || arg === "-h") {
-    console.log("Usage: bun run install.ts [--claude] [--opencode] [--all]");
-    console.log("");
-    console.log("  --claude    Install hooks/skills for Claude Code");
-    console.log("  --opencode  Install context/skills for opencode");
-    console.log("  --all       Install for both (default)");
-    process.exit(0);
-  } else {
-    log.error(`Unknown option: ${arg}`);
-    process.exit(1);
-  }
-}
-
-// --- Check bun ---
-if (installClaude) {
-  try {
-    Bun.version; // always available in bun
-  } catch {
-    log.error("bun is required: curl -fsSL https://bun.sh/install | bash");
-    process.exit(1);
-  }
-}
-
-console.log("");
-console.log("  ╔═══════════════════════════════════╗");
-console.log("  ║  PAL — Portable Agent Layer       ║");
-console.log("  ║  Non-destructive · Modular        ║");
-console.log("  ╚═══════════════════════════════════╝");
-console.log("");
-
-// --- Scaffold TELOS + seed setup state ---
-scaffoldTelos();
-ensureSetupState();
-
-// --- Run target installers ---
-if (installClaude) {
-  console.log("━━━ Claude Code ━━━");
-  await import("../targets/claude/install");
-  console.log("");
-}
-
-if (installOpencode) {
-  console.log("━━━ opencode ━━━");
-  await import("../targets/opencode/install");
-  console.log("");
-}
-
-log.success("Done. Existing config was preserved — only new entries were added.");
-console.log("");
-log.info("Next steps:");
-
-const state = ensureSetupState();
-if (!isSetupComplete(state)) {
-  log.info("  1. Start a session — PAL will guide you through first-run setup");
-  log.info("  2. Or fill in telos/*.md manually, then re-run install.ts");
-} else {
-  log.info("  1. Fill in telos/*.md with your info (if not already done)");
-  log.info("  2. Re-run install.ts to regenerate context files");
-}
-log.info("  3. Add skills by dropping .md files into skills/");
-log.info("  4. Uninstall: bun run uninstall.ts [--claude] [--opencode]");

package/src/cli/uninstall.ts

@@ -1,45 +0,0 @@
-/**
- * PAL — main uninstaller entry point (TypeScript)
- * Usage: bun run uninstall.ts [--claude] [--opencode] [--all]
- */
-
-import { palHome } from "../hooks/lib/paths";
-import { log } from "../targets/lib";
-
-const args = process.argv.slice(2);
-let removeClaude = false;
-let removeOpencode = false;
-
-if (args.length === 0) {
-  removeClaude = true;
-  removeOpencode = true;
-}
-
-for (const arg of args) {
-  if (arg === "--claude") removeClaude = true;
-  else if (arg === "--opencode") removeOpencode = true;
-  else if (arg === "--all") {
-    removeClaude = true;
-    removeOpencode = true;
-  } else if (arg === "--help" || arg === "-h") {
-    console.log("Usage: bun run uninstall.ts [--claude] [--opencode] [--all]");
-    process.exit(0);
-  } else {
-    log.error(`Unknown option: ${arg}`);
-    process.exit(1);
-  }
-}
-
-if (removeClaude) {
-  console.log("━━━ Claude Code ━━━");
-  await import("../targets/claude/uninstall");
-  console.log("");
-}
-
-if (removeOpencode) {
-  console.log("━━━ opencode ━━━");
-  await import("../targets/opencode/uninstall");
-  console.log("");
-}
-
-log.success(`PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`);