portable-agent-layer 0.1.0

package/src/hooks/lib/work-tracking.ts

@@ -0,0 +1,193 @@
+/**
+ * Structured work tracking: session history + persistent projects.
+ * Replaces the single-file current-work.json approach.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+import { now } from "./time";
+
+// ── Session Records ──────────────────────────────────────────────
+
+export interface SessionRecord {
+  sessionId: string;
+  name: string;
+  ts: string;
+  cwd: string;
+  status: "completed" | "in-progress";
+  summary: string;
+  artifacts: string[];
+  handoff: string;
+  messageCount: number;
+  projectId?: string;
+}
+
+const MAX_SESSIONS = 50;
+const MAX_ARTIFACTS = 20;
+
+function sessionsPath(): string {
+  return resolve(ensureDir(paths.state()), "sessions.json");
+}
+
+export function readSessions(): SessionRecord[] {
+  const p = sessionsPath();
+  if (!existsSync(p)) return [];
+  try {
+    const data = JSON.parse(readFileSync(p, "utf-8"));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+export function writeSession(record: SessionRecord): void {
+  const sessions = readSessions();
+  // Replace existing record with same sessionId, or append
+  const idx = sessions.findIndex((s) => s.sessionId === record.sessionId);
+  if (idx >= 0) {
+    sessions[idx] = record;
+  } else {
+    sessions.push(record);
+  }
+  // Prune to last N
+  const pruned = sessions.slice(-MAX_SESSIONS);
+  writeFileSync(sessionsPath(), JSON.stringify(pruned, null, 2), "utf-8");
+}
+
+/** Filter sessions within the last N hours */
+export function recentSessions(hours: number): SessionRecord[] {
+  const cutoff = Date.now() - hours * 60 * 60 * 1000;
+  return readSessions().filter((s) => new Date(s.ts).getTime() > cutoff);
+}
+
+/** Detect session completion status from last assistant message */
+export function detectStatus(lastAssistant: string): SessionRecord["status"] {
+  const completionSignals =
+    /\b(done|all set|let me know|ready to|complete|finished|that's it|looks good|should be good|merged|shipped|deployed)\b/i;
+  return completionSignals.test(lastAssistant) ? "completed" : "in-progress";
+}
+
+/** Extract file paths mentioned in assistant messages */
+export function extractArtifacts(
+  messages: { role: string; content: string | unknown }[]
+): string[] {
+  const seen = new Set<string>();
+  const artifacts: string[] = [];
+
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+    const text = typeof msg.content === "string" ? msg.content : "";
+    // Match file paths: /absolute/paths and relative/paths with extensions
+    const pathMatches = text.match(/(?:\/[\w./-]+\.[\w]+|[\w./-]+\/[\w.-]+\.[\w]+)/g);
+    if (!pathMatches) continue;
+    for (const p of pathMatches) {
+      // Skip URLs, common noise
+      if (p.includes("://") || p.includes("node_modules")) continue;
+      if (!seen.has(p)) {
+        seen.add(p);
+        artifacts.push(p);
+      }
+      if (artifacts.length >= MAX_ARTIFACTS) return artifacts;
+    }
+  }
+
+  return artifacts;
+}
+
+/** Strip code blocks, paths, and technical noise from text */
+function cleanForHandoff(text: string): string {
+  return (
+    text
+      // Remove fenced code blocks
+      .replace(/```[\s\S]*?```/g, "")
+      // Remove inline code
+      .replace(/`[^`]+`/g, "")
+      // Remove file paths
+      .replace(/(?:\/[\w./-]+\.[\w]+)/g, "")
+      // Remove markdown formatting
+      .replace(/\*\*([^*]+)\*\*/g, "$1")
+      .replace(/^[#]+\s*/gm, "")
+      // Remove tool call artifacts
+      .replace(/^\s*[-*]\s*`[^`]+`.*$/gm, "")
+      // Collapse whitespace
+      .replace(/\n{3,}/g, "\n\n")
+      .trim()
+  );
+}
+
+/** Extract handoff notes from last assistant message */
+export function extractHandoff(lastAssistant: string): string {
+  // Look for explicit next-steps / TODO / remaining sections
+  const sectionMatch = lastAssistant.match(
+    /(?:next steps?|todo|remaining|what's left|still need|want me to)[:\s]*\n([\s\S]{10,300}?)(?:\n\n|\n(?=[A-Z#]))/i
+  );
+  if (sectionMatch) return cleanForHandoff(sectionMatch[1]);
+
+  // Look for closing question/offer (common assistant pattern)
+  const closingMatch = lastAssistant.match(
+    /(?:want (?:me to|to)|shall I|should I|ready to|anything else|let me know)[^\n]*$/im
+  );
+
+  const cleaned = cleanForHandoff(lastAssistant);
+
+  // Use last meaningful paragraph
+  const paragraphs = cleaned
+    .split(/\n\n+/)
+    .map((p) => p.trim())
+    .filter((p) => p.length >= 15 && p.length <= 300);
+
+  if (closingMatch) return closingMatch[0].trim();
+  if (paragraphs.length > 0) return paragraphs[paragraphs.length - 1];
+  if (cleaned.length > 200) return cleaned.slice(-200).trim();
+  return cleaned;
+}
+
+// ── Persistent Projects ──────────────────────────────────────────
+
+export interface Project {
+  id: string;
+  name: string;
+  created: string;
+  updated: string;
+  status: "active" | "paused" | "completed";
+  objectives: string[];
+  decisions: string[];
+  completed: string[];
+  blockers: string[];
+  nextSteps: string[];
+  handoff: string;
+  sessions: string[];
+}
+
+function projectsPath(): string {
+  return resolve(ensureDir(paths.state()), "projects.json");
+}
+
+export function readProjects(): Record<string, Project> {
+  const p = projectsPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeProject(project: Project): void {
+  const projects = readProjects();
+  project.updated = now();
+  projects[project.id] = project;
+  writeFileSync(projectsPath(), JSON.stringify(projects, null, 2), "utf-8");
+}
+
+export function activeProjects(): Project[] {
+  return Object.values(readProjects()).filter((p) => p.status === "active");
+}
+
+export function staleProjects(days = 7): Project[] {
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  return Object.values(readProjects()).filter(
+    (p) => p.status === "active" && new Date(p.updated).getTime() < cutoff
+  );
+}

package/src/hooks/setup-check.ts

@@ -0,0 +1,42 @@
+/**
+ * CLI helper: check setup state and output results.
+ *
+ * Usage:
+ *   bun run hooks/setup-check.ts status     → "complete" or "incomplete"
+ *   bun run hooks/setup-check.ts init        → create setup.json if missing
+ *   bun run hooks/setup-check.ts prompt      → output setup prompt (if incomplete)
+ *
+ * Used by shell scripts to avoid duplicating setup logic.
+ */
+
+import {
+  buildSetupPrompt,
+  ensureSetupState,
+  isSetupComplete,
+  readSetupState,
+} from "./lib/setup";
+
+const command = process.argv[2] ?? "status";
+
+switch (command) {
+  case "status": {
+    const state = readSetupState();
+    console.log(state && isSetupComplete(state) ? "complete" : "incomplete");
+    break;
+  }
+  case "init": {
+    ensureSetupState();
+    break;
+  }
+  case "prompt": {
+    const state = readSetupState();
+    if (state) {
+      const prompt = buildSetupPrompt(state);
+      if (prompt) console.log(prompt);
+    }
+    break;
+  }
+  default:
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+}

package/src/targets/claude/install.ts

@@ -0,0 +1,145 @@
+/**
+ * PAL — Claude Code target installer (TypeScript)
+ * Merges hooks into existing settings.json (never overwrites).
+ * Copies skills additively. 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 {
+  copyAgents,
+  copySkills,
+  countAgents,
+  countMd,
+  countSkills,
+  log,
+  readJson,
+  writeJson,
+} from "../lib";
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CLAUDE_DIR = platform.claudeDir();
+const SETTINGS = resolve(CLAUDE_DIR, "settings.json");
+
+// --- Ensure settings.json exists ---
+mkdirSync(CLAUDE_DIR, { recursive: true });
+if (!existsSync(SETTINGS)) {
+  writeFileSync(SETTINGS, "{}\n", "utf-8");
+  log.info("Created new settings.json");
+}
+
+// --- Backup ---
+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`,
+          },
+        ],
+      },
+    ],
+  },
+};
+
+// --- 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");
+
+// --- Copy skills ---
+const skillsDir = resolve(CLAUDE_DIR, "skills");
+copySkills(skillsDir);
+
+// --- Copy agents ---
+copyAgents();
+
+// --- 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

@@ -0,0 +1,101 @@
+/**
+ * PAL — Claude Code uninstaller (TypeScript)
+ * Removes PAL hooks, skills, and env from settings.json.
+ */
+
+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";
+
+const PKG_ROOT = palPkg();
+const CLAUDE_DIR = platform.claudeDir();
+const SETTINGS = resolve(CLAUDE_DIR, "settings.json");
+
+if (!existsSync(SETTINGS)) {
+  log.info("No settings.json found, nothing to do.");
+  process.exit(0);
+}
+
+// --- Backup ---
+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> };
+
+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");
+
+// --- Remove PAL skills ---
+const removed = removeSkills(resolve(CLAUDE_DIR, "skills"));
+if (removed.length > 0) {
+  log.success(`Removed ${removed.length} skill(s): ${removed.join(", ")}`);
+} else {
+  log.info("No PAL skills found");
+}
+
+// --- Remove PAL agents ---
+const removedAgents = removeAgents();
+if (removedAgents.length > 0) {
+  log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
+} else {
+  log.info("No PAL agents found");
+}
+
+// --- Remove AGENTS.md and CLAUDE.md symlink ---
+const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
+const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");
+try {
+  unlinkSync(claudeMd);
+  log.success("Removed ~/.claude/CLAUDE.md");
+} catch {
+  /* gone */
+}
+try {
+  unlinkSync(agentsMd);
+  log.success("Removed ~/.config/opencode/AGENTS.md");
+} catch {
+  /* gone */
+}
+
+log.success("Claude Code uninstall complete");