@soleri/cli 9.4.0 → 9.6.0

package/src/__tests__/validator.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, vi } from 'vitest';
+import { execSync } from 'node:child_process';
+import { generateFixtures, validateHookScript } from '../hook-packs/validator.js';
+import type { TestFixture } from '../hook-packs/validator.js';
+
+// Mock execSync to avoid needing actual shell scripts in tests
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(() => ''),
+}));
+
+const mockedExecSync = vi.mocked(execSync);
+
+describe('validator', () => {
+  describe('generateFixtures', () => {
+    it('should return 15 fixtures for PreToolUse (5 matching + 10 non-matching)', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Write');
+      expect(fixtures).toHaveLength(15);
+
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      expect(matching).toHaveLength(5);
+      expect(nonMatching).toHaveLength(10);
+    });
+
+    it('should return 15 fixtures for PostToolUse', () => {
+      const fixtures = generateFixtures('PostToolUse', 'Edit|Write');
+      expect(fixtures).toHaveLength(15);
+
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      expect(matching).toHaveLength(5);
+      expect(nonMatching).toHaveLength(10);
+    });
+
+    it('should return 15 fixtures for PreCompact', () => {
+      const fixtures = generateFixtures('PreCompact');
+      expect(fixtures).toHaveLength(15);
+
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      expect(matching).toHaveLength(5);
+      expect(nonMatching).toHaveLength(10);
+    });
+
+    it('should return 15 fixtures for Notification', () => {
+      const fixtures = generateFixtures('Notification');
+      expect(fixtures).toHaveLength(15);
+    });
+
+    it('should return 15 fixtures for Stop', () => {
+      const fixtures = generateFixtures('Stop');
+      expect(fixtures).toHaveLength(15);
+    });
+
+    it('matching PreToolUse fixtures should have shouldMatch: true', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Bash');
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      for (const f of matching) {
+        expect(f.shouldMatch).toBe(true);
+      }
+    });
+
+    it('non-matching PreToolUse fixtures should have shouldMatch: false', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Write');
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      for (const f of nonMatching) {
+        expect(f.shouldMatch).toBe(false);
+      }
+    });
+
+    it('PreToolUse matching fixtures should contain tool_name and tool_input', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Write|Edit');
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      for (const f of matching) {
+        expect(f.payload).toHaveProperty('tool_name');
+        expect(f.payload).toHaveProperty('tool_input');
+        const toolInput = f.payload.tool_input as Record<string, unknown>;
+        expect(toolInput).toHaveProperty('file_path');
+        expect(toolInput).toHaveProperty('command');
+      }
+    });
+
+    it('PreToolUse non-matching fixtures should contain tool_name and tool_input', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Write');
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      for (const f of nonMatching) {
+        expect(f.payload).toHaveProperty('tool_name');
+        expect(f.payload).toHaveProperty('tool_input');
+      }
+    });
+
+    it('should use provided toolMatcher tools in matching fixtures', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Edit|Write');
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      const toolNames = matching.map((f) => f.payload.tool_name);
+      for (const name of toolNames) {
+        expect(['Edit', 'Write']).toContain(name);
+      }
+    });
+
+    it('should default to Write when no toolMatcher provided for PreToolUse', () => {
+      const fixtures = generateFixtures('PreToolUse');
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      for (const f of matching) {
+        expect(f.payload.tool_name).toBe('Write');
+      }
+    });
+
+    it('PreCompact matching fixtures should have session_id', () => {
+      const fixtures = generateFixtures('PreCompact');
+      const matching = fixtures.filter((f) => f.shouldMatch);
+      for (const f of matching) {
+        expect(f.payload).toHaveProperty('session_id');
+        expect(f.payload).toHaveProperty('context');
+      }
+    });
+
+    it('PreCompact non-matching fixtures should have empty payloads', () => {
+      const fixtures = generateFixtures('PreCompact');
+      const nonMatching = fixtures.filter((f) => !f.shouldMatch);
+      for (const f of nonMatching) {
+        expect(Object.keys(f.payload)).toHaveLength(0);
+      }
+    });
+
+    it('all fixtures should have event matching the requested event', () => {
+      for (const event of [
+        'PreToolUse',
+        'PostToolUse',
+        'PreCompact',
+        'Notification',
+        'Stop',
+      ] as const) {
+        const fixtures = generateFixtures(event);
+        for (const f of fixtures) {
+          expect(f.event).toBe(event);
+        }
+      }
+    });
+
+    it('all fixtures should have unique names', () => {
+      const fixtures = generateFixtures('PreToolUse', 'Write|Edit');
+      const names = fixtures.map((f) => f.name);
+      expect(new Set(names).size).toBe(names.length);
+    });
+  });
+
+  describe('validateHookScript', () => {
+    it('should report correctly with a script that produces no output (exit 0)', () => {
+      // execSync mock returns '' (empty string) — no match detected
+      mockedExecSync.mockReturnValue('');
+
+      const fixtures: TestFixture[] = [
+        {
+          name: 'should-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Write', tool_input: { file_path: 'test.ts' } },
+          shouldMatch: true,
+        },
+        {
+          name: 'should-not-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Read', tool_input: { file_path: 'test.ts' } },
+          shouldMatch: false,
+        },
+      ];
+
+      const report = validateHookScript('/fake/script.sh', fixtures);
+
+      expect(report.total).toBe(2);
+      // Script produces no output, so matched = false for all
+      // should-match expected match but got none -> false negative
+      // should-not-match expected no match and got none -> correct
+      expect(report.falseNegatives).toHaveLength(1);
+      expect(report.falseNegatives[0].fixture.name).toBe('should-match');
+      expect(report.falsePositives).toHaveLength(0);
+      expect(report.passed).toBe(1);
+    });
+
+    it('should detect false positives when script always matches', () => {
+      mockedExecSync.mockReturnValue('{"continue": true, "message": "always matches"}');
+
+      const fixtures: TestFixture[] = [
+        {
+          name: 'should-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Write', tool_input: {} },
+          shouldMatch: true,
+        },
+        {
+          name: 'should-not-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Read', tool_input: {} },
+          shouldMatch: false,
+        },
+      ];
+
+      const report = validateHookScript('/fake/script.sh', fixtures);
+
+      expect(report.total).toBe(2);
+      // Script always outputs "continue", so matched = true for all
+      // should-not-match expected no match but got one -> false positive
+      expect(report.falsePositives).toHaveLength(1);
+      expect(report.falsePositives[0].fixture.name).toBe('should-not-match');
+      expect(report.falseNegatives).toHaveLength(0);
+      expect(report.passed).toBe(1);
+    });
+
+    it('should report all passed when script matches correctly', () => {
+      mockedExecSync.mockImplementation((cmd: unknown) => {
+        if (typeof cmd === 'string' && cmd.includes('Write')) {
+          return '{"continue": true, "message": "matched"}';
+        }
+        return '';
+      });
+
+      const fixtures: TestFixture[] = [
+        {
+          name: 'should-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Write', tool_input: {} },
+          shouldMatch: true,
+        },
+        {
+          name: 'should-not-match',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Read', tool_input: {} },
+          shouldMatch: false,
+        },
+      ];
+
+      const report = validateHookScript('/fake/script.sh', fixtures);
+
+      expect(report.total).toBe(2);
+      expect(report.passed).toBe(2);
+      expect(report.falsePositives).toHaveLength(0);
+      expect(report.falseNegatives).toHaveLength(0);
+    });
+
+    it('should handle script errors gracefully (exit code != 0)', () => {
+      mockedExecSync.mockImplementation(() => {
+        const err = new Error('script failed') as Error & { status: number; stdout: string };
+        err.status = 1;
+        err.stdout = '';
+        throw err;
+      });
+
+      const fixtures: TestFixture[] = [
+        {
+          name: 'error-fixture',
+          event: 'PreToolUse',
+          payload: { tool_name: 'Write', tool_input: {} },
+          shouldMatch: true,
+        },
+      ];
+
+      const report = validateHookScript('/fake/script.sh', fixtures);
+
+      expect(report.total).toBe(1);
+      // Error means matched = false, but shouldMatch = true -> false negative
+      expect(report.falseNegatives).toHaveLength(1);
+      expect(report.passed).toBe(0);
+    });
+  });
+});

package/src/commands/create.ts

@@ -1,6 +1,5 @@
 import { readFileSync, existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { homedir } from 'node:os';
+import { resolve } from 'node:path';
 import type { Command } from 'commander';
 import * as p from '@clack/prompts';
 import {
@@ -15,9 +14,6 @@ import { runCreateWizard } from '../prompts/create-wizard.js';
 import { listPacks } from '../hook-packs/registry.js';
 import { installPack } from '../hook-packs/installer.js';
 
-/** Default parent directory for new agents: ~/.soleri/ */
-const SOLERI_HOME = process.env.SOLERI_HOME ?? join(homedir(), '.soleri');
-
 function parseSetupTarget(value?: string): SetupTarget | undefined {
   if (!value) return undefined;
   if ((SETUP_TARGETS as readonly string[]).includes(value)) {
@@ -41,7 +37,7 @@ export function registerCreate(program: Command): void {
       `Setup target: ${SETUP_TARGETS.join(', ')} (default: claude)`,
     )
     .option('-y, --yes', 'Skip confirmation prompts (use with --config for fully non-interactive)')
-    .option('--dir <path>', `Parent directory for the agent (default: ~/.soleri/)`)
+    .option('--dir <path>', `Parent directory for the agent (default: current directory)`)
     .option('--filetree', 'Create a file-tree agent (v7 — no TypeScript, no build step)')
     .option('--legacy', 'Create a legacy TypeScript agent (v6 — requires npm install + build)')
     .description('Create a new Soleri agent')
@@ -154,7 +150,7 @@ export function registerCreate(program: Command): void {
               })),
             };
 
-            const outputDir = opts?.dir ? resolve(opts.dir) : (config.outputDir ?? SOLERI_HOME);
+            const outputDir = opts?.dir ? resolve(opts.dir) : (config.outputDir ?? process.cwd());
             const nonInteractive = !!(opts?.yes || opts?.config);
 
             if (!nonInteractive) {

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                 |