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

package/src/bot/error-classifier.ts

@@ -0,0 +1,90 @@
+/**
+ * Unified error classification — merges error-guide.ts and retry-utils.ts
+ * into a single source of truth for error handling.
+ */
+
+export interface ErrorClassification {
+  isTransient: boolean;
+  guidance: string | null;
+  category: 'auth' | 'network' | 'rate-limit' | 'timeout' | 'parse' | 'system' | 'unknown';
+}
+
+const PATTERNS: Array<{ pattern: RegExp; isTransient: boolean; guidance: string; category: ErrorClassification['category'] }> = [
+  { pattern: /ETIMEDOUT/i, isTransient: true, guidance: 'Network timeout. Check internet or increase timeout.', category: 'timeout' },
+  { pattern: /ECONNRESET/i, isTransient: true, guidance: 'Connection reset. Retry in a few seconds.', category: 'network' },
+  { pattern: /ECONNREFUSED/i, isTransient: true, guidance: 'Connection refused. Is the service running?', category: 'network' },
+  { pattern: /EPIPE|ENOTFOUND/i, isTransient: true, guidance: 'Network error.', category: 'network' },
+  { pattern: /401|authentication|invalid.*key/i, isTransient: false, guidance: 'Authentication failed. Check API key or run "weaver init".', category: 'auth' },
+  { pattern: /403|forbidden/i, isTransient: false, guidance: 'Access denied. API key may lack permissions.', category: 'auth' },
+  { pattern: /429|rate.?limit|too many requests/i, isTransient: true, guidance: 'Rate limited. Wait a few minutes or reduce --parallel.', category: 'rate-limit' },
+  { pattern: /502|bad gateway/i, isTransient: true, guidance: 'Server error (502). Will auto-retry.', category: 'network' },
+  { pattern: /503|service unavailable|overloaded/i, isTransient: true, guidance: 'Service overloaded. Will auto-retry.', category: 'network' },
+  { pattern: /504|gateway timeout/i, isTransient: true, guidance: 'Gateway timeout (504). Will auto-retry.', category: 'timeout' },
+  { pattern: /exit(?:ed with)? code 143/i, isTransient: true, guidance: 'Process killed (SIGTERM). Likely timeout or Ctrl+C.', category: 'timeout' },
+  { pattern: /exit code 137/i, isTransient: false, guidance: 'Process killed (OOM). System may be low on memory.', category: 'system' },
+  { pattern: /ENOMEM/i, isTransient: false, guidance: 'Out of memory.', category: 'system' },
+  { pattern: /ENOSPC/i, isTransient: false, guidance: 'Disk full.', category: 'system' },
+  { pattern: /lock.*retries|failed to acquire.*lock/i, isTransient: true, guidance: 'File lock contention. Another weaver process may be running.', category: 'system' },
+  { pattern: /not a workflow|No @flowWeaver/i, isTransient: false, guidance: 'Not a Flow Weaver workflow. Ensure @flowWeaver annotations exist.', category: 'parse' },
+  { pattern: /parse.*json|unexpected token/i, isTransient: false, guidance: 'JSON parse error. AI may have returned malformed output.', category: 'parse' },
+  { pattern: /Queue full/i, isTransient: false, guidance: 'Too many pending tasks (200 max). Process or clear first.', category: 'system' },
+];
+
+/**
+ * Classify an error into transient/permanent with guidance and category.
+ */
+export function classifyError(err: unknown): ErrorClassification {
+  const msg = err instanceof Error ? err.message : String(err);
+  // Also check Node.js error codes
+  const code = err instanceof Error && 'code' in err ? (err as NodeJS.ErrnoException).code : undefined;
+  const fullMsg = code ? `${msg} ${code}` : msg;
+
+  for (const p of PATTERNS) {
+    if (p.pattern.test(fullMsg)) {
+      return { isTransient: p.isTransient, guidance: p.guidance, category: p.category };
+    }
+  }
+  return { isTransient: false, guidance: null, category: 'unknown' };
+}
+
+/** Convenience: check if an error is transient (retriable). */
+export function isTransientError(err: unknown): boolean {
+  return classifyError(err).isTransient;
+}
+
+/** Convenience: get actionable guidance for an error message. */
+export function getErrorGuidance(msg: string): string | null {
+  return classifyError(new Error(msg)).guidance;
+}
+
+/**
+ * Run a function with exponential backoff retry on transient errors.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    multiplier?: number;
+    onRetry?: (attempt: number, delay: number, err: Error) => void;
+  },
+): Promise<T> {
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelay = options?.baseDelayMs ?? 5_000;
+  const multiplier = options?.multiplier ?? 3;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err: unknown) {
+      const isLast = attempt >= maxRetries;
+      if (isLast || !isTransientError(err)) throw err;
+      const delay = baseDelay * Math.pow(multiplier, attempt);
+      options?.onRetry?.(attempt + 1, delay, err instanceof Error ? err : new Error(String(err)));
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+
+  // Unreachable, but TypeScript needs it
+  throw new Error('withRetry: exhausted retries');
+}

package/src/bot/error-guide.ts

@@ -0,0 +1,4 @@
+/**
+ * @deprecated Use error-classifier.ts instead. This file re-exports for backward compatibility.
+ */
+export { getErrorGuidance } from './error-classifier.js';

package/src/bot/knowledge-store.ts

@@ -0,0 +1,59 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+
+export interface KnowledgeEntry {
+  key: string;
+  value: string;
+  source: string;
+  createdAt: number;
+}
+
+export class KnowledgeStore {
+  private filePath: string;
+
+  constructor(projectDir?: string) {
+    const dir = projectDir
+      ? path.join(os.homedir(), '.weaver', 'projects', crypto.createHash('sha256').update(projectDir).digest('hex').slice(0, 8))
+      : path.join(os.homedir(), '.weaver');
+    this.filePath = path.join(dir, 'knowledge.ndjson');
+  }
+
+  learn(key: string, value: string, source: string): void {
+    // Append entry to NDJSON file. If key exists, update it.
+    const entries = this.readAll().filter(e => e.key !== key);
+    entries.push({ key, value, source, createdAt: Date.now() });
+    this.writeAll(entries);
+  }
+
+  recall(query: string): KnowledgeEntry[] {
+    // Fuzzy match: return entries whose key contains the query (case-insensitive)
+    const lower = query.toLowerCase();
+    return this.readAll().filter(e => e.key.toLowerCase().includes(lower) || e.value.toLowerCase().includes(lower));
+  }
+
+  forget(key: string): void {
+    const entries = this.readAll().filter(e => e.key !== key);
+    this.writeAll(entries);
+  }
+
+  list(): KnowledgeEntry[] {
+    return this.readAll();
+  }
+
+  private readAll(): KnowledgeEntry[] {
+    if (!fs.existsSync(this.filePath)) return [];
+    const content = fs.readFileSync(this.filePath, 'utf-8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean) as KnowledgeEntry[];
+  }
+
+  private writeAll(entries: KnowledgeEntry[]): void {
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(this.filePath, entries.map(e => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : ''));
+  }
+}

package/src/bot/paths.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared path resolution — single source of truth for .weaver directory layout.
+ */
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+
+/**
+ * Hash a directory path into a short filesystem-safe string.
+ * Used for per-project isolation under ~/.weaver/projects/.
+ */
+export function hashDir(dir: string): string {
+  return crypto.createHash('sha256').update(dir).digest('hex').slice(0, 8);
+}
+
+/**
+ * Resolve the weaver working directory.
+ * Priority: explicit > WEAVER_QUEUE_DIR > WEAVER_STEERING_DIR > project-scoped > global fallback.
+ */
+export function resolveWeaverDir(explicit?: string): string {
+  return explicit
+    ?? process.env.WEAVER_QUEUE_DIR
+    ?? process.env.WEAVER_STEERING_DIR
+    ?? (process.env.WEAVER_PROJECT_DIR
+      ? path.join(os.homedir(), '.weaver', 'projects', hashDir(process.env.WEAVER_PROJECT_DIR))
+      : path.join(os.homedir(), '.weaver'));
+}

package/src/bot/retry-utils.ts

@@ -0,0 +1,4 @@
+/**
+ * @deprecated Use error-classifier.ts instead. This file re-exports for backward compatibility.
+ */
+export { isTransientError, withRetry } from './error-classifier.js';

package/src/bot/runner.ts

@@ -224,6 +224,16 @@ export async function runWorkflow(
     const summary = buildSummary(result);
     const outcome = success ? 'completed' : 'failed';
 
+    // Extract stepLog from WeaverContext if available
+    let stepLog: import('./types.js').StepLogEntry[] | undefined;
+    try {
+      const ctxStr = result?.ctx as string | undefined;
+      if (ctxStr) {
+        const ctx = JSON.parse(ctxStr);
+        if (ctx.stepLogJson) stepLog = JSON.parse(ctx.stepLogJson);
+      }
+    } catch { /* stepLog extraction is best-effort */ }
+
     await notifier({
       type: 'workflow-complete',
       workflowFile: absPath,
@@ -237,7 +247,7 @@ export async function runWorkflow(
     recordRun(store, {
       id: runId, workflowFile: absPath, startedAt, success, outcome: outcome as RunOutcome, summary,
       functionName: execResult.functionName, executionTime: execResult.executionTime,
-      dryRun: false, provider: providerConfig.name, params: options?.params,
+      dryRun: false, provider: providerConfig.name, params: options?.params, stepLog,
     }, verbose);
 
     auditEmit('run-complete', { success, outcome, summary });
@@ -282,6 +292,7 @@ function recordRun(
     outcome: RunOutcome; summary: string; functionName?: string;
     executionTime?: number; dryRun: boolean; provider?: string;
     params?: Record<string, unknown>;
+    stepLog?: import('./types.js').StepLogEntry[];
   },
   verbose: boolean,
 ): void {

package/src/bot/safety.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared safety constants and checks — single source of truth.
+ */
+
+export const BLOCKED_COMMANDS = ['rm -rf', 'git push', 'npm publish', 'sudo', 'curl|sh', 'wget|sh'];
+export const BLOCKED_URL_PATTERN = /localhost|127\.0\.0\.1|0\.0\.0\.0|10\.\d|172\.(1[6-9]|2\d|3[01])\.|192\.168\./i;
+export const MAX_READ_SIZE = 1_048_576;
+export const CHARS_PER_TOKEN = 4;
+
+export function isBlockedCommand(cmd: string): boolean {
+  return BLOCKED_COMMANDS.some(b => cmd.includes(b));
+}
+
+export function isBlockedUrl(url: string): boolean {
+  return BLOCKED_URL_PATTERN.test(url);
+}

package/src/bot/session-state.ts

@@ -40,7 +40,8 @@ export class SessionStore {
     try {
       if (!fs.existsSync(this.filePath)) return null;
       return JSON.parse(fs.readFileSync(this.filePath, 'utf-8')) as SessionState;
-    } catch {
+    } catch (err) {
+      if (process.env.WEAVER_VERBOSE) process.stderr.write(`[weaver] session state load failed: ${err}\n`);
       return null;
     }
   }

package/src/bot/steering.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { withFileLock } from './file-lock.js';
+import { resolveWeaverDir } from './paths.js';
 
 export interface SteeringCommand {
   command: 'pause' | 'resume' | 'cancel' | 'redirect' | 'queue';
@@ -13,7 +13,7 @@ export class SteeringController {
   private controlPath: string;
 
   constructor(controlDir?: string) {
-    const dir = controlDir ?? path.join(os.homedir(), '.weaver');
+    const dir = controlDir ?? resolveWeaverDir();
     this.controlPath = path.join(dir, 'control.json');
   }
 

package/src/bot/step-executor.ts

@@ -1,27 +1,335 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { execSync } from 'node:child_process';
 import { runCommand } from '@synergenius/flow-weaver';
 
+// ---------------------------------------------------------------------------
+// Safety thresholds
+// ---------------------------------------------------------------------------
+
+/** Refuse writes that shrink an existing file by more than this ratio (0-1). */
+const MAX_SHRINK_RATIO = 0.5;
+
+/** Minimum file size (bytes) before shrink guard kicks in. */
+const SHRINK_GUARD_MIN_SIZE = 100;
+
+/** Maximum number of files that can be written in a single plan. */
+const MAX_FILES_PER_PLAN = 50;
+
+/** Maximum shell command execution time (ms). */
+const SHELL_TIMEOUT = 60_000;
+
+/** Maximum file size for read/patch operations (1MB). */
+const MAX_READ_SIZE = 1_048_576;
+
+/** Maximum files returned by list-files. */
+const MAX_LIST_FILES = 1000;
+
+/** Shell commands that are NEVER allowed (destructive operations). */
+const BLOCKED_SHELL_PATTERNS = [
+  /\brm\s+(-[a-z]*r|-[a-z]*f)[a-z]*\s/i,  // rm with -r or -f flags
+  /\bgit\s+push\b/i,              // git push (no remote ops)
+  /\bgit\s+reset\s+--hard\b/i,    // git reset --hard
+  /\bnpm\s+publish\b/i,           // npm publish
+  /\bcurl\b.*\|\s*(sh|bash)\b/i,  // curl | sh/bash
+  /\bwget\b.*\|\s*(sh|bash)\b/i,  // wget | sh/bash
+  /\bsudo\b/i,                    // sudo
+  /\bchmod\s+777\b/i,             // chmod 777
+  /\bkill\s+-9\b/i,               // kill -9
+  /\bmkfs\b/i,                    // format disk
+  /\bdd\s+if=/i,                  // dd (disk destroyer)
+  />\s*\/dev\/sd/i,               // write to raw disk
+];
+
+/** Track files written in this process to enforce the per-plan cap. */
+let filesWrittenThisPlan = 0;
+
+/** Reset the per-plan counter between plans. */
+export function resetPlanFileCounter(): void {
+  filesWrittenThisPlan = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Path safety
+// ---------------------------------------------------------------------------
+
+function assertSafePath(filePath: string, projectDir: string): void {
+  const resolved = path.resolve(projectDir, filePath);
+  if (!resolved.startsWith(path.resolve(projectDir))) {
+    throw new Error(
+      `Path traversal blocked: "${filePath}" resolves outside project directory.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write safety
+// ---------------------------------------------------------------------------
+
+interface WriteGuardResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+function checkWriteSafety(filePath: string, content: string): WriteGuardResult {
+  // Guard 1: Empty content
+  if (!content || content.trim().length === 0) {
+    return {
+      allowed: false,
+      reason:
+        `Refusing to write empty content to ${path.basename(filePath)}. ` +
+        `Use read-file first, then write the complete modified file back.`,
+    };
+  }
+
+  // Guard 2: Per-plan file cap
+  if (filesWrittenThisPlan >= MAX_FILES_PER_PLAN) {
+    return {
+      allowed: false,
+      reason: `File write limit reached (${MAX_FILES_PER_PLAN} files per plan).`,
+    };
+  }
+
+  // Guard 3: Shrink detection
+  if (fs.existsSync(filePath)) {
+    const existingSize = fs.statSync(filePath).size;
+    const newSize = Buffer.byteLength(content, 'utf-8');
+    if (existingSize > SHRINK_GUARD_MIN_SIZE && newSize < existingSize * MAX_SHRINK_RATIO) {
+      const shrinkPct = Math.round((1 - newSize / existingSize) * 100);
+      return {
+        allowed: false,
+        reason:
+          `Refusing to write ${path.basename(filePath)}: new content (${newSize}B) ` +
+          `is ${shrinkPct}% smaller than existing (${existingSize}B). ` +
+          `Use read-file first, make targeted changes, write complete file back.`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// Shell safety
+// ---------------------------------------------------------------------------
+
+function checkShellSafety(command: string): WriteGuardResult {
+  for (const pattern of BLOCKED_SHELL_PATTERNS) {
+    if (pattern.test(command)) {
+      return {
+        allowed: false,
+        reason: `Shell command blocked by safety policy: matches "${pattern.source}"`,
+      };
+    }
+  }
+  return { allowed: true };
+}
+
+// ---------------------------------------------------------------------------
+// Main executor
+// ---------------------------------------------------------------------------
+
+export interface StepResult {
+  file?: string;
+  files?: string[];
+  created?: boolean;
+  output?: string;
+  blocked?: boolean;
+  blockReason?: string;
+}
+
 export async function executeStep(
   step: { operation: string; args: Record<string, unknown> },
   projectDir: string,
-): Promise<{ file?: string; files?: string[]; created?: boolean; output?: string }> {
+): Promise<StepResult> {
   const args = step.args;
   const file = args.file as string | undefined;
 
   switch (step.operation) {
+    // -----------------------------------------------------------------
+    // File write operations (with safety guards)
+    // -----------------------------------------------------------------
     case 'write-file':
     case 'create-workflow':
     case 'modify-source':
     case 'implement-node': {
-      const filePath = path.resolve(projectDir, file!);
+      if (!file) {
+        return { blocked: true, blockReason: `${step.operation} requires a "file" argument.` };
+      }
+      assertSafePath(file, projectDir);
+      const filePath = path.resolve(projectDir, file);
+      const content = (args.content as string) ?? (args.body as string) ?? '';
+
+      const guard = checkWriteSafety(filePath, content);
+      if (!guard.allowed) {
+        return { file: filePath, blocked: true, blockReason: guard.reason };
+      }
+
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
       const existed = fs.existsSync(filePath);
-      fs.writeFileSync(filePath, (args.content as string) ?? (args.body as string) ?? '', 'utf-8');
+      fs.writeFileSync(filePath, content, 'utf-8');
+      filesWrittenThisPlan++;
       return { file: filePath, created: !existed };
     }
-    case 'read-file':
-      return {};
+
+    // -----------------------------------------------------------------
+    // Patch file: surgical find-and-replace (no full rewrite needed)
+    // -----------------------------------------------------------------
+    case 'patch-file': {
+      if (!file) {
+        return { blocked: true, blockReason: 'patch-file requires a "file" argument.' };
+      }
+      assertSafePath(file, projectDir);
+      const filePath = path.resolve(projectDir, file);
+
+      if (!fs.existsSync(filePath)) {
+        return { blocked: true, blockReason: `File not found: ${file}` };
+      }
+
+      // File size guard
+      const fileSize = fs.statSync(filePath).size;
+      if (fileSize > MAX_READ_SIZE) {
+        return { blocked: true, blockReason: `File too large for patch-file (${fileSize} bytes, max ${MAX_READ_SIZE}).` };
+      }
+
+      let content = fs.readFileSync(filePath, 'utf-8');
+      const patches = (args.patches as Array<{ find: string; replace: string }>) ?? [];
+
+      if (!patches.length && args.find && args.replace !== undefined) {
+        patches.push({ find: args.find as string, replace: args.replace as string });
+      }
+
+      if (!patches.length) {
+        return { blocked: true, blockReason: 'patch-file requires "patches" array or "find"+"replace" args.' };
+      }
+
+      let applied = 0;
+      const notFound: string[] = [];
+
+      for (const patch of patches) {
+        if (content.includes(patch.find)) {
+          content = content.split(patch.find).join(patch.replace); // replaceAll without regex
+          applied++;
+        } else {
+          notFound.push(patch.find.substring(0, 60));
+        }
+      }
+
+      if (applied === 0) {
+        return {
+          file: filePath,
+          output: `No patches applied. Search strings not found: ${notFound.join('; ')}`,
+        };
+      }
+
+      fs.writeFileSync(filePath, content, 'utf-8');
+      filesWrittenThisPlan++;
+
+      const summary = `Applied ${applied}/${patches.length} patches` +
+        (notFound.length ? `. Not found: ${notFound.join('; ')}` : '');
+      return { file: filePath, output: summary };
+    }
+
+    // -----------------------------------------------------------------
+    // Read file: return content for AI context
+    // -----------------------------------------------------------------
+    case 'read-file': {
+      if (!file) {
+        return { output: '' };
+      }
+      assertSafePath(file, projectDir);
+      const filePath = path.resolve(projectDir, file);
+      if (!fs.existsSync(filePath)) {
+        return { output: `File not found: ${file}` };
+      }
+      if (fs.statSync(filePath).isDirectory()) {
+        const entries = fs.readdirSync(filePath, { encoding: 'utf-8' });
+        return { output: `"${file}" is a directory. Contents:\n${entries.join('\n')}` };
+      }
+      const fileSize = fs.statSync(filePath).size;
+      if (fileSize > MAX_READ_SIZE) {
+        return { output: `File too large to read (${fileSize} bytes, max ${MAX_READ_SIZE}). Use run-shell with head/tail instead.` };
+      }
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return { file: filePath, output: content };
+    }
+
+    // -----------------------------------------------------------------
+    // Shell command: run arbitrary command with safety guards
+    // -----------------------------------------------------------------
+    case 'run-shell': {
+      const command = (args.command as string) ?? '';
+      if (!command.trim()) {
+        return { blocked: true, blockReason: 'run-shell requires a "command" argument.' };
+      }
+
+      const shellGuard = checkShellSafety(command);
+      if (!shellGuard.allowed) {
+        return { blocked: true, blockReason: shellGuard.reason };
+      }
+
+      try {
+        const output = execSync(command, {
+          cwd: projectDir,
+          encoding: 'utf-8',
+          timeout: SHELL_TIMEOUT,
+          maxBuffer: 1024 * 1024, // 1MB output cap
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { output: output.trim() };
+      } catch (err: unknown) {
+        // Shell commands that exit non-zero still return useful output
+        const execErr = err as { stdout?: string; stderr?: string; status?: number };
+        const stdout = (execErr.stdout ?? '').trim();
+        const stderr = (execErr.stderr ?? '').trim();
+        const combined = [stdout, stderr].filter(Boolean).join('\n');
+        return {
+          output: combined || (err instanceof Error ? err.message : String(err)),
+        };
+      }
+    }
+
+    // -----------------------------------------------------------------
+    // List files: glob-like directory listing
+    // -----------------------------------------------------------------
+    case 'list-files': {
+      const dir = (args.directory as string) ?? (args.dir as string) ?? '.';
+      const pattern = (args.pattern as string) ?? '';
+      assertSafePath(dir, projectDir);
+      const targetDir = path.resolve(projectDir, dir);
+
+      if (!fs.existsSync(targetDir)) {
+        return { output: `Directory not found: ${dir}` };
+      }
+
+      const entries = fs.readdirSync(targetDir, { recursive: true, encoding: 'utf-8' }) as string[];
+      let files = entries
+        .filter(e => {
+          if (e.includes('node_modules') || e.includes('.git')) return false;
+          const full = path.join(targetDir, e);
+          try { return fs.statSync(full).isFile(); } catch { return false; }
+        })
+        .sort();
+
+      if (pattern) {
+        try {
+          const regex = new RegExp(pattern);
+          files = files.filter(f => regex.test(f));
+        } catch {
+          return { output: `Invalid regex pattern: ${pattern}` };
+        }
+      }
+
+      if (files.length > MAX_LIST_FILES) {
+        files = files.slice(0, MAX_LIST_FILES);
+      }
+
+      return { files: files.map(f => path.join(dir, f)), output: files.join('\n') };
+    }
+
+    // -----------------------------------------------------------------
+    // Flow-weaver CLI commands (via programmatic API)
+    // -----------------------------------------------------------------
     default: {
       const result = await runCommand(step.operation, { ...args, cwd: projectDir });
       return {