@soleri/core 9.7.2 → 9.9.0

package/src/workflows/orchestrate-integration.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { applyWorkflowOverride } from '../runtime/orchestrate-ops.js';
+import type { OrchestrationPlan, PlanStep } from '../flows/types.js';
+import type { WorkflowOverride } from './workflow-loader.js';
+
+function makePlan(steps: PlanStep[]): OrchestrationPlan {
+  return {
+    planId: 'test-plan-1',
+    intent: 'BUILD',
+    flowId: 'BUILD-flow',
+    steps,
+    skipped: [],
+    epilogue: ['capture_knowledge'],
+    warnings: [],
+    summary: 'Test plan',
+    estimatedTools: steps.reduce((acc, s) => acc + s.tools.length, 0),
+    context: {
+      intent: 'BUILD',
+      probes: {
+        vault: true,
+        brain: false,
+        designSystem: false,
+        sessionStore: true,
+        projectRules: false,
+        active: true,
+      },
+      entities: { components: [], actions: [] },
+      projectPath: '.',
+    },
+  };
+}
+
+function makeStep(id: string, tools: string[] = []): PlanStep {
+  return {
+    id,
+    name: id,
+    tools,
+    parallel: false,
+    requires: [],
+    status: 'pending',
+  };
+}
+
+describe('applyWorkflowOverride', () => {
+  it('merges gates into matching plan steps', () => {
+    const plan = makePlan([
+      makeStep('pre-execution-vault-search', ['vault_search']),
+      makeStep('completion-capture', ['capture_knowledge']),
+    ]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [
+        {
+          phase: 'pre-execution',
+          requirement: 'Plan approved by user',
+          check: 'plan-approved',
+        },
+        {
+          phase: 'completion',
+          requirement: 'Knowledge captured',
+          check: 'knowledge-captured',
+        },
+      ],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // Gates should be attached to matching steps
+    expect(plan.steps[0].gate).toBeDefined();
+    expect(plan.steps[0].gate!.type).toBe('GATE');
+    expect(plan.steps[0].gate!.condition).toBe('Plan approved by user');
+
+    expect(plan.steps[1].gate).toBeDefined();
+    expect(plan.steps[1].gate!.condition).toBe('Knowledge captured');
+  });
+
+  it('appends unmatched gates as new steps', () => {
+    const plan = makePlan([makeStep('vault-search', ['vault_search'])]);
+
+    const override: WorkflowOverride = {
+      name: 'bug-fix',
+      gates: [
+        {
+          phase: 'post-task',
+          requirement: 'All tests pass',
+          check: 'tests-pass',
+        },
+      ],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // Original step untouched
+    expect(plan.steps[0].gate).toBeUndefined();
+
+    // New gate step appended
+    expect(plan.steps).toHaveLength(2);
+    expect(plan.steps[1].id).toBe('workflow-gate-post-task');
+    expect(plan.steps[1].gate!.condition).toBe('All tests pass');
+  });
+
+  it('merges tools into all plan steps (deduplicated)', () => {
+    const plan = makePlan([makeStep('step1', ['existing_tool']), makeStep('step2', [])]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [],
+      tools: ['soleri_vault op:search_intelligent', 'existing_tool'],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // step1 already had existing_tool — should not duplicate
+    expect(plan.steps[0].tools).toEqual(['existing_tool', 'soleri_vault op:search_intelligent']);
+    // step2 gets the tools
+    expect(plan.steps[1].tools).toEqual(['soleri_vault op:search_intelligent', 'existing_tool']);
+    // estimatedTools updated
+    expect(plan.estimatedTools).toBe(plan.steps.reduce((acc, s) => acc + s.tools.length, 0));
+  });
+
+  it('does nothing when override has no gates or tools', () => {
+    const plan = makePlan([makeStep('step1', ['t1'])]);
+    const originalSteps = plan.steps.length;
+    const originalTools = plan.steps[0].tools.length;
+
+    const override: WorkflowOverride = {
+      name: 'empty',
+      gates: [],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    expect(plan.steps).toHaveLength(originalSteps);
+    expect(plan.steps[0].tools).toHaveLength(originalTools);
+    // Warning still added
+    expect(plan.warnings).toContain('Workflow override "empty" applied (0 gate(s), 0 tool(s)).');
+  });
+
+  it('plan remains unchanged when no workflow matches', () => {
+    // This tests the calling code path — if getWorkflowForIntent returns null,
+    // applyWorkflowOverride is never called
+    const plan = makePlan([makeStep('step1', ['t1'])]);
+    expect(plan.warnings).toHaveLength(0);
+    expect(plan.steps[0].gate).toBeUndefined();
+  });
+
+  it('adds info warning about applied override', () => {
+    const plan = makePlan([makeStep('step1')]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [{ phase: 'pre', requirement: 'ok', check: 'go' }],
+      tools: ['tool1', 'tool2'],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    expect(plan.warnings).toContain(
+      'Workflow override "feature-dev" applied (1 gate(s), 2 tool(s)).',
+    );
+  });
+});

package/src/workflows/workflow-loader.test.ts

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadAgentWorkflows, getWorkflowForIntent, WORKFLOW_TO_INTENT } from './workflow-loader.js';
+import type { WorkflowOverride } from './workflow-loader.js';
+
+vi.mock('node:fs', () => ({
+  default: {
+    readdirSync: vi.fn(),
+    statSync: vi.fn(),
+    readFileSync: vi.fn(),
+  },
+}));
+
+describe('workflow-loader', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('loadAgentWorkflows', () => {
+    it('returns empty map when directory does not exist', () => {
+      (fs.readdirSync as ReturnType<typeof vi.fn>).mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+
+      const result = loadAgentWorkflows('/nonexistent/workflows');
+      expect(result.size).toBe(0);
+    });
+
+    it('loads gates and tools from workflow folder', () => {
+      (fs.readdirSync as ReturnType<typeof vi.fn>).mockReturnValue(['feature-dev']);
+      (fs.statSync as ReturnType<typeof vi.fn>).mockReturnValue({ isDirectory: () => true });
+      (fs.readFileSync as ReturnType<typeof vi.fn>).mockImplementation((filePath: string) => {
+        if (filePath.endsWith('prompt.md')) {
+          return '# Feature Dev\nBuild new features.';
+        }
+        if (filePath.endsWith('gates.yaml')) {
+          return `gates:
+  - phase: pre-execution
+    requirement: Plan approved
+    check: plan-approved
+  - phase: completion
+    requirement: Tests pass
+    check: tests-pass
+`;
+        }
+        if (filePath.endsWith('tools.yaml')) {
+          return `tools:
+  - soleri_vault op:search_intelligent
+  - soleri_plan op:create_plan
+`;
+        }
+        throw new Error('ENOENT');
+      });
+
+      const result = loadAgentWorkflows('/agent/workflows');
+      expect(result.size).toBe(1);
+
+      const workflow = result.get('feature-dev')!;
+      expect(workflow.name).toBe('feature-dev');
+      expect(workflow.prompt).toBe('# Feature Dev\nBuild new features.');
+      expect(workflow.gates).toHaveLength(2);
+      expect(workflow.gates[0]).toEqual({
+        phase: 'pre-execution',
+        requirement: 'Plan approved',
+        check: 'plan-approved',
+      });
+      expect(workflow.gates[1]).toEqual({
+        phase: 'completion',
+        requirement: 'Tests pass',
+        check: 'tests-pass',
+      });
+      expect(workflow.tools).toEqual([
+        'soleri_vault op:search_intelligent',
+        'soleri_plan op:create_plan',
+      ]);
+    });
+
+    it('skips non-directory entries', () => {
+      (fs.readdirSync as ReturnType<typeof vi.fn>).mockReturnValue(['README.md']);
+      (fs.statSync as ReturnType<typeof vi.fn>).mockReturnValue({ isDirectory: () => false });
+
+      const result = loadAgentWorkflows('/agent/workflows');
+      expect(result.size).toBe(0);
+    });
+
+    it('skips workflow folders with no content', () => {
+      (fs.readdirSync as ReturnType<typeof vi.fn>).mockReturnValue(['empty-workflow']);
+      (fs.statSync as ReturnType<typeof vi.fn>).mockReturnValue({ isDirectory: () => true });
+      (fs.readFileSync as ReturnType<typeof vi.fn>).mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+
+      const result = loadAgentWorkflows('/agent/workflows');
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe('getWorkflowForIntent', () => {
+    it('returns matching workflow for BUILD intent', () => {
+      const workflows = new Map<string, WorkflowOverride>([
+        ['feature-dev', { name: 'feature-dev', gates: [], tools: ['tool1'] }],
+      ]);
+
+      const result = getWorkflowForIntent(workflows, 'BUILD');
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe('feature-dev');
+    });
+
+    it('returns null when no matching workflow', () => {
+      const workflows = new Map<string, WorkflowOverride>([
+        ['feature-dev', { name: 'feature-dev', gates: [], tools: ['tool1'] }],
+      ]);
+
+      const result = getWorkflowForIntent(workflows, 'EXPLORE');
+      expect(result).toBeNull();
+    });
+
+    it('uses custom mapping when provided', () => {
+      const workflows = new Map<string, WorkflowOverride>([
+        ['my-custom', { name: 'my-custom', gates: [], tools: ['t1'] }],
+      ]);
+
+      const result = getWorkflowForIntent(workflows, 'DESIGN', {
+        'my-custom': 'DESIGN',
+      });
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe('my-custom');
+    });
+
+    it('is case-insensitive for intent', () => {
+      const workflows = new Map<string, WorkflowOverride>([
+        ['bug-fix', { name: 'bug-fix', gates: [], tools: [] }],
+      ]);
+
+      // bug-fix maps to FIX in WORKFLOW_TO_INTENT
+      const result = getWorkflowForIntent(workflows, 'fix');
+      expect(result).not.toBeNull();
+      expect(result!.name).toBe('bug-fix');
+    });
+  });
+
+  describe('WORKFLOW_TO_INTENT', () => {
+    it('maps known workflow names to intents', () => {
+      expect(WORKFLOW_TO_INTENT['feature-dev']).toBe('BUILD');
+      expect(WORKFLOW_TO_INTENT['bug-fix']).toBe('FIX');
+      expect(WORKFLOW_TO_INTENT['code-review']).toBe('REVIEW');
+    });
+  });
+});

package/src/workflows/workflow-loader.ts

@@ -0,0 +1,238 @@
+/**
+ * Workflow loader — reads agent workflow overrides from the file tree.
+ *
+ * Each workflow is a folder under `workflows/` containing:
+ *   - `prompt.md`  — system prompt for the workflow (optional)
+ *   - `gates.yaml` — gate definitions (optional)
+ *   - `tools.yaml` — tool allowlist (optional)
+ *
+ * These overrides are merged into the OrchestrationPlan when
+ * the detected intent matches a workflow via WORKFLOW_TO_INTENT.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export const WorkflowGateSchema = z.object({
+  phase: z.string(),
+  requirement: z.string(),
+  check: z.string(),
+});
+
+export const WorkflowOverrideSchema = z.object({
+  name: z.string(),
+  prompt: z.string().optional(),
+  gates: z.array(WorkflowGateSchema).default([]),
+  tools: z.array(z.string()).default([]),
+});
+
+export type WorkflowGate = z.infer<typeof WorkflowGateSchema>;
+export type WorkflowOverride = z.infer<typeof WorkflowOverrideSchema>;
+
+// ---------------------------------------------------------------------------
+// Workflow → Intent mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps workflow folder names to intent strings.
+ * Used by `getWorkflowForIntent()` to find a matching workflow.
+ */
+export const WORKFLOW_TO_INTENT: Record<string, string> = {
+  'feature-dev': 'BUILD',
+  'bug-fix': 'FIX',
+  'code-review': 'REVIEW',
+  'component-build': 'BUILD',
+  'token-migration': 'ENHANCE',
+  'a11y-remediation': 'FIX',
+};
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load all workflow overrides from an agent's `workflows/` directory.
+ *
+ * Returns an empty Map if the directory doesn't exist or can't be read
+ * (graceful degradation — no throw).
+ */
+export function loadAgentWorkflows(workflowsDir: string): Map<string, WorkflowOverride> {
+  const workflows = new Map<string, WorkflowOverride>();
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(workflowsDir);
+  } catch {
+    // Directory doesn't exist or can't be read — that's fine
+    return workflows;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(workflowsDir, entry);
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(fullPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    const override: WorkflowOverride = { name: entry, gates: [], tools: [] };
+
+    // Read prompt.md
+    const promptPath = path.join(fullPath, 'prompt.md');
+    try {
+      override.prompt = fs.readFileSync(promptPath, 'utf-8').trim();
+    } catch {
+      // No prompt — that's fine
+    }
+
+    // Read gates.yaml
+    const gatesPath = path.join(fullPath, 'gates.yaml');
+    try {
+      const raw = fs.readFileSync(gatesPath, 'utf-8');
+      // Simple YAML parsing for the gates structure
+      const gates = parseGatesYaml(raw);
+      override.gates = gates;
+    } catch {
+      // No gates — that's fine
+    }
+
+    // Read tools.yaml
+    const toolsPath = path.join(fullPath, 'tools.yaml');
+    try {
+      const raw = fs.readFileSync(toolsPath, 'utf-8');
+      const tools = parseToolsYaml(raw);
+      override.tools = tools;
+    } catch {
+      // No tools — that's fine
+    }
+
+    // Only store if we got something useful
+    if (override.prompt || override.gates.length > 0 || override.tools.length > 0) {
+      workflows.set(entry, override);
+    }
+  }
+
+  return workflows;
+}
+
+// ---------------------------------------------------------------------------
+// Intent matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a workflow override that matches the given intent.
+ *
+ * Uses WORKFLOW_TO_INTENT mapping, optionally overridden by customMapping.
+ * Returns null if no matching workflow is found.
+ */
+export function getWorkflowForIntent(
+  workflows: Map<string, WorkflowOverride>,
+  intent: string,
+  customMapping?: Record<string, string>,
+): WorkflowOverride | null {
+  const mapping = customMapping ?? WORKFLOW_TO_INTENT;
+  const normalizedIntent = intent.toUpperCase();
+
+  for (const [workflowName, mappedIntent] of Object.entries(mapping)) {
+    if (mappedIntent.toUpperCase() === normalizedIntent && workflows.has(workflowName)) {
+      return workflows.get(workflowName)!;
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Minimal YAML parsers (no external dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a simple gates.yaml file. Expected format:
+ *
+ * ```yaml
+ * gates:
+ *   - phase: brainstorming
+ *     requirement: Requirements are clear
+ *     check: user-approval
+ * ```
+ */
+function parseGatesYaml(raw: string): WorkflowGate[] {
+  const gates: WorkflowGate[] = [];
+  const lines = raw.split('\n');
+
+  let current: Partial<WorkflowGate> | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and the root "gates:" key
+    if (!trimmed || trimmed === 'gates:') continue;
+
+    // New list item
+    if (trimmed.startsWith('- ')) {
+      if (current && current.phase && current.requirement && current.check) {
+        gates.push(current as WorkflowGate);
+      }
+      current = {};
+      // Parse inline key from "- phase: value"
+      const inlineMatch = trimmed.match(/^-\s+(\w+):\s*(.+)$/);
+      if (inlineMatch) {
+        const [, key, value] = inlineMatch;
+        if (key === 'phase' || key === 'requirement' || key === 'check') {
+          current[key] = value.trim();
+        }
+      }
+      continue;
+    }
+
+    // Continuation key: "    requirement: value"
+    if (current) {
+      const kvMatch = trimmed.match(/^(\w+):\s*(.+)$/);
+      if (kvMatch) {
+        const [, key, value] = kvMatch;
+        if (key === 'phase' || key === 'requirement' || key === 'check') {
+          current[key] = value.trim();
+        }
+      }
+    }
+  }
+
+  // Flush last entry
+  if (current && current.phase && current.requirement && current.check) {
+    gates.push(current as WorkflowGate);
+  }
+
+  return gates;
+}
+
+/**
+ * Parse a simple tools.yaml file. Expected format:
+ *
+ * ```yaml
+ * tools:
+ *   - soleri_vault op:search_intelligent
+ *   - soleri_plan op:create_plan
+ * ```
+ */
+function parseToolsYaml(raw: string): string[] {
+  const tools: string[] = [];
+  const lines = raw.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed === 'tools:') continue;
+
+    if (trimmed.startsWith('- ')) {
+      tools.push(trimmed.slice(2).trim());
+    }
+  }
+
+  return tools;
+}