@synergenius/flow-weaver-pack-weaver 0.8.1

package/src/node-types/genesis-try-apply.ts

@@ -0,0 +1,165 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import type { GenesisConfig, GenesisProposal, GenesisOperation, GenesisContext } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Applies proposal operations then validates + compiles. On compile
+ * failure, restores the snapshot and returns the failure path with
+ * error details so the parent scope can retry with a revised proposal.
+ *
+ * @flowWeaver nodeType
+ * @label Genesis Try Apply
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with apply results (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export async function genesisTryApply(
+  execute: boolean,
+  ctx: string,
+): Promise<{
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+}> {
+  const context = JSON.parse(ctx) as GenesisContext;
+
+  if (!execute) {
+    const result = { applied: 0, failed: 0, errors: [] };
+    context.applyResultJson = JSON.stringify(result);
+    context.error = '';
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  const { env } = context;
+  const config = JSON.parse(context.genesisConfigJson) as GenesisConfig;
+  const proposal = JSON.parse(context.proposalJson!) as GenesisProposal;
+  const targetPath = path.resolve(env.projectDir, config.targetWorkflow);
+
+  // Apply operations
+  let applied = 0;
+  let failed = 0;
+  const errors: string[] = [];
+
+  for (const op of proposal.operations) {
+    const validationError = validateOperationArgs(op);
+    if (validationError) {
+      failed++;
+      errors.push(validationError);
+      console.error(`\x1b[31m  x ${op.type} (pre-validation): ${validationError}\x1b[0m`);
+      continue;
+    }
+
+    try {
+      const cliArgs = buildModifyArgs(op, targetPath);
+      execFileSync('flow-weaver', cliArgs, {
+        cwd: env.projectDir,
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 30_000,
+      });
+      applied++;
+      console.log(`\x1b[32m  + ${op.type}: ${op.rationale}\x1b[0m`);
+    } catch (err: unknown) {
+      failed++;
+      const msg = err instanceof Error ? err.message : String(err);
+      errors.push(`${op.type}: ${msg}`);
+      console.error(`\x1b[31m  x ${op.type}: ${msg}\x1b[0m`);
+    }
+  }
+
+  const applyResult = { applied, failed, errors };
+  context.applyResultJson = JSON.stringify(applyResult);
+
+  console.log(`\x1b[36m→ Apply: ${applied} succeeded, ${failed} failed\x1b[0m`);
+
+  // If all operations failed, no point compiling
+  if (applied === 0) {
+    context.error = '';
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+
+  // Validate + compile
+  try {
+    execFileSync('flow-weaver', ['validate', targetPath], {
+      cwd: env.projectDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30_000,
+    });
+    console.log('\x1b[32m→ Validation passed\x1b[0m');
+
+    execFileSync('flow-weaver', ['compile', targetPath], {
+      cwd: env.projectDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 60_000,
+    });
+    console.log('\x1b[32m→ Compilation passed\x1b[0m');
+
+    context.error = '';
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m→ Compile/validate failed: ${msg}\x1b[0m`);
+
+    // Restore from snapshot
+    const store = new GenesisStore(env.projectDir);
+    const snapshot = store.loadSnapshot(context.snapshotPath!);
+    if (snapshot) {
+      fs.writeFileSync(targetPath, snapshot, 'utf-8');
+      console.log('\x1b[33m→ Restored from snapshot\x1b[0m');
+    }
+
+    context.error = msg;
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+}
+
+function validateOperationArgs(op: GenesisOperation): string | null {
+  const { type, args } = op;
+
+  if (type === 'addConnection' || type === 'removeConnection') {
+    const from = args.from as string | undefined;
+    const to = args.to as string | undefined;
+    if (!from || !to) return `${type}: missing 'from' or 'to' arg`;
+    if (!from.includes('.') || from.includes(':'))
+      return `${type}: 'from' must be "node.port" format (dot separator), got "${from}"`;
+    if (!to.includes('.') || to.includes(':'))
+      return `${type}: 'to' must be "node.port" format (dot separator), got "${to}"`;
+  }
+
+  if (type === 'addNode') {
+    if (!args.nodeId || !args.nodeType)
+      return `addNode: missing 'nodeId' or 'nodeType'`;
+  }
+
+  if (type === 'removeNode') {
+    if (!args.nodeId) return `removeNode: missing 'nodeId'`;
+  }
+
+  if (type === 'implementNode') {
+    if (!args.nodeId || args.nodeId === 'undefined')
+      return `implementNode: missing or invalid 'nodeId'`;
+  }
+
+  return null;
+}
+
+function buildModifyArgs(op: GenesisOperation, targetPath: string): string[] {
+  switch (op.type) {
+    case 'addNode':
+      return ['modify', 'addNode', '--file', targetPath, '--nodeId', String(op.args.nodeId), '--nodeType', String(op.args.nodeType)];
+    case 'removeNode':
+      return ['modify', 'removeNode', '--file', targetPath, '--nodeId', String(op.args.nodeId)];
+    case 'addConnection':
+      return ['modify', 'addConnection', '--file', targetPath, '--from', String(op.args.from), '--to', String(op.args.to)];
+    case 'removeConnection':
+      return ['modify', 'removeConnection', '--file', targetPath, '--from', String(op.args.from), '--to', String(op.args.to)];
+    case 'implementNode':
+      return ['implement', targetPath, '--nodeId', String(op.args.nodeId)];
+    default:
+      throw new Error(`Unknown genesis operation type: ${op.type}`);
+  }
+}

package/src/node-types/genesis-update-history.ts

@@ -0,0 +1,72 @@
+import type { GenesisFingerprint, GenesisProposal, GenesisCycleRecord, GenesisContext } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Builds a cycle record from all available data, determines the outcome,
+ * appends it to the genesis history, and saves the current fingerprint.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Genesis Update History
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with cycleRecordJson (JSON)
+ * @output onFailure [hidden]
+ */
+export function genesisUpdateHistory(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const { env } = context;
+
+  const fingerprint = context.fingerprintJson
+    ? JSON.parse(context.fingerprintJson) as GenesisFingerprint
+    : null;
+  const proposal = context.proposalJson ? JSON.parse(context.proposalJson) as GenesisProposal : null;
+  const applyResult = context.applyResultJson ? JSON.parse(context.applyResultJson) as { applied: number; failed: number; errors: string[] } : null;
+
+  const durationMs = context.startTimeMs ? Date.now() - context.startTimeMs : 0;
+
+  // Determine outcome
+  let outcome: GenesisCycleRecord['outcome'];
+  if (context.error) {
+    outcome = 'error';
+  } else if (!proposal || proposal.operations.length === 0) {
+    outcome = 'no-change';
+  } else if (context.approved === false) {
+    outcome = 'rejected';
+  } else if (applyResult && applyResult.failed > 0) {
+    outcome = 'rolled-back';
+  } else if (context.approved === true && applyResult && applyResult.failed === 0) {
+    outcome = 'applied';
+  } else {
+    outcome = 'error';
+  }
+
+  const record: GenesisCycleRecord = {
+    id: context.cycleId,
+    timestamp: new Date().toISOString(),
+    durationMs,
+    fingerprint: fingerprint!,
+    proposal,
+    outcome,
+    diffSummary: proposal?.summary ?? null,
+    approvalRequired: context.approved !== undefined,
+    approved: context.approved ?? null,
+    error: context.error ?? (applyResult?.errors?.length ? applyResult.errors.join('; ') : null),
+    snapshotFile: context.snapshotPath ?? null,
+  };
+
+  try {
+    const store = new GenesisStore(env.projectDir);
+    store.appendCycle(record);
+    if (fingerprint) {
+      store.saveFingerprint(fingerprint);
+    }
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m→ Failed to save history: ${msg}\x1b[0m`);
+  }
+
+  console.log(`\x1b[36m→ Cycle ${context.cycleId}: ${outcome} (${durationMs}ms)\x1b[0m`);
+
+  context.cycleRecordJson = JSON.stringify(record);
+  return { ctx: JSON.stringify(context) };
+}

package/src/node-types/genesis-validate-proposal.ts

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import type { GenesisConfig, GenesisProposal, GenesisOperation, GenesisContext } from '../bot/types.js';
+import { checkDesignQuality } from '../bot/design-checker.js';
+
+const COST_MAP: Record<string, number> = {
+  addNode: 1,
+  removeNode: 1,
+  addConnection: 1,
+  removeConnection: 1,
+  implementNode: 2,
+  selfModifyWorkflow: 3,
+  selfModifyNodeType: 2,
+  selfModifyModule: 2,
+};
+
+const SELF_MODIFY_TYPES = new Set(['selfModifyWorkflow', 'selfModifyNodeType', 'selfModifyModule']);
+
+/**
+ * Validates and trims a genesis proposal to fit within the budget.
+ * Recalculates costs (never trusts the AI), filters out disallowed
+ * operations in stabilize mode, and trims from the end if over budget.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Genesis Validate Proposal
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with validated proposalJson (JSON)
+ * @output onFailure [hidden]
+ */
+export function genesisValidateProposal(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const config = JSON.parse(context.genesisConfigJson) as GenesisConfig;
+  const proposal = JSON.parse(context.proposalJson!) as GenesisProposal;
+
+  let ops = proposal.operations;
+
+  // In stabilize mode, hard-reject addNode and addConnection
+  if (context.stabilized) {
+    const before = ops.length;
+    ops = ops.filter(op => op.type !== 'addNode' && op.type !== 'addConnection');
+    if (ops.length < before) {
+      console.log(`\x1b[33m→ Stabilize: filtered ${before - ops.length} disallowed operations\x1b[0m`);
+    }
+  }
+
+  // Filter self-modify ops if selfEvolve is disabled
+  if (!config.selfEvolve) {
+    const before = ops.length;
+    ops = ops.filter(op => !SELF_MODIFY_TYPES.has(op.type));
+    if (ops.length < before) {
+      console.log(`\x1b[33m→ Self-evolve disabled: filtered ${before - ops.length} self-modify operations\x1b[0m`);
+    }
+  }
+
+  // Validate self-modify ops have required args
+  ops = ops.filter(op => {
+    if (SELF_MODIFY_TYPES.has(op.type)) {
+      if (!op.args.file || !op.args.content) {
+        console.log(`\x1b[33m→ Filtered ${op.type}: missing file or content\x1b[0m`);
+        return false;
+      }
+    }
+    return true;
+  });
+
+  // Recalculate costs (never trust the AI values)
+  for (const op of ops) {
+    op.costUnits = COST_MAP[op.type] ?? 1;
+  }
+
+  // Split into regular and self-modify ops for separate budget enforcement
+  const regularOps = ops.filter(op => !SELF_MODIFY_TYPES.has(op.type));
+  let selfOps = ops.filter(op => SELF_MODIFY_TYPES.has(op.type));
+
+  // Trim regular ops to regular budget
+  let regularCost = regularOps.reduce((sum, op) => sum + op.costUnits, 0);
+  while (regularCost > config.budgetPerCycle && regularOps.length > 0) {
+    regularOps.pop();
+    regularCost = regularOps.reduce((sum, op) => sum + op.costUnits, 0);
+  }
+
+  // Trim self-modify ops to self-evolve budget
+  const selfBudget = config.selfEvolveBudget ?? 2;
+  let selfCost = selfOps.reduce((sum, op) => sum + op.costUnits, 0);
+  while (selfCost > selfBudget && selfOps.length > 0) {
+    selfOps.pop();
+    selfCost = selfOps.reduce((sum, op) => sum + op.costUnits, 0);
+  }
+
+  ops = [...regularOps, ...selfOps];
+  let totalCost = regularCost + selfCost;
+
+  const validated: GenesisProposal = {
+    ...proposal,
+    operations: ops,
+    totalCost,
+  };
+
+  console.log(`\x1b[36m→ Validated proposal: ${ops.length} ops, cost=${totalCost}/${config.budgetPerCycle}\x1b[0m`);
+
+  // Design quality gate: parse current workflow and check design score.
+  // If the score is below the threshold, flag for review.
+  const designThreshold = 50;
+  try {
+    const targetPath = config.targetWorkflow;
+    if (targetPath) {
+      const { projectDir } = context.env;
+      const astJson = execFileSync('flow-weaver', ['parse', targetPath, '--format', 'json'], {
+        cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30_000,
+      });
+      const ast = JSON.parse(astJson);
+      const report = checkDesignQuality(ast);
+      if (report.score < designThreshold) {
+        console.log(`\x1b[33m→ Design score ${report.score} below threshold ${designThreshold}\x1b[0m`);
+        context.approvalRequired = true;
+      }
+    }
+  } catch {
+    // Non-fatal: if we can't parse the workflow yet, skip the design check
+  }
+
+  context.proposalJson = JSON.stringify(validated);
+  return { ctx: JSON.stringify(context) };
+}

package/src/node-types/git-ops.ts

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process';
+import type { WeaverContext } from '../bot/types.js';
+import { auditEmit } from '../bot/audit-logger.js';
+
+/**
+ * Git operations on created/modified files: stage, commit, branch.
+ * Runs in parallel with notifications after execution.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Git Operations
+ * @input ctx [order:0] - Weaver context (JSON)
+ * @output ctx [order:0] - Weaver context with gitResultJson (JSON)
+ * @output onFailure [hidden]
+ */
+export function weaverGitOps(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as WeaverContext;
+  const { projectDir, config } = context.env;
+  const files: string[] = context.filesModified ? JSON.parse(context.filesModified) : [];
+  const gitConfig = (config as unknown as { git?: { enabled?: boolean; branch?: string; commitPrefix?: string } }).git ?? {};
+
+  if (gitConfig.enabled === false || files.length === 0) {
+    context.gitResultJson = JSON.stringify({ skipped: true, reason: files.length === 0 ? 'no files' : 'git disabled' });
+    return { ctx: JSON.stringify(context) };
+  }
+
+  // Check if we're in a git repo
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    context.gitResultJson = JSON.stringify({ skipped: true, reason: 'not a git repo' });
+    return { ctx: JSON.stringify(context) };
+  }
+
+  const results: string[] = [];
+
+  // Create branch if specified
+  if (gitConfig.branch) {
+    try {
+      execFileSync('git', ['checkout', '-b', gitConfig.branch], { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+      results.push(`Created branch: ${gitConfig.branch}`);
+    } catch {
+      // Branch may already exist
+      try {
+        execFileSync('git', ['checkout', gitConfig.branch], { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        results.push(`Switched to branch: ${gitConfig.branch}`);
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Stage files
+  for (const file of files) {
+    try {
+      execFileSync('git', ['add', file], { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch { /* ignore unstaged files */ }
+  }
+
+  // Commit
+  const prefix = gitConfig.commitPrefix ?? 'weaver:';
+  const commitMsg = `${prefix} bot task (${files.length} file${files.length === 1 ? '' : 's'})`;
+  try {
+    execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    results.push(`Committed: ${commitMsg}`);
+    console.log(`\x1b[36m→ Git: ${commitMsg}\x1b[0m`);
+  } catch {
+    results.push('Nothing to commit');
+  }
+
+  auditEmit('git-operation', { branch: gitConfig.branch, filesCount: files.length, results });
+  context.gitResultJson = JSON.stringify({ skipped: false, results });
+  return { ctx: JSON.stringify(context) };
+}

package/src/node-types/index.ts

@@ -0,0 +1,36 @@
+export { weaverLoadConfig } from './load-config.js';
+export { weaverDetectProvider } from './detect-provider.js';
+export { weaverResolveTarget } from './resolve-target.js';
+export { weaverExecuteTarget } from './execute-target.js';
+export { weaverSendNotify } from './send-notify.js';
+export { weaverReport } from './report.js';
+export { weaverReceiveTask } from './receive-task.js';
+export { weaverRouteTask } from './route-task.js';
+export { weaverReadWorkflow } from './read-workflow.js';
+export { weaverBuildContext } from './build-context.js';
+export { weaverPlanTask } from './plan-task.js';
+export { weaverApprovalGate } from './approval-gate.js';
+export { weaverAbortTask } from './abort-task.js';
+export { weaverExecValidateRetry } from './exec-validate-retry.js';
+export { weaverExecutePlan } from './execute-plan.js';
+export { weaverValidateResult } from './validate-result.js';
+export { weaverFixErrors } from './fix-errors.js';
+export { weaverGitOps } from './git-ops.js';
+export { weaverBotReport } from './bot-report.js';
+export { genesisLoadConfig } from './genesis-load-config.js';
+export { genesisObserve } from './genesis-observe.js';
+export { genesisDiffFingerprint } from './genesis-diff-fingerprint.js';
+export { genesisCheckStabilize } from './genesis-check-stabilize.js';
+export { genesisPropose } from './genesis-propose.js';
+export { genesisValidateProposal } from './genesis-validate-proposal.js';
+export { genesisSnapshot } from './genesis-snapshot.js';
+export { genesisApply } from './genesis-apply.js';
+export { genesisCompileValidate } from './genesis-compile-validate.js';
+export { genesisApplyRetry } from './genesis-apply-retry.js';
+export { genesisTryApply } from './genesis-try-apply.js';
+export { genesisDiffWorkflow } from './genesis-diff-workflow.js';
+export { genesisCheckThreshold } from './genesis-check-threshold.js';
+export { genesisApprove } from './genesis-approve.js';
+export { genesisCommit } from './genesis-commit.js';
+export { genesisUpdateHistory } from './genesis-update-history.js';
+export { genesisReport } from './genesis-report.js';

package/src/node-types/load-config.ts

@@ -0,0 +1,27 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { WeaverConfig } from '../bot/types.js';
+
+/**
+ * Read .weaver.json, merge with defaults, and output the config object.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Load Config
+ * @input [projectDir] [order:0] - Project root directory (defaults to cwd)
+ * @output projectDir [order:0] - Project root directory (pass-through)
+ * @output config [order:1] - Weaver configuration
+ * @output onFailure [hidden]
+ */
+export function weaverLoadConfig(projectDir?: string): { projectDir: string; config: WeaverConfig } {
+  const dir = projectDir || process.cwd();
+  const configPath = path.join(dir, '.weaver.json');
+  let config: WeaverConfig = { provider: 'auto' };
+  if (fs.existsSync(configPath)) {
+    config = { ...config, ...JSON.parse(fs.readFileSync(configPath, 'utf-8')) };
+    console.log(`\x1b[36m→ Loaded config from ${configPath}\x1b[0m`);
+  } else {
+    console.log('\x1b[36m→ No .weaver.json found, using defaults (provider: auto)\x1b[0m');
+  }
+  return { projectDir: dir, config };
+}

package/src/node-types/plan-task.ts

@@ -0,0 +1,66 @@
+import type { WeaverContext } from '../bot/types.js';
+import { callAI, parseJsonResponse } from '../bot/ai-client.js';
+import { auditEmit } from '../bot/audit-logger.js';
+
+/**
+ * Sends task + context to the AI provider and gets back a structured
+ * execution plan. The core AI planning node.
+ *
+ * @flowWeaver nodeType
+ * @label Plan Task
+ * @input ctx [order:0] - Weaver context (JSON)
+ * @output ctx [order:0] - Weaver context with planJson (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export async function weaverPlanTask(
+  execute: boolean,
+  ctx: string,
+): Promise<{
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+}> {
+  const context = JSON.parse(ctx) as WeaverContext;
+  const { env } = context;
+
+  if (!execute) {
+    context.planJson = '{"steps":[],"summary":"dry run"}';
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  const { providerInfo: pInfo } = env;
+  const task = JSON.parse(context.taskJson!);
+
+  let systemPrompt: string;
+  try {
+    const mod = await import('../bot/system-prompt.js');
+    const basePrompt = await mod.buildSystemPrompt();
+    let cliCommands: { name: string; description: string; group?: string; botCompatible?: boolean; options?: { flags: string; arg?: string; description: string }[] }[] = [];
+    try {
+      const docMeta = await import('@synergenius/flow-weaver/doc-metadata');
+      cliCommands = docMeta.CLI_COMMANDS ?? [];
+    } catch { /* older flow-weaver version */ }
+    const botPrompt = mod.buildBotSystemPrompt(context.contextBundle!, cliCommands);
+    systemPrompt = basePrompt + '\n\n' + botPrompt;
+  } catch {
+    systemPrompt = 'You are Weaver, an AI workflow bot. Return ONLY valid JSON with a plan.';
+  }
+
+  const userPrompt = `Task: ${task.instruction}\nMode: ${task.mode ?? 'create'}\n${task.targets ? 'Targets: ' + task.targets.join(', ') : ''}\n\nPlan this task. Return a JSON plan with steps and summary.`;
+
+  try {
+    const text = await callAI(pInfo, systemPrompt, userPrompt, 8192);
+
+    const plan = parseJsonResponse(text);
+    console.log(`\x1b[36m→ Plan: ${(plan as { summary?: string }).summary ?? 'generated'}\x1b[0m`);
+    auditEmit('plan-created', { summary: (plan as { summary?: string }).summary, stepCount: (plan as { steps?: unknown[] }).steps?.length ?? 0 });
+
+    context.planJson = JSON.stringify(plan);
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m→ Planning failed: ${msg}\x1b[0m`);
+    context.planJson = JSON.stringify({ steps: [], summary: `Planning failed: ${msg}` });
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+}

package/src/node-types/read-workflow.ts

@@ -0,0 +1,68 @@
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { WeaverContext } from '../bot/types.js';
+
+/**
+ * Reads and analyzes a workflow file. Produces structured description
+ * with diagram using flow-weaver CLI commands.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Read Workflow
+ * @input ctx [order:0] - Weaver context (JSON)
+ * @output ctx [order:0] - Weaver context with resultJson (JSON)
+ * @output onFailure [hidden]
+ */
+export function weaverReadWorkflow(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as WeaverContext;
+  const task = JSON.parse(context.taskJson!) as { targets?: string[]; instruction?: string };
+  const targets = task.targets ?? [];
+  const { projectDir } = context.env;
+
+  if (targets.length === 0) {
+    context.resultJson = JSON.stringify({ success: false, error: 'No target files specified for read' });
+    context.filesModified = '[]';
+    return { ctx: JSON.stringify(context) };
+  }
+
+  const results: Array<{ file: string; source?: string; diagram?: string; description?: string; error?: string }> = [];
+
+  for (const target of targets) {
+    const filePath = path.isAbsolute(target) ? target : path.resolve(projectDir, target);
+
+    if (!fs.existsSync(filePath)) {
+      results.push({ file: target, error: `File not found: ${filePath}` });
+      continue;
+    }
+
+    const source = fs.readFileSync(filePath, 'utf-8');
+    let diagram = '';
+    let description = '';
+
+    try {
+      diagram = execFileSync('flow-weaver', ['diagram', filePath, '-f', 'ascii-compact'], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 30_000,
+        cwd: projectDir,
+      }).trim();
+    } catch { /* diagram generation failed, continue without it */ }
+
+    try {
+      description = execFileSync('flow-weaver', ['describe', filePath], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 30_000,
+        cwd: projectDir,
+      }).trim();
+    } catch { /* description failed, continue without it */ }
+
+    results.push({ file: target, source, diagram, description });
+    console.log(`\x1b[36m→ Read: ${target}\x1b[0m`);
+  }
+
+  context.resultJson = JSON.stringify({ success: true, results });
+  context.filesModified = '[]';
+  return { ctx: JSON.stringify(context) };
+}