@synergenius/flow-weaver-pack-weaver 0.9.0 → 0.9.4

package/src/bot/tool-registry.ts

@@ -0,0 +1,477 @@
+/**
+ * Unified tool registry — single source of truth for all weaver tool definitions.
+ * Merges assistant-tools.ts ASSISTANT_TOOLS and weaver-tools.ts WEAVER_TOOLS
+ * into one registry with metadata (category, contexts, verboseOutput).
+ */
+
+import type { ToolDefinition } from '@synergenius/flow-weaver/agent';
+
+export interface WeaverTool extends ToolDefinition {
+  verboseOutput?: boolean;
+  category: 'bot-management' | 'queue' | 'flow-weaver' | 'project' | 'knowledge' | 'conversation' | 'ci' | 'web';
+  contexts: Array<'bot' | 'assistant'>;
+}
+
+export const ALL_TOOLS: WeaverTool[] = [
+  // ── Bot management (assistant only) ──────────────────────────────
+  {
+    name: 'bot_spawn',
+    description: 'Start a new bot session. Returns the bot name and status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Unique name for this bot (e.g. "fix-templates")' },
+        project_dir: { type: 'string', description: 'Project directory for the bot to work in' },
+        parallel: { type: 'number', description: 'Number of parallel tasks (1-5, default 1)' },
+        deadline: { type: 'string', description: 'Stop time in HH:MM format (optional)' },
+        branch: { type: 'string', description: 'Git branch for commits (keeps main clean, good for overnight runs)' },
+      },
+      required: ['name'],
+    },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_list',
+    description: 'List all bot sessions with their status, task counts, and cost.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_status',
+    description: 'Get detailed status of a specific bot including queue and recent activity.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Bot name' } },
+      required: ['name'],
+    },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_pause',
+    description: 'Pause a running bot. It will finish its current task then wait.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Bot name' } },
+      required: ['name'],
+    },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_resume',
+    description: 'Resume a paused bot.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Bot name' } },
+      required: ['name'],
+    },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_stop',
+    description: 'Gracefully stop a bot (finishes current task, then exits).',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Bot name' } },
+      required: ['name'],
+    },
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'bot_logs',
+    description: 'Get recent output log from a bot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Bot name' },
+        lines: { type: 'number', description: 'Number of lines to return (default 30)' },
+      },
+      required: ['name'],
+    },
+    verboseOutput: true,
+    category: 'bot-management',
+    contexts: ['assistant'],
+  },
+
+  // ── Queue management (assistant only) ────────────────────────────
+  {
+    name: 'queue_add',
+    description: 'Add a task to a bot\'s queue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bot: { type: 'string', description: 'Bot name' },
+        instruction: { type: 'string', description: 'Task instruction' },
+        targets: { type: 'array', items: { type: 'string' }, description: 'Target files (optional)' },
+      },
+      required: ['bot', 'instruction'],
+    },
+    category: 'queue',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'queue_add_batch',
+    description: 'Add multiple tasks to a bot\'s queue at once.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bot: { type: 'string', description: 'Bot name' },
+        tasks: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              instruction: { type: 'string' },
+              targets: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['instruction'],
+          },
+          description: 'Array of tasks to add',
+        },
+      },
+      required: ['bot', 'tasks'],
+    },
+    category: 'queue',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'queue_list',
+    description: 'List all tasks in a bot\'s queue with their status.',
+    inputSchema: {
+      type: 'object',
+      properties: { bot: { type: 'string', description: 'Bot name' } },
+      required: ['bot'],
+    },
+    category: 'queue',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'queue_retry',
+    description: 'Reset all failed tasks in a bot\'s queue to pending.',
+    inputSchema: {
+      type: 'object',
+      properties: { bot: { type: 'string', description: 'Bot name' } },
+      required: ['bot'],
+    },
+    category: 'queue',
+    contexts: ['assistant'],
+  },
+
+  // ── Flow-weaver tools ────────────────────────────────────────────
+  {
+    name: 'validate',
+    description: 'Run flow-weaver validate on a workflow file. Returns JSON with errors and warnings. Use this FIRST to discover issues, and AFTER patching to confirm fixes.',
+    inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Path to the workflow file to validate' } }, required: ['file'] },
+    category: 'flow-weaver',
+    contexts: ['bot'],
+  },
+  {
+    name: 'fw_validate',
+    description: 'Validate a workflow or directory of workflows. Returns errors and warnings.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'File or directory path' } },
+      required: ['path'],
+    },
+    category: 'flow-weaver',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'fw_diagram',
+    description: 'Generate a text diagram of a workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: { file: { type: 'string', description: 'Workflow file path' } },
+      required: ['file'],
+    },
+    verboseOutput: true,
+    category: 'flow-weaver',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'fw_describe',
+    description: 'Get a natural language description of a workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: { file: { type: 'string', description: 'Workflow file path' } },
+      required: ['file'],
+    },
+    verboseOutput: true,
+    category: 'flow-weaver',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'fw_docs',
+    description: 'Look up Flow Weaver documentation by topic. Topics: concepts, jsdoc-grammar, advanced-annotations, built-in-nodes, scaffold, node-conversion, patterns, error-codes, debugging, export-interface.',
+    inputSchema: {
+      type: 'object',
+      properties: { topic: { type: 'string', description: 'Documentation topic slug' } },
+      required: ['topic'],
+    },
+    verboseOutput: true,
+    category: 'flow-weaver',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'fw_diagram_mermaid',
+    description: 'Generate a Mermaid diagram of a workflow (can be rendered in any Mermaid viewer).',
+    inputSchema: {
+      type: 'object',
+      properties: { file: { type: 'string', description: 'Workflow file path' } },
+      required: ['file'],
+    },
+    verboseOutput: true,
+    category: 'flow-weaver',
+    contexts: ['assistant'],
+  },
+
+  // ── Project tools (shared or context-specific) ───────────────────
+  {
+    name: 'read_file',
+    description: 'Read a file and return its contents.',
+    inputSchema: {
+      type: 'object',
+      properties: { file: { type: 'string', description: 'File path' } },
+      required: ['file'],
+    },
+    category: 'project',
+    contexts: ['bot', 'assistant'],
+  },
+  {
+    name: 'list_files',
+    description: 'List files in a directory, optionally filtered by regex pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        directory: { type: 'string', description: 'Directory to list' },
+        pattern: { type: 'string', description: 'Optional regex filter pattern' },
+      },
+      required: ['directory'],
+    },
+    category: 'project',
+    contexts: ['bot', 'assistant'],
+  },
+  {
+    name: 'run_shell',
+    description: 'Run a shell command (read-only operations recommended). Blocked: rm -rf, git push, sudo.',
+    inputSchema: {
+      type: 'object',
+      properties: { command: { type: 'string', description: 'Shell command to execute' } },
+      required: ['command'],
+    },
+    category: 'project',
+    contexts: ['bot', 'assistant'],
+  },
+  {
+    name: 'patch_file',
+    description: 'Apply surgical find-and-replace patches to a file. Each patch must have exact "find" and "replace" strings. Preferred over write_file for modifications.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to the file to patch' },
+        patches: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              find: { type: 'string', description: 'Exact string to find' },
+              replace: { type: 'string', description: 'String to replace with' },
+            },
+            required: ['find', 'replace'],
+          },
+          description: 'Array of find/replace patches',
+        },
+      },
+      required: ['file', 'patches'],
+    },
+    category: 'project',
+    contexts: ['bot'],
+  },
+  {
+    name: 'write_file',
+    description: 'Write content to a file (creates or overwrites). Use patch_file instead for modifications to existing files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to the file to write' },
+        content: { type: 'string', description: 'Complete file content' },
+      },
+      required: ['file', 'content'],
+    },
+    category: 'project',
+    contexts: ['bot'],
+  },
+  {
+    name: 'tsc_check',
+    description: 'Run TypeScript compiler check (no emit). Returns errors if any.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    verboseOutput: true,
+    category: 'project',
+    contexts: ['bot'],
+  },
+  {
+    name: 'run_tests',
+    description: 'Run project tests. Returns structured results with pass/fail counts.',
+    inputSchema: { type: 'object', properties: { pattern: { type: 'string', description: 'Test file pattern (optional)' } }, required: [] },
+    verboseOutput: true,
+    category: 'project',
+    contexts: ['bot'],
+  },
+  {
+    name: 'project_list',
+    description: 'List known project directories that have been used with weaver.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    category: 'project',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'project_context',
+    description: 'Read package.json and .weaver-plan.md from a project directory to understand its context.',
+    inputSchema: {
+      type: 'object',
+      properties: { directory: { type: 'string', description: 'Absolute path to project directory' } },
+      required: ['directory'],
+    },
+    category: 'project',
+    contexts: ['assistant'],
+  },
+
+  // ── Knowledge tools ──────────────────────────────────────────────
+  {
+    name: 'knowledge_list',
+    description: 'List all stored knowledge entries for the current project.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    category: 'knowledge',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'knowledge_search',
+    description: 'Search stored knowledge by keyword.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search query' } },
+      required: ['query'],
+    },
+    category: 'knowledge',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'learn',
+    description: 'Store a fact for future tasks. Key should be descriptive (e.g. "file:src/agent.ts:port-issue").',
+    inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] },
+    category: 'knowledge',
+    contexts: ['bot'],
+  },
+  {
+    name: 'recall',
+    description: 'Look up stored knowledge. Returns matching entries.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+    category: 'knowledge',
+    contexts: ['bot'],
+  },
+
+  // ── Conversation management (assistant only) ─────────────────────
+  {
+    name: 'conversation_list',
+    description: 'List saved assistant conversations with message counts and timestamps.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    category: 'conversation',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'conversation_delete',
+    description: 'Delete a saved conversation by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'Conversation ID to delete' } },
+      required: ['id'],
+    },
+    category: 'conversation',
+    contexts: ['assistant'],
+  },
+  {
+    name: 'conversation_summary',
+    description: 'Get a summary of the current conversation (message count, tokens, bots spawned).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+    category: 'conversation',
+    contexts: ['assistant'],
+  },
+
+  // ── CI/CD (assistant only) ───────────────────────────────────────
+  {
+    name: 'github_status',
+    description: 'Check GitHub Actions status for a branch or PR. Requires gh CLI installed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        branch: { type: 'string', description: 'Branch name (optional, defaults to current)' },
+        pr: { type: 'number', description: 'PR number (optional, checks PR status instead of branch)' },
+      },
+      required: [],
+    },
+    category: 'ci',
+    contexts: ['assistant'],
+  },
+
+  // ── Web access (shared) ──────────────────────────────────────────
+  {
+    name: 'web_fetch',
+    description: 'Fetch HTTP content from a URL. Returns text body (max 10KB).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to fetch' },
+        method: { type: 'string', description: 'HTTP method (default GET)', enum: ['GET', 'POST'] },
+      },
+      required: ['url'],
+    },
+    category: 'web',
+    contexts: ['bot', 'assistant'],
+  },
+
+  // ── Bot-only interactive ─────────────────────────────────────────
+  {
+    name: 'ask_user',
+    description: 'Ask the user a question and wait for response. Use when you need a decision.',
+    inputSchema: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'] },
+    category: 'project',
+    contexts: ['bot'],
+  },
+];
+
+// ── Derived exports ──────────────────────────────────────────────────
+
+export const BOT_TOOLS: ToolDefinition[] = ALL_TOOLS.filter(t => t.contexts.includes('bot'));
+export const ASSISTANT_TOOLS: ToolDefinition[] = ALL_TOOLS.filter(t => t.contexts.includes('assistant'));
+export const VERBOSE_TOOL_NAMES = new Set(ALL_TOOLS.filter(t => t.verboseOutput).map(t => t.name));
+
+/**
+ * Generate a prompt section grouping assistant tools by category.
+ */
+export function generateToolPromptSection(): string {
+  const groups = new Map<string, WeaverTool[]>();
+  for (const t of ALL_TOOLS.filter(t => t.contexts.includes('assistant'))) {
+    const list = groups.get(t.category) ?? [];
+    list.push(t);
+    groups.set(t.category, list);
+  }
+  const lines: string[] = [];
+  for (const [cat, tools] of groups) {
+    lines.push(`${cat}:`);
+    for (const t of tools) lines.push(`  - ${t.name}: ${t.description}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Generate a comma-separated list of tools that produce verbose output.
+ */
+export function generateVerboseToolList(): string {
+  return [...VERBOSE_TOOL_NAMES].join(', ');
+}

package/src/bot/types.ts

@@ -171,6 +171,12 @@ export interface WorkflowResult {
 
 export type RunOutcome = 'completed' | 'failed' | 'error' | 'skipped';
 
+export interface StepLogEntry {
+  step: string;
+  status: 'ok' | 'blocked' | 'error';
+  detail?: string;
+}
+
 export interface RunRecord {
   id: string;
   workflowFile: string;
@@ -187,6 +193,7 @@ export interface RunRecord {
   provider?: string;
   pipelineName?: string;
   stageName?: string;
+  stepLog?: StepLogEntry[];
 }
 
 export interface RunFilter {
@@ -494,6 +501,7 @@ export interface WeaverContext {
   resultJson?: string;
   validationResultJson?: string;
   filesModified?: string;
+  stepLogJson?: string;
   allValid?: boolean;
   gitResultJson?: string;
 }

package/src/bot/weaver-tools.ts

@@ -0,0 +1,134 @@
+/**
+ * Weaver-specific tool definitions and executor.
+ *
+ * These are the tools the weaver bot uses: validate, read_file, patch_file,
+ * run_shell, list_files, write_file. Tool execution delegates to step-executor
+ * with all safety guards (path traversal, shrink detection, blocked commands).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { executeStep } from './step-executor.js';
+import type { ToolDefinition } from '@synergenius/flow-weaver/agent';
+import { BOT_TOOLS as WEAVER_TOOLS } from './tool-registry.js';
+import { isBlockedUrl } from './safety.js';
+
+export { WEAVER_TOOLS };
+
+/** Map tool names to step-executor operations. */
+const OPERATION_MAP: Record<string, string> = {
+  validate: 'run-shell',
+  read_file: 'read-file',
+  patch_file: 'patch-file',
+  run_shell: 'run-shell',
+  list_files: 'list-files',
+  write_file: 'write-file',
+};
+
+/**
+ * Execute a weaver tool call. Delegates to step-executor with safety guards.
+ * Bound to a specific project directory via closure.
+ */
+export function createWeaverExecutor(projectDir: string) {
+  return async (
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<{ result: string; isError: boolean }> => {
+    // Handle new tools that bypass step-executor
+    switch (name) {
+      case 'web_fetch': {
+        const url = String(args.url);
+        // Safety: block localhost, internal IPs
+        if (isBlockedUrl(url)) {
+          return { result: 'Blocked: cannot fetch internal/localhost URLs.', isError: true };
+        }
+        const resp = await fetch(url, { method: (args.method as string) ?? 'GET', signal: AbortSignal.timeout(15_000) });
+        const text = await resp.text();
+        return { result: text.slice(0, 10_000), isError: !resp.ok };
+      }
+
+      case 'tsc_check': {
+        try {
+          const output = execFileSync('npx', ['tsc', '--noEmit', '--pretty'], { cwd: projectDir, encoding: 'utf-8', timeout: 60_000, stdio: ['pipe', 'pipe', 'pipe'] });
+          return { result: output.trim() || 'No TypeScript errors.', isError: false };
+        } catch (err: any) {
+          return { result: (err.stdout ?? err.message ?? '').slice(0, 5000), isError: true };
+        }
+      }
+
+      case 'run_tests': {
+        try {
+          const pattern = args.pattern ? String(args.pattern) : '';
+          const testArgs = ['vitest', 'run', '--reporter', 'json'];
+          if (pattern) testArgs.push(pattern);
+          const output = execFileSync('npx', testArgs, { cwd: projectDir, encoding: 'utf-8', timeout: 120_000, stdio: ['pipe', 'pipe', 'pipe'] });
+          try {
+            const json = JSON.parse(output);
+            const passed = json.numPassedTests ?? 0;
+            const failed = json.numFailedTests ?? 0;
+            const failures = (json.testResults ?? []).filter((t: any) => t.status === 'failed').map((t: any) => t.name).slice(0, 10);
+            return { result: JSON.stringify({ passed, failed, total: passed + failed, failures }), isError: failed > 0 };
+          } catch {
+            return { result: output.slice(0, 5000), isError: false };
+          }
+        } catch (err: any) {
+          return { result: (err.stdout ?? err.stderr ?? err.message ?? '').slice(0, 5000), isError: true };
+        }
+      }
+
+      case 'ask_user': {
+        const question = String(args.question);
+        if (process.env.WEAVER_AUTO_APPROVE) {
+          return { result: '(Auto-approved — no user input available in autonomous mode)', isError: false };
+        }
+        // In interactive mode, prompt via readline
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(`\n  Bot asks: ${question}\n  > `, (ans) => { rl.close(); resolve(ans); });
+        });
+        return { result: answer || '(no answer)', isError: false };
+      }
+
+      case 'learn': {
+        const { KnowledgeStore } = await import('./knowledge-store.js');
+        const store = new KnowledgeStore(projectDir);
+        store.learn(String(args.key), String(args.value), 'bot');
+        return { result: `Learned: ${args.key}`, isError: false };
+      }
+
+      case 'recall': {
+        const { KnowledgeStore } = await import('./knowledge-store.js');
+        const store = new KnowledgeStore(projectDir);
+        const entries = store.recall(String(args.query));
+        if (entries.length === 0) return { result: 'No knowledge found.', isError: false };
+        return { result: entries.map(e => `${e.key}: ${e.value}`).join('\n'), isError: false };
+      }
+
+      default:
+        break;
+    }
+
+    // Existing step-executor-based tools
+    const operation = OPERATION_MAP[name];
+    if (!operation) {
+      return { result: `Unknown tool: ${name}`, isError: true };
+    }
+
+    // Transform validate tool to run-shell with flow-weaver validate command
+    let stepArgs = { ...args };
+    if (name === 'validate') {
+      stepArgs = { command: `npx flow-weaver validate ${args.file} --json` };
+    }
+
+    try {
+      const result = await executeStep({ operation, args: stepArgs }, projectDir);
+      if (result.blocked) {
+        return { result: result.blockReason ?? 'Blocked by safety guard', isError: true };
+      }
+      return { result: result.output ?? 'Done', isError: false };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { result: msg, isError: true };
+    }
+  };
+}

package/src/cli-bridge.ts

@@ -3,7 +3,9 @@ import {
   handleRun, handleHistory, handleCosts, handleWatch,
   handleCron, handlePipeline, handleDashboard, handleProviders,
   handleEject, handleBot, handleSession, handleSteer, handleQueue,
-  handleGenesis, handleAudit, handleInit, printHelp,
+  handleStatus, handleGenesis, handleAudit, handleInit, handleAssistant,
+  handleExamples, handleDoctor,
+  printHelp,
 } from './cli-handlers.js';
 
 const handlers: Record<string, (opts: ParsedArgs) => Promise<void>> = {
@@ -20,9 +22,13 @@ const handlers: Record<string, (opts: ParsedArgs) => Promise<void>> = {
   session: handleSession,
   steer: handleSteer,
   queue: handleQueue,
+  status: handleStatus,
   genesis: handleGenesis,
   audit: handleAudit,
   init: handleInit,
+  assistant: handleAssistant,
+  examples: handleExamples,
+  doctor: handleDoctor,
 };
 
 export async function handleCommand(