@soleri/forge 0.0.1 → 4.0.0

package/src/__tests__/scaffolder.test.ts

@@ -0,0 +1,323 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { scaffold, previewScaffold, listAgents } from '../scaffolder.js';
+import type { AgentConfig } from '../types.js';
+
+describe('Scaffolder', () => {
+  let tempDir: string;
+
+  const testConfig: AgentConfig = {
+    id: 'atlas',
+    name: 'Atlas',
+    role: 'Data Engineering Advisor',
+    description:
+      'Atlas provides guidance on data pipelines, ETL patterns, and data quality practices.',
+    domains: ['data-pipelines', 'data-quality', 'etl'],
+    principles: [
+      'Data quality is non-negotiable',
+      'Idempotent pipelines always',
+      'Schema evolution over breaking changes',
+    ],
+    greeting: 'Atlas here. I help with data engineering patterns and best practices.',
+    outputDir: '', // set in beforeEach
+  };
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `forge-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    testConfig.outputDir = tempDir;
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('previewScaffold', () => {
+    it('should return preview without creating files', () => {
+      const preview = previewScaffold(testConfig);
+
+      expect(preview.agentDir).toBe(join(tempDir, 'atlas'));
+      expect(preview.persona.name).toBe('Atlas');
+      expect(preview.persona.role).toBe('Data Engineering Advisor');
+      expect(preview.domains).toEqual(['data-pipelines', 'data-quality', 'etl']);
+      expect(preview.files.length).toBeGreaterThan(15);
+
+      // Should include README, setup script, and LLM client (static modules now in @soleri/core)
+      const paths = preview.files.map((f) => f.path);
+      expect(paths).toContain('README.md');
+      expect(paths).toContain('scripts/setup.sh');
+      expect(paths).toContain('src/llm/llm-client.ts');
+      expect(paths).toContain('src/__tests__/facades.test.ts');
+      // Static modules should NOT be in preview (they live in @soleri/core now)
+      expect(paths).not.toContain('src/vault/vault.ts');
+      expect(paths).not.toContain('src/brain/brain.ts');
+      expect(paths).not.toContain('src/planning/planner.ts');
+
+      // Should have domain facades + core facade
+      expect(preview.facades).toHaveLength(4); // 3 domains + core
+      expect(preview.facades[0].name).toBe('atlas_data_pipelines');
+
+      // Should NOT create any files
+      expect(existsSync(join(tempDir, 'atlas'))).toBe(false);
+    });
+  });
+
+  describe('scaffold', () => {
+    it('should create a complete agent project', () => {
+      const result = scaffold(testConfig);
+
+      expect(result.success).toBe(true);
+      expect(result.agentDir).toBe(join(tempDir, 'atlas'));
+      expect(result.domains).toEqual(['data-pipelines', 'data-quality', 'etl']);
+      expect(result.filesCreated.length).toBeGreaterThan(10);
+    });
+
+    it('should create all expected directories', () => {
+      scaffold(testConfig);
+      const agentDir = join(tempDir, 'atlas');
+
+      expect(existsSync(join(agentDir, 'src', 'facades'))).toBe(true);
+      expect(existsSync(join(agentDir, 'src', 'intelligence', 'data'))).toBe(true);
+      expect(existsSync(join(agentDir, 'src', 'identity'))).toBe(true);
+      expect(existsSync(join(agentDir, 'src', 'activation'))).toBe(true);
+      expect(existsSync(join(agentDir, 'src', 'llm'))).toBe(true);
+      // Static module directories should NOT exist (now in @soleri/core)
+      expect(existsSync(join(agentDir, 'src', 'vault'))).toBe(false);
+      expect(existsSync(join(agentDir, 'src', 'planning'))).toBe(false);
+      expect(existsSync(join(agentDir, 'src', 'brain'))).toBe(false);
+    });
+
+    it('should create valid package.json', () => {
+      scaffold(testConfig);
+      const pkg = JSON.parse(readFileSync(join(tempDir, 'atlas', 'package.json'), 'utf-8'));
+
+      expect(pkg.name).toBe('atlas-mcp');
+      expect(pkg.type).toBe('module');
+      expect(pkg.dependencies['@modelcontextprotocol/sdk']).toBeDefined();
+      expect(pkg.dependencies['@soleri/core']).toBeDefined();
+      expect(pkg.dependencies['zod']).toBeDefined();
+      expect(pkg.dependencies['@anthropic-ai/sdk']).toBeDefined();
+      // better-sqlite3 is now transitive via @soleri/core
+      expect(pkg.dependencies['better-sqlite3']).toBeUndefined();
+    });
+
+    it('should create persona with correct config', () => {
+      scaffold(testConfig);
+      const persona = readFileSync(
+        join(tempDir, 'atlas', 'src', 'identity', 'persona.ts'),
+        'utf-8',
+      );
+
+      expect(persona).toContain("name: 'Atlas'");
+      expect(persona).toContain("role: 'Data Engineering Advisor'");
+      expect(persona).toContain('Data quality is non-negotiable');
+    });
+
+    it('should create domain facades', () => {
+      scaffold(testConfig);
+      const facadesDir = join(tempDir, 'atlas', 'src', 'facades');
+      const files = readdirSync(facadesDir);
+
+      expect(files).toContain('data-pipelines.facade.ts');
+      expect(files).toContain('data-quality.facade.ts');
+      expect(files).toContain('etl.facade.ts');
+      expect(files).toContain('core.facade.ts');
+      // facade-factory.ts and types.ts are now in @soleri/core
+      expect(files).not.toContain('facade-factory.ts');
+      expect(files).not.toContain('types.ts');
+    });
+
+    it('should create empty intelligence data files', () => {
+      scaffold(testConfig);
+      const dataDir = join(tempDir, 'atlas', 'src', 'intelligence', 'data');
+      const files = readdirSync(dataDir);
+
+      expect(files).toContain('data-pipelines.json');
+      expect(files).toContain('data-quality.json');
+      expect(files).toContain('etl.json');
+
+      // Each file should have empty entries array
+      const bundle = JSON.parse(readFileSync(join(dataDir, 'data-pipelines.json'), 'utf-8'));
+      expect(bundle.domain).toBe('data-pipelines');
+      expect(bundle.entries).toEqual([]);
+    });
+
+    it('should create entry point importing from @soleri/core', () => {
+      scaffold(testConfig);
+      const entry = readFileSync(join(tempDir, 'atlas', 'src', 'index.ts'), 'utf-8');
+
+      expect(entry).toContain('createDataPipelinesFacade');
+      expect(entry).toContain('createDataQualityFacade');
+      expect(entry).toContain('createEtlFacade');
+      expect(entry).toContain('createCoreFacade');
+      expect(entry).toContain("name: 'atlas-mcp'");
+      expect(entry).toContain('Brain');
+      expect(entry).toContain('LLMClient');
+      expect(entry).toContain('KeyPool');
+      expect(entry).toContain('loadKeyPoolConfig');
+      expect(entry).toContain('Hello');
+      // Should import shared modules from @soleri/core
+      expect(entry).toContain("from '@soleri/core'");
+      expect(entry).toContain("loadKeyPoolConfig('atlas')");
+    });
+
+    it('should create .mcp.json for client config', () => {
+      scaffold(testConfig);
+      const mcp = JSON.parse(readFileSync(join(tempDir, 'atlas', '.mcp.json'), 'utf-8'));
+
+      expect(mcp.mcpServers.atlas).toBeDefined();
+      expect(mcp.mcpServers.atlas.command).toBe('node');
+    });
+
+    it('should create activation files', () => {
+      scaffold(testConfig);
+      const activationDir = join(tempDir, 'atlas', 'src', 'activation');
+      const files = readdirSync(activationDir);
+
+      expect(files).toContain('claude-md-content.ts');
+      expect(files).toContain('inject-claude-md.ts');
+      expect(files).toContain('activate.ts');
+    });
+
+    it('should create activation files with correct content', () => {
+      scaffold(testConfig);
+      const activationDir = join(tempDir, 'atlas', 'src', 'activation');
+
+      const claudeMd = readFileSync(join(activationDir, 'claude-md-content.ts'), 'utf-8');
+      expect(claudeMd).toContain('atlas:mode');
+      expect(claudeMd).toContain('getClaudeMdContent');
+
+      const inject = readFileSync(join(activationDir, 'inject-claude-md.ts'), 'utf-8');
+      expect(inject).toContain('injectClaudeMd');
+      expect(inject).toContain('getClaudeMdContent');
+
+      const activate = readFileSync(join(activationDir, 'activate.ts'), 'utf-8');
+      expect(activate).toContain('activateAgent');
+      expect(activate).toContain('deactivateAgent');
+      expect(activate).toContain('PERSONA');
+    });
+
+    it('should create README.md with agent-specific content', () => {
+      scaffold(testConfig);
+      const readme = readFileSync(join(tempDir, 'atlas', 'README.md'), 'utf-8');
+
+      expect(readme).toContain('# Atlas');
+      expect(readme).toContain('Data Engineering Advisor');
+      expect(readme).toContain('Hello, Atlas!');
+      expect(readme).toContain('Goodbye, Atlas!');
+      expect(readme).toContain('data-pipelines');
+      expect(readme).toContain('data-quality');
+      expect(readme).toContain('etl');
+      expect(readme).toContain('Data quality is non-negotiable');
+      expect(readme).toContain('./scripts/setup.sh');
+    });
+
+    it('should create executable setup.sh with agent-specific content', () => {
+      scaffold(testConfig);
+      const setupPath = join(tempDir, 'atlas', 'scripts', 'setup.sh');
+      const setup = readFileSync(setupPath, 'utf-8');
+
+      // Content checks
+      expect(setup).toContain('AGENT_NAME="atlas"');
+      expect(setup).toContain('=== Atlas Setup ===');
+      expect(setup).toContain('Building Atlas...');
+      expect(setup).toContain('Hello, Atlas!');
+      expect(setup).toContain('#!/usr/bin/env bash');
+      expect(setup).toContain('claude mcp add');
+
+      // Executable permission check
+      const stats = statSync(setupPath);
+      const isExecutable = (stats.mode & 0o111) !== 0;
+      expect(isExecutable).toBe(true);
+    });
+
+    it('should create LLM client file importing from @soleri/core', () => {
+      scaffold(testConfig);
+      const llmDir = join(tempDir, 'atlas', 'src', 'llm');
+      // Only llm-client.ts should exist (types, utils, key-pool are in @soleri/core)
+      expect(existsSync(join(llmDir, 'llm-client.ts'))).toBe(true);
+      expect(existsSync(join(llmDir, 'types.ts'))).toBe(false);
+      expect(existsSync(join(llmDir, 'utils.ts'))).toBe(false);
+      expect(existsSync(join(llmDir, 'key-pool.ts'))).toBe(false);
+
+      const client = readFileSync(join(llmDir, 'llm-client.ts'), 'utf-8');
+      expect(client).toContain('class LLMClient');
+      expect(client).toContain('class ModelRouter');
+      expect(client).toContain('.atlas');
+      expect(client).toContain("from '@soleri/core'");
+    });
+
+    it('should only create facades test file (static tests in @soleri/core)', () => {
+      scaffold(testConfig);
+      const testsDir = join(tempDir, 'atlas', 'src', '__tests__');
+      const files = readdirSync(testsDir);
+
+      expect(files).toContain('facades.test.ts');
+      // Static module tests are now in @soleri/core
+      expect(files).not.toContain('vault.test.ts');
+      expect(files).not.toContain('loader.test.ts');
+      expect(files).not.toContain('planner.test.ts');
+      expect(files).not.toContain('brain.test.ts');
+      expect(files).not.toContain('llm.test.ts');
+    });
+
+    it('should generate facade tests referencing all domains', () => {
+      scaffold(testConfig);
+      const facadesTest = readFileSync(
+        join(tempDir, 'atlas', 'src', '__tests__', 'facades.test.ts'),
+        'utf-8',
+      );
+
+      expect(facadesTest).toContain('atlas_data_pipelines');
+      expect(facadesTest).toContain('atlas_data_quality');
+      expect(facadesTest).toContain('atlas_etl');
+      expect(facadesTest).toContain('atlas_core');
+      expect(facadesTest).toContain('createDataPipelinesFacade');
+      // Should import shared modules from @soleri/core
+      expect(facadesTest).toContain("from '@soleri/core'");
+      // Activation ops should be tested
+      expect(facadesTest).toContain('activate');
+      expect(facadesTest).toContain('inject_claude_md');
+      expect(facadesTest).toContain('setup');
+      // Memory + planning ops should be tested
+      expect(facadesTest).toContain('memory_capture');
+      expect(facadesTest).toContain('memory_search');
+      expect(facadesTest).toContain('create_plan');
+      expect(facadesTest).toContain('complete_plan');
+      // Brain ops should be tested
+      expect(facadesTest).toContain('record_feedback');
+      expect(facadesTest).toContain('rebuild_vocabulary');
+      expect(facadesTest).toContain('brain_stats');
+      // LLM ops should be tested
+      expect(facadesTest).toContain('llm_status');
+      expect(facadesTest).toContain('LLMClient');
+      expect(facadesTest).toContain('KeyPool');
+    });
+
+    it('should fail if directory already exists', () => {
+      scaffold(testConfig);
+      const result = scaffold(testConfig); // second time
+
+      expect(result.success).toBe(false);
+      expect(result.summary).toContain('already exists');
+    });
+  });
+
+  describe('listAgents', () => {
+    it('should list scaffolded agents', () => {
+      scaffold(testConfig);
+
+      const agents = listAgents(tempDir);
+      expect(agents).toHaveLength(1);
+      expect(agents[0].id).toBe('atlas');
+      expect(agents[0].domains).toEqual(['data-pipelines', 'data-quality', 'etl']);
+    });
+
+    it('should return empty for non-existent directory', () => {
+      const agents = listAgents('/non/existent/path');
+      expect(agents).toEqual([]);
+    });
+  });
+});

package/src/facades/forge.facade.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { scaffold, previewScaffold, listAgents } from '../scaffolder.js';
+import { AgentConfigSchema } from '../types.js';
+import { installKnowledge } from '../knowledge-installer.js';
+
+interface OpDef {
+  name: string;
+  description: string;
+  schema?: z.ZodType;
+  handler: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+export const forgeOps: OpDef[] = [
+  {
+    name: 'preview',
+    description:
+      'Preview what will be created for an agent BEFORE scaffolding. ' +
+      'Show this to the user so they can confirm the structure looks right. ' +
+      'Always call preview before create.',
+    schema: AgentConfigSchema,
+    handler: async (params) => {
+      const config = AgentConfigSchema.parse(params);
+      return previewScaffold(config);
+    },
+  },
+  {
+    name: 'create',
+    description:
+      'Scaffold a complete MCP agent project with activation system. ' +
+      'This creates the full directory structure, source files, config, and activation module. ' +
+      'After creation: npm install && npm run build, then say "Hello, {Name}!" to activate.',
+    schema: AgentConfigSchema,
+    handler: async (params) => {
+      const config = AgentConfigSchema.parse(params);
+      return scaffold(config);
+    },
+  },
+  {
+    name: 'list_agents',
+    description:
+      'List all agents found in a directory. ' +
+      'Useful to see what agents already exist before creating a new one.',
+    schema: z.object({
+      directory: z.string().describe('Parent directory to scan for agent projects'),
+    }),
+    handler: async (params) => {
+      const agents = listAgents(params.directory as string);
+      return {
+        agents,
+        count: agents.length,
+        note: agents.length === 0 ? 'No agents found. Use create to scaffold one.' : undefined,
+      };
+    },
+  },
+  {
+    name: 'guide',
+    description:
+      'Get a structured guide for the AI agent to follow when helping a user create an agent. ' +
+      'This provides the recommended conversation flow and questions to ask.',
+    handler: async () => {
+      return {
+        title: 'Agent Creation Guide',
+        instructions:
+          'Follow these steps to help the user create a new MCP agent. Ask questions conversationally — do not dump all questions at once.',
+        steps: [
+          {
+            step: 1,
+            action: 'Understand the need',
+            ask: 'What role should this agent fill? Who will use it? What kind of guidance should it provide?',
+            examples: [
+              'backend architecture advisor',
+              'QA testing patterns',
+              'data engineering best practices',
+            ],
+          },
+          {
+            step: 2,
+            action: 'Choose name and identity',
+            ask: 'What should we name this agent? A good name is memorable and reflects its domain.',
+            tips: [
+              'Single word works best (Gaudi, Atlas, Nova)',
+              'The name becomes the persona — it will introduce itself with this name',
+            ],
+          },
+          {
+            step: 3,
+            action: 'Select domains',
+            ask: 'What knowledge domains should this agent cover? Domain names should be kebab-case (e.g., api-design, database, security).',
+            tips: [
+              '3-6 domains is ideal',
+              'Each domain becomes a facade (MCP tool) and an intelligence data file',
+              'User can always add more later',
+            ],
+          },
+          {
+            step: 4,
+            action: 'Define principles',
+            ask: 'What are 3-5 core principles this agent should follow? These shape its personality and advice style.',
+            examples: [
+              'Security first — always validate inputs',
+              'Simplicity over cleverness',
+              'Test everything that can break',
+            ],
+          },
+          {
+            step: 5,
+            action: 'Preview and confirm',
+            ask: 'Call preview with the collected config. Show the user what will be created. Ask for confirmation.',
+          },
+          {
+            step: 6,
+            action: 'Create the agent',
+            ask: 'Call create with the confirmed config. Then guide the user through npm install and npm run build. The MCP server is automatically registered in ~/.claude.json.',
+          },
+          {
+            step: 7,
+            action: 'Next steps',
+            suggest: [
+              'Restart Claude Code so the new MCP server is picked up',
+              'Say "Hello, {AgentName}!" to activate the persona in any session',
+              'The agent will check setup status and offer to inject its CLAUDE.md sections',
+              'Add initial knowledge by creating entries in the intelligence data JSON files',
+              'Or use the agent and capture knowledge via the capture ops as you work',
+            ],
+          },
+        ],
+      };
+    },
+  },
+  {
+    name: 'install_knowledge',
+    description:
+      'Install knowledge packs (intelligence bundles) into an existing MCP agent. ' +
+      'Copies bundle JSON files, generates domain facades for new domains, ' +
+      'patches index.ts and claude-md-content.ts, then rebuilds.',
+    schema: z.object({
+      agentPath: z.string().describe('Absolute path to the target agent project'),
+      bundlePath: z.string().describe('Path to bundles directory or single .json file'),
+      generateFacades: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Generate domain facades for new domains (default true)'),
+    }),
+    handler: async (params) =>
+      installKnowledge(
+        params as { agentPath: string; bundlePath: string; generateFacades?: boolean },
+      ),
+  },
+];

package/src/index.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { forgeOps } from './facades/forge.facade.js';
+
+async function main(): Promise<void> {
+  const server = new McpServer({
+    name: 'soleri',
+    version: '3.0.0',
+  });
+
+  // Register the forge tool with op dispatch
+  const opNames = forgeOps.map((o) => o.name);
+
+  server.tool(
+    'forge',
+    `Soleri Forge — scaffold AI agents that learn, remember, and grow.\n\nOperations: ${opNames.join(', ')}\n\nStart by calling 'guide' to get the recommended conversation flow for helping a user create an agent.`,
+    {
+      op: z.string().describe(`Operation: ${opNames.join(' | ')}`),
+      params: z.record(z.unknown()).optional().default({}).describe('Operation parameters'),
+    },
+    async ({ op, params }) => {
+      const opDef = forgeOps.find((o) => o.name === op);
+      if (!opDef) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  success: false,
+                  error: `Unknown operation "${op}". Available: ${opNames.join(', ')}`,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      try {
+        let validatedParams = params;
+        if (opDef.schema) {
+          const result = opDef.schema.safeParse(params);
+          if (!result.success) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: JSON.stringify({ success: false, error: result.error.message }, null, 2),
+                },
+              ],
+            };
+          }
+          validatedParams = result.data as Record<string, unknown>;
+        }
+
+        const data = await opDef.handler(validatedParams);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({ success: true, data }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(
+                {
+                  success: false,
+                  error: err instanceof Error ? err.message : String(err),
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+    },
+  );
+
+  console.error('[soleri] Soleri Forge — AI agent scaffolding tool');
+  console.error(`[soleri] ${forgeOps.length} operations available`);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[soleri] Connected via stdio');
+}
+
+main().catch((err) => {
+  console.error('[soleri] Fatal:', err);
+  process.exit(1);
+});