@synergenius/flow-weaver 0.2.1 → 0.3.0

package/README.md

@@ -3,290 +3,350 @@
 [![License: ELv2-based](https://img.shields.io/badge/License-ELv2--based-blue.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 
-TypeScript annotation-based workflow compiler for Flow Weaver.
+**Workflow compiler for AI agents.** LLMs create, validate, iterate, and test workflows programmatically. Humans review them visually. Compiled output is standalone TypeScript with no runtime dependencies.
 
-Build visual workflows using JSDoc annotations and TypeScript function signatures. Full type safety, IDE autocomplete, and instant validation.
+Flow Weaver turns standard TypeScript functions into executable workflow graphs using JSDoc annotations. No YAML. No JSON configs. No drag-and-drop. Just TypeScript with full type safety, IDE autocomplete, and compile-time validation, in a format LLMs can read and write directly. Compiled output runs anywhere with no dependency on Flow Weaver.
 
-## Table of Contents
+## Why Flow Weaver?
 
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [API](#api)
-- [Exports](#exports)
-- [CLI Reference](#cli-reference)
-- [STEP Port Architecture](#step-port-architecture)
-- [Annotations](#annotations)
-- [Deployment](#deployment)
-- [MCP Integration](#mcp-integration)
-- [API Documentation](#api-documentation)
-- [Testing](#testing)
-- [Development](#development)
-- [License](#license)
+**Agents generate code well. They don't generate reliable systems.**
 
-## Installation
+With Flow Weaver, an agent builds a typed workflow graph instead of a monolithic script. Every connection is type-checked, every required input is enforced, every error path is explicit.
+
+The development loop (steps 1-4 are fully autonomous):
+
+1. **Agent creates**: scaffolds from templates or builds from scratch via 35+ MCP tools
+2. **Compiler validates**: 15+ validation passes catch missing connections, type mismatches, unreachable paths
+3. **Agent iterates**: validation errors include fix suggestions, the agent corrects and re-validates until clean
+4. **Agent tests**: deterministic mock providers for reproducible testing without real API calls
+5. **Human reviews**: visual editor renders the workflow as an interactive graph for final approval
+
+The compiled code is yours. No runtime lock-in, no framework dependency.
+
+## Quick Start
+
+### Install
 
 ```bash
 npm install @synergenius/flow-weaver
 ```
 
-## Quick Start
+### Define a workflow
 
-Create a workflow file (any `.ts`, `.tsx`, `.js`, or `.jsx` file works):
+Workflows are plain TypeScript. Annotations declare the graph structure:
 
 ```typescript
-// math-workflow.ts
+// data-pipeline.ts
 
 /**
  * @flowWeaver nodeType
- * @input x
- * @input y
- * @output result
+ * @input rawData - string
+ * @output cleaned - string
+ * @output wordCount - number
  */
-function multiply(execute: boolean, x: number, y: number) {
-  if (!execute) return { onSuccess: false, onFailure: false, result: 0 };
-  return { onSuccess: true, onFailure: false, result: x * y };
+function processText(execute: boolean, rawData: string) {
+  if (!execute) return { onSuccess: false, onFailure: false, cleaned: '', wordCount: 0 };
+  const cleaned = rawData.trim().toLowerCase();
+  return { onSuccess: true, onFailure: false, cleaned, wordCount: cleaned.split(/\s+/).length };
 }
 
 /**
  * @flowWeaver workflow
- * @node multiplier multiply
- * @connect Start.x -> multiplier.x
- * @connect Start.y -> multiplier.y
- * @connect multiplier.result -> Exit.result
+ * @node processor processText
+ * @connect Start.rawData -> processor.rawData
+ * @connect processor.cleaned -> Exit.cleaned
+ * @connect processor.wordCount -> Exit.wordCount
  */
-export async function multiplyWorkflow(
+export async function dataPipeline(
   execute: boolean,
-  params: { x: number; y: number }
-): Promise<{ onSuccess: boolean; onFailure: boolean; result: number }> {
-  throw new Error('Not implemented');
+  params: { rawData: string }
+): Promise<{ onSuccess: boolean; onFailure: boolean; cleaned: string; wordCount: number }> {
+  throw new Error('Not compiled');
 }
 ```
 
-Compile:
+### Compile and run
 
 ```bash
-npx flow-weaver compile math-workflow.ts
+npx flow-weaver compile data-pipeline.ts    # generates executable code in-place
+npx flow-weaver run data-pipeline.ts --params '{"rawData": "Hello World"}'
 ```
 
-## API
+The compiler fills in the function body while preserving your code outside the generated markers.
 
-```typescript
-import {
-  parseWorkflow,      // Parse workflow file to AST
-  compileWorkflow,    // Parse + generate in one step
-  validateWorkflow,   // Validate AST
-  generateCode,       // Generate code from AST
-} from '@synergenius/flow-weaver';
+## AI-Native Development with MCP
 
-// Parse and compile
-const { code } = await compileWorkflow('workflow.ts');
+Flow Weaver includes an MCP server with 35+ tools for Claude Code (or any MCP-compatible agent):
 
-// Or step by step
-const { ast } = await parseWorkflow('workflow.ts');
-const code = generateCode(ast);
+```bash
+npx flow-weaver mcp-server    # auto-registers with Claude Code
 ```
 
-Additional APIs: `compileWorkflows()`, `compilePattern()`, `generateInPlace()`. See [API documentation](#api-documentation) for details.
+What an AI agent can do:
 
-## Exports
+| Capability | MCP Tools |
+|-----------|-----------|
+| **Build** | `fw_scaffold`, `fw_modify`, `fw_modify_batch`, `fw_add_node`, `fw_connect` |
+| **Validate** | `fw_validate` (with friendly error hints), `fw_doctor` |
+| **Understand** | `fw_describe` (json/text/mermaid), `fw_query` (10 query types), `fw_diff` |
+| **Test** | `fw_execute_workflow` (with trace), `fw_compile` |
+| **Visualize** | `fw_diagram` (SVG), `fw_get_state`, `fw_focus_node` |
+| **Deploy** | `fw_export` (Lambda, Vercel, Cloudflare, Inngest), `fw_compile --target inngest` |
+| **Reuse** | `fw_list_patterns`, `fw_apply_pattern`, `fw_extract_pattern` |
+| **Extend** | `fw_market_search`, `fw_market_install` |
 
-| Import Path | Purpose |
-|-------------|---------|
-| `@synergenius/flow-weaver` | Main — parse, validate, compile, generate, AST types, builders, diff, JSDoc sync |
-| `@synergenius/flow-weaver/runtime` | Execution context & errors for generated code |
-| `@synergenius/flow-weaver/built-in-nodes` | Built-in workflow nodes (delay, waitForEvent, invokeWorkflow) |
-| `@synergenius/flow-weaver/diagram` | Workflow diagram layout and rendering |
-| `@synergenius/flow-weaver/describe` | Programmatic workflow description (structure, nodes, paths) |
+The agent reads validation errors, fixes issues, and re-validates until the workflow compiles clean.
 
-## CLI Reference
+## Agent Workflow Templates
 
-### Core Commands
+Built-in templates for AI agent workflows (LLM reasoning, tool calling, looping):
 
 ```bash
-flow-weaver compile <file>              # Compile workflow files
-  --production                          # Production mode (no debug events)
-  --watch                               # Recompile on changes
-  --dry-run                             # Preview without writing
-  --optimize                            # Optimize workflow compilation
-  --strict                              # Strict validation mode
-  --source-map                          # Generate source maps
-  --format esm|cjs|auto                 # Output module format
-
-flow-weaver validate <file>             # Validate without compiling
-  --verbose | --quiet | --json          # Output format
-  --strict                              # Strict type checking
-
-flow-weaver run <file>                  # Execute a workflow
-  --params '{"key":"val"}'              # Input parameters (JSON)
-  --params-file params.json             # Parameters from file
-  --production                          # Production mode
-  --trace                               # Include execution trace
-  --timeout 30000                       # Execution timeout (ms)
-
-flow-weaver dev <file>                  # Watch + compile + run
-  --params '{"key":"val"}'              # Input parameters
-  --once                                # Run once then exit
-
-flow-weaver watch <file>                # Watch and recompile
-flow-weaver describe <file>             # Output structure
-  --format json|text|mermaid|paths      # Output format
-  --node <id>                           # Focus on specific node
-flow-weaver diagram <file>              # Generate SVG diagram
-  --theme dark|light                    # Color theme (default: dark)
-  --width <pixels>                      # SVG width
-  --no-port-labels                      # Hide port data type labels
-  -o, --output <file>                   # Write to file (default: stdout)
-flow-weaver diff <f1> <f2>              # Semantic comparison
-  --format text|json|compact            # Output format
-```
+# Scaffold a tool-calling agent with memory and error handling
+npx flow-weaver create workflow ai-agent my-agent.ts --provider openai --model gpt-4o
 
-### Project Setup
+# ReAct pattern (Thought -> Action -> Observation loop)
+npx flow-weaver create workflow ai-react react-agent.ts
 
-```bash
-flow-weaver init [directory]            # Create new project
-  --template <name>                     # Project template
-  --yes                                 # Accept defaults
-flow-weaver create workflow <tmpl> <f>  # Scaffold workflow from template
-flow-weaver create node <name> <file>   # Scaffold node type
-flow-weaver templates                   # List available templates
-flow-weaver doctor                      # Check project compatibility
-flow-weaver grammar                     # Output annotation grammar (EBNF/railroad)
+# RAG pipeline (Retrieve -> Augment -> Generate)
+npx flow-weaver create workflow ai-rag rag-pipeline.ts
+
+# Durable agent with per-step retries (compiles to Inngest)
+npx flow-weaver create workflow ai-agent-durable durable-agent.ts
 ```
 
-### Deployment
+**12 workflow templates** cover common patterns:
 
-```bash
-flow-weaver serve [directory]           # HTTP server for workflows
-  --port 3000                           # Server port
-  --swagger                             # Enable Swagger UI at /docs
-  --production                          # Production mode
-flow-weaver export <file>               # Serverless export
-  --target lambda|vercel|cloudflare     # Deployment target
-  --multi                               # Multi-workflow service
-  --docs                                # Include OpenAPI routes
-flow-weaver openapi <directory>         # Generate OpenAPI spec
-  --format json|yaml                    # Output format
-```
+| Template | What it builds |
+|----------|---------------|
+| `ai-agent` | Tool-calling agent with explicit loop and termination semantics |
+| `ai-react` | ReAct agent (Thought -> Action -> Observation) |
+| `ai-rag` | Retrieval-Augmented Generation pipeline |
+| `ai-chat` | Stateful conversational AI with memory |
+| `ai-agent-durable` | Durable agent pipeline with Inngest step-level retries |
+| `ai-pipeline-durable` | Multi-step AI pipeline with durability |
+| `sequential` | Linear data pipeline |
+| `foreach` | Iteration over collections |
+| `conditional` | Branching logic |
+| `aggregator` | Multi-source aggregation |
+| `webhook` | HTTP event handler |
+| `error-handler` | Error recovery pattern |
 
-### Patterns and Migration
+**12 node templates** for common node types: `llm-call`, `tool-executor`, `conversation-memory`, `prompt-template`, `json-extractor`, `human-approval`, `agent-router`, `rag-retriever`, `validator`, `transformer`, `http`, `aggregator`.
 
-```bash
-flow-weaver pattern list <path>         # List patterns in file
-flow-weaver pattern apply <pat> <tgt>   # Apply pattern to workflow
-flow-weaver pattern extract <source>    # Extract pattern from nodes
-flow-weaver migrate <glob>              # Migrate to current syntax
-  --dry-run                             # Preview changes
-  --diff                                # Show changes
-flow-weaver changelog                   # Generate changelog from git
-```
+## Agent-Aware Validation
 
-### IDE Integration
+The validator understands AI agent patterns and enforces safety rules:
 
-```bash
-flow-weaver mcp-server                  # Start MCP server for Claude Code
-flow-weaver listen                      # Stream editor events (JSON lines)
-flow-weaver plugin init <name>          # Scaffold external plugin
-flow-weaver ui focus-node <id>          # Focus node in editor
-flow-weaver ui add-node <type>          # Add node to editor
-flow-weaver ui open-workflow <path>     # Open workflow file
-flow-weaver ui get-state                # Get editor state
-flow-weaver ui batch <json>             # Batch editor commands
+```
+AGENT_LLM_MISSING_ERROR_HANDLER    LLM node's onFailure is unconnected — add error handling
+AGENT_UNGUARDED_TOOL_EXECUTOR      Tool executor has no human-approval upstream — add a gate
+AGENT_MISSING_MEMORY_IN_LOOP       Agent loop has LLM but no memory — conversations will be stateless
+AGENT_LLM_NO_FALLBACK              LLM failure goes directly to Exit — add retry or fallback logic
+AGENT_TOOL_NO_OUTPUT_HANDLING      Tool executor outputs are all unconnected — results are discarded
 ```
 
-## STEP Port Architecture
+Not generic lint rules. The validator identifies LLM, tool-executor, human-approval, and memory nodes by port signatures, annotations, and naming patterns, then applies agent-specific checks.
 
-All nodes follow this pattern:
+## Deterministic Agent Testing
 
-```typescript
-function nodeName(
-  execute: boolean,    // Control input
-  ...inputs            // Data inputs
-): {
-  onSuccess: boolean;  // Success control output
-  onFailure: boolean;  // Failure control output
-  ...outputs           // Data outputs
-}
-```
+Test LLM workflows without real API calls:
 
-Expression nodes (`@expression`) skip the control flow boilerplate — inputs and outputs are inferred from the TypeScript signature.
+```typescript
+import { createMockLlmProvider, createRecordingProvider, loadRecording } from '@synergenius/flow-weaver/testing';
 
-## Annotations
+// Mock: deterministic responses for CI
+const mock = createMockLlmProvider([
+  { content: 'I need to search for that.', toolCalls: [{ name: 'search', args: { q: 'test' } }] },
+  { content: 'Based on the results, the answer is 42.' },
+]);
 
-### @flowWeaver nodeType
+// Record: capture real LLM calls, replay later
+const recorder = createRecordingProvider(realProvider);
+// ... run workflow ...
+saveRecording(recorder.getRecording(), 'fixtures/agent-session.json');
 
-```typescript
-/**
- * @flowWeaver nodeType
- * @input value
- * @output result
- * @label Double
- * @pullExecution execute
- */
+// Replay: reproducible tests from recorded sessions
+const replay = loadRecording('fixtures/agent-session.json');
 ```
 
-### @flowWeaver workflow
+Mock human approvals, fast-forward delays, and simulate external events. Configured via `globalThis.__fw_mock_config__`.
+
+## Scoped Ports: Agent Loops Without Cycles
+
+Most workflow engines either ban loops (DAG-only) or allow arbitrary cycles (hard to reason about). Flow Weaver uses **scoped ports** to express iteration without graph cycles:
 
 ```typescript
 /**
  * @flowWeaver workflow
- * @node instance1 nodeType
- * @connect Start.input -> instance1.value
- * @connect instance1.result -> Exit.output
- * @path Start -> n1 -> n2 -> Exit
- * @path n1:fail -> errorHandler -> Exit
+ * @node agent llmCall
+ * @node tools toolExecutor
+ * @node memory conversationMemory
+ * @scope agent, tools, memory           // these nodes iterate together
+ * @connect agent.toolCalls -> tools.calls
+ * @connect tools.results -> memory.input
+ * @connect memory.history -> agent.context
  */
 ```
 
-## Deployment
+The scope's output ports become callback parameters, and input ports become return values. This enables:
+- Agent reasoning loops (LLM -> tools -> memory -> LLM)
+- ForEach over collections
+- Map/reduce patterns
+- Nested sub-workflows
 
-### HTTP Server
+All while keeping the graph acyclic and statically analyzable.
+
+## Multi-Target Compilation
+
+Same workflow source, multiple deployment targets:
 
 ```bash
-flow-weaver serve ./workflows --swagger --port 3000
+# Plain TypeScript (default)
+flow-weaver compile workflow.ts
+
+# Inngest durable functions (per-node step.run, retries, cron)
+flow-weaver compile workflow.ts --target inngest --retries 3 --cron "0 9 * * *"
+
+# Serverless exports
+flow-weaver export workflow.ts --target lambda --output deploy/
+flow-weaver export workflow.ts --target vercel --output deploy/
+flow-weaver export workflow.ts --target cloudflare --output deploy/
+
+# HTTP server with OpenAPI docs
+flow-weaver serve ./workflows --port 3000 --swagger
 ```
 
-Serves all workflows as HTTP endpoints with optional Swagger UI at `/docs`.
+Inngest compilation wraps each node in `step.run()` for individual durability, parallelizes independent nodes with `Promise.all()`, and generates typed Zod event schemas.
+
+## Visual Human-in-the-Loop
 
-### Serverless Export
+Workflows compile from code, but humans review them visually:
 
 ```bash
-# AWS Lambda (generates SAM template + handler)
-flow-weaver export workflow.ts --target lambda --output deploy/
+# Generate SVG diagram
+flow-weaver diagram workflow.ts -o workflow.svg --theme dark
 
-# Vercel (generates api/ handler + vercel.json)
-flow-weaver export workflow.ts --target vercel --output deploy/
+# Describe structure for quick review
+flow-weaver describe workflow.ts --format text
 
-# Cloudflare Workers (generates worker + wrangler.toml)
-flow-weaver export workflow.ts --target cloudflare --output deploy/
+# Semantic diff between versions
+flow-weaver diff workflow-v1.ts workflow-v2.ts
+```
+
+Flow Weaver Studio is a visual editor with bidirectional sync: code changes update the canvas, canvas changes update the code. 80+ plugins handle rendering, state, minimap, undo/redo, and more.
+
+## API
+
+```typescript
+import {
+  parseWorkflow,      // Parse workflow file to AST
+  compileWorkflow,    // Parse + validate + generate in one step
+  validateWorkflow,   // Validate AST (returns errors and warnings)
+  generateCode,       // Generate code from AST
+  generateInPlace,    // Regenerate only the compiled markers in-place
+} from '@synergenius/flow-weaver';
 
-# Multi-workflow service with OpenAPI docs
-flow-weaver export workflow.ts --target vercel --multi --docs --output deploy/
+// Full compilation
+const { code, ast, errors } = await compileWorkflow('workflow.ts');
+
+// Step by step
+const { ast } = await parseWorkflow('workflow.ts');
+const { errors, warnings } = validateWorkflow(ast);
+const code = generateCode(ast);
 ```
 
-## MCP Integration
+### Package Exports
 
-Start the MCP server for use with Claude Code:
+| Import Path | Purpose |
+|-------------|---------|
+| `@synergenius/flow-weaver` | Parse, validate, compile, generate, AST types, builders, diff, patterns |
+| `@synergenius/flow-weaver/runtime` | Execution context, errors, function registry for generated code |
+| `@synergenius/flow-weaver/built-in-nodes` | delay, waitForEvent, invokeWorkflow |
+| `@synergenius/flow-weaver/diagram` | SVG diagram layout and rendering |
+| `@synergenius/flow-weaver/describe` | Programmatic workflow description |
+| `@synergenius/flow-weaver/doc-metadata` | Documentation metadata extractors |
+
+## CLI Reference
 
 ```bash
-npx flow-weaver mcp-server
+# Core
+flow-weaver compile <file>           # Compile to TypeScript or Inngest
+flow-weaver validate <file>          # Validate without compiling
+flow-weaver run <file>               # Execute a workflow
+flow-weaver dev <file>               # Watch + compile + run
+flow-weaver describe <file>          # Structure output (json/text/mermaid)
+flow-weaver diagram <file>           # Generate SVG diagram
+flow-weaver diff <f1> <f2>           # Semantic workflow comparison
+
+# Setup
+flow-weaver init [directory]         # Create new project
+flow-weaver create workflow <t> <f>  # Scaffold from template
+flow-weaver create node <name> <f>   # Scaffold node type
+flow-weaver templates                # List available templates
+flow-weaver doctor                   # Check project compatibility
+flow-weaver grammar                  # Output annotation grammar (EBNF/railroad)
+
+# Deploy
+flow-weaver serve [directory]        # HTTP server with Swagger UI
+flow-weaver export <file>            # Export to Lambda/Vercel/Cloudflare/Inngest
+flow-weaver openapi <directory>      # Generate OpenAPI spec
+
+# Patterns
+flow-weaver pattern list <path>      # List reusable patterns
+flow-weaver pattern apply <p> <t>    # Apply pattern to workflow
+flow-weaver pattern extract <src>    # Extract pattern from nodes
+
+# Docs
+flow-weaver docs                     # List documentation topics
+flow-weaver docs read <topic>        # Read a topic
+flow-weaver docs search <query>      # Search documentation
+
+# Marketplace
+flow-weaver market search [query]    # Search npm for packages
+flow-weaver market install <pkg>     # Install a package
+flow-weaver market list              # List installed packages
+
+# IDE
+flow-weaver mcp-server               # Start MCP server for Claude Code
+flow-weaver listen                   # Stream editor events
 ```
 
-30+ tools across five categories:
-- **Editor** (13): check events, get state, focus/add/remove nodes, connect, batch, execute, undo/redo
-- **Query** (6): describe, validate, compile, diff, query (10 query types), doctor
-- **Template** (2): list templates, scaffold
-- **Pattern** (7): list/apply/extract patterns, find workflows, modify, modify batch, migrate
-- **Export** (1): export to serverless targets
+## Built-in Nodes
 
-## API Documentation
+| Node | Purpose |
+|------|---------|
+| `delay` | Sleep for a duration (ms, s, m, h, d). Mockable for fast testing. |
+| `waitForEvent` | Wait for an external event with optional field matching and timeout. Maps to Inngest `step.waitForEvent()` for zero-cost durable pauses. |
+| `invokeWorkflow` | Invoke another workflow by ID with payload and timeout. Maps to Inngest `step.invoke()`. |
 
-Generate TypeDoc API reference:
+## STEP Port Architecture
 
-```bash
-npm run docs
+Every node follows a consistent contract:
+
+```typescript
+function nodeName(
+  execute: boolean,    // Control: should this node run?
+  ...inputs            // Data inputs (typed)
+): {
+  onSuccess: boolean;  // Success control output
+  onFailure: boolean;  // Failure control output
+  ...outputs           // Data outputs (typed)
+}
 ```
 
-Output is in `docs/api/`. Covers all public APIs with parameters, return types, and examples.
+Expression nodes (`@expression`) skip the control flow boilerplate. Inputs and outputs map directly to the TypeScript signature.
+
+## Marketplace
+
+Distribute node types, workflows, and patterns as npm packages:
+
+```bash
+flow-weaver market init my-nodes          # Scaffold a package
+flow-weaver market pack                   # Validate and generate manifest
+flow-weaver market publish                # Publish to npm
+flow-weaver market install flowweaver-pack-openai   # Install
+```
 
 ## Testing
 
@@ -299,7 +359,7 @@ npm run test:watch    # Watch mode
 
 ```bash
 npm run build         # Build
-npm run dev           # Watch mode
+npm run watch         # Watch mode
 npm run typecheck     # Type check
 npm run docs          # Generate API docs
 ```
@@ -308,8 +368,8 @@ npm run docs          # Generate API docs
 
 Custom license based on the Elastic License 2.0. See [LICENSE](./LICENSE) for full terms.
 
-- **Free to use** — any individual or organization can install, run, and compile workflows
+- **Free to use**: install, run, and compile workflows in any organization
 - **Free to host internally** for organizations with 15 or fewer people
-- **Commercial license required** to host internally for organizations with more than 15 people — contact support@synergenius.pt
-- **External hosting prohibited** — cannot be provided as a hosted/managed service to third parties without a commercial license
-- **Output is unrestricted** — compiled workflows, generated code, and deployment artifacts are yours
+- **Commercial license required** to host internally for 16+ people (contact support@synergenius.pt)
+- **External hosting prohibited** without a commercial license
+- **Output is unrestricted**: compiled workflows, generated code, and deployment artifacts are yours

package/dist/cli/commands/docs.d.ts

@@ -0,0 +1,11 @@
+export interface DocsCommandOptions {
+    compact?: boolean;
+    json?: boolean;
+}
+export interface DocsSearchOptions {
+    json?: boolean;
+}
+export declare function docsListCommand(options: DocsCommandOptions): Promise<void>;
+export declare function docsReadCommand(topic: string, options: DocsCommandOptions): Promise<void>;
+export declare function docsSearchCommand(query: string, options: DocsSearchOptions): Promise<void>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/cli/commands/docs.js

@@ -0,0 +1,77 @@
+import { listTopics, readTopic, readTopicStructured, searchDocs } from '../../docs/index.js';
+import { logger } from '../utils/logger.js';
+export async function docsListCommand(options) {
+    const topics = listTopics();
+    if (topics.length === 0) {
+        logger.error('No documentation topics found.');
+        process.exit(1);
+    }
+    if (options.json) {
+        process.stdout.write(JSON.stringify({ topics }, null, 2) + '\n');
+        return;
+    }
+    logger.section('Flow Weaver Documentation');
+    logger.newline();
+    const maxSlug = Math.max(...topics.map((t) => t.slug.length));
+    for (const topic of topics) {
+        logger.log(`  ${topic.slug.padEnd(maxSlug + 2)} ${topic.description}`);
+    }
+    logger.newline();
+    logger.log('  Usage: flow-weaver docs <topic>');
+    logger.log('  Search: flow-weaver docs search <query>');
+    logger.newline();
+}
+export async function docsReadCommand(topic, options) {
+    if (options.json) {
+        const structured = readTopicStructured(topic);
+        if (!structured) {
+            logger.error(`Unknown topic: "${topic}". Run "flow-weaver docs" to see available topics.`);
+            process.exit(1);
+        }
+        process.stdout.write(JSON.stringify(structured, null, 2) + '\n');
+        return;
+    }
+    const doc = readTopic(topic, options.compact);
+    if (!doc) {
+        logger.error(`Unknown topic: "${topic}". Run "flow-weaver docs" to see available topics.`);
+        process.exit(1);
+    }
+    process.stdout.write(doc.content + '\n');
+}
+export async function docsSearchCommand(query, options) {
+    const results = searchDocs(query);
+    if (options.json) {
+        process.stdout.write(JSON.stringify({ query, results }, null, 2) + '\n');
+        return;
+    }
+    if (results.length === 0) {
+        logger.log(`No results found for "${query}".`);
+        return;
+    }
+    logger.section(`Search results for "${query}"`);
+    logger.newline();
+    // Deduplicate by topic+heading, show top results
+    const seen = new Set();
+    let shown = 0;
+    for (const result of results) {
+        const key = `${result.slug}:${result.heading}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        logger.log(`  [${result.slug}] ${result.heading}`);
+        if (result.excerpt) {
+            const excerptLines = result.excerpt.split('\n').slice(0, 2);
+            for (const line of excerptLines) {
+                logger.log(`    ${line}`);
+            }
+        }
+        logger.newline();
+        shown++;
+        if (shown >= 15)
+            break;
+    }
+    logger.log(`  ${results.length} matching section(s) across ${new Set(results.map((r) => r.slug)).size} topic(s).`);
+    logger.log('  Read a topic: flow-weaver docs <topic>');
+    logger.newline();
+}
+//# sourceMappingURL=docs.js.map