groundswell 0.0.1 → 0.0.3

package/scripts/generate-llms-full.ts

@@ -1,206 +0,0 @@
-#!/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

@@ -1,256 +0,0 @@
-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

@@ -1,114 +0,0 @@
-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();
-      }
-    }
-  });
-});