portable-agent-layer 0.51.1 → 0.51.2

package/README.md

@@ -142,9 +142,16 @@ PAL routes inference through the host agent's subscription CLI by default. API k
 
 ### Debug / test
 
+Enable verbose hook logging with:
+
+```
+pal cli debug on    # enable  → logs to memory/state/debug.log
+pal cli debug off   # disable
+pal cli debug       # show current status and log path
+```
+
 | Variable | Description |
 |----------|-------------|
-| `PAL_DEBUG` | Set to `1` to emit verbose hook logs to `memory/state/debug.log` |
 | `PAL_INFERENCE_DISABLED` | Set to `1` to disable all inference (used by the test suite to prevent real CLI spawns) |
 | `PAL_NOTIFICATIONS_DISABLED` | Set to `1` to suppress desktop notifications (used by the test suite) |
 

package/package.json

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

package/src/cli/index.ts

@@ -18,14 +18,23 @@
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name>               Evaluate a skill against the authoring best practices
+ *   debug [on|off]                    Enable / disable verbose hook debug logging
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
-import { DEBUG_LOG_MAX_ROTATED } from "../hooks/lib/log";
+import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
@@ -200,6 +209,9 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "debug":
+      cliDebug(args);
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -244,6 +256,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
+    pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -1151,10 +1164,19 @@ async function exportState(args: string[]) {
 
   const dryRun = args.includes("--dry-run");
   const pathArg = args.find((a) => !a.startsWith("-"));
-  const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
-
+  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const argIsDir =
+    resolvedArg !== null &&
+    existsSync(resolvedArg) &&
+    statSync(resolvedArg).isDirectory();
+  const outputPath = argIsDir
+    ? resolve(resolvedArg, `pal-export-${timestamp()}.zip`)
+    : (resolvedArg ?? resolve(palHome(), `pal-export-${timestamp()}.zip`));
+
+  logDebug("export", `start dryRun=${dryRun} outputPath=${outputPath}`);
   if (dryRun) {
     const files = collectExportFiles();
+    logDebug("export", `dry-run collected ${files.length} files`);
     if (files.length === 0) {
       console.log("Nothing to export.");
     } else {
@@ -1163,6 +1185,7 @@ async function exportState(args: string[]) {
     }
   } else {
     const count = exportZip(outputPath);
+    logDebug("export", `done count=${count} path=${outputPath}`);
     if (count === 0) {
       console.log("Nothing to export.");
     } else {
@@ -1179,49 +1202,50 @@ async function importState(args: string[]) {
   const home = palHome();
   const dryRun = args.includes("--dry-run");
   const pathArg = args.find((a) => !a.startsWith("-"));
+  logDebug("import", `start dryRun=${dryRun} pathArg=${pathArg ?? "(auto)"}`);
 
-  function findLatest(): string | null {
+  function findLatestIn(dirs: string[]): string | null {
     const candidates: string[] = [];
-
-    try {
-      candidates.push(
-        ...readdirSync(home)
-          .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
-          .map((f) => resolve(home, f))
-      );
-    } catch {
-      /* empty */
-    }
-
-    try {
-      const backupDir = resolve(home, "backups");
-      candidates.push(
-        ...readdirSync(backupDir)
-          .filter(
-            (f) =>
-              (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
-              f.endsWith(".zip")
-          )
-          .map((f) => resolve(backupDir, f))
-      );
-    } catch {
-      /* empty */
+    for (const dir of dirs) {
+      try {
+        candidates.push(
+          ...readdirSync(dir)
+            .filter(
+              (f) =>
+                (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
+                f.endsWith(".zip")
+            )
+            .map((f) => resolve(dir, f))
+        );
+      } catch {
+        /* empty */
+      }
     }
-
     if (candidates.length === 0) return null;
     return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
   }
 
   let zipPath: string;
 
-  if (pathArg) {
-    zipPath = resolve(pathArg);
+  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const argIsDir =
+    resolvedArg !== null &&
+    existsSync(resolvedArg) &&
+    statSync(resolvedArg).isDirectory();
+
+  if (resolvedArg && !argIsDir) {
+    zipPath = resolvedArg;
+    logDebug("import", `using provided path=${zipPath}`);
   } else {
-    const latest = findLatest();
+    const searchDirs = argIsDir ? [resolvedArg] : [home, resolve(home, "backups")];
+    logDebug("import", `searching dirs=${searchDirs.join(",")}`);
+    const latest = findLatestIn(searchDirs);
     if (!latest) {
+      logDebug("import", "no export/backup files found");
       log.error("No export or backup files found. Provide a path: pal cli import <path>");
       process.exit(1);
     }
+    logDebug("import", `auto-selected latest=${latest}`);
     console.log(`Found: ${latest}`);
     const zip = new AdmZip(latest);
     console.log(
@@ -1253,11 +1277,13 @@ async function importState(args: string[]) {
     process.exit(0);
   }
 
+  logDebug("import", `zip=${zipPath} entries=${entries.length} dryRun=${dryRun}`);
   if (dryRun) {
     console.log(`Would import ${entries.length} files → ${home}\n`);
     for (const e of entries) console.log(`  ${e.entryName}`);
   } else {
     zip.extractAllTo(home, true);
+    logDebug("import", `done extracted=${entries.length} to=${home}`);
     console.log(`Imported ${entries.length} files → ${home}`);
     log.info("Run 'pal cli install' to re-register hooks.");
   }
@@ -1309,6 +1335,25 @@ async function update() {
   await install(resolveTargets([]));
 }
 
+function cliDebug(args: string[]) {
+  const stateDir = resolve(palHome(), "memory", "state");
+  const flagFile = resolve(stateDir, "debug-enabled");
+  const logFile = resolve(stateDir, "debug.log");
+  const sub = args[0];
+  if (sub === "on") {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(flagFile, "");
+    log.success(`Debug logging enabled → ${logFile}`);
+  } else if (sub === "off") {
+    rmSync(flagFile, { force: true });
+    log.success("Debug logging disabled");
+  } else {
+    const on = existsSync(flagFile);
+    console.log(`  Debug: ${on ? "ON" : "OFF"}`);
+    console.log(`  Log:   ${logFile}`);
+  }
+}
+
 async function status() {
   const home = palHome();
   const pkg = palPkg();

package/src/hooks/lib/log.ts

@@ -2,12 +2,12 @@
  * Simple file-based debug logger for PAL hooks.
  * Writes to memory/state/debug.log — rotated on each session start.
  *
- * Only writes when PAL_DEBUG=1 or when called via logError (always logged).
+ * Only writes when debug is enabled (`pal cli debug on`) or when called via logError (always logged).
  */
 
 import { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
-import { paths } from "./paths";
+import { palHome, paths } from "./paths";
 
 const MAX_LOG_SIZE = 50_000; // ~50KB per file
 const MAX_ROTATED = 5; // keep up to 5 rotated files (.1 newest → .5 oldest)
@@ -74,9 +74,13 @@ function rotateIfNeeded(path: string): void {
 /** Test-only: max rotated count for callers that need to enumerate. */
 export const DEBUG_LOG_MAX_ROTATED = MAX_ROTATED;
 
-/** Log a debug message (only when PAL_DEBUG=1) */
+function isDebugEnabled(): boolean {
+  return existsSync(resolve(palHome(), "memory", "state", "debug-enabled"));
+}
+
+/** Log a debug message (only when debug is enabled via `pal cli debug on`) */
 export function logDebug(source: string, message: string): void {
-  if (process.env.PAL_DEBUG !== "1") return;
+  if (!isDebugEnabled()) return;
   const path = logFile();
   rotateIfNeeded(path);
   try {
@@ -86,7 +90,7 @@ export function logDebug(source: string, message: string): void {
   }
 }
 
-/** Log an error (always written, regardless of PAL_DEBUG) */
+/** Log an error (always written, regardless of debug mode) */
 export function logError(source: string, error: unknown): void {
   const path = logFile();
   rotateIfNeeded(path);

package/src/targets/opencode/plugin.ts

@@ -192,9 +192,6 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       output: { env: Record<string, string> }
     ) => {
       output.env.PAL_DIR = PAL_DIR;
-      if (process.env.PAL_DEBUG) {
-        output.env.PAL_DEBUG = process.env.PAL_DEBUG;
-      }
     },
   };
 };