@soleri/cli 9.4.0 → 9.5.0

package/src/commands/hooks.ts

@@ -1,9 +1,24 @@
 import type { Command } from 'commander';
+import { mkdirSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { SUPPORTED_EDITORS, type EditorId } from '../hooks/templates.js';
 import { installHooks, removeHooks, detectInstalledHooks } from '../hooks/generator.js';
 import { detectAgent } from '../utils/agent-context.js';
 import { listPacks, getPack } from '../hook-packs/registry.js';
 import { installPack, removePack, isPackInstalled } from '../hook-packs/installer.js';
+import { promotePack, demotePack } from '../hook-packs/graduation.js';
+import {
+  generateHookScript,
+  generateManifest,
+  HOOK_EVENTS,
+  ACTION_LEVELS,
+} from '../hook-packs/converter/template.js';
+import type {
+  HookEvent,
+  ActionLevel,
+  HookConversionConfig,
+} from '../hook-packs/converter/template.js';
+import { generateFixtures, validateHookScript } from '../hook-packs/validator.js';
 import * as log from '../utils/logger.js';
 
 export function registerHooks(program: Command): void {
@@ -201,6 +216,163 @@ export function registerHooks(program: Command): void {
       const total = installed.length + scripts.length + lifecycleHooks.length;
       log.info(`Pack "${packName}" upgraded to v${packVersion} (${total} items)`);
     });
+
+  hooks
+    .command('convert')
+    .argument('<name>', 'Name for the converted hook pack (kebab-case)')
+    .requiredOption(
+      '--event <event>',
+      'Hook event: PreToolUse, PostToolUse, PreCompact, Notification, Stop',
+    )
+    .option(
+      '--matcher <tools>',
+      'Tool name matcher (e.g., "Write|Edit") — for PreToolUse/PostToolUse',
+    )
+    .option('--pattern <globs...>', 'File glob patterns to match (e.g., "**/marketing/**")')
+    .option('--action <level>', 'Action level: remind (default), warn, block', 'remind')
+    .requiredOption('--message <text>', 'Context message when hook fires')
+    .option('--project', 'Output to .soleri/hook-packs/ instead of built-in packs dir')
+    .description('Convert a skill into an automated hook pack')
+    .action(
+      (
+        name: string,
+        opts: {
+          event: string;
+          matcher?: string;
+          pattern?: string[];
+          action: string;
+          message: string;
+          project?: boolean;
+        },
+      ) => {
+        if (!HOOK_EVENTS.includes(opts.event as HookEvent)) {
+          log.fail(`Invalid event "${opts.event}". Must be one of: ${HOOK_EVENTS.join(', ')}`);
+          process.exit(1);
+        }
+
+        if (!ACTION_LEVELS.includes(opts.action as ActionLevel)) {
+          log.fail(`Invalid action "${opts.action}". Must be one of: ${ACTION_LEVELS.join(', ')}`);
+          process.exit(1);
+        }
+
+        const config: HookConversionConfig = {
+          name,
+          event: opts.event as HookEvent,
+          toolMatcher: opts.matcher,
+          filePatterns: opts.pattern,
+          action: opts.action as ActionLevel,
+          message: opts.message,
+        };
+
+        const script = generateHookScript(config);
+        const manifest = generateManifest(config);
+
+        const baseDir = opts.project
+          ? join(process.cwd(), '.soleri', 'hook-packs', name)
+          : join(process.cwd(), 'packages', 'cli', 'src', 'hook-packs', name);
+
+        const scriptsDir = join(baseDir, 'scripts');
+        mkdirSync(scriptsDir, { recursive: true });
+
+        const manifestPath = join(baseDir, 'manifest.json');
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+        log.pass(`Created ${manifestPath}`);
+
+        const scriptPath = join(scriptsDir, `${name}.sh`);
+        writeFileSync(scriptPath, script);
+        if (process.platform !== 'win32') {
+          chmodSync(scriptPath, 0o755);
+        }
+        log.pass(`Created ${scriptPath}`);
+
+        log.info(`Hook pack "${name}" generated (event: ${opts.event}, action: ${opts.action})`);
+      },
+    );
+  hooks
+    .command('promote')
+    .argument('<pack>', 'Hook pack name')
+    .description('Promote hook action level: remind → warn → block')
+    .action((packName: string) => {
+      try {
+        const result = promotePack(packName);
+        log.pass(`${packName}: ${result.previousLevel} → ${result.newLevel}`);
+      } catch (err: unknown) {
+        log.fail((err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  hooks
+    .command('demote')
+    .argument('<pack>', 'Hook pack name')
+    .description('Demote hook action level: block → warn → remind')
+    .action((packName: string) => {
+      try {
+        const result = demotePack(packName);
+        log.pass(`${packName}: ${result.previousLevel} → ${result.newLevel}`);
+      } catch (err: unknown) {
+        log.fail((err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  hooks
+    .command('test')
+    .argument('<pack>', 'Hook pack name to test')
+    .description('Run validation tests against a hook pack')
+    .action((packName: string) => {
+      const pack = getPack(packName);
+      if (!pack) {
+        log.fail(`Unknown pack "${packName}"`);
+        process.exit(1);
+      }
+
+      // Find the script
+      const scripts = pack.manifest.scripts;
+      if (!scripts || scripts.length === 0) {
+        log.fail(`Pack "${packName}" has no scripts to test`);
+        process.exit(1);
+      }
+
+      const scriptFile = scripts[0].file;
+      // Resolve script path from pack directory
+      const scriptPath = join(pack.dir, 'scripts', scriptFile);
+
+      if (!existsSync(scriptPath)) {
+        log.fail(`Script not found: ${scriptPath}`);
+        process.exit(1);
+      }
+
+      // Determine event and matcher from lifecycle hooks
+      const lc = pack.manifest.lifecycleHooks?.[0];
+      const event = (lc?.event ?? 'PreToolUse') as HookEvent;
+      const toolMatcher = lc?.matcher;
+
+      // Generate fixtures and run
+      const fixtures = generateFixtures(event, toolMatcher);
+      log.heading(`Testing ${packName} (${fixtures.length} fixtures)`);
+
+      const report = validateHookScript(scriptPath, fixtures);
+      log.info(`Results: ${report.passed}/${report.total} passed`);
+
+      if (report.falsePositives.length > 0) {
+        log.fail(`False positives: ${report.falsePositives.length}`);
+        for (const fp of report.falsePositives) {
+          log.warn(`  ${fp.fixture.name}: expected no match, got output`);
+        }
+      }
+
+      if (report.falseNegatives.length > 0) {
+        log.warn(`False negatives: ${report.falseNegatives.length}`);
+        for (const fn of report.falseNegatives) {
+          log.warn(`  ${fn.fixture.name}: expected match, got no output`);
+        }
+      }
+
+      if (report.falsePositives.length === 0 && report.falseNegatives.length === 0) {
+        log.pass('All fixtures passed — zero false positives');
+      }
+    });
 }
 
 function isValidEditor(editor: string): editor is EditorId {

package/src/commands/install.ts

@@ -170,6 +170,12 @@ function escapeRegExp(s: string): string {
  * e.g., typing `ernesto` opens Claude Code with that agent's MCP config.
  */
 function installLauncher(agentId: string, agentDir: string): void {
+  // Launcher scripts to /usr/local/bin are Unix-only
+  if (process.platform === 'win32') {
+    p.log.info('Launcher scripts are not supported on Windows — skipping');
+    return;
+  }
+
   const binPath = join('/usr/local/bin', agentId);
 
   const script = [

package/src/hook-packs/converter/README.md

@@ -0,0 +1,99 @@
+# Skill-to-Hook Conversion System
+
+Convert repeatedly-invoked skills into automated Claude Code hooks. Hooks fire automatically on matching events — no manual invocation, no LLM round trip.
+
+## Workflow
+
+```
+Score → Convert → Test → Graduate
+```
+
+### 1. Score the Candidate
+
+Evaluate 4 dimensions (each HIGH or LOW):
+
+| Dimension             | HIGH when...                                             |
+| --------------------- | -------------------------------------------------------- |
+| **Frequency**         | 3+ manual calls per session for same event type          |
+| **Event Correlation** | Skill consistently triggers on a recognizable hook event |
+| **Determinism**       | Skill produces consistent, non-exploratory guidance      |
+| **Autonomy**          | Skill requires no interactive user decisions             |
+
+**Threshold:** 3/4 HIGH = candidate for conversion.
+
+```typescript
+import { scoreCandidateForConversion } from '@soleri/core';
+
+const result = scoreCandidateForConversion({
+  frequency: 'HIGH',
+  eventCorrelation: 'HIGH',
+  determinism: 'HIGH',
+  autonomy: 'LOW',
+});
+// result.candidate === true (3/4)
+```
+
+### 2. Convert
+
+```bash
+soleri hooks convert marketing-research \
+  --event PreToolUse \
+  --matcher "Write|Edit" \
+  --pattern "**/marketing/**" \
+  --action remind \
+  --message "Check brand guidelines and A/B testing data"
+```
+
+This creates a hook pack with `manifest.json` and a POSIX shell script.
+
+### 3. Test
+
+```bash
+soleri hooks test marketing-research
+```
+
+Runs 15 fixtures (5 matching + 10 non-matching) against the hook script. Reports false positives and false negatives. **Zero false positives required before graduation.**
+
+### 4. Graduate
+
+Hooks default to `remind` (gentle context injection). After proving zero false positives:
+
+```bash
+soleri hooks promote marketing-research   # remind → warn
+soleri hooks promote marketing-research   # warn → block
+```
+
+To step back:
+
+```bash
+soleri hooks demote marketing-research    # block → warn
+```
+
+## Hook Events
+
+| Event          | When it fires                                |
+| -------------- | -------------------------------------------- |
+| `PreToolUse`   | Before a tool call (Write, Edit, Bash, etc.) |
+| `PostToolUse`  | After a tool call completes                  |
+| `PreCompact`   | Before context compaction                    |
+| `Notification` | On notification events                       |
+| `Stop`         | When the session ends                        |
+
+## Action Levels
+
+| Level    | Behavior                              |
+| -------- | ------------------------------------- |
+| `remind` | Inject context, don't block (default) |
+| `warn`   | Inject warning context, don't block   |
+| `block`  | Block the operation with a reason     |
+
+## CLI Commands
+
+| Command                           | Description                           |
+| --------------------------------- | ------------------------------------- |
+| `soleri hooks convert <name>`     | Create a new hook pack from a skill   |
+| `soleri hooks test <pack>`        | Validate a hook pack against fixtures |
+| `soleri hooks promote <pack>`     | Step up action level                  |
+| `soleri hooks demote <pack>`      | Step down action level                |
+| `soleri hooks add-pack <pack>`    | Install a hook pack                   |
+| `soleri hooks remove-pack <pack>` | Uninstall a hook pack                 |

package/src/hook-packs/converter/template.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { generateHookScript, generateManifest, HOOK_EVENTS, ACTION_LEVELS } from './template.js';
+import type { HookConversionConfig } from './template.js';
+
+describe('generateHookScript', () => {
+  const baseConfig: HookConversionConfig = {
+    name: 'test-hook',
+    event: 'PreToolUse',
+    toolMatcher: 'Write|Edit',
+    filePatterns: ['**/marketing/**'],
+    action: 'remind',
+    message: 'Check brand guidelines before editing marketing files',
+  };
+
+  it('should generate a valid POSIX shell script', () => {
+    const script = generateHookScript(baseConfig);
+    expect(script).toContain('#!/bin/sh');
+    expect(script).toContain('set -eu');
+    expect(script).toContain('INPUT=$(cat)');
+  });
+
+  it('should include tool matcher for PreToolUse', () => {
+    const script = generateHookScript(baseConfig);
+    expect(script).toContain('TOOL_NAME=');
+    expect(script).toContain('Write|Edit');
+    expect(script).toContain('case "$TOOL_NAME" in');
+  });
+
+  it('should include file pattern matching', () => {
+    const script = generateHookScript(baseConfig);
+    expect(script).toContain('FILE_PATH=');
+    expect(script).toContain('MATCHED=false');
+    expect(script).toContain('marketing');
+  });
+
+  it('should output remind action by default', () => {
+    const script = generateHookScript(baseConfig);
+    expect(script).toContain('REMINDER:');
+    expect(script).toContain('continue: true');
+  });
+
+  it('should output warn action', () => {
+    const script = generateHookScript({ ...baseConfig, action: 'warn' });
+    expect(script).toContain('WARNING:');
+    expect(script).toContain('continue: true');
+  });
+
+  it('should output block action', () => {
+    const script = generateHookScript({ ...baseConfig, action: 'block' });
+    expect(script).toContain('BLOCKED:');
+    expect(script).toContain('continue: false');
+  });
+
+  it('should skip tool matcher for non-tool events', () => {
+    const script = generateHookScript({ ...baseConfig, event: 'PreCompact' });
+    expect(script).not.toContain('TOOL_NAME');
+    expect(script).not.toContain('case');
+  });
+
+  it('should skip file pattern matching when no patterns', () => {
+    const script = generateHookScript({ ...baseConfig, filePatterns: undefined });
+    expect(script).not.toContain('FILE_PATH');
+    expect(script).not.toContain('MATCHED');
+  });
+
+  it('should generate scripts for all 5 hook events', () => {
+    for (const event of HOOK_EVENTS) {
+      const script = generateHookScript({ ...baseConfig, event });
+      expect(script).toContain(`# Event: ${event}`);
+      expect(script).toContain('#!/bin/sh');
+    }
+  });
+
+  it('should escape single quotes in messages', () => {
+    const script = generateHookScript({ ...baseConfig, message: "Don't forget the guidelines" });
+    // Should not have unbalanced quotes
+    expect(script).toContain('forget');
+  });
+});
+
+describe('generateManifest', () => {
+  const config: HookConversionConfig = {
+    name: 'my-hook',
+    event: 'PreToolUse',
+    toolMatcher: 'Write',
+    action: 'remind',
+    message: 'Test message',
+  };
+
+  it('should generate valid manifest with required fields', () => {
+    const manifest = generateManifest(config);
+    expect(manifest.name).toBe('my-hook');
+    expect(manifest.version).toBe('1.0.0');
+    expect(manifest.hooks).toEqual([]);
+    expect(manifest.scripts).toHaveLength(1);
+    expect(manifest.lifecycleHooks).toHaveLength(1);
+  });
+
+  it('should set script name and file correctly', () => {
+    const manifest = generateManifest(config);
+    expect(manifest.scripts![0].name).toBe('my-hook');
+    expect(manifest.scripts![0].file).toBe('my-hook.sh');
+    expect(manifest.scripts![0].targetDir).toBe('hooks');
+  });
+
+  it('should set lifecycle hook event and command', () => {
+    const manifest = generateManifest(config);
+    const lc = manifest.lifecycleHooks![0];
+    expect(lc.event).toBe('PreToolUse');
+    expect(lc.command).toBe('sh ~/.claude/hooks/my-hook.sh');
+    expect(lc.type).toBe('command');
+    expect(lc.timeout).toBe(10);
+  });
+
+  it('should use description from config or fallback to message', () => {
+    expect(generateManifest(config).description).toBe('Test message');
+    expect(generateManifest({ ...config, description: 'Custom desc' }).description).toBe(
+      'Custom desc',
+    );
+  });
+
+  it('should include actionLevel', () => {
+    expect(generateManifest(config).actionLevel).toBe('remind');
+    expect(generateManifest({ ...config, action: 'block' }).actionLevel).toBe('block');
+  });
+
+  it('should generate manifests for all action levels', () => {
+    for (const action of ACTION_LEVELS) {
+      const manifest = generateManifest({ ...config, action });
+      expect(manifest.actionLevel).toBe(action);
+    }
+  });
+});

package/src/hook-packs/converter/template.ts

@@ -0,0 +1,163 @@
+/**
+ * Conversion template for skill-to-hook conversion.
+ * Generates POSIX shell scripts and pack manifests for converted hooks.
+ */
+
+import type { HookPackManifest, HookPackLifecycleHook, HookPackScript } from '../registry.js';
+
+/** Supported Claude Code hook events */
+export type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PreCompact' | 'Notification' | 'Stop';
+
+/** Action levels for graduated enforcement */
+export type ActionLevel = 'remind' | 'warn' | 'block';
+
+/** Configuration for generating a converted hook */
+export interface HookConversionConfig {
+  /** Hook pack name (kebab-case) */
+  name: string;
+  /** Claude Code hook event to trigger on */
+  event: HookEvent;
+  /** Tool name matcher (e.g., 'Write|Edit', 'Bash') — only for PreToolUse/PostToolUse */
+  toolMatcher?: string;
+  // File glob patterns to match (e.g., ['**/marketing/**', '**/*.tsx'])
+  filePatterns?: string[];
+  /** Action level: remind (default), warn, or block */
+  action: ActionLevel;
+  /** Context message to inject when the hook fires */
+  message: string;
+  /** Optional description for the pack */
+  description?: string;
+}
+
+export const HOOK_EVENTS: HookEvent[] = [
+  'PreToolUse',
+  'PostToolUse',
+  'PreCompact',
+  'Notification',
+  'Stop',
+];
+export const ACTION_LEVELS: ActionLevel[] = ['remind', 'warn', 'block'];
+
+/**
+ * Generate a POSIX shell script for a converted hook.
+ * Reads JSON from stdin, matches tool/file patterns, outputs action JSON.
+ */
+export function generateHookScript(config: HookConversionConfig): string {
+  const lines: string[] = [
+    '#!/bin/sh',
+    `# Converted hook: ${config.name} (Soleri Hook Pack)`,
+    `# Event: ${config.event} | Action: ${config.action}`,
+    '#',
+    `# ${config.message}`,
+    '#',
+    '# Dependencies: jq (required)',
+    '# POSIX sh compatible.',
+    '',
+    'set -eu',
+    '',
+    'INPUT=$(cat)',
+    '',
+  ];
+
+  if (config.event === 'PreToolUse' || config.event === 'PostToolUse') {
+    // Tool-based hooks read tool_name and tool_input from stdin
+    lines.push('# Extract tool name and input from stdin JSON');
+    lines.push("TOOL_NAME=$(printf '%s' \"$INPUT\" | jq -r '.tool_name // empty' 2>/dev/null)");
+    lines.push('');
+
+    // Tool matcher
+    if (config.toolMatcher) {
+      lines.push('# Check tool name matcher');
+      lines.push(`case "$TOOL_NAME" in`);
+      // Split on | for case pattern matching
+      const tools = config.toolMatcher.split('|').map((t) => t.trim());
+      lines.push(`  ${tools.join('|')}) ;; # matched`);
+      lines.push('  *) exit 0 ;; # not a matching tool');
+      lines.push('esac');
+      lines.push('');
+    }
+
+    // File pattern matching
+    if (config.filePatterns && config.filePatterns.length > 0) {
+      lines.push('# Extract file path from tool input');
+      lines.push(
+        "FILE_PATH=$(printf '%s' \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.command // empty' 2>/dev/null)",
+      );
+      lines.push('');
+      lines.push('# Check file patterns');
+      lines.push('MATCHED=false');
+      for (const pattern of config.filePatterns) {
+        // Convert glob to grep-compatible regex
+        const regex = pattern.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*');
+        lines.push(`printf '%s' "$FILE_PATH" | grep -qE '${regex}' && MATCHED=true`);
+      }
+      lines.push('');
+      lines.push('if [ "$MATCHED" = false ]; then');
+      lines.push('  exit 0');
+      lines.push('fi');
+      lines.push('');
+    }
+  }
+
+  // Output the action
+  const escapedMessage = config.message.replace(/'/g, "'\\''");
+
+  if (config.action === 'block') {
+    lines.push('# Block the operation');
+    lines.push('jq -n \\');
+    lines.push(`  --arg msg '${escapedMessage}' \\`);
+    lines.push("  '{");
+    lines.push('    continue: false,');
+    lines.push('    stopReason: ("BLOCKED: " + $msg)');
+    lines.push("  }'");
+  } else if (config.action === 'warn') {
+    lines.push('# Warn — allow but inject context');
+    lines.push('jq -n \\');
+    lines.push(`  --arg msg '${escapedMessage}' \\`);
+    lines.push("  '{");
+    lines.push('    continue: true,');
+    lines.push('    message: ("WARNING: " + $msg)');
+    lines.push("  }'");
+  } else {
+    // remind (default)
+    lines.push('# Remind — inject context without blocking');
+    lines.push('jq -n \\');
+    lines.push(`  --arg msg '${escapedMessage}' \\`);
+    lines.push("  '{");
+    lines.push('    continue: true,');
+    lines.push('    message: ("REMINDER: " + $msg)');
+    lines.push("  }'");
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Generate a HookPackManifest for a converted hook.
+ */
+export function generateManifest(config: HookConversionConfig): HookPackManifest {
+  const script: HookPackScript = {
+    name: config.name,
+    file: `${config.name}.sh`,
+    targetDir: 'hooks',
+  };
+
+  const lifecycleHook: HookPackLifecycleHook = {
+    event: config.event,
+    matcher: config.toolMatcher ?? '',
+    type: 'command',
+    command: `sh ~/.claude/hooks/${config.name}.sh`,
+    timeout: 10,
+    statusMessage: config.message,
+  };
+
+  return {
+    name: config.name,
+    version: '1.0.0',
+    description: config.description ?? config.message,
+    hooks: [],
+    scripts: [script],
+    lifecycleHooks: [lifecycleHook],
+    actionLevel: config.action,
+  };
+}

package/src/hook-packs/flock-guard/README.md

@@ -0,0 +1,65 @@
+# flock-guard
+
+Parallel agent lock guard for Soleri. Prevents lockfile corruption when multiple agents run concurrently in worktrees of the same repository.
+
+## What it protects
+
+Intercepts commands that modify package manager lockfiles:
+
+| Package Manager | Commands                      |
+| --------------- | ----------------------------- |
+| npm             | `npm install`, `npm ci`       |
+| yarn            | `yarn`, `yarn install`        |
+| pnpm            | `pnpm install`                |
+| cargo           | `cargo build`, `cargo update` |
+| pip             | `pip install`, `pip3 install` |
+
+## How locking works
+
+1. **PreToolUse** hook fires before any Bash command
+2. If the command matches a lockfile-modifying pattern, the hook acquires a lock via `mkdir` (atomic on POSIX)
+3. Lock state is written to a JSON file inside the lock directory: agent ID, timestamp, command
+4. If another agent already holds the lock, the command is **blocked** with a descriptive error
+5. **PostToolUse** hook fires after the command completes and releases the lock
+
+### Lock path
+
+```
+/tmp/soleri-guard-<project-hash>.lock/lock.json
+```
+
+The project hash is derived from the git repository root path, so all worktrees of the same repository share the same lock. This is intentional — lockfile writes in any worktree can conflict at the npm/yarn cache level.
+
+### Reentrant locking
+
+If the same agent (identified by `CLAUDE_SESSION_ID` or PID) already holds the lock, the hook refreshes the timestamp and allows the command through. This prevents self-deadlock when chaining multiple install commands.
+
+### Stale lock detection
+
+Locks older than **30 seconds** are considered stale and automatically cleaned up. This handles the case where an agent crashes mid-install without releasing the lock.
+
+## Installation
+
+```bash
+soleri hooks add-pack flock-guard
+```
+
+## Troubleshooting
+
+### Stuck lock
+
+If a lock is stuck (agent crashed, machine rebooted mid-install), clear it manually:
+
+```bash
+rm -rf /tmp/soleri-guard-*.lock
+```
+
+### Checking lock status
+
+```bash
+cat /tmp/soleri-guard-*.lock/lock.json 2>/dev/null || echo "No active locks"
+```
+
+### Dependencies
+
+Requires `jq` to be installed and available on PATH.