@soleri/cli 0.0.1 → 1.0.1

package/src/hooks/templates.ts

@@ -0,0 +1,185 @@
+/**
+ * Editor-specific hook/config templates.
+ *
+ * Each template function reads agent identity and generates
+ * editor-appropriate configuration files.
+ */
+import { detectAgent } from '../utils/agent-context.js';
+
+export type EditorId = 'claude-code' | 'cursor' | 'windsurf' | 'copilot';
+
+export const SUPPORTED_EDITORS: EditorId[] = ['claude-code', 'cursor', 'windsurf', 'copilot'];
+
+interface AgentMeta {
+  agentId: string;
+  packageName: string;
+}
+
+/** Sanitize agent ID for safe interpolation into shell commands and templates. */
+function sanitizeId(id: string): string {
+  return id.replace(/[^a-z0-9-]/g, '');
+}
+
+function getAgentMeta(dir?: string): AgentMeta | null {
+  const ctx = detectAgent(dir);
+  if (!ctx) return null;
+  return { agentId: sanitizeId(ctx.agentId), packageName: ctx.packageName };
+}
+
+// ── Claude Code ──
+
+function generateClaudeCodeSettings(dir?: string): Record<string, string> {
+  const meta = getAgentMeta(dir);
+  const agentId = meta?.agentId ?? 'my-agent';
+
+  const settings = JSON.stringify(
+    {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: '*',
+            hooks: [
+              {
+                type: 'command',
+                command: `echo "[${agentId}] tool: $TOOL_NAME"`,
+              },
+            ],
+          },
+        ],
+        PostToolUse: [
+          {
+            matcher: 'Edit|Write',
+            hooks: [
+              {
+                type: 'command',
+                command: `echo "[${agentId}] file changed"`,
+              },
+            ],
+          },
+        ],
+        SessionStart: [
+          {
+            hooks: [
+              {
+                type: 'command',
+                command: `echo "[${agentId}] session started"`,
+              },
+            ],
+          },
+        ],
+      },
+    },
+    null,
+    2,
+  );
+
+  return {
+    '.claude/settings.json': settings,
+  };
+}
+
+// ── Cursor ──
+
+function generateCursorRules(dir?: string): Record<string, string> {
+  const meta = getAgentMeta(dir);
+  const agentId = meta?.agentId ?? 'my-agent';
+
+  const rules = `# ${agentId} — Cursor Rules
+# Generated by soleri hooks add cursor
+
+## Agent Context
+This project is a Soleri AI agent (${agentId}).
+The agent uses the MCP protocol and is structured with facades, a vault, and a brain.
+
+## Key Directories
+- src/facades/ — MCP tool facades (one per domain)
+- src/intelligence/data/ — Knowledge bundles (JSON)
+- src/identity/ — Persona definition
+- src/activation/ — Activation and CLAUDE.md injection
+
+## Conventions
+- All facades follow the FacadeConfig pattern from @soleri/core
+- Knowledge entries use the pattern/anti-pattern/rule taxonomy
+- Domain names are kebab-case
+- Facade names use the pattern: {agentId}_{domain}
+`;
+
+  return {
+    '.cursorrules': rules,
+  };
+}
+
+// ── Windsurf ──
+
+function generateWindsurfRules(dir?: string): Record<string, string> {
+  const meta = getAgentMeta(dir);
+  const agentId = meta?.agentId ?? 'my-agent';
+
+  const rules = `# ${agentId} — Windsurf Rules
+# Generated by soleri hooks add windsurf
+
+## Agent Context
+This project is a Soleri AI agent (${agentId}).
+The agent uses the MCP protocol and is structured with facades, a vault, and a brain.
+
+## Key Directories
+- src/facades/ — MCP tool facades (one per domain)
+- src/intelligence/data/ — Knowledge bundles (JSON)
+- src/identity/ — Persona definition
+- src/activation/ — Activation and CLAUDE.md injection
+
+## Conventions
+- All facades follow the FacadeConfig pattern from @soleri/core
+- Knowledge entries use the pattern/anti-pattern/rule taxonomy
+- Domain names are kebab-case
+- Facade names use the pattern: {agentId}_{domain}
+`;
+
+  return {
+    '.windsurfrules': rules,
+  };
+}
+
+// ── GitHub Copilot ──
+
+function generateCopilotInstructions(dir?: string): Record<string, string> {
+  const meta = getAgentMeta(dir);
+  const agentId = meta?.agentId ?? 'my-agent';
+
+  const instructions = `# ${agentId} — Copilot Instructions
+<!-- Generated by soleri hooks add copilot -->
+
+## Agent Context
+This project is a Soleri AI agent (${agentId}).
+The agent uses the MCP protocol and is structured with facades, a vault, and a brain.
+
+## Key Directories
+- \`src/facades/\` — MCP tool facades (one per domain)
+- \`src/intelligence/data/\` — Knowledge bundles (JSON)
+- \`src/identity/\` — Persona definition
+- \`src/activation/\` — Activation and CLAUDE.md injection
+
+## Conventions
+- All facades follow the FacadeConfig pattern from @soleri/core
+- Knowledge entries use the pattern/anti-pattern/rule taxonomy
+- Domain names are kebab-case
+- Facade names use the pattern: \`{agentId}_{domain}\`
+`;
+
+  return {
+    '.github/copilot-instructions.md': instructions,
+  };
+}
+
+export function getEditorFiles(editor: EditorId, dir?: string): Record<string, string> {
+  switch (editor) {
+    case 'claude-code':
+      return generateClaudeCodeSettings(dir);
+    case 'cursor':
+      return generateCursorRules(dir);
+    case 'windsurf':
+      return generateWindsurfRules(dir);
+    case 'copilot':
+      return generateCopilotInstructions(dir);
+  }
+}

package/src/main.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { registerCreate } from './commands/create.js';
+import { registerList } from './commands/list.js';
+import { registerAddDomain } from './commands/add-domain.js';
+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';
+
+const program = new Command();
+
+program
+  .name('soleri')
+  .description('Developer CLI for creating and managing Soleri AI agents')
+  .version('1.0.0');
+
+registerCreate(program);
+registerList(program);
+registerAddDomain(program);
+registerInstallKnowledge(program);
+registerDev(program);
+registerDoctor(program);
+registerHooks(program);
+
+program.parse();

package/src/prompts/create-wizard.ts

@@ -0,0 +1,129 @@
+/**
+ * Interactive create wizard using @clack/prompts.
+ */
+import * as p from '@clack/prompts';
+import type { AgentConfig } from '@soleri/forge/lib';
+
+/**
+ * Run the interactive create wizard and return an AgentConfig.
+ * Returns null if the user cancels.
+ */
+export async function runCreateWizard(initialName?: string): Promise<AgentConfig | null> {
+  p.intro('Create a new Soleri agent');
+
+  const id =
+    initialName ??
+    ((await p.text({
+      message: 'Agent ID (kebab-case)',
+      placeholder: 'my-agent',
+      validate: (v = '') => {
+        if (!/^[a-z][a-z0-9-]*$/.test(v)) return 'Must be kebab-case (e.g., "my-agent")';
+      },
+    })) as string);
+
+  if (p.isCancel(id)) return null;
+
+  const name = (await p.text({
+    message: 'Display name',
+    placeholder: 'My Agent',
+    validate: (v) => {
+      if (!v || v.length > 50) return 'Required (max 50 chars)';
+    },
+  })) as string;
+
+  if (p.isCancel(name)) return null;
+
+  const role = (await p.text({
+    message: 'Role (one line)',
+    placeholder: 'A helpful AI assistant for...',
+    validate: (v) => {
+      if (!v || v.length > 100) return 'Required (max 100 chars)';
+    },
+  })) as string;
+
+  if (p.isCancel(role)) return null;
+
+  const description = (await p.text({
+    message: 'Description',
+    placeholder: 'This agent helps developers with...',
+    validate: (v) => {
+      if (!v || v.length < 10 || v.length > 500) return 'Required (10-500 chars)';
+    },
+  })) as string;
+
+  if (p.isCancel(description)) return null;
+
+  const domainsRaw = (await p.text({
+    message: 'Domains (comma-separated, kebab-case)',
+    placeholder: 'api-design, security, testing',
+    validate: (v = '') => {
+      const parts = v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (parts.length === 0) return 'At least one domain required';
+      for (const d of parts) {
+        if (!/^[a-z][a-z0-9-]*$/.test(d)) return `Invalid domain "${d}" — must be kebab-case`;
+      }
+    },
+  })) as string;
+
+  if (p.isCancel(domainsRaw)) return null;
+
+  const domains = domainsRaw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const principlesRaw = (await p.text({
+    message: 'Principles (one per line)',
+    placeholder: 'Security first\nSimplicity over cleverness\nTest everything',
+    validate: (v = '') => {
+      const lines = v
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (lines.length === 0) return 'At least one principle required';
+      if (lines.length > 10) return 'Max 10 principles';
+    },
+  })) as string;
+
+  if (p.isCancel(principlesRaw)) return null;
+
+  const principles = principlesRaw
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const greeting = (await p.text({
+    message: 'Greeting message',
+    placeholder: `Hello! I'm ${name}, your AI assistant for...`,
+    validate: (v) => {
+      if (!v || v.length < 10 || v.length > 300) return 'Required (10-300 chars)';
+    },
+  })) as string;
+
+  if (p.isCancel(greeting)) return null;
+
+  const outputDir = (await p.text({
+    message: 'Output directory',
+    defaultValue: process.cwd(),
+    placeholder: process.cwd(),
+    validate: (v) => {
+      if (!v) return 'Required';
+    },
+  })) as string;
+
+  if (p.isCancel(outputDir)) return null;
+
+  return {
+    id,
+    name,
+    role,
+    description,
+    domains,
+    principles,
+    greeting,
+    outputDir,
+  };
+}

package/src/utils/agent-context.ts

@@ -0,0 +1,38 @@
+/**
+ * Detect and validate an agent project in the current working directory.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+interface AgentContext {
+  agentPath: string;
+  agentId: string;
+  packageName: string;
+  hasBrain: boolean;
+}
+
+/**
+ * Detect an agent in the given directory.
+ * Returns null if the directory is not a valid agent project.
+ */
+export function detectAgent(dir?: string): AgentContext | null {
+  const agentPath = resolve(dir ?? process.cwd());
+  const pkgPath = join(agentPath, 'package.json');
+
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const name: string = pkg.name ?? '';
+    if (!name.endsWith('-mcp')) return null;
+
+    return {
+      agentPath,
+      agentId: name.replace(/-mcp$/, ''),
+      packageName: name,
+      hasBrain: existsSync(join(agentPath, 'src', 'brain')),
+    };
+  } catch {
+    return null;
+  }
+}

package/src/utils/checks.ts

@@ -0,0 +1,148 @@
+/**
+ * Health check utilities for the doctor command.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { detectAgent } from './agent-context.js';
+
+interface CheckResult {
+  status: 'pass' | 'fail' | 'warn';
+  label: string;
+  detail?: string;
+}
+
+export function checkNodeVersion(): CheckResult {
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major >= 18) {
+    return { status: 'pass', label: 'Node.js', detail: `v${process.versions.node}` };
+  }
+  return { status: 'fail', label: 'Node.js', detail: `v${process.versions.node} (>=18 required)` };
+}
+
+export function checkNpm(): CheckResult {
+  try {
+    const version = execFileSync('npm', ['--version'], { encoding: 'utf-8' }).trim();
+    return { status: 'pass', label: 'npm', detail: `v${version}` };
+  } catch {
+    return { status: 'fail', label: 'npm', detail: 'not found' };
+  }
+}
+
+function checkTsx(): CheckResult {
+  try {
+    const version = execFileSync('npx', ['tsx', '--version'], {
+      encoding: 'utf-8',
+      timeout: 10_000,
+    }).trim();
+    return { status: 'pass', label: 'tsx', detail: `v${version}` };
+  } catch {
+    return { status: 'warn', label: 'tsx', detail: 'not found — needed for soleri dev' };
+  }
+}
+
+export function checkAgentProject(dir?: string): CheckResult {
+  const ctx = detectAgent(dir);
+  if (!ctx) {
+    return { status: 'warn', label: 'Agent project', detail: 'not detected in current directory' };
+  }
+  return { status: 'pass', label: 'Agent project', detail: `${ctx.agentId} (${ctx.packageName})` };
+}
+
+export function checkAgentBuild(dir?: string): CheckResult {
+  const ctx = detectAgent(dir);
+  if (!ctx) return { status: 'warn', label: 'Agent build', detail: 'no agent detected' };
+
+  if (!existsSync(join(ctx.agentPath, 'dist'))) {
+    return { status: 'fail', label: 'Agent build', detail: 'dist/ not found — run npm run build' };
+  }
+  if (!existsSync(join(ctx.agentPath, 'dist', 'index.js'))) {
+    return {
+      status: 'fail',
+      label: 'Agent build',
+      detail: 'dist/index.js not found — run npm run build',
+    };
+  }
+  return { status: 'pass', label: 'Agent build', detail: 'dist/index.js exists' };
+}
+
+export function checkNodeModules(dir?: string): CheckResult {
+  const ctx = detectAgent(dir);
+  if (!ctx) return { status: 'warn', label: 'Dependencies', detail: 'no agent detected' };
+
+  if (!existsSync(join(ctx.agentPath, 'node_modules'))) {
+    return {
+      status: 'fail',
+      label: 'Dependencies',
+      detail: 'node_modules/ not found — run npm install',
+    };
+  }
+  return { status: 'pass', label: 'Dependencies', detail: 'node_modules/ exists' };
+}
+
+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)) {
+    return {
+      status: 'warn',
+      label: 'MCP registration',
+      detail: '~/.claude.json not found',
+    };
+  }
+
+  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' };
+  }
+}
+
+function checkCognee(): CheckResult {
+  const url = process.env.COGNEE_URL ?? 'http://localhost:8000/';
+  let host: string;
+  try {
+    host = new URL(url).host;
+  } catch {
+    return { status: 'warn', label: 'Cognee', detail: `invalid COGNEE_URL: ${url}` };
+  }
+  try {
+    execFileSync('curl', ['-fsS', '--max-time', '5', url], { stdio: 'ignore', timeout: 7_000 });
+    return { status: 'pass', label: 'Cognee', detail: `available at ${host}` };
+  } catch {
+    return {
+      status: 'warn',
+      label: 'Cognee',
+      detail: `not running at ${host} — vector search disabled (FTS5 still works)`,
+    };
+  }
+}
+
+export function runAllChecks(dir?: string): CheckResult[] {
+  return [
+    checkNodeVersion(),
+    checkNpm(),
+    checkTsx(),
+    checkAgentProject(dir),
+    checkNodeModules(dir),
+    checkAgentBuild(dir),
+    checkMcpRegistration(dir),
+    checkCognee(),
+  ];
+}

package/src/utils/logger.ts

@@ -0,0 +1,39 @@
+/**
+ * Simple colored output helpers for the CLI.
+ * Uses ANSI codes directly — no chalk dependency needed.
+ */
+
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+export function pass(label: string, detail?: string): void {
+  const suffix = detail ? ` ${DIM}${detail}${RESET}` : '';
+  console.log(`  ${GREEN}✓${RESET} ${label}${suffix}`);
+}
+
+export function fail(label: string, detail?: string): void {
+  const suffix = detail ? ` ${DIM}${detail}${RESET}` : '';
+  console.log(`  ${RED}✗${RESET} ${label}${suffix}`);
+}
+
+export function warn(label: string, detail?: string): void {
+  const suffix = detail ? ` ${DIM}${detail}${RESET}` : '';
+  console.log(`  ${YELLOW}!${RESET} ${label}${suffix}`);
+}
+
+export function info(message: string): void {
+  console.log(`  ${CYAN}ℹ${RESET} ${message}`);
+}
+
+export function heading(title: string): void {
+  console.log(`\n${BOLD}${title}${RESET}\n`);
+}
+
+export function dim(message: string): void {
+  console.log(`  ${DIM}${message}${RESET}`);
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noEmitOnError": true,
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/__tests__/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/__tests__/**/*.test.ts'],
+    testTimeout: 15_000,
+  },
+});