@synergenius/flow-weaver-pack-weaver 0.8.3 → 0.9.3

package/src/bot/error-guide.ts

@@ -0,0 +1,34 @@
+/**
+ * Actionable error guidance — maps cryptic error messages
+ * to human-readable explanations with fix suggestions.
+ */
+
+const GUIDES: Array<{ pattern: RegExp; guidance: string }> = [
+  { pattern: /ETIMEDOUT/i, guidance: 'Network timeout. Check internet connection or increase timeout with --timeout.' },
+  { pattern: /ECONNRESET/i, guidance: 'Connection reset. The server closed the connection. Retry in a few seconds.' },
+  { pattern: /ECONNREFUSED/i, guidance: 'Connection refused. Is the service running? Check the provider URL.' },
+  { pattern: /401|authentication|invalid.*key/i, guidance: 'Authentication failed. Check ANTHROPIC_API_KEY or run "weaver init" to reconfigure.' },
+  { pattern: /403|forbidden/i, guidance: 'Access denied. Your API key may not have permission for this model.' },
+  { pattern: /429|rate.?limit|too many requests/i, guidance: 'Rate limited. Wait a few minutes or reduce --parallel.' },
+  { pattern: /502|bad gateway/i, guidance: 'Server error (502). The API is temporarily unavailable. Will auto-retry.' },
+  { pattern: /503|service unavailable|overloaded/i, guidance: 'Service overloaded. Will auto-retry with backoff.' },
+  { pattern: /exit code 143/i, guidance: 'Process was killed (SIGTERM). Likely our timeout or Ctrl+C.' },
+  { pattern: /exit code 137/i, guidance: 'Process was killed (OOM or SIGKILL). System may be low on memory.' },
+  { pattern: /ENOMEM/i, guidance: 'Out of memory. Close other applications or increase available RAM.' },
+  { pattern: /ENOSPC/i, guidance: 'Disk full. Free up disk space.' },
+  { pattern: /lock.*retries|failed to acquire.*lock/i, guidance: 'File lock contention. Another weaver process may be running. Check with "ps aux | grep weaver".' },
+  { pattern: /not a workflow|No @flowWeaver/i, guidance: 'File is not a Flow Weaver workflow. Ensure it has @flowWeaver annotations.' },
+  { pattern: /parse.*json|unexpected token/i, guidance: 'JSON parse error. The AI may have returned malformed output. Retry the task.' },
+  { pattern: /Queue full/i, guidance: 'Too many pending tasks (200 max). Process or clear existing tasks first.' },
+];
+
+/**
+ * Get actionable guidance for an error message.
+ * Returns null if no guidance is available.
+ */
+export function getErrorGuidance(msg: string): string | null {
+  for (const { pattern, guidance } of GUIDES) {
+    if (pattern.test(msg)) return guidance;
+  }
+  return null;
+}

package/src/bot/genesis-store.ts

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import type { GenesisConfig, GenesisHistory, GenesisCycleRecord, GenesisFingerprint, EscrowToken, GenesisSelfMigrationRecord } from './types.js';
+import { jsonParseOr } from './safe-json.js';
 
 const DEFAULT_CONFIG: GenesisConfig = {
   intent: 'Improve workflow reliability and efficiency',
@@ -32,7 +33,8 @@ export class GenesisStore {
       fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf-8');
       return { ...DEFAULT_CONFIG };
     }
-    const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const raw = jsonParseOr(content, {} as Record<string, unknown>, 'genesis config');
     return { ...DEFAULT_CONFIG, ...raw };
   }
 
@@ -46,7 +48,8 @@ export class GenesisStore {
     if (!fs.existsSync(historyPath)) {
       return { configHash: '', cycles: [] };
     }
-    return JSON.parse(fs.readFileSync(historyPath, 'utf-8'));
+    const content = fs.readFileSync(historyPath, 'utf-8');
+    return jsonParseOr<GenesisHistory>(content, { configHash: '', cycles: [] }, 'genesis history');
   }
 
   appendCycle(cycle: GenesisCycleRecord): void {
@@ -79,11 +82,8 @@ export class GenesisStore {
   getLastFingerprint(): GenesisFingerprint | null {
     const fpPath = path.join(this.genesisDir, 'fingerprint.json');
     if (!fs.existsSync(fpPath)) return null;
-    try {
-      return JSON.parse(fs.readFileSync(fpPath, 'utf-8'));
-    } catch {
-      return null;
-    }
+    const content = fs.readFileSync(fpPath, 'utf-8');
+    return jsonParseOr<GenesisFingerprint | null>(content, null, 'genesis fingerprint');
   }
 
   getRecentOutcomes(count: number): string[] {
@@ -109,11 +109,8 @@ export class GenesisStore {
   loadEscrowToken(): EscrowToken | null {
     const tokenPath = path.join(this.genesisDir, 'escrow', 'token.json');
     if (!fs.existsSync(tokenPath)) return null;
-    try {
-      return JSON.parse(fs.readFileSync(tokenPath, 'utf-8'));
-    } catch {
-      return null;
-    }
+    const content = fs.readFileSync(tokenPath, 'utf-8');
+    return jsonParseOr<EscrowToken | null>(content, null, 'escrow token');
   }
 
   saveEscrowToken(token: EscrowToken): void {
@@ -145,11 +142,8 @@ export class GenesisStore {
   loadSelfHistory(): GenesisSelfMigrationRecord[] {
     const histPath = path.join(this.genesisDir, 'self-history.json');
     if (!fs.existsSync(histPath)) return [];
-    try {
-      return JSON.parse(fs.readFileSync(histPath, 'utf-8'));
-    } catch {
-      return [];
-    }
+    const content = fs.readFileSync(histPath, 'utf-8');
+    return jsonParseOr<GenesisSelfMigrationRecord[]>(content, [], 'genesis self-history');
   }
 
   appendSelfMigration(record: GenesisSelfMigrationRecord): void {

package/src/bot/index.ts

@@ -112,6 +112,11 @@ export { GenesisStore } from './genesis-store.js';
 export { withFileLock } from './file-lock.js';
 export type { FileLockOptions } from './file-lock.js';
 
+// Safe utilities
+export { safeJsonParse, jsonParseOr, parseNdjson } from './safe-json.js';
+export type { SafeParseResult } from './safe-json.js';
+export { safePath, safePathOrThrow } from './safe-path.js';
+
 // Shared modules
 export { callCli, callApi, parseJsonResponse } from './ai-client.js';
 export { executeStep } from './step-executor.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/pipeline-runner.ts

@@ -31,7 +31,13 @@ export class PipelineRunner {
       throw new Error(`Pipeline config not found: ${absPath}`);
     }
 
-    const raw = JSON.parse(fs.readFileSync(absPath, 'utf-8')) as PipelineConfig;
+    let raw: PipelineConfig;
+    try {
+      raw = JSON.parse(fs.readFileSync(absPath, 'utf-8')) as PipelineConfig;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Invalid JSON in pipeline config: ${absPath}\n  ${msg}`);
+    }
     const configDir = path.dirname(absPath);
 
     // Resolve workflow paths relative to config file

package/src/bot/retry-utils.ts

@@ -0,0 +1,76 @@
+/**
+ * Retry utilities for transient error handling with exponential backoff.
+ */
+
+const TRANSIENT_STATUS_CODES = [429, 502, 503, 504];
+const TRANSIENT_ERROR_CODES = ['ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ENOTFOUND'];
+const TRANSIENT_MESSAGES = ['rate limit', 'too many requests', 'overloaded', 'bad gateway', 'service unavailable'];
+
+/**
+ * Check if an error is transient (retriable) vs permanent.
+ * Transient: network issues, rate limits, server errors.
+ * Permanent: auth failures, parse errors, validation errors.
+ */
+export function isTransientError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  const lower = msg.toLowerCase();
+
+  // Check for HTTP status codes in message
+  for (const code of TRANSIENT_STATUS_CODES) {
+    if (msg.includes(String(code))) return true;
+  }
+
+  // Check for Node.js error codes
+  if (err instanceof Error && 'code' in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code && TRANSIENT_ERROR_CODES.includes(code)) return true;
+  }
+
+  // Also check message for error code strings (e.g. "ETIMEDOUT" in message)
+  for (const code of TRANSIENT_ERROR_CODES) {
+    if (msg.includes(code)) return true;
+  }
+
+  // Check for rate limit / overload messages
+  for (const phrase of TRANSIENT_MESSAGES) {
+    if (lower.includes(phrase)) return true;
+  }
+
+  // Check for exit code 143 (SIGTERM — likely our timeout killed the process)
+  if (msg.includes('exit code 143') || msg.includes('exited with code 143')) return true;
+
+  return false;
+}
+
+/**
+ * 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/run-store.ts

@@ -3,6 +3,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as os from 'node:os';
 import type { RunRecord, RunFilter, RetentionPolicy } from './types.js';
+import { parseNdjson } from './safe-json.js';
 
 export class RunStore {
   private readonly dir: string;
@@ -153,17 +154,7 @@ export class RunStore {
     if (!fs.existsSync(this.filePath)) return [];
 
     const content = fs.readFileSync(this.filePath, 'utf-8');
-    const lines = content.split('\n').filter((line) => line.trim().length > 0);
-    const records: RunRecord[] = [];
-
-    for (const line of lines) {
-      try {
-        records.push(JSON.parse(line) as RunRecord);
-      } catch {
-        console.error('[weaver] Skipping corrupt history line');
-      }
-    }
-
+    const { records } = parseNdjson<RunRecord>(content, 'history');
     return records;
   }
 }

package/src/bot/runner.ts

@@ -58,17 +58,29 @@ function resolveWeaverConfig(
   const dir = path.dirname(filePath);
   const localConfig = path.join(dir, '.weaver.json');
   if (fs.existsSync(localConfig)) {
-    return JSON.parse(fs.readFileSync(localConfig, 'utf-8'));
+    return parseConfigFile(localConfig);
   }
 
   const cwdConfig = path.join(process.cwd(), '.weaver.json');
   if (fs.existsSync(cwdConfig)) {
-    return JSON.parse(fs.readFileSync(cwdConfig, 'utf-8'));
+    return parseConfigFile(cwdConfig);
   }
 
   return { provider: 'auto' };
 }
 
+function parseConfigFile(configPath: string): WeaverConfig {
+  const content = fs.readFileSync(configPath, 'utf-8');
+  try {
+    return JSON.parse(content) as WeaverConfig;
+  } catch {
+    throw new Error(
+      `Invalid JSON in config file: ${configPath}\n` +
+      `  Fix the file or delete it to use defaults.`,
+    );
+  }
+}
+
 function buildSummary(result: unknown): string {
   if (!result || typeof result !== 'object') return String(result);
 
@@ -212,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,
@@ -225,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 });
@@ -270,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/safe-json.ts

@@ -0,0 +1,76 @@
+/**
+ * Safe JSON parsing utilities.
+ *
+ * Wraps JSON.parse with proper error handling and optional context for
+ * meaningful error messages. Prevents crashes from malformed config files,
+ * corrupt NDJSON lines, or unexpected AI output.
+ */
+
+export type SafeParseResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: string;
+};
+
+/**
+ * Parse JSON safely, returning a discriminated result instead of throwing.
+ */
+export function safeJsonParse<T = unknown>(
+  text: string,
+  context?: string,
+): SafeParseResult<T> {
+  try {
+    return { ok: true, value: JSON.parse(text) as T };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const prefix = context ? `${context}: ` : '';
+    return { ok: false, error: `${prefix}Invalid JSON — ${msg}` };
+  }
+}
+
+/**
+ * Parse JSON or return a fallback value on failure.
+ * Optionally logs a warning when parsing fails.
+ */
+export function jsonParseOr<T>(
+  text: string,
+  fallback: T,
+  context?: string,
+): T {
+  const result = safeJsonParse<T>(text, context);
+  if (result.ok) return result.value;
+  if (context) {
+    console.error(`[weaver] ${result.error}`);
+  }
+  return fallback;
+}
+
+/**
+ * Parse NDJSON (newline-delimited JSON) safely.
+ * Skips corrupt lines and optionally reports them.
+ */
+export function parseNdjson<T>(
+  content: string,
+  context?: string,
+): { records: T[]; errors: number } {
+  const lines = content.split('\n').filter((line) => line.trim().length > 0);
+  const records: T[] = [];
+  let errors = 0;
+
+  for (const line of lines) {
+    const result = safeJsonParse<T>(line);
+    if (result.ok) {
+      records.push(result.value);
+    } else {
+      errors++;
+    }
+  }
+
+  if (errors > 0 && context) {
+    console.error(`[weaver] ${context}: skipped ${errors} corrupt line(s)`);
+  }
+
+  return { records, errors };
+}

package/src/bot/safe-path.ts

@@ -0,0 +1,44 @@
+/**
+ * Path safety utilities.
+ *
+ * Prevents path traversal attacks and ensures file operations stay within
+ * expected boundaries. Critical for any code that constructs paths from
+ * user input, AI output, or external configuration.
+ */
+
+import * as path from 'node:path';
+
+/**
+ * Validate that a relative path does not escape the base directory.
+ * Returns the resolved absolute path if safe, or null if the path
+ * attempts traversal.
+ */
+export function safePath(baseDir: string, relativePath: string): string | null {
+  const normalized = path.normalize(relativePath);
+
+  // Reject absolute paths and explicit traversal
+  if (path.isAbsolute(normalized)) return null;
+  if (normalized.startsWith('..')) return null;
+
+  const resolved = path.resolve(baseDir, normalized);
+  const resolvedBase = path.resolve(baseDir);
+
+  // Ensure resolved path is within baseDir
+  if (!resolved.startsWith(resolvedBase + path.sep) && resolved !== resolvedBase) {
+    return null;
+  }
+
+  return resolved;
+}
+
+/**
+ * Validate and resolve a path, throwing a descriptive error on traversal.
+ */
+export function safePathOrThrow(baseDir: string, relativePath: string, context?: string): string {
+  const resolved = safePath(baseDir, relativePath);
+  if (resolved === null) {
+    const prefix = context ? `${context}: ` : '';
+    throw new Error(`${prefix}Unsafe file path rejected: "${relativePath}"`);
+  }
+  return resolved;
+}

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

@@ -13,7 +13,7 @@ export class SteeringController {
   private controlPath: string;
 
   constructor(controlDir?: string) {
-    const dir = controlDir ?? path.join(os.homedir(), '.weaver');
+    const dir = controlDir ?? process.env.WEAVER_STEERING_DIR ?? path.join(os.homedir(), '.weaver');
     this.controlPath = path.join(dir, 'control.json');
   }