@soleri/cli 1.2.0 → 1.4.0

package/src/commands/governance.ts

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { detectAgent } from '../utils/agent-context.js';
+import * as log from '../utils/logger.js';
+
+const VALID_PRESETS = ['strict', 'moderate', 'permissive'] as const;
+
+export function registerGovernance(program: Command): void {
+  program
+    .command('governance')
+    .description('Manage vault governance policy for an agent')
+    .option('--preset <name>', 'Apply preset (strict|moderate|permissive)')
+    .option('--show', 'Show current policy and quota status')
+    .action(async (opts: { preset?: string; show?: boolean }) => {
+      const agent = detectAgent();
+      if (!agent) {
+        log.fail('Not in a Soleri agent project', 'Run from an agent directory');
+        process.exit(1);
+      }
+
+      const dbPath = join(homedir(), `.${agent.agentId}`, 'vault.db');
+      if (!existsSync(dbPath)) {
+        log.fail('Vault DB not found', `Expected ${dbPath}`);
+        log.info('Run the agent once to initialize its vault database.');
+        process.exit(1);
+      }
+
+      // Dynamic import to avoid loading better-sqlite3 unless needed
+      const { Vault, Governance } = await import('@soleri/core');
+      const vault = new Vault(dbPath);
+
+      try {
+        const governance = new Governance(vault);
+
+        if (opts.preset) {
+          if (!VALID_PRESETS.includes(opts.preset as typeof VALID_PRESETS[number])) {
+            log.fail('Invalid preset', `Must be one of: ${VALID_PRESETS.join(', ')}`);
+            process.exit(1);
+          }
+
+          governance.applyPreset(
+            agent.agentId,
+            opts.preset as 'strict' | 'moderate' | 'permissive',
+            'soleri-cli',
+          );
+          log.heading('Governance — Preset Applied');
+          log.pass(`Preset "${opts.preset}" applied to ${agent.agentId}`);
+          console.log();
+          showPolicy(governance, agent.agentId);
+        } else {
+          // Default: --show
+          log.heading('Governance — Current Policy');
+          showPolicy(governance, agent.agentId);
+          console.log();
+          showQuotaStatus(governance, agent.agentId);
+        }
+      } finally {
+        vault.close();
+      }
+    });
+}
+
+function showPolicy(governance: InstanceType<typeof import('@soleri/core').Governance>, agentId: string): void {
+  const policy = governance.getPolicy(agentId);
+
+  log.info('Quotas:');
+  log.dim(`  Max entries total:        ${policy.quotas.maxEntriesTotal}`);
+  log.dim(`  Max entries per category: ${policy.quotas.maxEntriesPerCategory}`);
+  log.dim(`  Max entries per type:     ${policy.quotas.maxEntriesPerType}`);
+  log.dim(`  Warn at:                  ${policy.quotas.warnAtPercent}%`);
+
+  console.log();
+  log.info('Retention:');
+  log.dim(`  Archive after:            ${policy.retention.archiveAfterDays} days`);
+  log.dim(`  Min hits to keep:         ${policy.retention.minHitsToKeep}`);
+  log.dim(`  Delete archived after:    ${policy.retention.deleteArchivedAfterDays} days`);
+
+  console.log();
+  log.info('Auto-capture:');
+  log.dim(`  Enabled:                  ${policy.autoCapture.enabled}`);
+  log.dim(`  Require review:           ${policy.autoCapture.requireReview}`);
+  log.dim(`  Max pending proposals:    ${policy.autoCapture.maxPendingProposals}`);
+  log.dim(`  Auto-expire:              ${policy.autoCapture.autoExpireDays} days`);
+}
+
+function showQuotaStatus(governance: InstanceType<typeof import('@soleri/core').Governance>, agentId: string): void {
+  const status = governance.getQuotaStatus(agentId);
+
+  log.info(`Quota usage: ${status.total} / ${status.maxTotal}`);
+
+  if (status.isWarning) {
+    log.warn('Approaching quota limit', `${Math.round((status.total / status.maxTotal) * 100)}% used`);
+  } else {
+    log.pass('Within quota', `${Math.round((status.total / status.maxTotal) * 100)}% used`);
+  }
+
+  if (Object.keys(status.byType).length > 0) {
+    console.log();
+    log.info('By type:');
+    for (const [type, count] of Object.entries(status.byType)) {
+      log.dim(`  ${type}: ${count}`);
+    }
+  }
+
+  if (Object.keys(status.byCategory).length > 0) {
+    console.log();
+    log.info('By category:');
+    for (const [cat, count] of Object.entries(status.byCategory)) {
+      log.dim(`  ${cat}: ${count}`);
+    }
+  }
+}

package/src/commands/hooks.ts

@@ -87,8 +87,9 @@ export function registerHooks(program: Command): void {
   hooks
     .command('add-pack')
     .argument('<pack>', 'Hook pack name')
-    .description('Install a hook pack globally (~/.claude/)')
-    .action((packName: string) => {
+    .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);
@@ -96,15 +97,17 @@ export function registerHooks(program: Command): void {
         process.exit(1);
       }
 
-      const { installed, skipped } = installPack(packName);
+      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`);
+        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)`);
+        log.info(`Pack "${packName}" installed (${installed.length} hooks) → ${target}`);
       } else {
         log.info(`Pack "${packName}" — all hooks already installed`);
       }
@@ -113,8 +116,9 @@ export function registerHooks(program: Command): void {
   hooks
     .command('remove-pack')
     .argument('<pack>', 'Hook pack name')
-    .description('Remove a hook pack from ~/.claude/')
-    .action((packName: string) => {
+    .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);
@@ -122,7 +126,8 @@ export function registerHooks(program: Command): void {
         process.exit(1);
       }
 
-      const { removed } = removePack(packName);
+      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 {
@@ -144,15 +149,53 @@ export function registerHooks(program: Command): void {
       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}`, `${pack.description} (${pack.hooks.length} hooks)`);
+          log.pass(
+            `${pack.name}${versionLabel}${sourceLabel}`,
+            `${pack.description} (${pack.hooks.length} hooks)`,
+          );
         } else if (status === 'partial') {
-          log.warn(`${pack.name}`, `${pack.description} (${pack.hooks.length} hooks) — partial`);
+          log.warn(
+            `${pack.name}${versionLabel}${sourceLabel}`,
+            `${pack.description} (${pack.hooks.length} hooks) — partial`,
+          );
         } else {
-          log.dim(`  ${pack.name} — ${pack.description} (${pack.hooks.length} hooks)`);
+          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)`);
+    });
 }
 
 function isValidEditor(editor: string): editor is EditorId {

package/src/hook-packs/a11y/hookify.focus-ring-required.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: a11y
+# Version: 1.0.0
 # Rule: focus-ring-required
 name: focus-ring-required
 enabled: true

package/src/hook-packs/a11y/hookify.semantic-html.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: a11y
+# Version: 1.0.0
 # Rule: semantic-html
 name: semantic-html
 enabled: true

package/src/hook-packs/a11y/hookify.ux-touch-targets.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: a11y
+# Version: 1.0.0
 # Rule: ux-touch-targets
 name: ux-touch-targets
 enabled: true

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

@@ -1,5 +1,6 @@
 {
   "name": "a11y",
+  "version": "1.0.0",
   "description": "Accessibility enforcement",
   "hooks": ["semantic-html", "focus-ring-required", "ux-touch-targets"]
 }

package/src/hook-packs/clean-commits/hookify.no-ai-attribution.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: clean-commits
+# Version: 1.0.0
 # Rule: no-ai-attribution
 name: no-ai-attribution
 enabled: true

package/src/hook-packs/clean-commits/manifest.json

@@ -1,5 +1,6 @@
 {
   "name": "clean-commits",
+  "version": "1.0.0",
   "description": "No AI attribution in git commits",
   "hooks": ["no-ai-attribution"]
 }

package/src/hook-packs/css-discipline/hookify.no-important.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: css-discipline
+# Version: 1.0.0
 # Rule: no-important
 name: no-important
 enabled: true

package/src/hook-packs/css-discipline/hookify.no-inline-styles.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: css-discipline
+# Version: 1.0.0
 # Rule: no-inline-styles
 name: no-inline-styles
 enabled: true

package/src/hook-packs/css-discipline/manifest.json

@@ -1,5 +1,6 @@
 {
   "name": "css-discipline",
+  "version": "1.0.0",
   "description": "CSS best practices",
   "hooks": ["no-important", "no-inline-styles"]
 }

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

@@ -1,5 +1,6 @@
 {
   "name": "full",
+  "version": "1.0.0",
   "description": "Complete quality suite — all 8 hooks",
   "hooks": ["no-any-types", "no-console-log", "no-important", "no-inline-styles", "semantic-html", "focus-ring-required", "ux-touch-targets", "no-ai-attribution"],
   "composedFrom": ["typescript-safety", "a11y", "css-discipline", "clean-commits"]

package/src/hook-packs/installer.ts

@@ -1,11 +1,17 @@
 /**
- * Hook pack installer — copies hookify files to ~/.claude/ for global enforcement.
+ * Hook pack installer — copies hookify files to ~/.claude/ (global) or project .claude/ (local).
  */
-import { existsSync, copyFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { existsSync, copyFileSync, unlinkSync, mkdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { getPack } from './registry.js';
 
+/** Resolve the target .claude/ directory. */
+function resolveClaudeDir(projectDir?: string): string {
+  if (projectDir) return join(projectDir, '.claude');
+  return join(homedir(), '.claude');
+}
+
 /**
  * Resolve all hookify file paths for a pack, handling composed packs.
  * Returns a map of hook name → source file path.
@@ -38,16 +44,19 @@ function resolveHookFiles(packName: string): Map<string, string> {
 }
 
 /**
- * Install a hook pack globally to ~/.claude/.
+ * Install a hook pack to ~/.claude/ (default) or project .claude/ (--project).
  * Skips files that already exist (idempotent).
  */
-export function installPack(packName: string): { installed: string[]; skipped: string[] } {
+export function installPack(
+  packName: string,
+  options?: { projectDir?: string },
+): { installed: string[]; skipped: string[] } {
   const pack = getPack(packName);
   if (!pack) {
     throw new Error(`Unknown hook pack: "${packName}"`);
   }
 
-  const claudeDir = join(homedir(), '.claude');
+  const claudeDir = resolveClaudeDir(options?.projectDir);
   mkdirSync(claudeDir, { recursive: true });
 
   const hookFiles = resolveHookFiles(packName);
@@ -68,15 +77,18 @@ export function installPack(packName: string): { installed: string[]; skipped: s
 }
 
 /**
- * Remove a hook pack's files from ~/.claude/.
+ * Remove a hook pack's files from target directory.
  */
-export function removePack(packName: string): { removed: string[] } {
+export function removePack(
+  packName: string,
+  options?: { projectDir?: string },
+): { removed: string[] } {
   const pack = getPack(packName);
   if (!pack) {
     throw new Error(`Unknown hook pack: "${packName}"`);
   }
 
-  const claudeDir = join(homedir(), '.claude');
+  const claudeDir = resolveClaudeDir(options?.projectDir);
   const removed: string[] = [];
 
   for (const hook of pack.manifest.hooks) {
@@ -94,11 +106,14 @@ export function removePack(packName: string): { removed: string[] } {
  * Check if a pack is installed.
  * Returns true (all hooks present), false (none present), or 'partial'.
  */
-export function isPackInstalled(packName: string): boolean | 'partial' {
+export function isPackInstalled(
+  packName: string,
+  options?: { projectDir?: string },
+): boolean | 'partial' {
   const pack = getPack(packName);
   if (!pack) return false;
 
-  const claudeDir = join(homedir(), '.claude');
+  const claudeDir = resolveClaudeDir(options?.projectDir);
   let present = 0;
 
   for (const hook of pack.manifest.hooks) {
@@ -111,3 +126,20 @@ export function isPackInstalled(packName: string): boolean | 'partial' {
   if (present === pack.manifest.hooks.length) return true;
   return 'partial';
 }
+
+/**
+ * Get the installed version of a hook from its file header.
+ * Returns null if no version found or file doesn't exist.
+ */
+export function getInstalledHookVersion(
+  hook: string,
+  options?: { projectDir?: string },
+): string | null {
+  const claudeDir = resolveClaudeDir(options?.projectDir);
+  const filePath = join(claudeDir, `hookify.${hook}.local.md`);
+  if (!existsSync(filePath)) return null;
+
+  const content = readFileSync(filePath, 'utf-8');
+  const match = content.match(/^# Version: (.+)$/m);
+  return match ? match[1] : null;
+}

package/src/hook-packs/registry.ts

@@ -11,21 +11,27 @@ export interface HookPackManifest {
   description: string;
   hooks: string[];
   composedFrom?: string[];
+  version?: string;
+  /** Whether this pack is built-in or user-defined */
+  source?: 'built-in' | 'local';
 }
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 /** Root directory containing all built-in hook packs. */
-function getPacksRoot(): string {
+function getBuiltinRoot(): string {
   return __dirname;
 }
 
-/**
- * List all available built-in hook packs.
- */
-export function listPacks(): HookPackManifest[] {
-  const root = getPacksRoot();
+/** Local custom packs directory. */
+function getLocalRoot(): string {
+  return join(process.cwd(), '.soleri', 'hook-packs');
+}
+
+/** Scan a directory for pack manifests. */
+function scanPacksDir(root: string, source: 'built-in' | 'local'): HookPackManifest[] {
+  if (!existsSync(root)) return [];
   const entries = readdirSync(root, { withFileTypes: true });
   const packs: HookPackManifest[] = [];
 
@@ -36,6 +42,7 @@ export function listPacks(): HookPackManifest[] {
 
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as HookPackManifest;
+      manifest.source = source;
       packs.push(manifest);
     } catch {
       // Skip malformed manifests
@@ -46,18 +53,47 @@ export function listPacks(): HookPackManifest[] {
 }
 
 /**
- * Get a specific pack by name.
+ * List all available hook packs (built-in + local custom).
+ * Local packs in .soleri/hook-packs/ override built-in packs with the same name.
+ */
+export function listPacks(): HookPackManifest[] {
+  const builtIn = scanPacksDir(getBuiltinRoot(), 'built-in');
+  const local = scanPacksDir(getLocalRoot(), 'local');
+
+  // Local packs override built-in packs with same name
+  const byName = new Map<string, HookPackManifest>();
+  for (const pack of builtIn) byName.set(pack.name, pack);
+  for (const pack of local) byName.set(pack.name, pack);
+
+  return Array.from(byName.values());
+}
+
+/**
+ * Get a specific pack by name. Local packs take precedence.
  */
 export function getPack(name: string): { manifest: HookPackManifest; dir: string } | null {
-  const root = getPacksRoot();
-  const dir = join(root, name);
-  const manifestPath = join(dir, 'manifest.json');
+  // Check local first
+  const localDir = join(getLocalRoot(), name);
+  const localManifest = join(localDir, 'manifest.json');
+  if (existsSync(localManifest)) {
+    try {
+      const manifest = JSON.parse(readFileSync(localManifest, 'utf-8')) as HookPackManifest;
+      manifest.source = 'local';
+      return { manifest, dir: localDir };
+    } catch {
+      // Fall through to built-in
+    }
+  }
 
-  if (!existsSync(manifestPath)) return null;
+  // Then built-in
+  const builtinDir = join(getBuiltinRoot(), name);
+  const builtinManifest = join(builtinDir, 'manifest.json');
+  if (!existsSync(builtinManifest)) return null;
 
   try {
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as HookPackManifest;
-    return { manifest, dir };
+    const manifest = JSON.parse(readFileSync(builtinManifest, 'utf-8')) as HookPackManifest;
+    manifest.source = 'built-in';
+    return { manifest, dir: builtinDir };
   } catch {
     return null;
   }

package/src/hook-packs/typescript-safety/hookify.no-any-types.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: typescript-safety
+# Version: 1.0.0
 # Rule: no-any-types
 name: no-any-types
 enabled: true

package/src/hook-packs/typescript-safety/hookify.no-console-log.local.md

@@ -1,5 +1,6 @@
 ---
 # Soleri Hook Pack: typescript-safety
+# Version: 1.0.0
 # Rule: no-console-log
 name: no-console-log
 enabled: true

package/src/hook-packs/typescript-safety/manifest.json

@@ -1,5 +1,6 @@
 {
   "name": "typescript-safety",
+  "version": "1.0.0",
   "description": "Block unsafe TypeScript patterns",
   "hooks": ["no-any-types", "no-console-log"]
 }

package/src/main.ts

@@ -8,13 +8,14 @@ import { registerInstallKnowledge } from './commands/install-knowledge.js';
 import { registerDev } from './commands/dev.js';
 import { registerDoctor } from './commands/doctor.js';
 import { registerHooks } from './commands/hooks.js';
+import { registerGovernance } from './commands/governance.js';
 
 const program = new Command();
 
 program
   .name('soleri')
   .description('Developer CLI for creating and managing Soleri AI agents')
-  .version('1.0.0');
+  .version('1.4.0');
 
 registerCreate(program);
 registerList(program);
@@ -23,5 +24,6 @@ registerInstallKnowledge(program);
 registerDev(program);
 registerDoctor(program);
 registerHooks(program);
+registerGovernance(program);
 
 program.parse();

package/src/utils/checks.ts

@@ -6,6 +6,7 @@ import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { detectAgent } from './agent-context.js';
+import { getInstalledPacks } from '../hook-packs/registry.js';
 
 interface CheckResult {
   status: 'pass' | 'fail' | 'warn';
@@ -134,6 +135,22 @@ function checkCognee(): CheckResult {
   }
 }
 
+export function checkHookPacks(): CheckResult {
+  const installed = getInstalledPacks();
+  if (installed.length === 0) {
+    return {
+      status: 'warn',
+      label: 'Hook packs',
+      detail: 'none installed — run soleri hooks list-packs',
+    };
+  }
+  return {
+    status: 'pass',
+    label: 'Hook packs',
+    detail: installed.join(', '),
+  };
+}
+
 export function runAllChecks(dir?: string): CheckResult[] {
   return [
     checkNodeVersion(),
@@ -143,6 +160,7 @@ export function runAllChecks(dir?: string): CheckResult[] {
     checkNodeModules(dir),
     checkAgentBuild(dir),
     checkMcpRegistration(dir),
+    checkHookPacks(),
     checkCognee(),
   ];
 }