groundswell 0.0.1

package/scripts/generate-llms-full.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env npx tsx
+/**
+ * Generates llms_full.txt by combining:
+ * 1. README.md and its linked markdown documentation files
+ * 2. Examples README and all example source files
+ *
+ * Future-proof design:
+ * - Auto-discovers markdown files linked from README.md (docs/*.md pattern)
+ * - Auto-discovers all example files matching examples/examples/*.ts
+ * - New docs and examples are automatically included without script changes
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT_DIR = path.resolve(__dirname, "..");
+const OUTPUT_FILE = path.join(ROOT_DIR, "llms_full.txt");
+
+interface Section {
+  title: string;
+  content: string;
+  filePath?: string;
+}
+
+function readFile(filePath: string): string {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    console.warn(`Warning: Could not read ${filePath}`);
+    return "";
+  }
+}
+
+function extractMarkdownLinks(content: string, baseDir: string): string[] {
+  // Match markdown links: [text](path.md) - only .md files
+  const linkRegex = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
+  const links: string[] = [];
+  let match;
+
+  while ((match = linkRegex.exec(content)) !== null) {
+    const linkPath = match[2];
+    // Only include relative links (not http/https)
+    if (!linkPath.startsWith("http://") && !linkPath.startsWith("https://")) {
+      const absolutePath = path.resolve(baseDir, linkPath);
+      if (fs.existsSync(absolutePath) && !links.includes(absolutePath)) {
+        links.push(absolutePath);
+      }
+    }
+  }
+
+  return links;
+}
+
+function discoverDocsMarkdown(): string[] {
+  const docsDir = path.join(ROOT_DIR, "docs");
+  if (!fs.existsSync(docsDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(docsDir)
+    .filter((file) => file.endsWith(".md"))
+    .map((file) => path.join(docsDir, file))
+    .sort();
+}
+
+function discoverExamples(): string[] {
+  const examplesDir = path.join(ROOT_DIR, "examples", "examples");
+  if (!fs.existsSync(examplesDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(examplesDir)
+    .filter((file) => file.endsWith(".ts"))
+    .sort() // Sorting ensures NN- prefixed files are in order
+    .map((file) => path.join(examplesDir, file));
+}
+
+function formatSection(section: Section): string {
+  const separator = "=".repeat(80);
+  const relativePath = section.filePath
+    ? path.relative(ROOT_DIR, section.filePath)
+    : "";
+
+  let header = `${separator}\n${section.title}`;
+  if (relativePath) {
+    header += `\nFile: ${relativePath}`;
+  }
+  header += `\n${separator}\n\n`;
+
+  return header + section.content.trim() + "\n\n";
+}
+
+function generateLlmsFull(): void {
+  const sections: Section[] = [];
+  const processedFiles = new Set<string>();
+
+  // 1. Main README
+  const readmePath = path.join(ROOT_DIR, "README.md");
+  const readmeContent = readFile(readmePath);
+  if (readmeContent) {
+    sections.push({
+      title: "PROJECT README",
+      content: readmeContent,
+      filePath: readmePath,
+    });
+    processedFiles.add(readmePath);
+  }
+
+  // 2. Documentation files from docs/ directory
+  // First, get links from README to preserve intended order
+  const linkedDocs = extractMarkdownLinks(readmeContent, ROOT_DIR);
+  // Then discover all docs to catch any not linked
+  const allDocs = discoverDocsMarkdown();
+
+  // Process linked docs first (preserves README order)
+  for (const docPath of linkedDocs) {
+    if (
+      docPath.includes("/docs/") &&
+      !processedFiles.has(docPath) &&
+      fs.existsSync(docPath)
+    ) {
+      const content = readFile(docPath);
+      const fileName = path.basename(docPath, ".md").toUpperCase();
+      sections.push({
+        title: `DOCUMENTATION: ${fileName}`,
+        content,
+        filePath: docPath,
+      });
+      processedFiles.add(docPath);
+    }
+  }
+
+  // Add any docs not linked from README
+  for (const docPath of allDocs) {
+    if (!processedFiles.has(docPath)) {
+      const content = readFile(docPath);
+      const fileName = path.basename(docPath, ".md").toUpperCase();
+      sections.push({
+        title: `DOCUMENTATION: ${fileName}`,
+        content,
+        filePath: docPath,
+      });
+      processedFiles.add(docPath);
+    }
+  }
+
+  // 3. Examples README
+  const examplesReadmePath = path.join(ROOT_DIR, "examples", "README.md");
+  if (fs.existsSync(examplesReadmePath)) {
+    const content = readFile(examplesReadmePath);
+    sections.push({
+      title: "EXAMPLES OVERVIEW",
+      content,
+      filePath: examplesReadmePath,
+    });
+    processedFiles.add(examplesReadmePath);
+  }
+
+  // 4. All example source files
+  const examples = discoverExamples();
+  for (const examplePath of examples) {
+    const content = readFile(examplePath);
+    const fileName = path.basename(examplePath);
+    // Extract example number and name from filename (e.g., "01-basic-workflow.ts")
+    const match = fileName.match(/^(\d+)-(.+)\.ts$/);
+    const exampleName = match
+      ? `Example ${parseInt(match[1])}: ${match[2].replace(/-/g, " ")}`
+      : fileName;
+
+    sections.push({
+      title: `EXAMPLE: ${exampleName.toUpperCase()}`,
+      content,
+      filePath: examplePath,
+    });
+  }
+
+  // Build output
+  const header = `GROUNDSWELL - LLM DOCUMENTATION
+Generated: ${new Date().toISOString()}
+${"=".repeat(80)}
+
+This file contains the complete documentation and examples for the Groundswell project.
+It is auto-generated by scripts/generate-llms-full.ts
+
+Contents:
+${sections.map((s, i) => `  ${i + 1}. ${s.title}`).join("\n")}
+
+`;
+
+  const output =
+    header + sections.map((section) => formatSection(section)).join("\n");
+
+  // Write output
+  fs.writeFileSync(OUTPUT_FILE, output);
+  console.log(`Generated ${path.relative(process.cwd(), OUTPUT_FILE)}`);
+  console.log(`Total sections: ${sections.length}`);
+  console.log(`Total size: ${(output.length / 1024).toFixed(1)} KB`);
+}
+
+// Run
+generateLlmsFull();

package/src/__tests__/integration/agent-workflow.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  Workflow,
+  Prompt,
+  Step,
+  WorkflowObserver,
+  WorkflowEvent,
+  runInContext,
+  type AgentExecutionContext,
+  createEventTreeHandle,
+} from '../../index.js';
+
+// Mock workflow that simulates agent prompt execution within steps
+class MockAgentWorkflow extends Workflow {
+  public events: WorkflowEvent[] = [];
+
+  @Step({ name: 'step1' })
+  async executeStep1(): Promise<string> {
+    return 'step1-result';
+  }
+
+  @Step({ name: 'step2' })
+  async executeStep2(): Promise<string> {
+    return 'step2-result';
+  }
+
+  async run(): Promise<string> {
+    this.setStatus('running');
+    await this.executeStep1();
+    await this.executeStep2();
+    this.setStatus('completed');
+    return 'done';
+  }
+}
+
+describe('Agent-Workflow Integration', () => {
+  it('should establish context in @Step decorated methods', async () => {
+    const workflow = new MockAgentWorkflow('TestWorkflow');
+    const events: WorkflowEvent[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    workflow.addObserver(observer);
+    await workflow.run();
+
+    // Should have step start/end events
+    const stepStarts = events.filter((e) => e.type === 'stepStart');
+    const stepEnds = events.filter((e) => e.type === 'stepEnd');
+
+    expect(stepStarts).toHaveLength(2);
+    expect(stepEnds).toHaveLength(2);
+  });
+
+  it('should track events emitted from within step context', async () => {
+    const emittedEvents: WorkflowEvent[] = [];
+
+    class ContextTrackingWorkflow extends Workflow {
+      @Step({ name: 'tracked-step' })
+      async trackedStep(): Promise<void> {
+        // This simulates what happens when Agent.prompt() is called
+        // The context should be available
+      }
+
+      async run(): Promise<void> {
+        this.setStatus('running');
+        await this.trackedStep();
+        this.setStatus('completed');
+      }
+    }
+
+    const workflow = new ContextTrackingWorkflow('ContextTest');
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => emittedEvents.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    workflow.addObserver(observer);
+    await workflow.run();
+
+    // Verify step events were emitted
+    expect(emittedEvents.some((e) => e.type === 'stepStart')).toBe(true);
+    expect(emittedEvents.some((e) => e.type === 'stepEnd')).toBe(true);
+  });
+
+  it('should support functional workflow pattern with step()', async () => {
+    const events: WorkflowEvent[] = [];
+
+    const workflow = new Workflow<string>({ name: 'FunctionalWorkflow' }, async (ctx) => {
+      await ctx.step('step-a', async () => {
+        return 'a';
+      });
+
+      await ctx.step('step-b', async () => {
+        return 'b';
+      });
+
+      return 'completed';
+    });
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    workflow.addObserver(observer);
+    const result = await workflow.run();
+
+    expect(result).toEqual({
+      data: 'completed',
+      node: expect.any(Object),
+      duration: expect.any(Number),
+    });
+
+    const stepStarts = events.filter((e) => e.type === 'stepStart');
+    const stepEnds = events.filter((e) => e.type === 'stepEnd');
+
+    expect(stepStarts).toHaveLength(2);
+    expect(stepEnds).toHaveLength(2);
+  });
+
+  it('should nest step events under workflow in tree', async () => {
+    const workflow = new Workflow<string>({ name: 'TreeTestWorkflow' }, async (ctx) => {
+      await ctx.step('nested-step', async () => {
+        return 'nested';
+      });
+
+      return 'done';
+    });
+
+    const result = await workflow.run();
+    const node = workflow.getNode();
+
+    // Check that the workflow node has children (the step nodes)
+    expect(node.children.length).toBeGreaterThan(0);
+  });
+
+  it('should propagate context through async boundaries', async () => {
+    let contextWasAvailable = false;
+
+    const workflow = new Workflow<boolean>({ name: 'AsyncContextWorkflow' }, async (ctx) => {
+      await ctx.step('async-step', async () => {
+        // Simulate async operation
+        await new Promise((resolve) => setTimeout(resolve, 10));
+
+        // The context should still be available after async boundary
+        // This is verified by the step completing successfully
+        contextWasAvailable = true;
+        return 'async-result';
+      });
+
+      return contextWasAvailable;
+    });
+
+    const result = await workflow.run();
+    // For functional workflows, result is WorkflowResult<T>
+    expect((result as { data: boolean }).data).toBe(true);
+  });
+
+  it('should create EventTreeHandle from workflow', async () => {
+    const workflow = new Workflow<void>({ name: 'EventTreeWorkflow' }, async (ctx) => {
+      await ctx.step('tree-step', async () => {});
+    });
+
+    await workflow.run();
+
+    const treeHandle = createEventTreeHandle(workflow.getNode());
+    expect(treeHandle.root).toBeDefined();
+    expect(treeHandle.root.name).toBe('EventTreeWorkflow');
+  });
+
+  it('should handle errors in steps', async () => {
+    const events: WorkflowEvent[] = [];
+
+    const workflow = new Workflow<void>({ name: 'ErrorWorkflow' }, async (ctx) => {
+      await ctx.step('failing-step', async () => {
+        throw new Error('Step failed');
+      });
+    });
+
+    const observer: WorkflowObserver = {
+      onLog: () => {},
+      onEvent: (event) => events.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    workflow.addObserver(observer);
+
+    await expect(workflow.run()).rejects.toThrow('Step failed');
+
+    const errorEvents = events.filter((e) => e.type === 'error');
+    // Error is emitted both from the step context and from the workflow
+    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
+    expect(workflow.status).toBe('failed');
+  });
+});
+
+describe('Prompt Integration', () => {
+  it('should create type-safe prompts with Zod schemas', () => {
+    const responseSchema = z.object({
+      answer: z.string(),
+      confidence: z.number().min(0).max(1),
+    });
+
+    const prompt = new Prompt({
+      user: 'What is 2 + 2?',
+      responseFormat: responseSchema,
+    });
+
+    // Valid response
+    const valid = prompt.validateResponse({ answer: '4', confidence: 0.99 });
+    expect(valid).toEqual({ answer: '4', confidence: 0.99 });
+
+    // Invalid response should throw
+    expect(() => prompt.validateResponse({ answer: '4' })).toThrow();
+  });
+
+  it('should support complex nested schemas', () => {
+    const schema = z.object({
+      items: z.array(
+        z.object({
+          id: z.number(),
+          name: z.string(),
+          tags: z.array(z.string()),
+        })
+      ),
+      metadata: z.object({
+        total: z.number(),
+        page: z.number(),
+      }),
+    });
+
+    const prompt = new Prompt({
+      user: 'List items',
+      responseFormat: schema,
+    });
+
+    const result = prompt.validateResponse({
+      items: [{ id: 1, name: 'Item 1', tags: ['a', 'b'] }],
+      metadata: { total: 1, page: 1 },
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.metadata.total).toBe(1);
+  });
+});

package/src/__tests__/integration/tree-mirroring.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import {
+  TDDOrchestrator,
+  WorkflowTreeDebugger,
+  WorkflowEvent,
+  WorkflowObserver,
+} from '../../index.js';
+
+describe('Tree Mirroring Integration', () => {
+  it('should create 1:1 tree mirror of workflow execution', async () => {
+    const orchestrator = new TDDOrchestrator('TDDOrchestrator');
+    (orchestrator as any).maxCycles = 1; // Limit to one cycle for test
+
+    const debugger_ = new WorkflowTreeDebugger(orchestrator);
+    const events: WorkflowEvent[] = [];
+
+    debugger_.events.subscribe({
+      next: (event) => events.push(event),
+    });
+
+    try {
+      await orchestrator.run();
+    } catch {
+      // May fail due to random test failures, that's ok
+    }
+
+    // Verify tree structure
+    const tree = debugger_.getTree();
+    expect(tree.name).toBe('TDDOrchestrator');
+
+    // Should have at least one child (the cycle)
+    expect(tree.children.length).toBeGreaterThanOrEqual(1);
+
+    // Child should be named Cycle-N
+    const cycleChild = tree.children.find((c) => c.name.startsWith('Cycle-'));
+    expect(cycleChild).toBeDefined();
+
+    // Verify events were captured
+    expect(events.some((e) => e.type === 'stepStart')).toBe(true);
+    expect(events.some((e) => e.type === 'taskStart')).toBe(true);
+  });
+
+  it('should propagate events to root observer', async () => {
+    const orchestrator = new TDDOrchestrator('Root');
+    (orchestrator as any).maxCycles = 1;
+
+    const allEvents: WorkflowEvent[] = [];
+    const allLogs: any[] = [];
+
+    const observer: WorkflowObserver = {
+      onLog: (entry) => allLogs.push(entry),
+      onEvent: (event) => allEvents.push(event),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    };
+
+    orchestrator.addObserver(observer);
+
+    try {
+      await orchestrator.run();
+    } catch {
+      // May fail
+    }
+
+    // Events from child workflows should reach root
+    expect(allLogs.length).toBeGreaterThan(0);
+    expect(allEvents.length).toBeGreaterThan(0);
+
+    // Should have events from both parent and child
+    const parentEvents = allEvents.filter(
+      (e) => 'node' in e && e.node.name === 'Root'
+    );
+    const childEvents = allEvents.filter(
+      (e) => 'node' in e && e.node.name.startsWith('Cycle-')
+    );
+
+    expect(parentEvents.length).toBeGreaterThan(0);
+    expect(childEvents.length).toBeGreaterThan(0);
+  });
+
+  it('should include state snapshot on error', async () => {
+    const orchestrator = new TDDOrchestrator('ErrorTest');
+    (orchestrator as any).maxCycles = 1;
+
+    const errorEvents: WorkflowEvent[] = [];
+
+    orchestrator.addObserver({
+      onLog: () => {},
+      onEvent: (event) => {
+        if (event.type === 'error') {
+          errorEvents.push(event);
+        }
+      },
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    });
+
+    try {
+      await orchestrator.run();
+    } catch {
+      // Expected
+    }
+
+    // If there was an error, it should have state
+    if (errorEvents.length > 0) {
+      const errEvent = errorEvents[0];
+      if (errEvent.type === 'error') {
+        expect(errEvent.error.state).toBeDefined();
+        expect(errEvent.error.logs).toBeDefined();
+        expect(errEvent.error.workflowId).toBeDefined();
+      }
+    }
+  });
+});