@soleri/cli 9.14.2 → 9.15.0

package/src/commands/brain.ts

@@ -0,0 +1,93 @@
+/**
+ * Brain CLI — brain session management.
+ *
+ * `soleri brain close-orphans`              — close orphaned sessions (default: --max-age 1h)
+ * `soleri brain close-orphans --max-age 2h` — close sessions older than 2h
+ */
+
+import type { Command } from 'commander';
+import { detectAgent } from '../utils/agent-context.js';
+import { pass, fail, info, heading } from '../utils/logger.js';
+import { resolveVaultDbPath } from '../utils/vault-db.js';
+
+function parseMaxAge(value: string): number {
+  const match = value.match(/^(\d+)(h|m|s)$/);
+  if (!match) throw new Error(`Invalid --max-age format "${value}". Use e.g. 1h, 30m, 90s`);
+  const n = parseInt(match[1], 10);
+  const unit = match[2];
+  if (unit === 'h') return n * 60 * 60 * 1000;
+  if (unit === 'm') return n * 60 * 1000;
+  return n * 1000;
+}
+
+export function registerBrain(program: Command): void {
+  const brain = program.command('brain').description('Brain session management');
+
+  brain
+    .command('close-orphans')
+    .description('Close orphaned brain sessions that were never completed')
+    .option('--max-age <duration>', 'Close sessions older than this age (e.g. 1h, 30m)', '1h')
+    .action(async (opts: { maxAge: string }) => {
+      const agent = detectAgent();
+      if (!agent) {
+        fail('Not in a Soleri agent project', 'Run from an agent directory');
+        process.exit(1);
+      }
+
+      const dbPath = resolveVaultDbPath(agent.agentId);
+      if (!dbPath) {
+        info('Vault DB not found — no sessions to close.');
+        process.exit(0);
+      }
+
+      let maxAgeMs: number;
+      try {
+        maxAgeMs = parseMaxAge(opts.maxAge);
+      } catch (e: unknown) {
+        fail(
+          e instanceof Error ? e.message : String(e),
+          'Example: soleri brain close-orphans --max-age 1h',
+        );
+        process.exit(1);
+      }
+
+      const { Vault, Brain, BrainIntelligence } = await import('@soleri/core');
+      const vault = new Vault(dbPath);
+
+      try {
+        const brainInstance = new Brain(vault);
+        const intelligence = new BrainIntelligence(vault, brainInstance);
+
+        const cutoff = new Date(Date.now() - maxAgeMs).toISOString().replace('T', ' ').slice(0, 19);
+        const activeSessions = intelligence.listSessions({ active: true, limit: 1000 });
+        const orphans = activeSessions.filter((s) => s.startedAt < cutoff);
+
+        if (orphans.length === 0) {
+          info(`No orphaned sessions older than ${opts.maxAge}.`);
+          process.exit(0);
+        }
+
+        heading('Brain — Close Orphans');
+
+        let closed = 0;
+        for (const s of orphans) {
+          try {
+            intelligence.lifecycle({
+              action: 'end',
+              sessionId: s.id,
+              planOutcome: 'abandoned',
+              context: `auto-closed via CLI: no completion after ${opts.maxAge}`,
+            });
+            closed++;
+          } catch {
+            // best-effort — never block on failures
+          }
+        }
+
+        pass(`Closed ${closed} orphaned session${closed === 1 ? '' : 's'}`);
+        process.exit(0);
+      } finally {
+        vault.close();
+      }
+    });
+}

package/src/commands/dream.ts

@@ -7,20 +7,10 @@
  * `soleri dream status`                 — show dream status + cron info
  */
 
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import type { Command } from 'commander';
 import { detectAgent } from '../utils/agent-context.js';
 import { pass, fail, info, heading, dim } from '../utils/logger.js';
-import { SOLERI_HOME } from '@soleri/core';
-
-function resolveVaultDbPath(agentId: string): string | null {
-  const newDbPath = join(SOLERI_HOME, agentId, 'vault.db');
-  const legacyDbPath = join(SOLERI_HOME, '..', `.${agentId}`, 'vault.db');
-  if (existsSync(newDbPath)) return newDbPath;
-  if (existsSync(legacyDbPath)) return legacyDbPath;
-  return null;
-}
+import { resolveVaultDbPath } from '../utils/vault-db.js';
 
 export function registerDream(program: Command): void {
   const dream = program.command('dream').description('Vault memory consolidation');

package/src/commands/install.ts

@@ -1,5 +1,4 @@
 import type { Command } from 'commander';
-import { createRequire } from 'node:module';
 import {
   accessSync,
   constants as fsConstants,
@@ -13,6 +12,7 @@ import { homedir } from 'node:os';
 import * as p from '@clack/prompts';
 import { detectAgent } from '../utils/agent-context.js';
 import { detectArtifacts } from '../utils/agent-artifacts.js';
+import { resolveInstalledEngineBin } from '../utils/core-resolver.js';
 
 /** Default parent directory for agents: ~/.soleri/ */
 const SOLERI_HOME = process.env.SOLERI_HOME ?? join(homedir(), '.soleri');
@@ -27,13 +27,8 @@ export const toPosix = (p: string): string => p.replace(/\\/g, '/');
  * Falls back to `npx @soleri/engine` if resolution fails (e.g. not installed globally).
  */
 export 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' };
-  }
+  const bin = resolveInstalledEngineBin();
+  return bin ? { command: 'node', bin } : { command: 'npx', bin: '@soleri/engine' };
 }
 
 /** MCP server entry for file-tree agents (resolved engine path, no npx) */

package/src/commands/validate-skills.ts

@@ -0,0 +1,58 @@
+/**
+ * `soleri validate-skills` — validate user-installed SKILL.md op-call examples
+ * against the engine's actual Zod schemas.
+ *
+ * Scans ~/.claude/skills/ for SKILL.md files, extracts inline op-call examples,
+ * and checks each example's params against the corresponding facade schema.
+ * Exits with code 1 if any mismatches are found.
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { validateSkillDocs } from '@soleri/core/skills/validate-skills';
+import * as log from '../utils/logger.js';
+
+const DEFAULT_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+
+export function registerValidateSkills(program: Command): void {
+  program
+    .command('validate-skills')
+    .description('Validate SKILL.md op-call examples against engine Zod schemas')
+    .option('--skills-dir <path>', 'Path to skills directory', DEFAULT_SKILLS_DIR)
+    .action((opts: { skillsDir: string }) => {
+      const skillsDir = opts.skillsDir;
+
+      log.heading('Soleri Validate Skills');
+      log.dim(`Scanning: ${skillsDir}`);
+      console.log();
+
+      const result = validateSkillDocs(skillsDir);
+
+      log.dim(`Schema registry: ${result.registrySize} ops`);
+      log.dim(`Skill files:     ${result.totalFiles}`);
+      log.dim(`Op examples:     ${result.totalExamples}`);
+      console.log();
+
+      if (result.totalFiles === 0) {
+        log.warn('No SKILL.md files found', skillsDir);
+        return;
+      }
+
+      if (result.valid) {
+        log.pass('All examples validate against their schemas.');
+        return;
+      }
+
+      log.fail(`Found ${result.errors.length} validation error(s):`);
+      console.log();
+
+      for (const err of result.errors) {
+        const location = err.line ? `:${err.line}` : '';
+        console.log(`  ERROR ${err.file}${location} — op:${err.op}: ${err.message}`);
+      }
+
+      console.log();
+      process.exit(1);
+    });
+}

package/src/commands/vault.ts

@@ -7,12 +7,10 @@
  */
 
 import { resolve } from 'node:path';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import type { Command } from 'commander';
 import { detectAgent } from '../utils/agent-context.js';
 import * as log from '../utils/logger.js';
-import { SOLERI_HOME } from '@soleri/core';
+import { resolveVaultDbPath } from '../utils/vault-db.js';
 
 export function registerVault(program: Command): void {
   const vault = program.command('vault').description('Vault knowledge management');
@@ -31,14 +29,7 @@ export function registerVault(program: Command): void {
 
       const outputDir = opts.path ? resolve(opts.path) : resolve('knowledge');
 
-      // Find vault DB — check new path first, then legacy
-      const newDbPath = join(SOLERI_HOME, agent.agentId, 'vault.db');
-      const legacyDbPath = join(SOLERI_HOME, '..', `.${agent.agentId}`, 'vault.db');
-      const vaultDbPath = existsSync(newDbPath)
-        ? newDbPath
-        : existsSync(legacyDbPath)
-          ? legacyDbPath
-          : null;
+      const vaultDbPath = resolveVaultDbPath(agent.agentId);
 
       if (!vaultDbPath) {
         log.fail('Vault DB not found', 'Run the agent once to initialize its vault database.');

package/src/main.ts

@@ -33,6 +33,8 @@ import { registerVault } from './commands/vault.js';
 import { registerYolo } from './commands/yolo.js';
 import { registerDream } from './commands/dream.js';
 import { registerUpdate } from './commands/update.js';
+import { registerBrain } from './commands/brain.js';
+import { registerValidateSkills } from './commands/validate-skills.js';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -98,4 +100,6 @@ registerVault(program);
 registerYolo(program);
 registerDream(program);
 registerUpdate(program);
+registerBrain(program);
+registerValidateSkills(program);
 program.parse();

package/src/prompts/create-wizard.ts

@@ -42,12 +42,16 @@ export async function runCreateWizard(initialName?: string): Promise<CreateWizar
   p.intro('Create a new Soleri agent');
 
   // ─── Step 1: Name ───────────────────────────────────────────
+  const NAME_PLACEHOLDER = 'aria';
+
   const name = (await p.text({
     message: 'What should your agent be called?',
-    placeholder: 'Ernesto',
+    placeholder: NAME_PLACEHOLDER,
     initialValue: initialName,
     validate: (v) => {
       if (!v || v.trim().length === 0) return 'Name is required';
+      if (v.trim().toLowerCase() === NAME_PLACEHOLDER)
+        return `"${NAME_PLACEHOLDER}" is just an example — type your own agent name`;
       if (v.length > 50) return 'Max 50 characters';
     },
   })) as string;

package/src/utils/checks.ts

@@ -4,8 +4,9 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { homedir } from 'node:os';
 import { detectAgent, type AgentFormat } from './agent-context.js';
+import { detectArtifacts } from './agent-artifacts.js';
+import { resolveCorePackageJsonPath } from './core-resolver.js';
 import { getInstalledPacks } from '../hook-packs/registry.js';
 
 export interface CheckResult {
@@ -166,49 +167,36 @@ export function checkInstructionsDir(agentPath: string): CheckResult {
 }
 
 export function checkEngineReachable(): CheckResult {
-  try {
-    require.resolve('@soleri/core/package.json');
+  if (resolveCorePackageJsonPath() !== null) {
     return { status: 'pass', label: 'Engine', detail: '@soleri/core reachable' };
-  } catch {
-    return {
-      status: 'fail',
-      label: 'Engine',
-      detail: '@soleri/core not found — engine is required for file-tree agents',
-    };
   }
+
+  return {
+    status: 'fail',
+    label: 'Engine',
+    detail: '@soleri/core not found — engine is required for file-tree agents',
+  };
 }
 
 function checkMcpRegistration(dir?: string): CheckResult {
   const ctx = detectAgent(dir);
   if (!ctx) return { status: 'warn', label: 'MCP registration', detail: 'no agent detected' };
 
-  const claudeJsonPath = join(homedir(), '.claude.json');
-  if (!existsSync(claudeJsonPath)) {
+  const artifacts = detectArtifacts(ctx.agentId, ctx.agentPath);
+  if (artifacts.mcpServerEntries.length === 0) {
     return {
       status: 'warn',
       label: 'MCP registration',
-      detail: '~/.claude.json not found',
+      detail: `not found in ~/.claude.json, ~/.codex/config.toml, or ~/.config/opencode/opencode.json`,
     };
   }
 
-  try {
-    const config = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
-    const servers = config.mcpServers ?? {};
-    if (ctx.agentId in servers) {
-      return {
-        status: 'pass',
-        label: 'MCP registration',
-        detail: `registered as "${ctx.agentId}"`,
-      };
-    }
-    return {
-      status: 'warn',
-      label: 'MCP registration',
-      detail: `"${ctx.agentId}" not found in ~/.claude.json`,
-    };
-  } catch {
-    return { status: 'fail', label: 'MCP registration', detail: 'failed to parse ~/.claude.json' };
-  }
+  const targets = [...new Set(artifacts.mcpServerEntries.map((entry) => entry.target))];
+  return {
+    status: 'pass',
+    label: 'MCP registration',
+    detail: `registered in ${targets.join(', ')}`,
+  };
 }
 
 function checkCognee(): CheckResult {

package/src/utils/core-resolver.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function resolveCoreEntryPath(): string | null {
+  try {
+    return fileURLToPath(import.meta.resolve('@soleri/core'));
+  } catch {
+    return null;
+  }
+}
+
+export function resolveCorePackageJsonPath(): string | null {
+  const entryPath = resolveCoreEntryPath();
+  if (!entryPath) return null;
+
+  const packageJsonPath = join(dirname(entryPath), '..', 'package.json');
+  return existsSync(packageJsonPath) ? packageJsonPath : null;
+}
+
+export function readInstalledCoreVersion(): string | null {
+  const packageJsonPath = resolveCorePackageJsonPath();
+  if (!packageJsonPath) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveInstalledEngineBin(): string | null {
+  const entryPath = resolveCoreEntryPath();
+  if (!entryPath) return null;
+
+  const engineBinPath = join(dirname(entryPath), 'engine', 'bin', 'soleri-engine.js');
+  return existsSync(engineBinPath) ? engineBinPath : null;
+}

package/src/utils/vault-db.ts

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { SOLERI_HOME } from '@soleri/core';
+
+/**
+ * Resolve the vault DB path for a given agent.
+ * Checks the current path first, then falls back to the legacy dot-prefixed path.
+ */
+export function resolveVaultDbPath(agentId: string): string | null {
+  const newDbPath = join(SOLERI_HOME, agentId, 'vault.db');
+  const legacyDbPath = join(SOLERI_HOME, '..', `.${agentId}`, 'vault.db');
+  if (existsSync(newDbPath)) return newDbPath;
+  if (existsSync(legacyDbPath)) return legacyDbPath;
+  return null;
+}

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

@@ -1,133 +0,0 @@
-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);
-    }
-  });
-});