@synergenius/flow-weaver-pack-weaver 0.8.1

package/src/bot/design-checker.ts

@@ -0,0 +1,327 @@
+/**
+ * Weaver Design Quality Checker
+ *
+ * Heuristic, context-dependent design checks that the bot evaluates during
+ * its exec-validate-retry loop and genesis proposal validation. These are
+ * opinionated recommendations, not core validator rules.
+ *
+ * Checks structural quality, complexity limits, and completeness.
+ */
+
+import type { TWorkflowAST, TNodeInstanceAST, TNodeTypeAST } from '@synergenius/flow-weaver';
+
+export interface DesignCheck {
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  message: string;
+  nodeId?: string;
+}
+
+export interface DesignReport {
+  score: number; // 0-100
+  checks: DesignCheck[];
+  passed: number;
+  failed: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resolveNodeType(ast: TWorkflowAST, instance: TNodeInstanceAST): TNodeTypeAST | undefined {
+  return ast.nodeTypes.find(
+    (nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType,
+  );
+}
+
+function getOutgoing(ast: TWorkflowAST, nodeId: string, portName?: string) {
+  return ast.connections.filter((c) => {
+    if (c.from.node !== nodeId) return false;
+    if (portName && c.from.port !== portName) return false;
+    return true;
+  });
+}
+
+function getIncoming(ast: TWorkflowAST, nodeId: string) {
+  return ast.connections.filter((c) => c.to.node === nodeId);
+}
+
+const GENERIC_ID_PATTERN = /^(node|n|tmp|x|test|foo|bar)\d*$/i;
+
+// ---------------------------------------------------------------------------
+// Structural Quality Checks
+// ---------------------------------------------------------------------------
+
+function checkVisualAnnotations(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  for (const inst of ast.instances) {
+    const hasColor = inst.config?.color;
+    const hasIcon = inst.config?.icon;
+    if (!hasColor && !hasIcon) {
+      checks.push({
+        code: 'WEAVER_MISSING_VISUALS',
+        severity: 'info',
+        message: `Node '${inst.id}' has no @color or @icon set. Visual annotations help readability.`,
+        nodeId: inst.id,
+      });
+    }
+  }
+  return checks;
+}
+
+function checkDescriptiveIds(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  for (const inst of ast.instances) {
+    if (GENERIC_ID_PATTERN.test(inst.id)) {
+      checks.push({
+        code: 'WEAVER_GENERIC_NODE_ID',
+        severity: 'warning',
+        message: `Node instance ID '${inst.id}' is generic. Use a descriptive ID that reflects the node's purpose.`,
+        nodeId: inst.id,
+      });
+    }
+  }
+  return checks;
+}
+
+function checkFlowDirection(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  if (!ast.ui?.instances || ast.ui.instances.length < 2) return checks;
+
+  // Check if x-positions generally increase along step connections
+  const posMap = new Map<string, number>();
+  for (const uiNode of ast.ui.instances) {
+    posMap.set(uiNode.name, uiNode.x);
+  }
+
+  let violations = 0;
+  let total = 0;
+  for (const conn of ast.connections) {
+    const fromX = posMap.get(conn.from.node);
+    const toX = posMap.get(conn.to.node);
+    if (fromX !== undefined && toX !== undefined) {
+      total++;
+      if (toX < fromX - 50) violations++; // Allow small tolerance
+    }
+  }
+
+  if (total > 0 && violations / total > 0.3) {
+    checks.push({
+      code: 'WEAVER_LAYOUT_DIRECTION',
+      severity: 'info',
+      message: `${violations} of ${total} connections flow right-to-left. Consider a left-to-right or top-to-bottom layout for readability.`,
+    });
+  }
+
+  return checks;
+}
+
+function checkDescription(ast: TWorkflowAST): DesignCheck[] {
+  if (!ast.description) {
+    return [{
+      code: 'WEAVER_NO_DESCRIPTION',
+      severity: 'info',
+      message: 'Workflow has no JSDoc description. A short summary helps collaborators understand its purpose.',
+    }];
+  }
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Complexity Checks
+// ---------------------------------------------------------------------------
+
+function checkNodeCount(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  const count = ast.instances.length;
+
+  if (count > 50) {
+    checks.push({
+      code: 'WEAVER_TOO_MANY_NODES',
+      severity: 'error',
+      message: `Workflow has ${count} nodes (limit: 50). Extract sub-workflows to reduce complexity.`,
+    });
+  } else if (count > 30) {
+    checks.push({
+      code: 'WEAVER_TOO_MANY_NODES',
+      severity: 'warning',
+      message: `Workflow has ${count} nodes (recommended limit: 30). Consider extracting sub-workflows.`,
+    });
+  }
+
+  return checks;
+}
+
+function checkScopeNesting(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  if (!ast.scopes) return checks;
+
+  // Build parent chain: instance -> scope -> parent instance
+  const instanceScopeDepth = new Map<string, number>();
+
+  function getDepth(instanceId: string, visited: Set<string>): number {
+    if (visited.has(instanceId)) return 0;
+    visited.add(instanceId);
+
+    const cached = instanceScopeDepth.get(instanceId);
+    if (cached !== undefined) return cached;
+
+    const inst = ast.instances.find((i) => i.id === instanceId);
+    if (!inst?.parent) {
+      instanceScopeDepth.set(instanceId, 0);
+      return 0;
+    }
+
+    const parentDepth = getDepth(inst.parent.id, visited);
+    const depth = parentDepth + 1;
+    instanceScopeDepth.set(instanceId, depth);
+    return depth;
+  }
+
+  for (const inst of ast.instances) {
+    const depth = getDepth(inst.id, new Set());
+    if (depth > 3) {
+      checks.push({
+        code: 'WEAVER_DEEP_NESTING',
+        severity: 'warning',
+        message: `Node '${inst.id}' is nested ${depth} scopes deep (limit: 3). Deep nesting makes workflows hard to follow.`,
+        nodeId: inst.id,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function checkFanInComplexity(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+
+  for (const inst of ast.instances) {
+    const dataIn = getIncoming(ast, inst.id).filter(
+      (c) => c.to.port !== 'execute' && c.to.port !== 'start',
+    );
+    if (dataIn.length > 5) {
+      checks.push({
+        code: 'WEAVER_HIGH_FANIN',
+        severity: 'warning',
+        message: `Node '${inst.id}' receives ${dataIn.length} data connections (limit: 5). This may be a bottleneck.`,
+        nodeId: inst.id,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function checkFanOutComplexity(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+  const stepPorts = new Set(['onSuccess', 'onFailure', 'execute', 'start', 'success', 'failure']);
+
+  for (const inst of ast.instances) {
+    const stepOut = getOutgoing(ast, inst.id).filter((c) => stepPorts.has(c.from.port));
+    const uniqueTargets = new Set(stepOut.map((c) => c.to.node));
+    if (uniqueTargets.size > 4) {
+      checks.push({
+        code: 'WEAVER_HIGH_FANOUT',
+        severity: 'warning',
+        message: `Node '${inst.id}' fans out to ${uniqueTargets.size} step targets (limit: 4). High branching increases complexity.`,
+        nodeId: inst.id,
+      });
+    }
+  }
+
+  return checks;
+}
+
+// ---------------------------------------------------------------------------
+// Completeness Checks
+// ---------------------------------------------------------------------------
+
+function checkNotificationPresence(ast: TWorkflowAST): DesignCheck[] {
+  const checks: DesignCheck[] = [];
+
+  // Check if workflow has side-effect nodes (heuristic: async nodes with write/send/push-like names)
+  const sideEffectPattern = /write|send|push|post|create|delete|update|deploy|publish|upload|notify/i;
+  const hasSideEffects = ast.instances.some((inst) => {
+    const nt = resolveNodeType(ast, inst);
+    const nameHint = `${inst.id} ${nt?.name ?? ''} ${nt?.functionName ?? ''} ${nt?.label ?? ''}`;
+    return sideEffectPattern.test(nameHint);
+  });
+
+  if (!hasSideEffects) return checks;
+
+  // Check if there's a notification-like node
+  const notifyPattern = /notify|notification|alert|report|summary|slack|email|webhook|message/i;
+  const hasNotification = ast.instances.some((inst) => {
+    const nt = resolveNodeType(ast, inst);
+    const nameHint = `${inst.id} ${nt?.name ?? ''} ${nt?.functionName ?? ''} ${nt?.label ?? ''}`;
+    return notifyPattern.test(nameHint);
+  });
+
+  if (!hasNotification) {
+    checks.push({
+      code: 'WEAVER_NO_NOTIFICATION',
+      severity: 'info',
+      message: 'Workflow has side-effect nodes but no notification or reporting node. Consider adding one for observability.',
+    });
+  }
+
+  return checks;
+}
+
+// ---------------------------------------------------------------------------
+// Score calculation
+// ---------------------------------------------------------------------------
+
+const SEVERITY_WEIGHTS: Record<string, number> = {
+  error: 10,
+  warning: 3,
+  info: 1,
+};
+
+function calculateScore(checks: DesignCheck[]): number {
+  if (checks.length === 0) return 100;
+
+  let penalty = 0;
+  for (const check of checks) {
+    penalty += SEVERITY_WEIGHTS[check.severity] ?? 1;
+  }
+
+  // Cap at 0
+  return Math.max(0, 100 - penalty);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function checkDesignQuality(ast: TWorkflowAST): DesignReport {
+  const allCheckers = [
+    checkVisualAnnotations,
+    checkDescriptiveIds,
+    checkFlowDirection,
+    checkDescription,
+    checkNodeCount,
+    checkScopeNesting,
+    checkFanInComplexity,
+    checkFanOutComplexity,
+    checkNotificationPresence,
+  ];
+
+  const checks: DesignCheck[] = [];
+  for (const checker of allCheckers) {
+    checks.push(...checker(ast));
+  }
+
+  const failed = checks.length;
+  // Total possible checks is roughly: instances * 2 (visuals, id) + 4 (globals)
+  const totalPossible = ast.instances.length * 2 + 4;
+  const passed = Math.max(0, totalPossible - failed);
+
+  return {
+    score: calculateScore(checks),
+    checks,
+    passed,
+    failed,
+  };
+}

package/src/bot/file-lock.ts

@@ -0,0 +1,73 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface FileLockOptions {
+  retries?: number;
+  retryWait?: number;
+  staleMs?: number;
+}
+
+interface LockInfo {
+  pid: number;
+  timestamp: number;
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => T | Promise<T>,
+  options?: FileLockOptions,
+): Promise<T> {
+  const retries = options?.retries ?? 50;
+  const retryWait = options?.retryWait ?? 50;
+  const staleMs = options?.staleMs ?? 10_000;
+  const lockDir = lockPath + '.lock';
+  const infoFile = path.join(lockDir, 'info.json');
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      fs.mkdirSync(lockDir, { recursive: false });
+
+      fs.writeFileSync(infoFile, JSON.stringify({ pid: process.pid, timestamp: Date.now() }), 'utf-8');
+
+      try {
+        return await fn();
+      } finally {
+        try { fs.rmSync(lockDir, { recursive: true }); } catch { /* ignore */ }
+      }
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+
+      // Lock exists, check if stale
+      try {
+        const raw = fs.readFileSync(infoFile, 'utf-8');
+        const info = JSON.parse(raw) as LockInfo;
+        const isStale = Date.now() - info.timestamp > staleMs;
+        const isDead = !isPidAlive(info.pid);
+
+        if (isStale || isDead) {
+          try { fs.rmSync(lockDir, { recursive: true }); } catch { /* ignore */ }
+          continue;
+        }
+      } catch {
+        // Can't read lock info, try to clean up
+        try { fs.rmSync(lockDir, { recursive: true }); } catch { /* ignore */ }
+        continue;
+      }
+
+      if (attempt < retries) {
+        await new Promise(r => setTimeout(r, retryWait));
+      }
+    }
+  }
+
+  throw new Error(`Failed to acquire file lock after ${retries} retries: ${lockPath}`);
+}

package/src/bot/file-validator.ts

@@ -0,0 +1,41 @@
+import { checkDesignQuality, type DesignReport } from './design-checker.js';
+import { fwValidate } from './fw-api.js';
+
+export interface FileValidationResult {
+  file: string;
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  designReport?: DesignReport;
+}
+
+export async function validateFiles(
+  files: string[],
+  projectDir: string,
+): Promise<FileValidationResult[]> {
+  const results: FileValidationResult[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith('.ts')) continue;
+    try {
+      const { valid, errors, warnings, ast } = await fwValidate(file);
+
+      if (!valid) {
+        results.push({ file, valid: false, errors, warnings });
+        continue;
+      }
+
+      const designReport = checkDesignQuality(ast);
+      const designWarnings = designReport.checks
+        .filter((c) => c.severity === 'warning' || c.severity === 'error')
+        .map((c) => `[${c.code}] ${c.message}`);
+
+      results.push({ file, valid: true, errors: [], warnings: [...warnings, ...designWarnings], designReport });
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      results.push({ file, valid: false, errors: [msg], warnings: [] });
+    }
+  }
+
+  return results;
+}

package/src/bot/file-watcher.ts

@@ -0,0 +1,103 @@
+import * as fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+
+export interface FileWatcherOptions {
+  filePath: string;
+  debounceMs?: number;
+  pollingIntervalMs?: number;
+}
+
+export class FileWatcher extends EventEmitter {
+  private filePath: string;
+  private debounceMs: number;
+  private pollingIntervalMs: number;
+  private watcher: fs.FSWatcher | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastMtime: number = 0;
+  private stopped = false;
+
+  constructor(options: FileWatcherOptions) {
+    super();
+    this.filePath = options.filePath;
+    this.debounceMs = options.debounceMs ?? 500;
+    this.pollingIntervalMs = options.pollingIntervalMs ?? 2000;
+  }
+
+  start(): void {
+    this.stopped = false;
+    this.lastMtime = this.getMtime();
+    this.attachFsWatch();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  private attachFsWatch(): void {
+    try {
+      this.watcher = fs.watch(this.filePath, () => this.onFsEvent());
+      this.watcher.on('error', () => this.switchToPolling());
+    } catch {
+      this.switchToPolling();
+    }
+  }
+
+  private switchToPolling(): void {
+    if (this.stopped) return;
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+    if (this.pollTimer) return;
+
+    this.pollTimer = setInterval(() => {
+      if (this.stopped) return;
+      const mtime = this.getMtime();
+      if (mtime > this.lastMtime) {
+        this.lastMtime = mtime;
+        this.emit('change');
+      }
+
+      // Try to re-attach fs.watch
+      if (!this.watcher && fs.existsSync(this.filePath)) {
+        try {
+          this.watcher = fs.watch(this.filePath, () => this.onFsEvent());
+          this.watcher.on('error', () => this.switchToPolling());
+          if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+          }
+        } catch {
+          // Stay in polling mode
+        }
+      }
+    }, this.pollingIntervalMs);
+  }
+
+  private onFsEvent(): void {
+    if (this.stopped) return;
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      const mtime = this.getMtime();
+      if (mtime > this.lastMtime) {
+        this.lastMtime = mtime;
+        this.emit('change');
+      }
+    }, this.debounceMs);
+  }
+
+  private getMtime(): number {
+    try {
+      return fs.statSync(this.filePath).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+}

package/src/bot/fw-api.ts

@@ -0,0 +1,18 @@
+import { parseWorkflow, validateWorkflow } from '@synergenius/flow-weaver';
+import type { TWorkflowAST } from '@synergenius/flow-weaver';
+
+export async function fwValidate(filePath: string): Promise<{
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  ast: TWorkflowAST;
+}> {
+  const parseResult = await parseWorkflow(filePath);
+  if (parseResult.errors.length > 0) {
+    return { valid: false, errors: parseResult.errors, warnings: parseResult.warnings, ast: parseResult.ast };
+  }
+  const validation = validateWorkflow(parseResult.ast);
+  const errors = validation.errors.map((e) => typeof e === 'string' ? e : e.message);
+  const warnings = validation.warnings.map((w) => typeof w === 'string' ? w : w.message);
+  return { valid: errors.length === 0, errors, warnings, ast: parseResult.ast };
+}

package/src/bot/genesis-prompt-context.ts

@@ -0,0 +1,135 @@
+/**
+ * Shared prompt helpers for genesis propose and revise steps.
+ * Centralises context building so the AI always gets the CLI grammar,
+ * operation syntax, and workflow structure it needs to produce valid proposals.
+ */
+
+import { buildSystemPrompt } from './system-prompt.js';
+import type { GenesisConfig } from './types.js';
+
+let cachedOpsContext: string | null = null;
+
+/**
+ * Full system prompt with annotation grammar, CLI commands, validation codes,
+ * and genesis protocol. Cached after first call.
+ */
+export async function getGenesisSystemPrompt(
+  config: GenesisConfig,
+  stabilized: boolean,
+  options?: { selfEvolveLocked?: boolean; graceRemaining?: number },
+): Promise<string> {
+  const base = await buildSystemPrompt();
+
+  const stabilizeClause = stabilized
+    ? '\n\nSTABILIZE MODE: Only removeNode, removeConnection, and implementNode operations are allowed. Do NOT propose addNode or addConnection.'
+    : '';
+
+  const selfEvolveClause = config.selfEvolve
+    ? [
+        '',
+        '## Self-Evolution',
+        `Self-evolution is ENABLED with a budget of ${config.selfEvolveBudget ?? 2} cost units.`,
+        'Cost map: selfModifyWorkflow=3, selfModifyNodeType=2, selfModifyModule=2.',
+        'Self-modify operations use { file: "relative/path.ts", content: "full file content" } in args.',
+        'The file path is relative to the pack root (e.g. "src/workflows/genesis-task.ts").',
+        'Content must be the complete replacement file, not a diff.',
+      ].join('\n')
+    : '';
+
+  const lockClause = options?.selfEvolveLocked
+    ? `\n\nSELF-EVOLUTION LOCKED: A migration is in grace period (${options.graceRemaining} cycles remaining). Do not propose selfModify operations.`
+    : '';
+
+  return [
+    base,
+    '',
+    '## Genesis Cycle Config',
+    `Intent: ${config.intent}`,
+    config.focus.length > 0 ? `Focus areas: ${config.focus.join(', ')}` : '',
+    config.constraints.length > 0 ? `Constraints: ${config.constraints.join(', ')}` : '',
+    `Budget: ${config.budgetPerCycle} cost units per cycle.`,
+    'Cost map: addNode=1, removeNode=1, addConnection=1, removeConnection=1, implementNode=2.',
+    stabilizeClause,
+    selfEvolveClause,
+    lockClause,
+  ].filter(Boolean).join('\n');
+}
+
+/**
+ * Operation format reference with concrete examples.
+ * Appended to both propose and revise prompts so the AI knows
+ * the exact CLI arg format.
+ */
+export function getOperationExamples(targetPath: string): string {
+  return `## Operation Format
+
+Each operation is { type, args, costUnits, rationale }.
+
+### addNode
+args: { "nodeId": "myNode", "nodeType": "someFunction", "file": "${targetPath}" }
+
+### removeNode
+args: { "nodeId": "myNode", "file": "${targetPath}" }
+
+### addConnection
+args: { "from": "sourceNode.portName", "to": "targetNode.portName", "file": "${targetPath}" }
+IMPORTANT: Connection format is "node.port" using a DOT separator. NOT "node:port", NOT "node:portName".
+
+### removeConnection
+args: { "from": "sourceNode.portName", "to": "targetNode.portName", "file": "${targetPath}" }
+
+### implementNode
+args: { "nodeId": "existingStubNodeId", "file": "${targetPath}" }
+Only works on nodes declared with \`declare function\` (stubs). The nodeId must match an existing stub in the workflow.
+
+### selfModifyWorkflow (cost: 3)
+args: { "file": "src/workflows/genesis-task.ts", "content": "// full file content..." }
+Replaces the genesis workflow file. File path is relative to pack root.
+
+### selfModifyNodeType (cost: 2)
+args: { "file": "src/node-types/genesis-propose.ts", "content": "// full file content..." }
+Replaces a genesis node type implementation.
+
+### selfModifyModule (cost: 2)
+args: { "file": "src/bot/genesis-prompt-context.ts", "content": "// full file content..." }
+Replaces a bot module file.
+
+## Response Format
+Return ONLY valid JSON with: { operations: [...], totalCost: number, impactLevel: "COSMETIC"|"MINOR"|"BREAKING"|"CRITICAL", summary: string, rationale: string }
+No markdown, no code fences, no explanation outside the JSON.`;
+}
+
+/**
+ * Ops context from flow-weaver docs (CLI reference, error codes, etc.).
+ * Falls back gracefully if the context module is unavailable.
+ */
+export async function getOpsContext(): Promise<string> {
+  if (cachedOpsContext) return cachedOpsContext;
+
+  try {
+    const { buildContext } = await import('@synergenius/flow-weaver/context');
+    const result = buildContext({ preset: 'ops', includeGrammar: false });
+    cachedOpsContext = result.content;
+  } catch {
+    cachedOpsContext = '(ops context unavailable)';
+  }
+
+  return cachedOpsContext!;
+}
+
+/**
+ * Gets a text description of the workflow using the describe module.
+ * Falls back to reading the raw file if describe isn't available.
+ */
+export async function getWorkflowDescription(filePath: string): Promise<string> {
+  try {
+    const { parseWorkflow } = await import('@synergenius/flow-weaver/api');
+    const { describeWorkflow, formatTextOutput } = await import('@synergenius/flow-weaver/describe');
+
+    const result = await parseWorkflow(filePath);
+    const output = describeWorkflow(result.ast);
+    return formatTextOutput(result.ast, output);
+  } catch {
+    return '(workflow description unavailable)';
+  }
+}