@soleri/cli 9.0.1 → 9.2.0

package/src/commands/hooks.ts

@@ -9,193 +9,94 @@ import * as log from '../utils/logger.js';
 export function registerHooks(program: Command): void {
   const hooks = program.command('hooks').description('Manage editor hooks and hook packs');
 
-  hooks
-    .command('add')
-    .argument('<editor>', `Editor: ${SUPPORTED_EDITORS.join(', ')}`)
-    .description('Generate editor hooks/config files')
-    .action((editor: string) => {
-      if (!isValidEditor(editor)) {
-        log.fail(`Unknown editor "${editor}". Supported: ${SUPPORTED_EDITORS.join(', ')}`);
-        process.exit(1);
-      }
-
-      const ctx = detectAgent();
-      if (!ctx) {
-        log.fail('No agent project detected in current directory.');
-        process.exit(1);
-      }
-
-      const files = installHooks(editor, ctx.agentPath);
-      for (const f of files) {
-        log.pass(`Created ${f}`);
-      }
-      log.info(`${editor} hooks installed for ${ctx.agentId}`);
-    });
-
-  hooks
-    .command('remove')
-    .argument('<editor>', `Editor: ${SUPPORTED_EDITORS.join(', ')}`)
-    .description('Remove editor hooks/config files')
-    .action((editor: string) => {
-      if (!isValidEditor(editor)) {
-        log.fail(`Unknown editor "${editor}". Supported: ${SUPPORTED_EDITORS.join(', ')}`);
-        process.exit(1);
-      }
-
-      const ctx = detectAgent();
-      if (!ctx) {
-        log.fail('No agent project detected in current directory.');
-        process.exit(1);
-      }
-
-      const removed = removeHooks(editor, ctx.agentPath);
-      if (removed.length === 0) {
-        log.info(`No ${editor} hooks found to remove.`);
-      } else {
-        for (const f of removed) {
-          log.warn(`Removed ${f}`);
-        }
-        log.info(`${editor} hooks removed from ${ctx.agentId}`);
-      }
-    });
-
-  hooks
-    .command('list')
-    .description('Show which editor hooks are installed')
-    .action(() => {
-      const ctx = detectAgent();
-      if (!ctx) {
-        log.fail('No agent project detected in current directory.');
-        process.exit(1);
-      }
-
-      const installed = detectInstalledHooks(ctx.agentPath);
-
-      log.heading(`Editor hooks for ${ctx.agentId}`);
-
-      for (const editor of SUPPORTED_EDITORS) {
-        if (installed.includes(editor)) {
-          log.pass(editor, 'installed');
-        } else {
-          log.dim(`  ${editor} — not installed`);
-        }
-      }
-    });
-
-  // ── Hook Pack subcommands ──
-
-  hooks
-    .command('add-pack')
-    .argument('<pack>', 'Hook pack name')
-    .option('--project', 'Install to project .claude/ instead of global ~/.claude/')
-    .description('Install a hook pack globally (~/.claude/) or per-project (--project)')
-    .action((packName: string, opts: { project?: boolean }) => {
-      const pack = getPack(packName);
-      if (!pack) {
-        const available = listPacks().map((p) => p.name);
-        log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`);
-        process.exit(1);
-      }
-
-      const projectDir = opts.project ? process.cwd() : undefined;
-      const target = opts.project ? '.claude/' : '~/.claude/';
-      const { installed, skipped } = installPack(packName, { projectDir });
-      for (const hook of installed) {
-        log.pass(`Installed hookify.${hook}.local.md → ${target}`);
-      }
-      for (const hook of skipped) {
-        log.dim(`  hookify.${hook}.local.md — already exists, skipped`);
-      }
-      if (installed.length > 0) {
-        log.info(`Pack "${packName}" installed (${installed.length} hooks) → ${target}`);
-      } else {
-        log.info(`Pack "${packName}" — all hooks already installed`);
-      }
-    });
-
-  hooks
-    .command('remove-pack')
-    .argument('<pack>', 'Hook pack name')
-    .option('--project', 'Remove from project .claude/ instead of global ~/.claude/')
-    .description('Remove a hook pack')
-    .action((packName: string, opts: { project?: boolean }) => {
-      const pack = getPack(packName);
-      if (!pack) {
-        const available = listPacks().map((p) => p.name);
-        log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`);
-        process.exit(1);
-      }
-
-      const projectDir = opts.project ? process.cwd() : undefined;
-      const { removed } = removePack(packName, { projectDir });
-      if (removed.length === 0) {
-        log.info(`No hooks from pack "${packName}" found to remove.`);
-      } else {
-        for (const hook of removed) {
-          log.warn(`Removed hookify.${hook}.local.md`);
-        }
-        log.info(`Pack "${packName}" removed (${removed.length} hooks)`);
-      }
-    });
-
-  hooks
-    .command('list-packs')
-    .description('Show available hook packs and their status')
-    .action(() => {
-      const packs = listPacks();
-
-      log.heading('Hook Packs');
-
-      for (const pack of packs) {
-        const status = isPackInstalled(pack.name);
-
-        const versionLabel = pack.version ? ` v${pack.version}` : '';
-        const sourceLabel = pack.source === 'local' ? ' [local]' : '';
-
-        if (status === true) {
-          log.pass(
-            `${pack.name}${versionLabel}${sourceLabel}`,
-            `${pack.description} (${pack.hooks.length} hooks)`,
-          );
-        } else if (status === 'partial') {
-          log.warn(
-            `${pack.name}${versionLabel}${sourceLabel}`,
-            `${pack.description} (${pack.hooks.length} hooks) — partial`,
-          );
-        } else {
-          log.dim(
-            `  ${pack.name}${versionLabel}${sourceLabel} — ${pack.description} (${pack.hooks.length} hooks)`,
-          );
-        }
-      }
-    });
-
-  hooks
-    .command('upgrade-pack')
-    .argument('<pack>', 'Hook pack name')
-    .option('--project', 'Upgrade in project .claude/ instead of global ~/.claude/')
-    .description('Upgrade a hook pack to the latest version (overwrites existing files)')
-    .action((packName: string, opts: { project?: boolean }) => {
-      const pack = getPack(packName);
-      if (!pack) {
-        const available = listPacks().map((p) => p.name);
-        log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`);
-        process.exit(1);
-      }
-
-      const projectDir = opts.project ? process.cwd() : undefined;
-      const packVersion = pack.manifest.version ?? 'unknown';
-
-      // Remove then reinstall to force overwrite
-      removePack(packName, { projectDir });
-      const { installed } = installPack(packName, { projectDir });
-
-      for (const hook of installed) {
-        log.pass(`hookify.${hook}.local.md → v${packVersion}`);
-      }
-
-      log.info(`Pack "${packName}" upgraded to v${packVersion} (${installed.length} hooks)`);
-    });
+  hooks.command('add').argument('<editor>', `Editor: ${SUPPORTED_EDITORS.join(', ')}`).description('Generate editor hooks/config files').action((editor: string) => {
+    if (!isValidEditor(editor)) { log.fail(`Unknown editor "${editor}". Supported: ${SUPPORTED_EDITORS.join(', ')}`); process.exit(1); }
+    const ctx = detectAgent();
+    if (!ctx) { log.fail('No agent project detected in current directory.'); process.exit(1); }
+    const files = installHooks(editor, ctx.agentPath);
+    for (const f of files) { log.pass(`Created ${f}`); }
+    log.info(`${editor} hooks installed for ${ctx.agentId}`);
+  });
+
+  hooks.command('remove').argument('<editor>', `Editor: ${SUPPORTED_EDITORS.join(', ')}`).description('Remove editor hooks/config files').action((editor: string) => {
+    if (!isValidEditor(editor)) { log.fail(`Unknown editor "${editor}". Supported: ${SUPPORTED_EDITORS.join(', ')}`); process.exit(1); }
+    const ctx = detectAgent();
+    if (!ctx) { log.fail('No agent project detected in current directory.'); process.exit(1); }
+    const removed = removeHooks(editor, ctx.agentPath);
+    if (removed.length === 0) { log.info(`No ${editor} hooks found to remove.`); } else {
+      for (const f of removed) { log.warn(`Removed ${f}`); }
+      log.info(`${editor} hooks removed from ${ctx.agentId}`);
+    }
+  });
+
+  hooks.command('list').description('Show which editor hooks are installed').action(() => {
+    const ctx = detectAgent();
+    if (!ctx) { log.fail('No agent project detected in current directory.'); process.exit(1); }
+    const installed = detectInstalledHooks(ctx.agentPath);
+    log.heading(`Editor hooks for ${ctx.agentId}`);
+    for (const editor of SUPPORTED_EDITORS) {
+      if (installed.includes(editor)) { log.pass(editor, 'installed'); } else { log.dim(`  ${editor} — not installed`); }
+    }
+  });
+
+  hooks.command('add-pack').argument('<pack>', 'Hook pack name').option('--project', 'Install to project .claude/ instead of global ~/.claude/').description('Install a hook pack globally (~/.claude/) or per-project (--project)').action((packName: string, opts: { project?: boolean }) => {
+    const pack = getPack(packName);
+    if (!pack) { const available = listPacks().map((p) => p.name); log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`); process.exit(1); }
+    const projectDir = opts.project ? process.cwd() : undefined;
+    const target = opts.project ? '.claude/' : '~/.claude/';
+    const { installed, skipped, scripts, lifecycleHooks } = installPack(packName, { projectDir });
+    for (const hook of installed) { log.pass(`Installed hookify.${hook}.local.md → ${target}`); }
+    for (const hook of skipped) { log.dim(`  hookify.${hook}.local.md — already exists, skipped`); }
+    for (const script of scripts) { log.pass(`Installed ${script} → ${target}`); }
+    for (const lc of lifecycleHooks) { log.pass(`Registered lifecycle hook: ${lc}`); }
+    const totalInstalled = installed.length + scripts.length + lifecycleHooks.length;
+    if (totalInstalled > 0) { log.info(`Pack "${packName}" installed (${totalInstalled} items) → ${target}`); } else { log.info(`Pack "${packName}" — all hooks already installed`); }
+  });
+
+  hooks.command('remove-pack').argument('<pack>', 'Hook pack name').option('--project', 'Remove from project .claude/ instead of global ~/.claude/').description('Remove a hook pack').action((packName: string, opts: { project?: boolean }) => {
+    const pack = getPack(packName);
+    if (!pack) { const available = listPacks().map((p) => p.name); log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`); process.exit(1); }
+    const projectDir = opts.project ? process.cwd() : undefined;
+    const { removed, scripts, lifecycleHooks } = removePack(packName, { projectDir });
+    const totalRemoved = removed.length + scripts.length + lifecycleHooks.length;
+    if (totalRemoved === 0) { log.info(`No hooks from pack "${packName}" found to remove.`); } else {
+      for (const hook of removed) { log.warn(`Removed hookify.${hook}.local.md`); }
+      for (const script of scripts) { log.warn(`Removed ${script}`); }
+      for (const lc of lifecycleHooks) { log.warn(`Removed lifecycle hook: ${lc}`); }
+      log.info(`Pack "${packName}" removed (${totalRemoved} items)`);
+    }
+  });
+
+  hooks.command('list-packs').description('Show available hook packs and their status').action(() => {
+    const packs = listPacks();
+    log.heading('Hook Packs');
+    for (const pack of packs) {
+      const status = isPackInstalled(pack.name);
+      const versionLabel = pack.version ? ` v${pack.version}` : '';
+      const sourceLabel = pack.source === 'local' ? ' [local]' : '';
+      const hookCount = pack.hooks.length;
+      const scriptCount = pack.scripts?.length ?? 0;
+      const itemCount = hookCount + scriptCount;
+      const itemLabel = itemCount === 1 ? '1 item' : `${itemCount} items`;
+      if (status === true) { log.pass(`${pack.name}${versionLabel}${sourceLabel}`, `${pack.description} (${itemLabel})`); }
+      else if (status === 'partial') { log.warn(`${pack.name}${versionLabel}${sourceLabel}`, `${pack.description} (${itemLabel}) — partial`); }
+      else { log.dim(`  ${pack.name}${versionLabel}${sourceLabel} — ${pack.description} (${itemLabel})`); }
+    }
+  });
+
+  hooks.command('upgrade-pack').argument('<pack>', 'Hook pack name').option('--project', 'Upgrade in project .claude/ instead of global ~/.claude/').description('Upgrade a hook pack to the latest version (overwrites existing files)').action((packName: string, opts: { project?: boolean }) => {
+    const pack = getPack(packName);
+    if (!pack) { const available = listPacks().map((p) => p.name); log.fail(`Unknown pack "${packName}". Available: ${available.join(', ')}`); process.exit(1); }
+    const projectDir = opts.project ? process.cwd() : undefined;
+    const packVersion = pack.manifest.version ?? 'unknown';
+    removePack(packName, { projectDir });
+    const { installed, scripts, lifecycleHooks } = installPack(packName, { projectDir });
+    for (const hook of installed) { log.pass(`hookify.${hook}.local.md → v${packVersion}`); }
+    for (const script of scripts) { log.pass(`${script} → v${packVersion}`); }
+    for (const lc of lifecycleHooks) { log.pass(`lifecycle hook ${lc} → v${packVersion}`); }
+    const total = installed.length + scripts.length + lifecycleHooks.length;
+    log.info(`Pack "${packName}" upgraded to v${packVersion} (${total} items)`);
+  });
 }
 
 function isValidEditor(editor: string): editor is EditorId {

package/src/commands/install.ts

@@ -1,14 +1,40 @@
 import type { Command } from 'commander';
+import { createRequire } from 'node:module';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import * as p from '@clack/prompts';
 import { detectAgent } from '../utils/agent-context.js';
 
+/** Default parent directory for agents: ~/.soleri/ */
+const SOLERI_HOME = process.env.SOLERI_HOME ?? join(homedir(), '.soleri');
+
 type Target = 'claude' | 'codex' | 'opencode' | 'both' | 'all';
 
-/** MCP server entry for file-tree agents (uses npx @soleri/engine) */
+/**
+ * Resolve the absolute path to the soleri-engine binary.
+ * Falls back to `npx @soleri/engine` if resolution fails (e.g. not installed globally).
+ */
+function resolveEngineBin(): { command: string; bin: string } {
+  try {
+    const require = createRequire(import.meta.url);
+    const bin = require.resolve('@soleri/core/dist/engine/bin/soleri-engine.js');
+    return { command: 'node', bin };
+  } catch {
+    return { command: 'npx', bin: '@soleri/engine' };
+  }
+}
+
+/** MCP server entry for file-tree agents (resolved engine path, no npx) */
 function fileTreeMcpEntry(agentDir: string): Record<string, unknown> {
+  const engine = resolveEngineBin();
+  if (engine.command === 'node') {
+    return {
+      type: 'stdio',
+      command: 'node',
+      args: [engine.bin, '--agent', join(agentDir, 'agent.yaml')],
+    };
+  }
   return {
     type: 'stdio',
     command: 'npx',
@@ -26,7 +52,7 @@ function legacyMcpEntry(agentDir: string): Record<string, unknown> {
   };
 }
 
-function installClaude(agentId: string, agentDir: string, isFileTree: boolean): void {
+export function installClaude(agentId: string, agentDir: string, isFileTree: boolean): void {
   const configPath = join(homedir(), '.claude.json');
   let config: Record<string, unknown> = {};
 
@@ -72,7 +98,12 @@ function installCodex(agentId: string, agentDir: string, isFileTree: boolean): v
   let section: string;
   if (isFileTree) {
     const agentYamlPath = join(agentDir, 'agent.yaml');
-    section = `\n\n${sectionHeader}\ncommand = "npx"\nargs = ["@soleri/engine", "--agent", "${agentYamlPath}"]\n`;
+    const engine = resolveEngineBin();
+    if (engine.command === 'node') {
+      section = `\n\n${sectionHeader}\ncommand = "node"\nargs = ["${engine.bin}", "--agent", "${agentYamlPath}"]\n`;
+    } else {
+      section = `\n\n${sectionHeader}\ncommand = "npx"\nargs = ["@soleri/engine", "--agent", "${agentYamlPath}"]\n`;
+    }
   } else {
     const entryPoint = join(agentDir, 'dist', 'index.js');
     section = `\n\n${sectionHeader}\ncommand = "node"\nargs = ["${entryPoint}"]\n`;
@@ -111,24 +142,12 @@ function installOpencode(agentId: string, agentDir: string, isFileTree: boolean)
 
   const servers = config.mcp as Record<string, unknown>;
   if (isFileTree) {
+    const engine = resolveEngineBin();
     servers[agentId] = {
       type: 'local',
-      command: [
-        'node',
-        join(
-          agentDir,
-          '..',
-          'soleri',
-          'packages',
-          'core',
-          'dist',
-          'engine',
-          'bin',
-          'soleri-engine.js',
-        ),
-        '--agent',
-        join(agentDir, 'agent.yaml'),
-      ],
+      command: engine.command === 'node'
+        ? ['node', engine.bin, '--agent', join(agentDir, 'agent.yaml')]
+        : ['npx', '-y', '@soleri/engine', '--agent', join(agentDir, 'agent.yaml')],
     };
   } else {
     servers[agentId] = {
@@ -174,15 +193,30 @@ function installLauncher(agentId: string, agentDir: string): void {
 export function registerInstall(program: Command): void {
   program
     .command('install')
-    .argument('[dir]', 'Agent directory (defaults to cwd)')
+    .argument('[dir]', 'Agent directory or agent name (checks ~/.soleri/<name> first, then cwd)')
     .option('--target <target>', 'Registration target: claude, opencode, codex, or all', 'claude')
     .description('Register agent as MCP server in editor config')
     .action(async (dir?: string, opts?: { target?: string }) => {
-      const resolvedDir = dir ? resolve(dir) : undefined;
+      let resolvedDir: string | undefined;
+
+      if (dir) {
+        // If dir looks like a bare agent name (no slashes), check ~/.soleri/{name} first
+        if (!dir.includes('/') && !dir.includes('\\')) {
+          const soleriPath = join(SOLERI_HOME, dir);
+          if (existsSync(join(soleriPath, 'agent.yaml'))) {
+            resolvedDir = soleriPath;
+          }
+        }
+        if (!resolvedDir) {
+          resolvedDir = resolve(dir);
+        }
+      }
+
       const ctx = detectAgent(resolvedDir);
 
       if (!ctx) {
         p.log.error('Not in an agent project. Run from an agent directory or pass its path.');
+        p.log.info(`Tip: agents created with "soleri create" live in ${SOLERI_HOME}/`);
         process.exit(1);
       }
 
@@ -196,7 +230,13 @@ export function registerInstall(program: Command): void {
       }
 
       if (isFileTree) {
-        p.log.info(`Detected file-tree agent (v7) — registering via @soleri/engine`);
+        const engine = resolveEngineBin();
+        if (engine.command === 'node') {
+          p.log.info(`Detected file-tree agent (v7) — using resolved engine at ${engine.bin}`);
+        } else {
+          p.log.warn(`Could not resolve @soleri/core locally — falling back to npx (slower startup)`);
+          p.log.info(`For instant startup: npm install -g @soleri/cli`);
+        }
       }
 
       if (target === 'claude' || target === 'both' || target === 'all') {

package/src/commands/pack.ts

@@ -636,7 +636,6 @@ export function registerPack(program: Command): void {
 
 function listMdFiles(dir: string): string[] {
   try {
-    const { readdirSync } = require('node:fs');
     const { basename } = require('node:path');
     return readdirSync(dir)
       .filter((f: string) => f.endsWith('.md'))

package/src/commands/staging.ts

@@ -0,0 +1,208 @@
+import type { Command } from 'commander';
+import { existsSync, readdirSync, statSync, rmSync, cpSync, mkdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { homedir } from 'node:os';
+import * as log from '../utils/logger.js';
+
+const STAGING_ROOT = join(homedir(), '.soleri', 'staging');
+
+interface StagedEntry {
+  id: string;
+  timestamp: string;
+  path: string;
+  size: number;
+  isDirectory: boolean;
+}
+
+/**
+ * Walk a directory tree and collect all items with their relative paths.
+ */
+function walkDir(dir: string, base: string): { relPath: string; size: number }[] {
+  const results: { relPath: string; size: number }[] = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(base, fullPath);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, base));
+    } else {
+      const stat = statSync(fullPath);
+      results.push({ relPath, size: stat.size });
+    }
+  }
+  return results;
+}
+
+/**
+ * List all staged entries.
+ */
+function listStaged(): StagedEntry[] {
+  if (!existsSync(STAGING_ROOT)) return [];
+
+  const entries: StagedEntry[] = [];
+  const dirs = readdirSync(STAGING_ROOT, { withFileTypes: true });
+
+  for (const dir of dirs) {
+    if (!dir.isDirectory()) continue;
+    const stagePath = join(STAGING_ROOT, dir.name);
+    const _stat = statSync(stagePath);
+    const files = walkDir(stagePath, stagePath);
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+
+    entries.push({
+      id: dir.name,
+      timestamp: dir.name,
+      path: stagePath,
+      size: totalSize,
+      isDirectory: true,
+    });
+  }
+
+  return entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
+/**
+ * Parse a duration string like "7d", "24h", "30m" into milliseconds.
+ */
+function parseDuration(duration: string): number | null {
+  const match = duration.match(/^(\d+)(d|h|m)$/);
+  if (!match) return null;
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case 'd':
+      return value * 24 * 60 * 60 * 1000;
+    case 'h':
+      return value * 60 * 60 * 1000;
+    case 'm':
+      return value * 60 * 1000;
+    default:
+      return null;
+  }
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function registerStaging(program: Command): void {
+  const staging = program.command('staging').description('Manage anti-deletion staging folder');
+
+  staging
+    .command('list')
+    .description('Show staged files with timestamps')
+    .action(() => {
+      const entries = listStaged();
+
+      if (entries.length === 0) {
+        log.info('No staged files found.');
+        log.dim(`  Staging directory: ${STAGING_ROOT}`);
+        return;
+      }
+
+      log.heading('Staged Files');
+
+      for (const entry of entries) {
+        const files = walkDir(entry.path, entry.path);
+        log.pass(entry.id, `${files.length} file(s), ${formatSize(entry.size)}`);
+        for (const file of files.slice(0, 10)) {
+          log.dim(`    ${file.relPath}`);
+        }
+        if (files.length > 10) {
+          log.dim(`    ... and ${files.length - 10} more`);
+        }
+      }
+
+      log.info(`${entries.length} staging snapshot(s) in ${STAGING_ROOT}`);
+    });
+
+  staging
+    .command('restore')
+    .argument('<id>', 'Staging snapshot ID (timestamp)')
+    .description('Restore files from staging to their original locations')
+    .action((id: string) => {
+      const stagePath = join(STAGING_ROOT, id);
+
+      if (!existsSync(stagePath)) {
+        log.fail(`Staging snapshot "${id}" not found.`);
+        const entries = listStaged();
+        if (entries.length > 0) {
+          log.info(`Available: ${entries.map((e) => e.id).join(', ')}`);
+        }
+        process.exit(1);
+      }
+
+      const files = walkDir(stagePath, stagePath);
+      let restored = 0;
+
+      for (const file of files) {
+        // The staging preserves absolute paths, so the relPath starts from root
+        const destPath = join('/', file.relPath);
+        const srcPath = join(stagePath, file.relPath);
+
+        try {
+          const destDir = join(destPath, '..');
+          mkdirSync(destDir, { recursive: true });
+          cpSync(srcPath, destPath, { force: true });
+          restored++;
+          log.pass(`Restored ${destPath}`);
+        } catch (err) {
+          log.fail(`Failed to restore ${destPath}: ${err}`);
+        }
+      }
+
+      log.info(`Restored ${restored}/${files.length} file(s) from snapshot "${id}"`);
+    });
+
+  staging
+    .command('purge')
+    .option('--older-than <duration>', 'Only purge snapshots older than duration (e.g. 7d, 24h)')
+    .description('Permanently delete staged files')
+    .action((opts: { olderThan?: string }) => {
+      if (!existsSync(STAGING_ROOT)) {
+        log.info('No staging directory found. Nothing to purge.');
+        return;
+      }
+
+      const entries = listStaged();
+
+      if (entries.length === 0) {
+        log.info('No staged files to purge.');
+        return;
+      }
+
+      let toPurge = entries;
+
+      if (opts.olderThan) {
+        const maxAge = parseDuration(opts.olderThan);
+        if (!maxAge) {
+          log.fail(`Invalid duration: "${opts.olderThan}". Use format like 7d, 24h, 30m`);
+          process.exit(1);
+        }
+
+        const cutoff = Date.now() - maxAge;
+        toPurge = entries.filter((entry) => {
+          const stat = statSync(entry.path);
+          return stat.mtimeMs < cutoff;
+        });
+      }
+
+      if (toPurge.length === 0) {
+        log.info('No snapshots match the purge criteria.');
+        return;
+      }
+
+      for (const entry of toPurge) {
+        rmSync(entry.path, { recursive: true, force: true });
+        log.warn(`Purged ${entry.id}`);
+      }
+
+      log.info(`Purged ${toPurge.length} staging snapshot(s)`);
+    });
+}

package/src/hook-packs/full/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "full",
   "version": "1.0.0",
-  "description": "Complete quality suite — all 8 hooks",
+  "description": "Complete quality suite — all hooks",
   "hooks": [
     "no-any-types",
     "no-console-log",
@@ -12,5 +12,5 @@
     "ux-touch-targets",
     "no-ai-attribution"
   ],
-  "composedFrom": ["typescript-safety", "a11y", "css-discipline", "clean-commits"]
+  "composedFrom": ["typescript-safety", "a11y", "css-discipline", "clean-commits", "yolo-safety"]
 }