keystone-cli 0.8.0 → 1.0.1

package/src/parser/workflow-parser.ts

@@ -1,8 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import * as yaml from 'js-yaml';
 import { z } from 'zod';
 import { ExpressionEvaluator } from '../expression/evaluator.ts';
+import { ResourceLoader } from '../utils/resource-loader.ts';
+import { validateJsonSchemaDefinition } from '../utils/schema-validator.ts';
 import { resolveAgentPath } from './agent-parser.ts';
 import { type Workflow, WorkflowSchema } from './schema.ts';
 
@@ -12,8 +13,12 @@ export class WorkflowParser {
    */
   static loadWorkflow(path: string): Workflow {
     try {
-      const content = readFileSync(path, 'utf-8');
+      const content = ResourceLoader.readFile(path);
+      if (content === null) {
+        throw new Error(`Workflow file not found at ${path}`);
+      }
       const raw = yaml.load(content);
+      WorkflowParser.normalizeAliases(raw);
       const workflow = WorkflowSchema.parse(raw);
       const workflowDir = dirname(path);
 
@@ -26,6 +31,9 @@ export class WorkflowParser {
       // Validate agents exist
       WorkflowParser.validateAgents(workflow, workflowDir);
 
+      // Validate errors block
+      WorkflowParser.validateErrors(workflow);
+
       // Validate finally block
       WorkflowParser.validateFinally(workflow);
 
@@ -44,11 +52,36 @@ export class WorkflowParser {
     }
   }
 
+  /**
+   * Normalize legacy or alias field names before schema validation.
+   */
+  private static normalizeAliases(value: unknown): void {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        WorkflowParser.normalizeAliases(item);
+      }
+      return;
+    }
+
+    const record = value as Record<string, unknown>;
+    if ('autoHeal' in record && !('auto_heal' in record)) {
+      record.auto_heal = record.autoHeal;
+    }
+    if ('autoHeal' in record) {
+      record.autoHeal = undefined;
+    }
+
+    for (const child of Object.values(record)) {
+      WorkflowParser.normalizeAliases(child);
+    }
+  }
+
   /**
    * Automatically detect step dependencies from expressions
    */
   private static resolveImplicitDependencies(workflow: Workflow): void {
-    const allSteps = [...workflow.steps, ...(workflow.finally || [])];
+    const allSteps = [...workflow.steps, ...(workflow.errors || []), ...(workflow.finally || [])];
     for (const step of allSteps) {
       const detected = new Set<string>();
 
@@ -127,7 +160,7 @@ export class WorkflowParser {
    * Validate that all agents referenced in LLM steps exist
    */
   private static validateAgents(workflow: Workflow, baseDir?: string): void {
-    const allSteps = [...workflow.steps, ...(workflow.finally || [])];
+    const allSteps = [...workflow.steps, ...(workflow.errors || []), ...(workflow.finally || [])];
     for (const step of allSteps) {
       if (step.type === 'llm') {
         try {
@@ -168,6 +201,39 @@ export class WorkflowParser {
     }
   }
 
+  /**
+   * Validate errors block
+   */
+  private static validateErrors(workflow: Workflow): void {
+    if (!workflow.errors) return;
+
+    const mainStepIds = new Set(workflow.steps.map((s) => s.id));
+    const errorsStepIds = new Set<string>();
+    const finallyStepIds = new Set((workflow.finally || []).map((s) => s.id));
+
+    for (const step of workflow.errors) {
+      if (mainStepIds.has(step.id)) {
+        throw new Error(`Step ID "${step.id}" in errors block conflicts with main steps`);
+      }
+      if (finallyStepIds.has(step.id)) {
+        throw new Error(`Step ID "${step.id}" in errors block conflicts with finally steps`);
+      }
+      if (errorsStepIds.has(step.id)) {
+        throw new Error(`Duplicate Step ID "${step.id}" in errors block`);
+      }
+      errorsStepIds.add(step.id);
+
+      // Errors steps can only depend on main steps or previous errors steps
+      for (const dep of step.needs) {
+        if (!mainStepIds.has(dep) && !errorsStepIds.has(dep)) {
+          throw new Error(
+            `Errors step "${step.id}" depends on non-existent step "${dep}". Errors steps can only depend on main steps or previous errors steps.`
+          );
+        }
+      }
+    }
+  }
+
   /**
    * Perform topological sort on steps
    * Returns steps in execution order
@@ -211,9 +277,10 @@ export class WorkflowParser {
       }
     }
 
-    while (queue.length > 0) {
-      const stepId = queue.shift();
-      if (!stepId) continue;
+    let queueIndex = 0;
+    while (queueIndex < queue.length) {
+      const stepId = queue[queueIndex];
+      queueIndex += 1;
       result.push(stepId);
 
       // Find all steps that depend on this step (O(1) lookup)
@@ -232,4 +299,83 @@ export class WorkflowParser {
 
     return result;
   }
+
+  /**
+   * Strict validation for schema definitions and enums.
+   */
+  static validateStrict(workflow: Workflow, source?: string): void {
+    const errors: string[] = [];
+
+    const locateSchema = (
+      stepId: string,
+      field: 'inputSchema' | 'outputSchema'
+    ): { line: number; column: number } | null => {
+      if (!source) return null;
+      const lines = source.split('\n');
+      const escaped = stepId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const inlineId = new RegExp(`^\\s*-\\s*id:\\s*['"]?${escaped}['"]?\\s*(#.*)?$`);
+      const idLine = new RegExp(`^\\s*id:\\s*['"]?${escaped}['"]?\\s*(#.*)?$`);
+
+      let inStep = false;
+      let stepIndent = 0;
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const indent = line.match(/^\s*/)?.[0].length ?? 0;
+
+        if (!inStep) {
+          if (inlineId.test(line) || idLine.test(line)) {
+            inStep = true;
+            stepIndent = indent;
+          }
+          continue;
+        }
+
+        if (trimmed.startsWith('- ') && indent <= stepIndent) {
+          inStep = false;
+          if (inlineId.test(line) || idLine.test(line)) {
+            inStep = true;
+            stepIndent = indent;
+          }
+          continue;
+        }
+
+        if (trimmed.startsWith(`${field}:`)) {
+          const column = line.indexOf(field) + 1;
+          return { line: i + 1, column: column > 0 ? column : 1 };
+        }
+      }
+
+      return null;
+    };
+
+    const allSteps = [...workflow.steps, ...(workflow.errors || []), ...(workflow.finally || [])];
+    for (const step of allSteps) {
+      if (step.inputSchema) {
+        const result = validateJsonSchemaDefinition(step.inputSchema);
+        if (!result.valid) {
+          const location = locateSchema(step.id, 'inputSchema');
+          const locSuffix = location
+            ? ` (at line ${location.line}, column ${location.column})`
+            : '';
+          errors.push(`step "${step.id}" inputSchema${locSuffix}: ${result.error}`);
+        }
+      }
+      if (step.outputSchema) {
+        const result = validateJsonSchemaDefinition(step.outputSchema);
+        if (!result.valid) {
+          const location = locateSchema(step.id, 'outputSchema');
+          const locSuffix = location
+            ? ` (at line ${location.line}, column ${location.column})`
+            : '';
+          errors.push(`step "${step.id}" outputSchema${locSuffix}: ${result.error}`);
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new Error(`Strict validation failed:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+    }
+  }
 }

package/src/runner/aggregate-error.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'bun:test';
+import { AggregateWorkflowError } from './aggregate-error';
+
+describe('AggregateWorkflowError', () => {
+  it('should create with multiple errors', () => {
+    const errors = [new Error('Error 1'), new Error('Error 2'), new Error('Error 3')];
+    const aggregate = new AggregateWorkflowError('test-step', errors);
+
+    expect(aggregate.name).toBe('AggregateWorkflowError');
+    expect(aggregate.stepId).toBe('test-step');
+    expect(aggregate.errors).toHaveLength(3);
+    expect(aggregate.count).toBe(3);
+  });
+
+  it('should format message with all errors', () => {
+    const errors = [new Error('First error'), new Error('Second error')];
+    const aggregate = new AggregateWorkflowError('my-step', errors);
+
+    expect(aggregate.message).toContain('my-step');
+    expect(aggregate.message).toContain('2 error(s)');
+    expect(aggregate.message).toContain('[1] First error');
+    expect(aggregate.message).toContain('[2] Second error');
+  });
+
+  it('should return first error', () => {
+    const first = new Error('First');
+    const errors = [first, new Error('Second')];
+    const aggregate = new AggregateWorkflowError('step', errors);
+
+    expect(aggregate.firstError).toBe(first);
+  });
+
+  it('should return undefined for empty errors', () => {
+    const aggregate = new AggregateWorkflowError('step', []);
+    expect(aggregate.firstError).toBeUndefined();
+  });
+
+  it('should check if all errors are of specific type', () => {
+    class CustomError extends Error {}
+    const errors = [new CustomError('a'), new CustomError('b')];
+    const aggregate = new AggregateWorkflowError('step', errors);
+
+    expect(aggregate.allOfType(CustomError)).toBe(true);
+    expect(aggregate.allOfType(TypeError)).toBe(false);
+  });
+
+  it('should filter errors by type', () => {
+    class CustomError extends Error {}
+    const custom = new CustomError('custom');
+    const errors = [custom, new Error('regular'), new CustomError('another')];
+    const aggregate = new AggregateWorkflowError('step', errors);
+
+    const customErrors = aggregate.ofType(CustomError);
+    expect(customErrors).toHaveLength(2);
+    expect(customErrors[0]).toBe(custom);
+  });
+});

package/src/runner/aggregate-error.ts

@@ -0,0 +1,46 @@
+/**
+ * Aggregate workflow error that collects multiple errors from parallel execution.
+ *
+ * This allows capturing all failures from a foreach loop or parallel workflow
+ * execution rather than failing on the first error.
+ */
+export class AggregateWorkflowError extends Error {
+  readonly errors: Error[];
+  readonly stepId: string;
+
+  constructor(stepId: string, errors: Error[]) {
+    const messages = errors.map((e, i) => `  [${i + 1}] ${e.message}`).join('\n');
+    super(`Step ${stepId} failed with ${errors.length} error(s):\n${messages}`);
+    this.name = 'AggregateWorkflowError';
+    this.stepId = stepId;
+    this.errors = errors;
+  }
+
+  /**
+   * Get the first error in the collection.
+   */
+  get firstError(): Error | undefined {
+    return this.errors[0];
+  }
+
+  /**
+   * Get the count of errors.
+   */
+  get count(): number {
+    return this.errors.length;
+  }
+
+  /**
+   * Check if all errors are of a specific type.
+   */
+  allOfType<T extends Error>(errorClass: new (...args: unknown[]) => T): boolean {
+    return this.errors.every((e) => e instanceof errorClass);
+  }
+
+  /**
+   * Filter errors by type.
+   */
+  ofType<T extends Error>(errorClass: new (...args: unknown[]) => T): T[] {
+    return this.errors.filter((e) => e instanceof errorClass) as T[];
+  }
+}

package/src/runner/audit-verification.test.ts

@@ -45,14 +45,14 @@ describe('Audit Fixes Verification', () => {
       // The sandbox now uses node:vm directly with security warnings.
       SafeSandbox.resetWarning();
       const code = '1 + 1';
-      const result = await SafeSandbox.execute(code, {});
+      const result = await SafeSandbox.execute(code, {}, { useProcessIsolation: false });
       expect(result).toBe(2);
     });
 
     it('should show security warning on first execution', async () => {
       SafeSandbox.resetWarning();
       const code = '2 + 2';
-      const result = await SafeSandbox.execute(code, {});
+      const result = await SafeSandbox.execute(code, {}, { useProcessIsolation: false });
       expect(result).toBe(4);
       // Warning is shown to stderr, we just verify execution works
     });

package/src/runner/auto-heal.test.ts

@@ -31,7 +31,7 @@ describe('WorkflowRunner Auto-Heal', () => {
 
     // biome-ignore lint/suspicious/noExplicitAny: Accessing private property for testing
     const db = (runner as any).db;
-    await db.createRun(runner.getRunId(), workflow.name, {});
+    await db.createRun(runner.runId, workflow.name, {});
 
     const spy = jest.spyOn(StepExecutor, 'executeStep');
 

package/src/runner/blueprint-executor.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import * as path from 'node:path';
+import type { ExpressionContext } from '../expression/evaluator';
+import type { Blueprint, BlueprintStep, Step } from '../parser/schema';
+import type { Logger } from '../utils/logger';
+import { executeBlueprintStep } from './blueprint-executor';
+import type { executeLlmStep } from './llm-executor';
+import type { StepResult } from './step-executor';
+
+describe('BlueprintExecutor', () => {
+  const tempDir = path.join(process.cwd(), '.tmp-blueprint-test');
+
+  it('should generate and persist a blueprint', async () => {
+    mkdirSync(tempDir, { recursive: true });
+
+    const mockStep: BlueprintStep = {
+      id: 'test_blueprint',
+      type: 'blueprint',
+      prompt: 'Build a todo app',
+      needs: [],
+      agent: 'keystone-architect',
+    };
+
+    const mockBlueprint: Blueprint = {
+      architecture: { description: 'Todo Architecture' },
+      files: [{ path: 'todo.ts', purpose: 'logic' }],
+    };
+
+    const mockExecuteLlmStep = mock(async () => ({
+      status: 'success',
+      output: mockBlueprint,
+      usage: { prompt_tokens: 10, completion_tokens: 10, total_tokens: 20 },
+    })) as unknown as typeof executeLlmStep;
+
+    const mockExecuteStep = mock(async () => ({ status: 'success', output: null }) as StepResult);
+
+    const context: ExpressionContext = { steps: {}, inputs: {}, env: {}, secrets: {} };
+    const logger: Logger = {
+      log: () => {},
+      error: () => {},
+      warn: () => {},
+      info: () => {},
+    };
+
+    try {
+      const result = await executeBlueprintStep(mockStep, context, mockExecuteStep, logger, {
+        artifactRoot: tempDir,
+        runId: 'test-run',
+        executeLlmStep: mockExecuteLlmStep,
+      });
+
+      expect(result.status).toBe('success');
+      expect(result.output).toMatchObject(mockBlueprint);
+      const output = result.output as Blueprint & { __hash: string; __artifactPath: string };
+      expect(output.__hash).toBeDefined();
+
+      expect(existsSync(output.__artifactPath)).toBe(true);
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/runner/blueprint-executor.ts

@@ -0,0 +1,157 @@
+import { mkdirSync } from 'node:fs';
+import * as path from 'node:path';
+import type { ExpressionContext } from '../expression/evaluator.ts';
+import type { Blueprint, BlueprintStep, LlmStep, Step } from '../parser/schema.ts';
+import { BlueprintUtils } from '../utils/blueprint-utils.ts';
+import type { Logger } from '../utils/logger.ts';
+import { executeLlmStep } from './llm-executor.ts';
+import type { MCPManager } from './mcp-manager.ts';
+import type { StepResult } from './step-executor.ts';
+
+/**
+ * Execute a blueprint step
+ */
+export async function executeBlueprintStep(
+  step: BlueprintStep,
+  context: ExpressionContext,
+  executeStepFn: (step: Step, context: ExpressionContext) => Promise<StepResult>,
+  logger: Logger,
+  options: {
+    mcpManager?: MCPManager;
+    workflowDir?: string;
+    abortSignal?: AbortSignal;
+    runId?: string;
+    artifactRoot?: string;
+    executeLlmStep?: typeof executeLlmStep;
+  }
+): Promise<StepResult> {
+  const {
+    mcpManager,
+    workflowDir,
+    abortSignal,
+    runId,
+    artifactRoot,
+    executeLlmStep: injected,
+  } = options;
+  const runLlmStep = injected || executeLlmStep;
+
+  // 1. Create a virtual LLM step to generate the blueprint
+  // We reuse the BlueprintSchema as the outputSchema for validation
+  const llmStep: LlmStep = {
+    id: `${step.id}_generation`,
+    type: 'llm',
+    agent: step.agent || 'keystone-architect',
+    prompt: step.prompt,
+    outputSchema: {
+      // Reference the actual BlueprintSchema structure
+      // Since we are in runtime, we need the raw object or a way to get it from Zod
+      // For now, let's assume BlueprintSchema is available or we define it here
+      // Actually, it's better to just use the Zod schema for validation later
+      // But the LLM needs a JSON Schema.
+      type: 'object',
+      properties: {
+        architecture: {
+          type: 'object',
+          properties: {
+            description: { type: 'string' },
+            patterns: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['description'],
+        },
+        apis: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              description: { type: 'string' },
+              endpoints: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    path: { type: 'string' },
+                    method: { type: 'string' },
+                    purpose: { type: 'string' },
+                  },
+                  required: ['path', 'method', 'purpose'],
+                },
+              },
+            },
+            required: ['name', 'description'],
+          },
+        },
+        files: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string' },
+              purpose: { type: 'string' },
+              constraints: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['path', 'purpose'],
+          },
+        },
+        dependencies: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              version: { type: 'string' },
+              purpose: { type: 'string' },
+            },
+            required: ['name', 'purpose'],
+          },
+        },
+        constraints: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['architecture', 'files'],
+    },
+    useStandardTools: true,
+    needs: [],
+    maxIterations: 10,
+  };
+
+  logger.log(`  🎨 Generating system blueprint using agent: ${llmStep.agent}`);
+
+  const llmResult = await runLlmStep(
+    llmStep,
+    context,
+    executeStepFn,
+    logger,
+    mcpManager,
+    workflowDir,
+    abortSignal
+  );
+
+  if (llmResult.status !== 'success') {
+    return llmResult;
+  }
+
+  const blueprint = llmResult.output as Blueprint;
+
+  // 2. Calculate hash for immutability check
+  const hash = BlueprintUtils.calculateHash(blueprint);
+
+  // 3. Persist as artifact
+  const root = artifactRoot || path.join(process.cwd(), '.keystone', 'artifacts');
+  const runDir = runId ? path.join(root, runId) : root;
+  mkdirSync(runDir, { recursive: true });
+
+  const artifactPath = path.join(runDir, `blueprint-${hash.substring(0, 8)}.json`);
+  await Bun.write(artifactPath, JSON.stringify(blueprint, null, 2));
+
+  logger.log(`  📦 Blueprint persisted: ${path.relative(process.cwd(), artifactPath)}`);
+
+  return {
+    output: {
+      ...blueprint,
+      __hash: hash,
+      __artifactPath: artifactPath,
+    },
+    status: 'success',
+    usage: llmResult.usage,
+  };
+}

package/src/runner/concurrency-limit.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'bun:test';
+import type { Workflow } from '../parser/schema';
+import { WorkflowRunner } from './workflow-runner';
+
+describe('Workflow Concurrency Integration', () => {
+  const dbPath = ':memory:';
+
+  it('should respect workflow-level concurrency limit', async () => {
+    const workflow: Workflow = {
+      name: 'concurrency-wf',
+      concurrency: 2,
+      steps: [
+        { id: 's1', type: 'sleep', duration: 100, needs: [] },
+        { id: 's2', type: 'sleep', duration: 100, needs: [] },
+        { id: 's3', type: 'sleep', duration: 100, needs: [] },
+        { id: 's4', type: 'sleep', duration: 100, needs: [] },
+      ],
+    } as unknown as Workflow;
+
+    const start = Date.now();
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    await runner.run();
+    const duration = Date.now() - start;
+
+    // Concurrent=2, Total=4 steps, 100ms each -> should take ~200ms
+    // seq=400ms, parallel=100ms.
+    // We expect 200ms <= duration < 250ms
+    expect(duration).toBeGreaterThanOrEqual(200);
+    expect(duration).toBeLessThan(350); // Safe buffer
+  });
+
+  it('should respect pool-level limits', async () => {
+    const workflow: Workflow = {
+      name: 'pool-wf',
+      pools: {
+        slow: 1,
+      },
+      steps: [
+        { id: 's1', type: 'sleep', duration: 100, pool: 'slow', needs: [] },
+        { id: 's2', type: 'sleep', duration: 100, pool: 'slow', needs: [] },
+        { id: 's3', type: 'sleep', duration: 100, needs: [] }, // Default pool (type=sleep)
+        { id: 's4', type: 'sleep', duration: 100, needs: [] }, // Default pool
+      ],
+    } as unknown as Workflow;
+
+    const start = Date.now();
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    await runner.run();
+    const duration = Date.now() - start;
+
+    // 'slow' pool limit 1 -> s1, s2 run sequentially (200ms)
+    // default pool (sleep) limit 10 (default) -> s3, s4 run parallel (100ms)
+    // Overall should take ~200ms
+    expect(duration).toBeGreaterThanOrEqual(200);
+    expect(duration).toBeLessThan(280);
+  });
+
+  it('should respect foreach concurrency limit', async () => {
+    const workflow: Workflow = {
+      name: 'foreach-concurrency-wf',
+      steps: [
+        {
+          id: 'process',
+          type: 'sleep',
+          duration: 50,
+          concurrency: 2,
+          foreach: '${{ [1, 2, 3, 4] }}',
+          needs: [],
+        },
+      ],
+    } as unknown as Workflow;
+
+    const start = Date.now();
+    const runner = new WorkflowRunner(workflow, { dbPath });
+    await runner.run();
+    const duration = Date.now() - start;
+
+    // 4 items, concurrency 2, 50ms each -> ~100ms
+    expect(duration).toBeGreaterThanOrEqual(100);
+    expect(duration).toBeLessThan(180);
+  });
+});