portable-agent-layer 0.104.2 → 0.105.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.104.2",
+  "version": "0.105.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/targets/antigravity/install.ts

@@ -6,7 +6,7 @@
  * never touched.
  */
 
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { skillsDirOf } from "../../hooks/lib/agent-registry";
 import { ensureAntigravityRule } from "../../hooks/lib/claude-md";
@@ -23,6 +23,7 @@ import {
   mergeSettings,
   nativeAgentsDir,
   readJson,
+  replaceJsonConfig,
   writeJson,
 } from "../lib";
 
@@ -49,8 +50,7 @@ log.success("PAL hooks → hooks.json");
 
 const SETTINGS = platform.antigravitySettings();
 mkdirSync(dirname(SETTINGS), { recursive: true });
-if (existsSync(SETTINGS)) copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
-writeJson(
+replaceJsonConfig(
   SETTINGS,
   addStatuslineConfig(
     mergeSettings(

package/src/targets/antigravity/uninstall.ts

@@ -5,14 +5,7 @@
  * removing the folder never walks into the skills they point at.
  */
 
-import {
-  copyFileSync,
-  existsSync,
-  lstatSync,
-  readdirSync,
-  rmSync,
-  unlinkSync,
-} from "node:fs";
+import { existsSync, lstatSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { skillsDirOf } from "../../hooks/lib/agent-registry";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
@@ -22,8 +15,8 @@ import {
   readJson,
   removeStatusline,
   removeStatuslineConfig,
+  replaceJsonConfig,
   unmergeSettings,
-  writeJson,
 } from "../lib";
 
 function unlinkSkillLinks(dir: string): string[] {
@@ -47,12 +40,11 @@ if (existsSync(PLUGIN_DIR)) {
 
 const SETTINGS = platform.antigravitySettings();
 if (existsSync(SETTINGS)) {
-  copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
   const template = loadSettingsTemplate(
     assets.antigravitySettingsTemplate(),
     palPkg().replaceAll("\\", "/")
   );
-  writeJson(
+  replaceJsonConfig(
     SETTINGS,
     removeStatuslineConfig(
       unmergeSettings(readJson(SETTINGS, {}), template),

package/src/targets/claude/install.ts

@@ -4,7 +4,7 @@
  * Copies skills, agents, and PAL docs. Generates CLAUDE.md from TELOS.
  */
 
-import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
 import { identity, raw as readPalSettings } from "../../hooks/lib/settings";
@@ -21,7 +21,7 @@ import {
   log,
   mergeSettings,
   readJson,
-  writeJson,
+  replaceJsonConfig,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -35,11 +35,6 @@ if (!existsSync(SETTINGS)) {
   log.info("Created new settings.json");
 }
 
-// --- Backup ---
-const backup = `${SETTINGS}.bak.${Date.now()}`;
-copyFileSync(SETTINGS, backup);
-log.info("Backed up settings.json");
-
 // --- Load template and merge into existing settings ---
 const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(SETTINGS, {});
@@ -58,7 +53,7 @@ if (attribution?.decided) {
   });
 }
 
-writeJson(SETTINGS, merged);
+replaceJsonConfig(SETTINGS, merged);
 log.success("Merged PAL settings into settings.json");
 
 // --- Copy skills ---

package/src/targets/claude/uninstall.ts

@@ -3,7 +3,7 @@
  * Removes exactly what the settings template added, plus skills, agents, and PAL docs.
  */
 
-import { copyFileSync, existsSync, unlinkSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -15,8 +15,8 @@ import {
   removeSkills,
   removeStatusline,
   removeStatuslineConfig,
+  replaceJsonConfig,
   unmergeSettings,
-  writeJson,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -28,10 +28,6 @@ if (!existsSync(SETTINGS)) {
   process.exit(0);
 }
 
-// --- Backup ---
-copyFileSync(SETTINGS, `${SETTINGS}.bak.${Date.now()}`);
-log.info("Backed up settings.json");
-
 // --- Load template and unmerge from existing settings ---
 const template = loadSettingsTemplate(assets.claudeSettingsTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(SETTINGS, {});
@@ -40,7 +36,7 @@ let cleaned = unmergeSettings(existing, template);
 // Remove statusLine config
 cleaned = removeStatuslineConfig(cleaned);
 
-writeJson(SETTINGS, cleaned);
+replaceJsonConfig(SETTINGS, cleaned);
 log.success("Removed PAL settings from settings.json");
 
 // --- Remove PAL skills ---

package/src/targets/codex/install.ts

@@ -4,13 +4,7 @@
  * Symlinks skills, renders agents to TOML. Ensures AGENTS.md symlink via regenerateIfNeeded().
  */
 
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -24,7 +18,8 @@ import {
   mergeCodexHooks,
   mergeCodexRules,
   readJson,
-  writeJson,
+  replaceConfig,
+  replaceJsonConfig,
 } from "../lib";
 
 /**
@@ -74,27 +69,18 @@ const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 mkdirSync(CODEX_DIR, { recursive: true });
 
 // --- Merge hooks ---
-if (existsSync(HOOKS_FILE)) {
-  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
-  log.info("Backed up hooks.json");
-}
-
 const template = loadCodexHooksTemplate(assets.codexHooksTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
 const merged = mergeCodexHooks(existing, template);
 
-writeJson(HOOKS_FILE, merged);
+replaceJsonConfig(HOOKS_FILE, merged);
 log.success(`Merged PAL hooks into ${HOOKS_FILE}`);
 
 // --- Merge allowlist rules ---
 mkdirSync(resolve(CODEX_DIR, "rules"), { recursive: true });
-if (existsSync(RULES_FILE)) {
-  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
-  log.info("Backed up rules/default.rules");
-}
 const rulesTemplate = loadCodexRulesTemplate(assets.codexRulesTemplate());
 const existingRules = existsSync(RULES_FILE) ? readFileSync(RULES_FILE, "utf-8") : "";
-writeFileSync(RULES_FILE, mergeCodexRules(existingRules, rulesTemplate), "utf-8");
+replaceConfig(RULES_FILE, mergeCodexRules(existingRules, rulesTemplate));
 log.success("Merged PAL allowlist rules into ~/.codex/rules/default.rules");
 
 // --- Symlink skills to ~/.codex/skills/ ---

package/src/targets/codex/uninstall.ts

@@ -4,7 +4,7 @@
  * Removes PAL skill symlinks and PAL agents.
  */
 
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -14,9 +14,10 @@ import {
   removeAgentsFromCodex,
   removeCodexStatuslineConfig,
   removeSkills,
+  replaceConfig,
+  replaceJsonConfig,
   unmergeCodexHooks,
   unmergeCodexRules,
-  writeJson,
 } from "../lib";
 
 /**
@@ -54,14 +55,11 @@ const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 
 // --- Remove PAL hooks from hooks.json ---
 if (existsSync(HOOKS_FILE)) {
-  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
-  log.info("Backed up hooks.json");
-
   const template = loadCodexHooksTemplate(assets.codexHooksTemplate(), PKG_ROOT);
   const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
   const cleaned = unmergeCodexHooks(existing, template);
 
-  writeJson(HOOKS_FILE, cleaned);
+  replaceJsonConfig(HOOKS_FILE, cleaned);
   log.success("Removed PAL hooks from ~/.codex/hooks.json");
 } else {
   log.info("No hooks.json found, nothing to do");
@@ -69,11 +67,8 @@ if (existsSync(HOOKS_FILE)) {
 
 // --- Remove PAL allowlist rules from default.rules ---
 if (existsSync(RULES_FILE)) {
-  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
-  log.info("Backed up rules/default.rules");
-
   const cleanedRules = unmergeCodexRules(readFileSync(RULES_FILE, "utf-8"));
-  writeFileSync(RULES_FILE, cleanedRules, "utf-8");
+  replaceConfig(RULES_FILE, cleanedRules);
   log.success("Removed PAL allowlist rules from ~/.codex/rules/default.rules");
 } else {
   log.info("No default.rules found, nothing to do");

package/src/targets/cursor/install.ts

@@ -4,7 +4,7 @@
  * Symlinks skills. Generates AGENTS.md.
  */
 
-import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -17,7 +17,7 @@ import {
   log,
   mergeCursorHooks,
   readJson,
-  writeJson,
+  replaceJsonConfig,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -29,17 +29,11 @@ const CLI_CONFIG = resolve(CURSOR_DIR, "cli-config.json");
 mkdirSync(CURSOR_DIR, { recursive: true });
 
 // --- Merge hooks ---
-if (existsSync(HOOKS_FILE)) {
-  const backup = `${HOOKS_FILE}.bak.${Date.now()}`;
-  copyFileSync(HOOKS_FILE, backup);
-  log.info("Backed up hooks.json");
-}
-
 const template = loadCursorHooksTemplate(assets.cursorHooksTemplate(), PKG_ROOT);
 const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
 const merged = mergeCursorHooks(existing, template);
 
-writeJson(HOOKS_FILE, merged);
+replaceJsonConfig(HOOKS_FILE, merged);
 log.success(`Merged PAL hooks into ${HOOKS_FILE}`);
 
 // --- Symlink skills to ~/.cursor/skills/ ---
@@ -56,12 +50,9 @@ copyStatusline("cursor");
 if (!existsSync(CLI_CONFIG)) {
   writeFileSync(CLI_CONFIG, "{}\n", "utf-8");
   log.info("Created new cli-config.json");
-} else {
-  copyFileSync(CLI_CONFIG, `${CLI_CONFIG}.bak.${Date.now()}`);
-  log.info("Backed up cli-config.json");
 }
 const cliConfig = readJson<Record<string, unknown>>(CLI_CONFIG, {});
-writeJson(CLI_CONFIG, addStatuslineConfig(cliConfig, "cursor"));
+replaceJsonConfig(CLI_CONFIG, addStatuslineConfig(cliConfig, "cursor"));
 log.success("Merged statusLine into cli-config.json");
 
 log.info(

package/src/targets/cursor/uninstall.ts

@@ -4,7 +4,7 @@
  * Removes PAL skill symlinks.
  */
 
-import { copyFileSync, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -17,8 +17,8 @@ import {
   removeSkills,
   removeStatusline,
   removeStatuslineConfig,
+  replaceJsonConfig,
   unmergeCursorHooks,
-  writeJson,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -28,15 +28,11 @@ const CLI_CONFIG = resolve(CURSOR_DIR, "cli-config.json");
 
 // --- Remove PAL hooks from hooks.json ---
 if (existsSync(HOOKS_FILE)) {
-  // Backup before modifying
-  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
-  log.info("Backed up hooks.json");
-
   const template = loadCursorHooksTemplate(assets.cursorHooksTemplate(), PKG_ROOT);
   const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
   const cleaned = unmergeCursorHooks(existing, template);
 
-  writeJson(HOOKS_FILE, cleaned);
+  replaceJsonConfig(HOOKS_FILE, cleaned);
   log.success("Removed PAL hooks from hooks.json");
 } else {
   log.info("No hooks.json found, nothing to do");
@@ -62,10 +58,8 @@ removePalDocs();
 
 // --- Remove statusline script and cli-config statusLine ---
 if (existsSync(CLI_CONFIG)) {
-  copyFileSync(CLI_CONFIG, `${CLI_CONFIG}.bak.${Date.now()}`);
-  log.info("Backed up cli-config.json");
   const cliConfig = readJson<Record<string, unknown>>(CLI_CONFIG, {});
-  writeJson(CLI_CONFIG, removeStatuslineConfig(cliConfig, "cursor"));
+  replaceJsonConfig(CLI_CONFIG, removeStatuslineConfig(cliConfig, "cursor"));
   log.success("Removed PAL statusLine from cli-config.json");
 } else {
   log.info("No cli-config.json found, skipping statusLine removal");

package/src/targets/lib.ts

@@ -17,7 +17,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 import { createStyle, PALETTE, type Rgb } from "../cli/ui/style";
 import {
   AGENT_NAMES,
@@ -113,8 +113,41 @@ export function readJson<T = Record<string, unknown>>(path: string, fallback: T)
   }
 }
 
+const jsonText = (data: unknown) => `${JSON.stringify(data, null, 2)}\n`;
+
 export function writeJson(path: string, data: unknown): void {
-  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+  writeFileSync(path, jsonText(data), "utf-8");
+}
+
+// --- Config backups ---
+
+const KEPT_BACKUPS = 5;
+
+function backupsOf(path: string): string[] {
+  const prefix = `${basename(path)}.bak.`;
+  const stampOf = (name: string) => Number(name.slice(prefix.length));
+  return readdirSync(dirname(path))
+    .filter((name) => name.startsWith(prefix) && /^\d+$/.test(name.slice(prefix.length)))
+    .sort((a, b) => stampOf(b) - stampOf(a))
+    .map((name) => resolve(dirname(path), name));
+}
+
+function pruneBackups(path: string): void {
+  for (const old of backupsOf(path).slice(KEPT_BACKUPS)) unlinkSync(old);
+}
+
+/** Writes a config only when its content changes, backing up what it replaces. */
+export function replaceConfig(path: string, content: string): void {
+  const current = existsSync(path) ? readFileSync(path, "utf-8") : null;
+  if (current !== content) {
+    if (current !== null) copyFileSync(path, `${path}.bak.${Date.now()}`);
+    writeFileSync(path, content, "utf-8");
+  }
+  pruneBackups(path);
+}
+
+export function replaceJsonConfig(path: string, data: unknown): void {
+  replaceConfig(path, jsonText(data));
 }
 
 // --- Git attribution ---