@soleri/cli 1.8.0 → 1.10.0

package/src/commands/agent.ts

@@ -0,0 +1,181 @@
+/**
+ * Agent lifecycle CLI — status, update, diff.
+ *
+ * `soleri agent status` — health report with version, packs, vault stats.
+ * `soleri agent update` — OTA engine upgrade with migration support.
+ */
+
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import type { Command } from 'commander';
+import * as p from '@clack/prompts';
+import { PackLockfile, checkNpmVersion, checkVersionCompat } from '@soleri/core';
+import { detectAgent } from '../utils/agent-context.js';
+
+export function registerAgent(program: Command): void {
+  const agent = program.command('agent').description('Agent lifecycle management');
+
+  // ─── status ─────────────────────────────────────────────────
+  agent
+    .command('status')
+    .option('--json', 'Output as JSON')
+    .description('Show agent health: version, packs, vault, and update availability')
+    .action((opts: { json?: boolean }) => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected in current directory.');
+        process.exit(1);
+        return;
+      }
+
+      // Read agent package.json
+      const pkgPath = join(ctx.agentPath, 'package.json');
+      const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf-8')) : {};
+      const agentName = pkg.name || 'unknown';
+      const agentVersion = pkg.version || '0.0.0';
+
+      // Read @soleri/core version
+      const corePkgPath = join(ctx.agentPath, 'node_modules', '@soleri', 'core', 'package.json');
+      const coreVersion = existsSync(corePkgPath)
+        ? JSON.parse(readFileSync(corePkgPath, 'utf-8')).version || 'unknown'
+        : pkg.dependencies?.['@soleri/core'] || 'not installed';
+
+      // Check for core update
+      const latestCore = checkNpmVersion('@soleri/core');
+
+      // Read lockfile
+      const lockfilePath = join(ctx.agentPath, 'soleri.lock');
+      const lockfile = new PackLockfile(lockfilePath);
+      const packs = lockfile.list();
+
+      // Count vault entries if db exists
+      const dbPath = join(ctx.agentPath, 'data', 'vault.db');
+      const hasVault = existsSync(dbPath);
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify(
+            {
+              agent: agentName,
+              version: agentVersion,
+              engine: coreVersion,
+              engineLatest: latestCore,
+              packs: packs.map((p) => ({
+                id: p.id,
+                version: p.version,
+                type: p.type,
+                source: p.source,
+              })),
+              vault: { exists: hasVault },
+            },
+            null,
+            2,
+          ),
+        );
+        return;
+      }
+
+      console.log(`\n  Agent: ${agentName} v${agentVersion}`);
+      console.log(
+        `  Engine: @soleri/core ${coreVersion}${latestCore && latestCore !== coreVersion ? ` (update available: ${latestCore})` : ''}`,
+      );
+
+      if (packs.length > 0) {
+        console.log(`\n  Packs (${packs.length} installed):`);
+        for (const pack of packs) {
+          const badge =
+            pack.source === 'npm' ? ' [npm]' : pack.source === 'built-in' ? ' [built-in]' : '';
+          console.log(`    ${pack.id}@${pack.version}  ${pack.type}${badge}`);
+        }
+      } else {
+        console.log('\n  Packs: none installed');
+      }
+
+      console.log(`\n  Vault: ${hasVault ? 'initialized' : 'not initialized'}`);
+      console.log('');
+    });
+
+  // ─── update ─────────────────────────────────────────────────
+  agent
+    .command('update')
+    .option('--check', 'Show what would change without updating')
+    .option('--dry-run', 'Preview migration steps')
+    .description('Update agent engine to latest compatible version')
+    .action((opts: { check?: boolean; dryRun?: boolean }) => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected in current directory.');
+        process.exit(1);
+        return;
+      }
+
+      const pkgPath = join(ctx.agentPath, 'package.json');
+      if (!existsSync(pkgPath)) {
+        p.log.error('No package.json found in agent directory.');
+        process.exit(1);
+        return;
+      }
+
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const currentRange = pkg.dependencies?.['@soleri/core'] || '';
+      const latestCore = checkNpmVersion('@soleri/core');
+
+      if (!latestCore) {
+        p.log.error('Could not check npm for latest @soleri/core version.');
+        process.exit(1);
+        return;
+      }
+
+      // Check compatibility
+      const compatible = checkVersionCompat(latestCore, currentRange);
+
+      if (opts.check) {
+        console.log(`\n  Current: @soleri/core ${currentRange}`);
+        console.log(`  Latest:  @soleri/core ${latestCore}`);
+        console.log(`  Compatible: ${compatible ? 'yes' : 'no (range: ' + currentRange + ')'}`);
+        console.log('');
+        return;
+      }
+
+      if (opts.dryRun) {
+        p.log.info(`Would update @soleri/core to ${latestCore}`);
+        p.log.info('Would run: npm install @soleri/core@' + latestCore);
+        return;
+      }
+
+      const s = p.spinner();
+      s.start(`Updating @soleri/core to ${latestCore}...`);
+
+      try {
+        execFileSync('npm', ['install', `@soleri/core@${latestCore}`], {
+          cwd: ctx.agentPath,
+          stdio: 'pipe',
+          timeout: 120_000,
+        });
+
+        s.stop(`Updated to @soleri/core@${latestCore}`);
+        p.log.info('Run `soleri test` to verify the update.');
+      } catch (err) {
+        s.stop('Update failed');
+        p.log.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── diff ───────────────────────────────────────────────────
+  agent
+    .command('diff')
+    .description('Show drift between agent templates and latest engine templates')
+    .action(() => {
+      const ctx = detectAgent();
+      if (!ctx) {
+        p.log.error('No agent project detected in current directory.');
+        process.exit(1);
+        return;
+      }
+
+      p.log.info('Template diff is available after `soleri agent update --check`.');
+      p.log.info('Full template comparison will be added in a future release.');
+    });
+}

package/src/commands/create.ts

@@ -2,137 +2,179 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { Command } from 'commander';
 import * as p from '@clack/prompts';
-import { previewScaffold, scaffold, AgentConfigSchema } from '@soleri/forge/lib';
+import {
+  previewScaffold,
+  scaffold,
+  AgentConfigSchema,
+  SETUP_TARGETS,
+  type SetupTarget,
+} from '@soleri/forge/lib';
 import { runCreateWizard } from '../prompts/create-wizard.js';
 import { listPacks } from '../hook-packs/registry.js';
 import { installPack } from '../hook-packs/installer.js';
 
+function parseSetupTarget(value?: string): SetupTarget | undefined {
+  if (!value) return undefined;
+  if ((SETUP_TARGETS as readonly string[]).includes(value)) {
+    return value as SetupTarget;
+  }
+  return undefined;
+}
+
+function includesClaudeSetup(target: SetupTarget | undefined): boolean {
+  const resolved = target ?? 'claude';
+  return resolved === 'claude' || resolved === 'both';
+}
+
 export function registerCreate(program: Command): void {
   program
     .command('create')
     .argument('[name]', 'Agent ID (kebab-case)')
     .option('-c, --config <path>', 'Path to JSON config file (skip interactive prompts)')
+    .option(
+      '--setup-target <target>',
+      `Setup target: ${SETUP_TARGETS.join(', ')} (default: claude)`,
+    )
     .option('-y, --yes', 'Skip confirmation prompts (use with --config for fully non-interactive)')
     .description('Create a new Soleri agent')
-    .action(async (name?: string, opts?: { config?: string; yes?: boolean }) => {
-      try {
-        let config;
-
-        if (opts?.config) {
-          // Non-interactive: read from config file
-          const configPath = resolve(opts.config);
-          if (!existsSync(configPath)) {
-            p.log.error(`Config file not found: ${configPath}`);
-            process.exit(1);
+    .action(
+      async (name?: string, opts?: { config?: string; yes?: boolean; setupTarget?: string }) => {
+        try {
+          let config;
+
+          if (opts?.config) {
+            // Non-interactive: read from config file
+            const configPath = resolve(opts.config);
+            if (!existsSync(configPath)) {
+              p.log.error(`Config file not found: ${configPath}`);
+              process.exit(1);
+            }
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const parsed = AgentConfigSchema.safeParse(raw);
+            if (!parsed.success) {
+              p.log.error(`Invalid config: ${parsed.error.message}`);
+              process.exit(1);
+            }
+            config = parsed.data;
+          } else {
+            // Interactive wizard
+            config = await runCreateWizard(name);
+            if (!config) {
+              p.outro('Cancelled.');
+              return;
+            }
           }
-          const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
-          const parsed = AgentConfigSchema.safeParse(raw);
-          if (!parsed.success) {
-            p.log.error(`Invalid config: ${parsed.error.message}`);
+
+          const setupTarget = parseSetupTarget(opts?.setupTarget);
+          if (opts?.setupTarget && !setupTarget) {
+            p.log.error(
+              `Invalid --setup-target "${opts.setupTarget}". Expected one of: ${SETUP_TARGETS.join(', ')}`,
+            );
             process.exit(1);
           }
-          config = parsed.data;
-        } else {
-          // Interactive wizard
-          config = await runCreateWizard(name);
-          if (!config) {
-            p.outro('Cancelled.');
-            return;
+          if (setupTarget) {
+            config = { ...config, setupTarget };
           }
-        }
+          const claudeSetup = includesClaudeSetup(config.setupTarget);
+
+          const nonInteractive = !!(opts?.yes || opts?.config);
 
-        const nonInteractive = !!(opts?.yes || opts?.config);
-
-        // Hook packs — from config file or interactive prompt
-        let selectedPacks: string[] = [];
-        if (config.hookPacks && config.hookPacks.length > 0) {
-          selectedPacks = config.hookPacks;
-
-          // Validate pack names against registry — warn and skip unknown
-          const available = listPacks().map((pk) => pk.name);
-          const unknown = selectedPacks.filter((pk) => !available.includes(pk));
-          if (unknown.length > 0) {
-            for (const name of unknown) {
-              p.log.warn(
-                `Unknown hook pack "${name}" — skipping. Available: ${available.join(', ')}`,
-              );
+          // Hook packs — from config file or interactive prompt
+          let selectedPacks: string[] = [];
+          if (!claudeSetup && config.hookPacks && config.hookPacks.length > 0) {
+            p.log.warn(
+              'Hook packs are Claude-only. Skipping because setup target excludes Claude.',
+            );
+          } else if (config.hookPacks && config.hookPacks.length > 0) {
+            selectedPacks = config.hookPacks;
+
+            // Validate pack names against registry — warn and skip unknown
+            const available = listPacks().map((pk) => pk.name);
+            const unknown = selectedPacks.filter((pk) => !available.includes(pk));
+            if (unknown.length > 0) {
+              for (const name of unknown) {
+                p.log.warn(
+                  `Unknown hook pack "${name}" — skipping. Available: ${available.join(', ')}`,
+                );
+              }
+              selectedPacks = selectedPacks.filter((pk) => available.includes(pk));
+            }
+          } else if (!nonInteractive && claudeSetup) {
+            const packs = listPacks();
+            const packChoices = packs.map((pk) => ({
+              value: pk.name,
+              label: pk.name,
+              hint: `${pk.description} (${pk.hooks.length} hooks)`,
+            }));
+
+            const chosen = await p.multiselect({
+              message: 'Install hook packs? (Claude quality gates for ~/.claude/)',
+              options: packChoices,
+              required: false,
+            });
+
+            if (!p.isCancel(chosen)) {
+              selectedPacks = chosen as string[];
             }
-            selectedPacks = selectedPacks.filter((pk) => available.includes(pk));
-          }
-        } else if (!nonInteractive) {
-          const packs = listPacks();
-          const packChoices = packs.map((pk) => ({
-            value: pk.name,
-            label: pk.name,
-            hint: `${pk.description} (${pk.hooks.length} hooks)`,
-          }));
-
-          const chosen = await p.multiselect({
-            message: 'Install hook packs? (quality gates for ~/.claude/)',
-            options: packChoices,
-            required: false,
-          });
-
-          if (!p.isCancel(chosen)) {
-            selectedPacks = chosen as string[];
           }
-        }
 
-        // Preview
-        const preview = previewScaffold(config);
+          // Preview
+          const preview = previewScaffold(config);
 
-        p.log.info(`Will create ${preview.files.length} files in ${preview.agentDir}`);
-        p.log.info(`Facades: ${preview.facades.map((f) => f.name).join(', ')}`);
-        p.log.info(`Domains: ${preview.domains.join(', ')}`);
-        if (config.tone) {
-          p.log.info(`Tone: ${config.tone}`);
-        }
-        if (config.skills?.length) {
-          p.log.info(`Skills: ${config.skills.length} selected`);
-        }
-        if (selectedPacks.length > 0) {
-          p.log.info(`Hook packs: ${selectedPacks.join(', ')}`);
-        }
+          p.log.info(`Will create ${preview.files.length} files in ${preview.agentDir}`);
+          p.log.info(`Facades: ${preview.facades.map((f) => f.name).join(', ')}`);
+          p.log.info(`Domains: ${preview.domains.join(', ')}`);
+          p.log.info(`Setup target: ${config.setupTarget ?? 'claude'}`);
+          if (config.tone) {
+            p.log.info(`Tone: ${config.tone}`);
+          }
+          if (config.skills?.length) {
+            p.log.info(`Skills: ${config.skills.length} selected`);
+          }
+          if (selectedPacks.length > 0) {
+            p.log.info(`Hook packs: ${selectedPacks.join(', ')}`);
+          }
 
-        if (!nonInteractive) {
-          const confirmed = await p.confirm({ message: 'Create agent?' });
-          if (p.isCancel(confirmed) || !confirmed) {
-            p.outro('Cancelled.');
-            return;
+          if (!nonInteractive) {
+            const confirmed = await p.confirm({ message: 'Create agent?' });
+            if (p.isCancel(confirmed) || !confirmed) {
+              p.outro('Cancelled.');
+              return;
+            }
           }
-        }
 
-        // Scaffold + auto-build
-        const s = p.spinner();
-        s.start('Scaffolding and building agent...');
-        const result = scaffold(config);
-        s.stop(result.success ? 'Agent created and built!' : 'Scaffolding failed');
+          // Scaffold + auto-build
+          const s = p.spinner();
+          s.start('Scaffolding and building agent...');
+          const result = scaffold(config);
+          s.stop(result.success ? 'Agent created and built!' : 'Scaffolding failed');
 
-        if (!result.success) {
-          p.log.error(result.summary);
-          process.exit(1);
-        }
+          if (!result.success) {
+            p.log.error(result.summary);
+            process.exit(1);
+          }
 
-        // Install selected hook packs
-        if (selectedPacks.length > 0) {
-          for (const packName of selectedPacks) {
-            const { installed } = installPack(packName, { projectDir: result.agentDir });
-            if (installed.length > 0) {
-              p.log.success(`Hook pack "${packName}" installed (${installed.length} hooks)`);
-            } else {
-              p.log.info(`Hook pack "${packName}" — all hooks already present`);
+          // Install selected hook packs
+          if (selectedPacks.length > 0) {
+            for (const packName of selectedPacks) {
+              const { installed } = installPack(packName, { projectDir: result.agentDir });
+              if (installed.length > 0) {
+                p.log.success(`Hook pack "${packName}" installed (${installed.length} hooks)`);
+              } else {
+                p.log.info(`Hook pack "${packName}" — all hooks already present`);
+              }
             }
           }
-        }
 
-        if (result.success) {
-          p.note(result.summary, 'Next steps');
-        }
+          if (result.success) {
+            p.note(result.summary, 'Next steps');
+          }
 
-        p.outro('Done!');
-      } catch (err) {
-        p.log.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
+          p.outro('Done!');
+        } catch (err) {
+          p.log.error(err instanceof Error ? err.message : String(err));
+          process.exit(1);
+        }
+      },
+    );
 }

package/src/commands/install-knowledge.ts

@@ -1,13 +1,74 @@
 import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import type { Command } from 'commander';
 import * as p from '@clack/prompts';
 import { installKnowledge } from '@soleri/forge/lib';
 import { detectAgent } from '../utils/agent-context.js';
 
+/**
+ * Resolve a pack identifier to a local path.
+ * If `pack` is a local path, return it directly.
+ * If it looks like a package name, download from npm.
+ */
+async function resolvePackPath(pack: string): Promise<string> {
+  // Local path — use directly
+  if (pack.startsWith('.') || pack.startsWith('/') || existsSync(pack)) {
+    return resolve(pack);
+  }
+
+  // npm package name — resolve to @soleri/knowledge-{name} or use as-is if scoped
+  const npmName = pack.startsWith('@') ? pack : `@soleri/knowledge-${pack.replace(/@.*$/, '')}`;
+  const version = pack.includes('@') && !pack.startsWith('@') ? pack.split('@').pop() : undefined;
+  const spec = version ? `${npmName}@${version}` : npmName;
+
+  const tmpDir = join(tmpdir(), `soleri-pack-${Date.now()}`);
+
+  p.log.info(`Resolving ${spec} from npm...`);
+
+  try {
+    execFileSync('npm', ['pack', spec, '--pack-destination', tmpDir], {
+      stdio: 'pipe',
+      timeout: 30_000,
+    });
+
+    // Find the tarball
+    const { readdirSync } = await import('node:fs');
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(tmpDir, { recursive: true });
+
+    // npm pack creates a .tgz file — extract it
+    const files = readdirSync(tmpDir).filter((f: string) => f.endsWith('.tgz'));
+    if (files.length === 0) {
+      throw new Error(`No tarball found after npm pack ${spec}`);
+    }
+
+    const extractDir = join(tmpDir, 'extracted');
+    mkdirSync(extractDir, { recursive: true });
+    execFileSync('tar', ['xzf', join(tmpDir, files[0]), '-C', extractDir], {
+      stdio: 'pipe',
+      timeout: 15_000,
+    });
+
+    // npm pack extracts to a 'package/' subdirectory
+    const packageDir = join(extractDir, 'package');
+    if (!existsSync(packageDir)) {
+      throw new Error(`Extracted package directory not found at ${packageDir}`);
+    }
+
+    return packageDir;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to resolve ${spec} from npm: ${msg}`, { cause: e });
+  }
+}
+
 export function registerInstallKnowledge(program: Command): void {
   program
     .command('install-knowledge')
-    .argument('<pack>', 'Path to knowledge bundle file or directory')
+    .argument('<pack>', 'Path to knowledge bundle, directory, or npm package name')
     .option('--no-facades', 'Skip facade generation for new domains')
     .description('Install knowledge packs into the agent in the current directory')
     .action(async (pack: string, opts: { facades: boolean }) => {
@@ -17,10 +78,20 @@ export function registerInstallKnowledge(program: Command): void {
         process.exit(1);
       }
 
-      const bundlePath = resolve(pack);
-
       const s = p.spinner();
-      s.start(`Installing knowledge from ${bundlePath}...`);
+      s.start(`Resolving knowledge pack: ${pack}...`);
+
+      let bundlePath: string;
+      try {
+        bundlePath = await resolvePackPath(pack);
+      } catch (err) {
+        s.stop('Resolution failed');
+        p.log.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+        return; // unreachable, for TS
+      }
+
+      s.message(`Installing knowledge from ${bundlePath}...`);
 
       try {
         const result = await installKnowledge({

package/src/commands/install.ts

@@ -0,0 +1,101 @@
+import type { Command } from 'commander';
+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';
+
+type Target = 'claude' | 'codex' | 'both';
+
+function installClaude(agentId: string, agentDir: string): void {
+  const configPath = join(homedir(), '.claude.json');
+  let config: Record<string, unknown> = {};
+
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      p.log.error(`Failed to parse ${configPath}. Fix it manually or delete it to start fresh.`);
+      process.exit(1);
+    }
+  }
+
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+    config.mcpServers = {};
+  }
+
+  (config.mcpServers as Record<string, unknown>)[agentId] = {
+    type: 'stdio',
+    command: 'node',
+    args: [join(agentDir, 'dist', 'index.js')],
+    env: {},
+  };
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  p.log.success(`Registered ${agentId} in ~/.claude.json`);
+}
+
+function installCodex(agentId: string, agentDir: string): void {
+  const codexDir = join(homedir(), '.codex');
+  const configPath = join(codexDir, 'config.toml');
+
+  if (!existsSync(codexDir)) {
+    mkdirSync(codexDir, { recursive: true });
+  }
+
+  let content = '';
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, 'utf-8');
+  }
+
+  // Remove existing section for this agent if present
+  const sectionHeader = `[mcp_servers.${agentId}]`;
+  const sectionRegex = new RegExp(`\\[mcp_servers\\.${escapeRegExp(agentId)}\\][^\\[]*`, 's');
+  content = content.replace(sectionRegex, '').trim();
+
+  const entryPoint = join(agentDir, 'dist', 'index.js');
+  const section = `\n\n${sectionHeader}\ncommand = "node"\nargs = ["${entryPoint}"]\n`;
+
+  content = content + section;
+
+  writeFileSync(configPath, content.trim() + '\n', 'utf-8');
+  p.log.success(`Registered ${agentId} in ~/.codex/config.toml`);
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function registerInstall(program: Command): void {
+  program
+    .command('install')
+    .argument('[dir]', 'Agent directory (defaults to cwd)')
+    .option('--target <target>', 'Registration target: claude, codex, or both', 'claude')
+    .description('Register agent as MCP server in editor config')
+    .action(async (dir?: string, opts?: { target?: string }) => {
+      const resolvedDir = dir ? resolve(dir) : undefined;
+      const ctx = detectAgent(resolvedDir);
+
+      if (!ctx) {
+        p.log.error('Not in an agent project. Run from an agent directory or pass its path.');
+        process.exit(1);
+      }
+
+      const target = (opts?.target ?? 'claude') as Target;
+
+      if (target !== 'claude' && target !== 'codex' && target !== 'both') {
+        p.log.error(`Invalid target "${target}". Use: claude, codex, or both`);
+        process.exit(1);
+      }
+
+      if (target === 'claude' || target === 'both') {
+        installClaude(ctx.agentId, ctx.agentPath);
+      }
+
+      if (target === 'codex' || target === 'both') {
+        installCodex(ctx.agentId, ctx.agentPath);
+      }
+
+      p.log.info(`Agent ${ctx.agentId} is now available as an MCP server.`);
+    });
+}