@synergenius/flow-weaver 0.23.5 → 0.24.1

package/dist/agent/index.d.ts

@@ -4,7 +4,8 @@
  * Provider-agnostic agent loop with MCP bridge for tool execution.
  * Built-in providers: Anthropic API, Claude CLI, OpenAI-compatible (GPT-4o, Groq, Ollama, etc).
  */
-export type { StreamEvent, AgentMessage, AgentProvider, ToolDefinition, ToolExecutor, ToolEvent, McpBridge, AgentLoopOptions, AgentLoopResult, StreamOptions, SpawnFn, ClaudeCliProviderOptions, CliSessionOptions, Logger, } from './types.js';
+export type { SplitPrompt, StreamEvent, AgentMessage, AgentProvider, ToolDefinition, ToolExecutor, ToolEvent, McpBridge, AgentLoopOptions, AgentLoopResult, StreamOptions, SpawnFn, ClaudeCliProviderOptions, CliSessionOptions, Logger, } from './types.js';
+export { joinSplitPrompt } from './types.js';
 export { runAgentLoop } from './agent-loop.js';
 export { AnthropicProvider, createAnthropicProvider } from './providers/anthropic.js';
 export type { AnthropicProviderOptions } from './providers/anthropic.js';

package/dist/agent/index.js

@@ -4,6 +4,8 @@
  * Provider-agnostic agent loop with MCP bridge for tool execution.
  * Built-in providers: Anthropic API, Claude CLI, OpenAI-compatible (GPT-4o, Groq, Ollama, etc).
  */
+// Prompt utilities
+export { joinSplitPrompt } from './types.js';
 // Agent loop
 export { runAgentLoop } from './agent-loop.js';
 // Providers

package/dist/agent/providers/anthropic.js

@@ -4,6 +4,19 @@
  *
  * Adapted from pack-weaver's streamAnthropicWithTools.
  */
+/**
+ * Convert a SplitPrompt to Anthropic's system content block array.
+ * The prefix gets cache_control for prompt caching; the suffix does not.
+ */
+function buildSystemBlocks(prompt) {
+    const blocks = [
+        { type: 'text', text: prompt.prefix, cache_control: { type: 'ephemeral' } },
+    ];
+    if (prompt.suffix) {
+        blocks.push({ type: 'text', text: prompt.suffix });
+    }
+    return blocks;
+}
 export class AnthropicProvider {
     apiKey;
     model;
@@ -49,7 +62,7 @@ export class AnthropicProvider {
             model,
             max_tokens: maxTokens,
             stream: true,
-            ...(options?.systemPrompt ? { system: options.systemPrompt } : {}),
+            ...(options?.systemPrompt ? { system: buildSystemBlocks(options.systemPrompt) } : {}),
             messages: apiMessages,
             ...(apiTools.length > 0 ? { tools: apiTools } : {}),
         });

package/dist/agent/providers/claude-cli.d.ts

@@ -5,7 +5,7 @@
  * Adapted from platform's streamClaudeCliChat. Platform-specific dependencies
  * (spawnSandboxed, getBinPath, config) are replaced with injectable options.
  */
-import type { AgentProvider, AgentMessage, ToolDefinition, StreamEvent, StreamOptions, ClaudeCliProviderOptions } from '../types.js';
+import { type AgentProvider, type AgentMessage, type ToolDefinition, type StreamEvent, type StreamOptions, type ClaudeCliProviderOptions } from '../types.js';
 export declare class ClaudeCliProvider implements AgentProvider {
     private binPath;
     private cwd;

package/dist/agent/providers/claude-cli.js

@@ -6,6 +6,7 @@
  * (spawnSandboxed, getBinPath, config) are replaced with injectable options.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
+import { joinSplitPrompt, } from '../types.js';
 import { StreamJsonParser } from '../streaming.js';
 import { createMcpBridge } from '../mcp-bridge.js';
 export class ClaudeCliProvider {
@@ -31,7 +32,9 @@ export class ClaudeCliProvider {
         const model = options?.model ?? this.model;
         // Format messages into a single prompt for -p mode
         const prompt = formatPrompt(messages);
-        const systemPrompt = options?.systemPrompt;
+        const systemPrompt = options?.systemPrompt
+            ? joinSplitPrompt(options.systemPrompt)
+            : undefined;
         // Set up MCP bridge for tool access if tools are provided and no config given
         let bridge = null;
         let mcpConfigPath = this.mcpConfigPath;

package/dist/agent/providers/openai-compat.d.ts

@@ -5,7 +5,7 @@
  * No SDK dependency. Uses only Node.js native fetch + SSE parsing.
  * Converts OpenAI's delta format to the canonical StreamEvent union.
  */
-import type { AgentProvider, AgentMessage, ToolDefinition, StreamEvent, StreamOptions } from '../types.js';
+import { type AgentProvider, type AgentMessage, type ToolDefinition, type StreamEvent, type StreamOptions } from '../types.js';
 export interface OpenAICompatProviderOptions {
     apiKey: string;
     model?: string;

package/dist/agent/providers/openai-compat.js

@@ -5,6 +5,7 @@
  * No SDK dependency. Uses only Node.js native fetch + SSE parsing.
  * Converts OpenAI's delta format to the canonical StreamEvent union.
  */
+import { joinSplitPrompt } from '../types.js';
 export class OpenAICompatProvider {
     apiKey;
     model;
@@ -38,7 +39,7 @@ export class OpenAICompatProvider {
         const body = {
             model,
             messages: [
-                ...(options?.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
+                ...(options?.systemPrompt ? [{ role: 'system', content: joinSplitPrompt(options.systemPrompt) }] : []),
                 ...apiMessages,
             ],
             max_tokens: maxTokens,

package/dist/agent/providers/platform.d.ts

@@ -3,7 +3,7 @@
  * Uses the platform's AI credits, no local API key needed.
  * Connects to POST /ai-chat/stream and parses SSE events.
  */
-import type { AgentProvider, AgentMessage, ToolDefinition, StreamEvent, StreamOptions } from '../types.js';
+import { type AgentProvider, type AgentMessage, type ToolDefinition, type StreamEvent, type StreamOptions } from '../types.js';
 export interface PlatformProviderOptions {
     /** JWT token or API key for platform auth */
     token: string;

package/dist/agent/providers/platform.js

@@ -3,6 +3,7 @@
  * Uses the platform's AI credits, no local API key needed.
  * Connects to POST /ai-chat/stream and parses SSE events.
  */
+import { joinSplitPrompt } from '../types.js';
 export class PlatformProvider {
     token;
     baseUrl;
@@ -37,7 +38,8 @@ export class PlatformProvider {
         const body = { message };
         if (options?.systemPrompt) {
             // Platform doesn't accept system prompt directly via API — embed in message
-            body.message = `[System context: ${options.systemPrompt.slice(0, 2000)}]\n\n${message}`;
+            const systemStr = joinSplitPrompt(options.systemPrompt);
+            body.message = `[System context: ${systemStr.slice(0, 2000)}]\n\n${message}`;
         }
         const response = await fetch(`${this.baseUrl}/ai-chat/stream`, {
             method: 'POST',

package/dist/agent/types.d.ts

@@ -65,8 +65,25 @@ export interface ToolEvent {
     result?: string;
     isError?: boolean;
 }
+/**
+ * Split system prompt for Anthropic API cache optimization.
+ *
+ * The prefix (stable FW knowledge) is cached across calls via cache_control.
+ * The suffix (per-task context) varies per call but rides on the cached prefix.
+ *
+ * Providers that support structured system blocks (Anthropic) use both parts.
+ * Providers that only accept strings (CLI, OpenAI, platform) concatenate them.
+ */
+export interface SplitPrompt {
+    /** Stable prefix — identical across calls. Cacheable. */
+    prefix: string;
+    /** Dynamic suffix — varies per task/call. Not cached. */
+    suffix: string;
+}
+/** Convert a SplitPrompt to a single string (for providers that don't support blocks). */
+export declare function joinSplitPrompt(prompt: SplitPrompt): string;
 export interface StreamOptions {
-    systemPrompt?: string;
+    systemPrompt?: SplitPrompt;
     model?: string;
     maxTokens?: number;
     signal?: AbortSignal;
@@ -89,7 +106,7 @@ export interface McpBridge {
     cleanup: () => void;
 }
 export interface AgentLoopOptions {
-    systemPrompt?: string;
+    systemPrompt?: SplitPrompt;
     maxIterations?: number;
     maxTokens?: number;
     model?: string;
@@ -145,6 +162,8 @@ export interface CliSessionOptions {
     model: string;
     /** Pre-configured MCP config path. */
     mcpConfigPath?: string;
+    /** Disable specific built-in tools (e.g. ['Read', 'Edit', 'Write', 'Bash'] to force MCP tools). */
+    disallowedTools?: string[];
     /** Custom spawn function. Defaults to child_process.spawn. */
     spawnFn?: SpawnFn;
     /** Idle timeout in milliseconds. Defaults to 600000 (10 minutes). */

package/dist/agent/types.js

@@ -3,5 +3,10 @@
  *
  * All types are pure — no runtime imports, no side effects.
  */
-export {};
+/** Convert a SplitPrompt to a single string (for providers that don't support blocks). */
+export function joinSplitPrompt(prompt) {
+    if (!prompt.suffix)
+        return prompt.prefix;
+    return prompt.prefix + '\n\n' + prompt.suffix;
+}
 //# sourceMappingURL=types.js.map

package/dist/api/generate-in-place.d.ts

@@ -29,17 +29,8 @@ export interface InPlaceGenerateOptions {
      * @default 'esm'
      */
     moduleFormat?: TModuleFormat;
-    /**
-     * Force inline runtime even when @synergenius/flow-weaver package is installed.
-     * When false/undefined, the compiler auto-detects the package and uses
-     * external imports when available (smaller generated code, shared runtime).
-     * @default false
-     */
-    inlineRuntime?: boolean;
     /**
      * Absolute path to the source file being compiled.
-     * Used to detect if @synergenius/flow-weaver is installed relative to the file.
-     * If not provided, falls back to process.cwd().
      */
     sourceFile?: string;
     /**

package/dist/api/generate-in-place.js

@@ -15,7 +15,6 @@ import { shouldWorkflowBeAsync } from '../generator/async-detection.js';
 import { detectSugarPatterns, filterStaleMacros } from '../sugar-optimizer.js';
 import * as ts from 'typescript';
 import * as path from 'path';
-import * as fs from 'fs';
 // Marker constants
 export const MARKERS = {
     RUNTIME_START: '// @flow-weaver-runtime-start',
@@ -23,30 +22,6 @@ export const MARKERS = {
     BODY_START: '// @flow-weaver-body-start',
     BODY_END: '// @flow-weaver-body-end',
 };
-/**
- * Check if `@synergenius/flow-weaver` is available as an npm package
- * by walking up from the given directory looking for node_modules.
- */
-function isFlowWeaverPackageInstalled(startDir) {
-    let dir = startDir;
-    const root = path.parse(dir).root;
-    while (dir !== root) {
-        const candidate = path.join(dir, 'node_modules', '@synergenius', 'flow-weaver');
-        try {
-            if (fs.existsSync(candidate)) {
-                return true;
-            }
-        }
-        catch {
-            // Permission error or similar — skip and keep walking
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return false;
-}
 /**
  * Generate executable code in-place, preserving user code.
  *
@@ -56,7 +31,7 @@ function isFlowWeaverPackageInstalled(startDir) {
  * @returns The updated source code with generated sections
  */
 export function generateInPlace(sourceCode, ast, options = {}) {
-    const { production = false, allWorkflows, moduleFormat = 'esm', inlineRuntime = false, sourceFile, skipParamReturns = false } = options;
+    const { production = false, allWorkflows, moduleFormat = 'esm', sourceFile, skipParamReturns = false } = options;
     let result = sourceCode;
     let hasChanges = false;
     // Step 1: Update JSDoc annotations for node type functions
@@ -90,15 +65,8 @@ export function generateInPlace(sourceCode, ast, options = {}) {
         result = jsdocResult.code;
         hasChanges = true;
     }
-    // Step 3: Generate and insert/replace runtime section
-    // Auto-detect external runtime unless --inline-runtime is forced
-    let useExternalRuntime = false;
-    if (!inlineRuntime) {
-        const lookupDir = sourceFile ? path.dirname(sourceFile) : (ast.sourceFile ? path.dirname(ast.sourceFile) : process.cwd());
-        useExternalRuntime = isFlowWeaverPackageInstalled(lookupDir);
-    }
-    const externalRuntimePath = useExternalRuntime ? '@synergenius/flow-weaver/runtime' : undefined;
-    const runtimeCode = generateRuntimeSection(ast.functionName, production, moduleFormat, externalRuntimePath);
+    // Step 3: Generate and insert/replace runtime section (always inlined — zero runtime dependencies)
+    const runtimeCode = generateRuntimeSection(ast.functionName, production, moduleFormat);
     const runtimeResult = replaceOrInsertSection(result, MARKERS.RUNTIME_START, MARKERS.RUNTIME_END, runtimeCode, 'top');
     if (runtimeResult.changed) {
         result = runtimeResult.code;
@@ -145,31 +113,15 @@ export function generateInPlace(sourceCode, ast, options = {}) {
 }
 /**
  * Generate the runtime section with proper markers.
- * When externalRuntimePath is provided, generates import statements instead of inline code.
+ * Runtime is always inlined — zero runtime dependencies.
  */
-function generateRuntimeSection(functionName, production, moduleFormat = 'esm', externalRuntimePath) {
+function generateRuntimeSection(functionName, production, moduleFormat = 'esm') {
     const lines = [];
     lines.push('// ============================================================================');
     lines.push('// DO NOT EDIT - This section is auto-generated by Flow Weaver');
     lines.push('// ============================================================================');
     lines.push('');
-    if (externalRuntimePath) {
-        // External runtime: generate import statements instead of inline code
-        lines.push(`import { GeneratedExecutionContext, CancellationError } from '${externalRuntimePath}';`);
-        if (!production) {
-            lines.push(`import type { TDebugger, TDebugController } from '${externalRuntimePath}';`);
-            // Declare __flowWeaverDebugger__ so body code can reference it
-            lines.push('declare const __flowWeaverDebugger__: TDebugger | undefined;');
-        }
-        else {
-            // Production mode still needs TDebugController for the __ctrl__ variable
-            lines.push(`import type { TDebugController } from '${externalRuntimePath}';`);
-        }
-    }
-    else {
-        // Inline runtime: embed all types and classes directly
-        lines.push(generateInlineRuntime(production));
-    }
+    lines.push(generateInlineRuntime(production));
     return lines.join('\n');
 }
 /**

package/dist/api/generate.d.ts

@@ -18,12 +18,11 @@ export interface GenerateOptions extends Partial<ASTGenerateOptions> {
      */
     moduleFormat?: TModuleFormat;
     /**
-     * Path to external runtime module (relative from the generated file).
-     * When set, generates import from this path instead of inlining runtime types.
-     * Use this for multi-workflow bundles to avoid duplicate type declarations.
-     * @example '../runtime/types.js'
+     * Enable bundle mode for multi-workflow bundles.
+     * When true, imports node types from node-types/ directory and workflows from sibling files.
+     * Runtime is always inlined regardless of this setting.
      */
-    externalRuntimePath?: string;
+    bundleMode?: boolean;
     /**
      * Constants from source file(s) to include at the top of the generated file.
      * Used in bundle mode when local node functions are inlined and need their

package/dist/api/generate.js

@@ -38,7 +38,7 @@ export function generateModuleExports(functionNames) {
     return `module.exports = { ${functionNames.join(', ')} };`;
 }
 export function generateCode(ast, options) {
-    const { production = false, sourceMap = false, allWorkflows = [], moduleFormat = 'esm', externalRuntimePath, constants = [], externalNodeTypes = {}, generateStubs = false, outputFormat = 'typescript', } = options || {};
+    const { production = false, sourceMap = false, allWorkflows = [], moduleFormat = 'esm', bundleMode = false, constants = [], externalNodeTypes = {}, generateStubs = false, outputFormat = 'typescript', } = options || {};
     // Check for stub nodes — refuse to generate unless explicitly allowed
     const stubNodeTypes = ast.nodeTypes.filter((nt) => nt.variant === 'STUB');
     if (stubNodeTypes.length > 0 && !generateStubs) {
@@ -78,8 +78,6 @@ export function generateCode(ast, options) {
         }
     };
     // Generate function body using existing body generator
-    // Bundle mode uses params object pattern for node wrapper calls
-    const bundleMode = !!externalRuntimePath;
     const functionBody = bodyGenerator.generateWithExecutionContext(ast, ast.nodeTypes, shouldBeAsync, production, bundleMode);
     // Build the complete module
     const lines = [];
@@ -87,25 +85,8 @@ export function generateCode(ast, options) {
     addLine();
     lines.push('');
     addLine();
-    // Include runtime (either inline or external import)
-    if (externalRuntimePath) {
-        // Import from external runtime module to avoid duplicate declarations in multi-file bundles
-        lines.push(`// Runtime imported from shared module`);
-        addLine();
-        lines.push(generateImportStatement(['GeneratedExecutionContext', 'CancellationError'], externalRuntimePath, moduleFormat));
-        addLine();
-        if (!production) {
-            // Import TDebugger type from external runtime
-            lines.push(moduleFormat === 'cjs'
-                ? `const { TDebugger } = require('${externalRuntimePath}');`
-                : `import type { TDebugger } from '${externalRuntimePath}';`);
-            addLine();
-        }
-        lines.push('');
-        addLine();
-    }
-    else {
-        // Include inline runtime (types + GeneratedExecutionContext)
+    // Include inline runtime (always inlined — zero runtime dependencies)
+    {
         const inlineRuntime = generateInlineRuntime(production);
         const runtimeLines = inlineRuntime.split('\n');
         runtimeLines.forEach((line) => {
@@ -172,11 +153,10 @@ export function generateCode(ast, options) {
         lines.push('');
         addLine();
         // Import regular node functions from source files
-        // In bundle mode (externalRuntimePath is set), import from node-types directory
+        // In bundle mode, import from node-types directory
         // Otherwise import from .generated files in the same directory
         functionImportsByFile.forEach((nodes, sourceFile) => {
-            if (externalRuntimePath) {
-                // Bundle mode: import from node-types directory
+            if (bundleMode) {
                 // Bundle mode: import _impl (positional data args for expression nodes, execute + data args for regular)
                 // The wrapper is only for HTTP entry points, not internal workflow calls
                 nodes.forEach((node) => {
@@ -199,7 +179,7 @@ export function generateCode(ast, options) {
         // Import workflows from their generated files
         // In bundle mode, import from sibling workflow files
         workflowImportsByFile.forEach((names, sourceFile) => {
-            if (externalRuntimePath) {
+            if (bundleMode) {
                 // Bundle mode: import each workflow from the workflows directory
                 names.forEach((name) => {
                     const relativePath = `./${name}.js`;

package/dist/cli/commands/compile.d.ts

@@ -16,11 +16,6 @@ export interface CompileOptions {
      * - 'auto': Auto-detect from project's package.json (default)
      */
     format?: 'esm' | 'cjs' | 'auto';
-    /**
-     * Force inline runtime even when @synergenius/flow-weaver package is installed.
-     * By default, the compiler uses external runtime imports when the package is available.
-     */
-    inlineRuntime?: boolean;
     /**
      * Omit redundant @param/@returns annotations from compiled output.
      * Useful for vibe coders who don't use the visual editor.

package/dist/cli/commands/compile.js

@@ -14,6 +14,7 @@ import { getFriendlyError } from '../../friendly-errors.js';
 import { detectProjectModuleFormat } from './doctor.js';
 import { compileTargetRegistry } from '../../generator/compile-target-registry.js';
 import { AnnotationParser } from '../../parser.js';
+import { safeWriteFile, safeAppendFile } from '../utils/safe-write.js';
 /** Show path relative to cwd for cleaner output */
 function displayPath(filePath) {
     const rel = path.relative(process.cwd(), filePath);
@@ -36,7 +37,7 @@ function resolveModuleFormat(format, cwd) {
     return detection.format;
 }
 export async function compileCommand(input, options = {}) {
-    const { production = false, sourceMap = false, strict = false, verbose = false, workflowName, dryRun = false, format, inlineRuntime = false, clean = false, target } = options;
+    const { production = false, sourceMap = false, strict = false, verbose = false, workflowName, dryRun = false, format, clean = false, target, output } = options;
     // Handle custom compile target
     if (target && target !== 'typescript') {
         return compileCustomTarget(target, input, { production, verbose, workflowName, dryRun, cron: options.cron, serve: options.serve, framework: options.framework, typedEvents: options.typedEvents, retries: options.retries, timeout: options.timeout });
@@ -67,6 +68,27 @@ export async function compileCommand(input, options = {}) {
     if (files.length === 0) {
         throw new Error(`No files found matching pattern: ${input}`);
     }
+    // Resolve --output: determine if it's a file or directory target
+    let outputDir;
+    let outputFile;
+    if (output) {
+        const isOutputDir = output.endsWith('/') || output.endsWith(path.sep) ||
+            (fs.existsSync(output) && fs.statSync(output).isDirectory());
+        if (isOutputDir) {
+            outputDir = output.endsWith('/') || output.endsWith(path.sep) ? output.slice(0, -1) : output;
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+        }
+        else if (files.length > 1) {
+            // Multiple input files but output is a single file — ambiguous
+            throw new Error(`Cannot use --output with a file path when compiling multiple files. ` +
+                `Use a directory path instead (e.g. --output ${output}/)`);
+        }
+        else {
+            outputFile = path.resolve(output);
+        }
+    }
     const totalTimer = logger.timer();
     logger.section('Compiling Workflows');
     if (verbose) {
@@ -161,10 +183,16 @@ export async function compileCommand(input, options = {}) {
             // Read original source
             const sourceCode = fs.readFileSync(file, 'utf8');
             // Generate code in-place (preserves types, interfaces, etc.)
-            const result = generateInPlace(sourceCode, parseResult.ast, { production, moduleFormat, inlineRuntime, sourceFile: file, skipParamReturns: clean });
-            // Write back to original file (skip in dry-run mode)
+            const result = generateInPlace(sourceCode, parseResult.ast, { production, moduleFormat, sourceFile: file, skipParamReturns: clean });
+            // Determine where to write the compiled output
+            const writePath = outputFile
+                ? outputFile
+                : outputDir
+                    ? path.join(outputDir, path.basename(file))
+                    : file; // in-place
+            // Write compiled output (skip in dry-run mode)
             if (!dryRun) {
-                fs.writeFileSync(file, result.code, 'utf8');
+                safeWriteFile(writePath, result.code);
                 // Generate source map if requested
                 if (sourceMap) {
                     const mapResult = generateCode(parseResult.ast, {
@@ -173,11 +201,11 @@ export async function compileCommand(input, options = {}) {
                         moduleFormat,
                     });
                     if (mapResult.sourceMap) {
-                        const mapPath = file + '.map';
-                        fs.writeFileSync(mapPath, mapResult.sourceMap, 'utf8');
+                        const mapPath = writePath + '.map';
+                        safeWriteFile(mapPath, mapResult.sourceMap);
                         const sourceMappingComment = `\n//# sourceMappingURL=${path.basename(mapPath)}\n`;
                         if (!result.code.includes('//# sourceMappingURL=')) {
-                            fs.appendFileSync(file, sourceMappingComment, 'utf8');
+                            safeAppendFile(writePath, sourceMappingComment);
                         }
                         if (verbose) {
                             logger.info(`    source map: ${displayPath(mapPath)}`);
@@ -291,7 +319,7 @@ export async function compileCustomTarget(target, input, options) {
         }
     }
     else {
-        fs.writeFileSync(outputPath, code, 'utf8');
+        safeWriteFile(outputPath, code);
         logger.success(`Compiled: ${displayPath(outputPath)}`);
     }
     logger.newline();

package/dist/cli/commands/context.js

@@ -1,9 +1,9 @@
 /**
  * Context command - generate LLM context bundles from documentation and grammar
  */
-import * as fs from 'fs';
 import { buildContext, PRESETS, PRESET_NAMES } from '../../context/index.js';
 import { logger } from '../utils/logger.js';
+import { safeWriteFile } from '../utils/safe-write.js';
 export async function contextCommand(preset, options) {
     // --list: show presets and exit
     if (options.list) {
@@ -22,14 +22,12 @@ export async function contextCommand(preset, options) {
     // Validate preset
     const presetName = (preset ?? 'core');
     if (!PRESET_NAMES.includes(presetName) && !options.topics) {
-        logger.error(`Unknown preset "${preset}". Available: ${PRESET_NAMES.join(', ')}. Or use --topics to specify topics directly.`);
-        process.exit(1);
+        throw new Error(`Unknown preset "${preset}". Available: ${PRESET_NAMES.join(', ')}. Or use --topics to specify topics directly.`);
     }
     // Validate profile
     const profile = options.profile ?? 'standalone';
     if (profile !== 'standalone' && profile !== 'assistant') {
-        logger.error(`Unknown profile "${profile}". Use "standalone" or "assistant".`);
-        process.exit(1);
+        throw new Error(`Unknown profile "${profile}". Use "standalone" or "assistant".`);
     }
     const result = buildContext({
         preset: PRESET_NAMES.includes(presetName) ? presetName : 'core',
@@ -40,7 +38,7 @@ export async function contextCommand(preset, options) {
     });
     // Write output
     if (options.output) {
-        fs.writeFileSync(options.output, result.content, 'utf-8');
+        safeWriteFile(options.output, result.content);
         logger.success(`Context written to ${options.output}`);
     }
     else {

package/dist/cli/commands/create.js

@@ -41,9 +41,7 @@ export async function createWorkflowCommand(template, file, options = {}) {
     const { line, async: isAsync = false, preview = false, provider, model, config: configJson, } = options;
     const templateDef = getWorkflowTemplate(template);
     if (!templateDef) {
-        logger.error(`Unknown workflow template: ${template}`);
-        logger.info("Run 'fw templates' to see available templates");
-        process.exit(1);
+        throw new Error(`Unknown workflow template: ${template}. Run 'fw templates' to see available templates`);
     }
     // Resolve to absolute path
     const filePath = path.resolve(file);
@@ -67,8 +65,7 @@ export async function createWorkflowCommand(template, file, options = {}) {
             Object.assign(config, JSON.parse(configJson));
         }
         catch {
-            logger.error('Invalid --config JSON');
-            process.exit(1);
+            throw new Error('Invalid --config JSON');
         }
     }
     // Generate the template code
@@ -91,8 +88,7 @@ export async function createWorkflowCommand(template, file, options = {}) {
         logger.info(`  Workflow function: ${workflowName}`);
     }
     catch (error) {
-        logger.error(`Failed to create workflow: ${getErrorMessage(error)}`);
-        process.exit(1);
+        throw new Error(`Failed to create workflow: ${getErrorMessage(error)}`);
     }
 }
 /**
@@ -103,9 +99,7 @@ export async function createNodeCommand(name, file, options = {}) {
     const { line, template = 'processor', preview = false, strategy, config: configJson } = options;
     const templateDef = getNodeTemplate(template);
     if (!templateDef) {
-        logger.error(`Unknown node template: ${template}`);
-        logger.info("Run 'fw templates' to see available templates");
-        process.exit(1);
+        throw new Error(`Unknown node template: ${template}. Run 'fw templates' to see available templates`);
     }
     // Resolve to absolute path
     const filePath = path.resolve(file);
@@ -118,8 +112,7 @@ export async function createNodeCommand(name, file, options = {}) {
             Object.assign(config, JSON.parse(configJson));
         }
         catch {
-            logger.error('Invalid --config JSON');
-            process.exit(1);
+            throw new Error('Invalid --config JSON');
         }
     }
     // Generate the template code with provided name and optional config
@@ -140,8 +133,7 @@ export async function createNodeCommand(name, file, options = {}) {
         logger.info(`  Node function: ${nodeName}`);
     }
     catch (error) {
-        logger.error(`Failed to create node: ${getErrorMessage(error)}`);
-        process.exit(1);
+        throw new Error(`Failed to create node: ${getErrorMessage(error)}`);
     }
 }
 //# sourceMappingURL=create.js.map

package/dist/cli/commands/describe.js

@@ -9,6 +9,7 @@ import { validator } from '../../validator.js';
 import { getNode, getIncomingConnections, getOutgoingConnections } from '../../api/query.js';
 import { logger } from '../utils/logger.js';
 import { getErrorMessage } from '../../utils/error-utils.js';
+import { safeWriteFile } from '../utils/safe-write.js';
 import { buildDiagramGraph } from '../../diagram/geometry.js';
 import { renderASCII, renderASCIICompact } from '../../diagram/ascii-renderer.js';
 export function buildNodeInfo(instance, nodeType) {
@@ -344,16 +345,13 @@ export async function describeCommand(input, options = {}) {
     const { format = 'json', node: focusNodeId, workflowName, compile = false } = options;
     const filePath = path.resolve(input);
     if (!fs.existsSync(filePath)) {
-        logger.error(`File not found: ${filePath}`);
-        process.exit(1);
+        throw new Error(`File not found: ${filePath}`);
     }
     try {
         // Parse the workflow
         const parseResult = await parseWorkflow(filePath, { workflowName });
         if (parseResult.errors.length > 0) {
-            logger.error(`Parse errors:`);
-            parseResult.errors.forEach((err) => logger.error(`  ${err}`));
-            process.exit(1);
+            throw new Error(`Parse errors:\n${parseResult.errors.map((err) => `  ${err}`).join('\n')}`);
         }
         const ast = parseResult.ast;
         // Only update runtime markers when explicitly requested via --compile
@@ -362,7 +360,7 @@ export async function describeCommand(input, options = {}) {
             const sourceCode = fs.readFileSync(filePath, 'utf8');
             const generated = generateInPlace(sourceCode, ast, { production: false });
             if (generated.hasChanges) {
-                fs.writeFileSync(filePath, generated.code, 'utf8');
+                safeWriteFile(filePath, generated.code);
                 logger.info(`Updated runtime markers in ${path.basename(filePath)}`);
             }
         }
@@ -373,11 +371,9 @@ export async function describeCommand(input, options = {}) {
     }
     catch (error) {
         if (error instanceof Error && error.message.startsWith('Node not found:')) {
-            logger.error(error.message);
-            process.exit(1);
+            throw error;
         }
-        logger.error(`Failed to describe workflow: ${getErrorMessage(error)}`);
-        process.exit(1);
+        throw new Error(`Failed to describe workflow: ${getErrorMessage(error)}`);
     }
 }
 //# sourceMappingURL=describe.js.map