@synergenius/flow-weaver 0.23.4 → 0.24.0

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import * as path from 'node:path';
 // Load built-in extensions (CI/CD, etc.) before any commands run
 import '../extensions/index.js';
 import { Command, Option } from 'commander';
+import { parseIntStrict } from './utils/parse-int-strict.js';
 import { logger } from './utils/logger.js';
 import { getErrorMessage } from '../utils/error-utils.js';
 const version = typeof __CLI_VERSION__ !== 'undefined' ? __CLI_VERSION__ : '0.0.0-dev';
@@ -71,14 +72,13 @@ program
     .option('-w, --workflow <name>', 'Specific workflow name to compile')
     .addOption(new Option('-f, --format <format>', 'Module format').choices(['esm', 'cjs', 'auto']).default('auto'))
     .option('--strict', 'Treat type coercion warnings as errors', false)
-    .option('--inline-runtime', 'Force inline runtime even when @synergenius/flow-weaver package is installed', false)
     .option('--clean', 'Omit redundant @param/@returns annotations from compiled output', false)
     .option('--target <target>', 'Compilation target: typescript (default) or a registered extension target')
     .option('--cron <schedule>', 'Set cron trigger schedule')
     .option('--serve', 'Generate serve() handler for HTTP event reception')
     .option('--framework <name>', 'Framework adapter for serve handler (next, express, hono, fastify, remix)')
     .option('--typed-events', 'Generate Zod event schemas from workflow @param annotations')
-    .option('--retries <n>', 'Number of retries per function', parseInt)
+    .option('--retries <n>', 'Number of retries per function', parseIntStrict)
     .option('--timeout <duration>', 'Function timeout (e.g. "30m", "1h")')
     .action(wrapAction(async (input, options) => {
     const { compileCommand } = await import('./commands/compile.js');
@@ -115,7 +115,7 @@ program
 program
     .command('diagram <input>')
     .description('Generate SVG or interactive HTML diagram of a workflow')
-    .option('-t, --theme <theme>', 'Color theme: dark, light', 'dark')
+    .addOption(new Option('-t, --theme <theme>', 'Color theme').choices(['dark', 'light']).default('dark'))
     .option('--width <pixels>', 'SVG width in pixels')
     .option('-p, --padding <pixels>', 'Canvas padding in pixels')
     .option('--no-port-labels', 'Hide data type labels on ports')
@@ -190,7 +190,6 @@ program
     .option('--with-weaver', 'Install Weaver AI assistant')
     .option('--no-weaver', 'Skip Weaver installation')
     .option('--force', 'Overwrite existing files', false)
-    .option('--json', 'Output results as JSON', false)
     .action(wrapAction(async (directory, options) => {
     const { initCommand } = await import('./commands/init.js');
     await initCommand(directory, options);
@@ -224,8 +223,6 @@ program
     .option('--once', 'Run once then exit', false)
     .option('--json', 'Output result as JSON', false)
     .option('--target <target>', 'Compilation target (default: typescript)')
-    .option('--framework <framework>', 'Framework for serve handler', 'express')
-    .option('--port <port>', 'Port for dev server', (v) => parseInt(v, 10), 3000)
     .action(wrapAction(async (input, options) => {
     const { devCommand } = await import('./commands/dev.js');
     await devCommand(input, options);
@@ -255,7 +252,7 @@ const createCmd = program.command('create').description('Create workflows or nod
 createCmd
     .command('workflow <template> <file>')
     .description('Create a workflow from a template')
-    .option('-l, --line <number>', 'Insert at specific line number', parseInt)
+    .option('-l, --line <number>', 'Insert at specific line number', parseIntStrict)
     .option('-a, --async', 'Generate an async workflow', false)
     .option('-p, --preview', 'Preview generated code without writing', false)
     .option('--provider <provider>', 'LLM provider (openai, anthropic, ollama, mock)')
@@ -272,7 +269,7 @@ createCmd
 createCmd
     .command('node <name> <file>')
     .description('Create a node type from a template')
-    .option('-l, --line <number>', 'Insert at specific line number', parseInt)
+    .option('-l, --line <number>', 'Insert at specific line number', parseIntStrict)
     .option('-t, --template <template>', 'Node template to use', 'transformer')
     .option('-p, --preview', 'Preview generated code without writing', false)
     .option('--strategy <strategy>', 'Template strategy (e.g. mock, callback, webhook)')
@@ -414,7 +411,7 @@ program
     .option('-t, --trace', 'Include execution trace events')
     .option('-s, --stream', 'Stream trace events in real-time')
     .option('--json', 'Output result as JSON', false)
-    .option('--timeout <ms>', 'Execution timeout in milliseconds', parseInt)
+    .option('--timeout <ms>', 'Execution timeout in milliseconds', parseIntStrict)
     .option('--mocks <json>', 'Mock config for built-in nodes (events, invocations, agents, fast) as JSON')
     .option('--mocks-file <path>', 'Path to JSON file with mock config for built-in nodes')
     .option('-d, --debug', 'Start in step-through debug mode')
@@ -439,7 +436,7 @@ program
     .action(wrapAction(async (directory, options) => {
     const { serveCommand } = await import('./commands/serve.js');
     await serveCommand(directory, {
-        port: parseInt(options.port, 10),
+        port: parseIntStrict(options.port),
         host: options.host,
         watch: options.watch,
         production: options.production,
@@ -455,7 +452,8 @@ program
     .requiredOption('-t, --target <target>', 'Target platform (install target packs via marketplace)')
     .requiredOption('-o, --output <path>', 'Output directory')
     .option('-w, --workflow <name>', 'Specific workflow name to export')
-    .option('-p, --production', 'Production mode', true)
+    .option('-p, --production', 'Production mode (no debug events)', false)
+    .option('--bundle', 'Bundle node types into the output', false)
     .option('--dry-run', 'Preview without writing files', false)
     .option('--multi', 'Export all workflows in file as a single multi-workflow service', false)
     .option('--workflows <names>', 'Comma-separated list of workflows to export (used with --multi)')
@@ -625,7 +623,7 @@ marketCmd
     .option('--json', 'Output as JSON', false)
     .action(wrapAction(async (query, options) => {
     const { marketSearchCommand } = await import('./commands/market.js');
-    await marketSearchCommand(query, { ...options, limit: parseInt(options.limit, 10) });
+    await marketSearchCommand(query, { ...options, limit: parseIntStrict(options.limit) });
 }));
 marketCmd
     .command('list')

package/dist/cli/postinstall.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Postinstall welcome message.
+ *
+ * Context-aware, shown once after npm install.
+ * Silent in CI. No telemetry, no file modifications, no dark patterns.
+ */
+export type InstallContext = 'ci' | 'global' | 'typescript' | 'existing' | 'project';
+/**
+ * Detect the installation context based on cwd and environment variables.
+ */
+export declare function detectContext(cwd: string, env: Record<string, string | undefined>): InstallContext;
+/**
+ * Format the welcome message for the detected context.
+ */
+export declare function formatMessage(context: InstallContext): string;
+//# sourceMappingURL=postinstall.d.ts.map

package/dist/cli/postinstall.js

@@ -0,0 +1,119 @@
+/**
+ * Postinstall welcome message.
+ *
+ * Context-aware, shown once after npm install.
+ * Silent in CI. No telemetry, no file modifications, no dark patterns.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const CI_ENV_VARS = ['CI', 'CONTINUOUS_INTEGRATION', 'BUILD_NUMBER', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'JENKINS_URL', 'CODEBUILD_BUILD_ID'];
+/**
+ * Scan .ts files in a directory (non-recursive) for @flowWeaver annotations.
+ */
+function dirHasFlowWeaver(dir) {
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const entry of entries) {
+            if (!entry.endsWith('.ts') || entry.endsWith('.d.ts'))
+                continue;
+            try {
+                const content = fs.readFileSync(path.join(dir, entry), 'utf8');
+                if (content.includes('@flowWeaver'))
+                    return true;
+            }
+            catch {
+                // Permission error or similar — skip
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read
+    }
+    return false;
+}
+/**
+ * Scan .ts files in a directory (non-recursive) for existence.
+ */
+function dirHasTsFiles(dir) {
+    try {
+        const entries = fs.readdirSync(dir);
+        return entries.some((e) => e.endsWith('.ts') && !e.endsWith('.d.ts'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect the installation context based on cwd and environment variables.
+ */
+export function detectContext(cwd, env) {
+    // CI — always silent
+    if (CI_ENV_VARS.some((v) => env[v])) {
+        return 'ci';
+    }
+    // No package.json — likely global install or outside a project
+    if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+        return 'global';
+    }
+    // Check for TypeScript project (tsconfig.json as proxy)
+    const hasTsConfig = fs.existsSync(path.join(cwd, 'tsconfig.json'));
+    if (!hasTsConfig) {
+        return 'project';
+    }
+    // Check for existing @flowWeaver usage (top-level and src/ only)
+    if (dirHasFlowWeaver(cwd) || dirHasFlowWeaver(path.join(cwd, 'src'))) {
+        return 'existing';
+    }
+    // TypeScript project without @flowWeaver
+    if (dirHasTsFiles(cwd) || dirHasTsFiles(path.join(cwd, 'src'))) {
+        return 'typescript';
+    }
+    // Has tsconfig but no .ts files yet
+    return 'typescript';
+}
+/**
+ * Format the welcome message for the detected context.
+ */
+export function formatMessage(context) {
+    switch (context) {
+        case 'ci':
+            return '';
+        case 'global':
+            return [
+                '',
+                '  flow-weaver installed \u2713',
+                '',
+                '  Create a project:  fw init my-project',
+                '  Or try it now:     fw create workflow hello-world',
+                '',
+            ].join('\n');
+        case 'typescript':
+            return [
+                '',
+                '  flow-weaver installed \u2713',
+                '',
+                '  Add above any function:  /** @flowWeaver nodeType */',
+                '  Then compile:            fw compile src/',
+                '',
+            ].join('\n');
+        case 'existing':
+            return [
+                '',
+                '  flow-weaver updated \u2713',
+                '',
+                '  Check health:  fw doctor',
+                '',
+            ].join('\n');
+        case 'project':
+            return [
+                '',
+                '  flow-weaver installed \u2713',
+                '',
+                '  Get started:  fw init',
+                '',
+            ].join('\n');
+    }
+}
+// Entry point logic lives in scripts/postinstall.cjs (standalone CJS, no build step).
+// This module is the testable source of truth for the detection/formatting logic.
+//# sourceMappingURL=postinstall.js.map

package/dist/cli/utils/parse-int-strict.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Strict integer parser for CLI options.
+ * Unlike parseInt, rejects partial matches ("12abc") and non-numeric values.
+ * Throws a clear error instead of silently returning NaN.
+ */
+export declare function parseIntStrict(value: string): number;
+//# sourceMappingURL=parse-int-strict.d.ts.map

package/dist/cli/utils/parse-int-strict.js

@@ -0,0 +1,17 @@
+/**
+ * Strict integer parser for CLI options.
+ * Unlike parseInt, rejects partial matches ("12abc") and non-numeric values.
+ * Throws a clear error instead of silently returning NaN.
+ */
+export function parseIntStrict(value) {
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        throw new Error(`"${value}" is not a valid number`);
+    }
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        throw new Error(`"${value}" is not a valid number`);
+    }
+    return n;
+}
+//# sourceMappingURL=parse-int-strict.js.map

package/dist/cli/utils/safe-write.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-platform safe file writing utilities.
+ *
+ * - Creates parent directories automatically
+ * - Provides clear error messages for permission issues
+ * - Works on Windows, macOS, and Linux
+ */
+/**
+ * Write content to a file, creating parent directories as needed.
+ * Throws a clear error on permission issues.
+ */
+export declare function safeWriteFile(filePath: string, content: string, encoding?: BufferEncoding): void;
+/**
+ * Append content to a file, creating the file and parent directories as needed.
+ * Throws a clear error on permission issues.
+ */
+export declare function safeAppendFile(filePath: string, content: string, encoding?: BufferEncoding): void;
+//# sourceMappingURL=safe-write.d.ts.map

package/dist/cli/utils/safe-write.js

@@ -0,0 +1,54 @@
+/**
+ * Cross-platform safe file writing utilities.
+ *
+ * - Creates parent directories automatically
+ * - Provides clear error messages for permission issues
+ * - Works on Windows, macOS, and Linux
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+function wrapIOError(filePath, error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        if (code === 'EACCES' || code === 'EPERM') {
+            throw new Error(`Permission denied: cannot write to ${filePath}. Check file/directory permissions.`);
+        }
+        if (code === 'EROFS') {
+            throw new Error(`Read-only file system: cannot write to ${filePath}.`);
+        }
+        throw error;
+    }
+    throw error;
+}
+/**
+ * Write content to a file, creating parent directories as needed.
+ * Throws a clear error on permission issues.
+ */
+export function safeWriteFile(filePath, content, encoding = 'utf8') {
+    try {
+        ensureDir(path.dirname(filePath));
+        fs.writeFileSync(filePath, content, encoding);
+    }
+    catch (error) {
+        wrapIOError(filePath, error);
+    }
+}
+/**
+ * Append content to a file, creating the file and parent directories as needed.
+ * Throws a clear error on permission issues.
+ */
+export function safeAppendFile(filePath, content, encoding = 'utf8') {
+    try {
+        ensureDir(path.dirname(filePath));
+        fs.appendFileSync(filePath, content, encoding);
+    }
+    catch (error) {
+        wrapIOError(filePath, error);
+    }
+}
+//# sourceMappingURL=safe-write.js.map

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.23.4";
+export declare const VERSION = "0.24.0";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.23.4';
+export const VERSION = '0.24.0';
 //# sourceMappingURL=generated-version.js.map

package/dist/generator/unified.js

@@ -456,7 +456,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                     branchNeedsClose = true;
                 }
             }
-            generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, nodeRegion, availableVars, generatedNodes, lines, branchIndent, false, branchingNodes, branchRegions, isAsync, 'ctx', bundleMode, promotedPreDeclared, branchingNodesNeedingSuccessFlag.has(instanceId), production);
+            generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, nodeRegion, availableVars, generatedNodes, lines, branchIndent, false, branchingNodes, branchRegions, isAsync, 'ctx', bundleMode, promotedPreDeclared, branchingNodesNeedingSuccessFlag.has(instanceId) || topLevelSuccessFlags.has(toValidIdentifier(instanceId)), production);
             if (branchNeedsClose) {
                 lines.push(`  }`);
             }
@@ -885,8 +885,8 @@ function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes,
     const preDeclaredFlags = new Set(alreadyDeclaredFlags);
     for (let i = 0; i < chain.length; i++) {
         const isLast = i === chain.length - 1;
-        if (!isLast || forceTrackSuccessNodes.has(chain[i])) {
-            const safeId = toValidIdentifier(chain[i]);
+        const safeId = toValidIdentifier(chain[i]);
+        if (!isLast || forceTrackSuccessNodes.has(chain[i]) || alreadyDeclaredFlags.has(safeId)) {
             if (!alreadyDeclaredFlags.has(safeId)) {
                 lines.push(`${indent}let ${safeId}_success = false;`);
             }
@@ -924,7 +924,7 @@ function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes,
             lines.push(`${indent}if (${guardCondition}) {`);
         }
         const nodeIndent = hasGuard ? indent + '  ' : indent;
-        generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, effectiveRegion, availableVars, generatedNodes, lines, nodeIndent, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, preDeclaredFlags, !isLast || forceTrackSuccessNodes.has(chain[i]), // forceTrackSuccess for non-last chain nodes or nodes with promoted dependents
+        generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, effectiveRegion, availableVars, generatedNodes, lines, nodeIndent, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, preDeclaredFlags, !isLast || forceTrackSuccessNodes.has(chain[i]) || alreadyDeclaredFlags.has(safeId), // forceTrackSuccess for non-last chain nodes, nodes with promoted dependents, or nodes with pre-declared flags
         production);
         // Generate scoped children for this chain node
         generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, nodeIndent, branchingNodes, branchRegions, isAsync, bundleMode, production);
@@ -1225,7 +1225,8 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
                     lines.push(`${indent}  let ${nestedSafeId}_success = false;`);
                     nestedPreDeclared.add(nestedSafeId);
                 }
-                generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, successVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, nestedPreDeclared, false, production);
+                generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, successVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, nestedPreDeclared, nestedPreDeclared.has(nestedSafeId), // force tracking if flag was pre-declared at higher scope
+                production);
                 successExecutedNodes.push(instanceId);
                 nestedRegion.successNodes.forEach((n) => successExecutedNodes.push(n));
                 nestedRegion.failureNodes.forEach((n) => successExecutedNodes.push(n));
@@ -1275,7 +1276,8 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
                         lines.push(`${indent}  let ${nestedSafeId}_success = false;`);
                         nestedPreDeclared.add(nestedSafeId);
                     }
-                    generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, failureVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, nestedPreDeclared, false, production);
+                    generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, failureVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, nestedPreDeclared, nestedPreDeclared.has(nestedSafeId), // force tracking if flag was pre-declared at higher scope
+                    production);
                     failureExecutedNodes.push(instanceId);
                     nestedRegion.successNodes.forEach((n) => failureExecutedNodes.push(n));
                     nestedRegion.failureNodes.forEach((n) => failureExecutedNodes.push(n));

package/docs/reference/cli-reference.md

@@ -67,7 +67,6 @@ fw compile <input> [options]
 | `-w, --workflow-name <name>` | Specific workflow name | all |
 | `-f, --format <format>` | Module format: `esm`, `cjs`, `auto` | `auto` |
 | `--strict` | Type coercion warnings become errors | `false` |
-| `--inline-runtime` | Force inline runtime | `false` |
 | `--clean` | Omit redundant @param/@returns | `false` |
 | `--target <target>` | `typescript` or `inngest` | `typescript` |
 | `--cron <schedule>` | Cron schedule (Inngest only) | — |

package/docs/reference/compilation.md

@@ -1,7 +1,7 @@
 ---
 name: Compilation
 description: How compilation works, TypeScript and Inngest targets, compile options, and serve handler generation
-keywords: [compile, compilation, target, typescript, inngest, production, source-map, format, strict, inline-runtime, clean, serve, framework, step.run, durable, trigger, cancelOn, retries, timeout, throttle, cron, markers]
+keywords: [compile, compilation, target, typescript, inngest, production, source-map, format, strict, clean, serve, framework, step.run, durable, trigger, cancelOn, retries, timeout, throttle, cron, markers]
 ---
 
 # Compilation
@@ -59,7 +59,7 @@ fw compile workflow.ts
 Generates code like:
 ```typescript
 // @flow-weaver-runtime — start
-import { ExecutionContext } from '@synergenius/flow-weaver/runtime';
+// (inline runtime: GeneratedExecutionContext, CancellationError, types)
 // @flow-weaver-runtime — end
 
 export function myWorkflow(params: { data: string }) {
@@ -272,14 +272,6 @@ fw compile workflow.ts --strict
 
 Equivalent to adding `@strictTypes` to the workflow annotation.
 
-### Inline Runtime (`--inline-runtime`)
-
-Force inline runtime code even when `@synergenius/flow-weaver` is installed as a dependency. Normally the compiler generates an import; this flag embeds the runtime directly.
-
-```bash
-fw compile workflow.ts --inline-runtime
-```
-
 ### Clean Output (`--clean`)
 
 Omit redundant `@param`/`@returns` annotations from the compiled output. Produces cleaner generated code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.23.4",
+  "version": "0.24.0",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",
@@ -108,6 +108,7 @@
     "dist",
     "!dist/**/*.map",
     "docs/reference",
+    "scripts/postinstall.cjs",
     "README.md",
     "LICENSE"
   ],
@@ -131,7 +132,8 @@
     "docs:serve": "npm run docs && npx http-server docs/api -c-1 -o",
     "prepare": "npm run build && husky || true",
     "cli": "tsx src/cli/index.ts",
-    "diagram": "tsx scripts/generate-diagram.ts"
+    "diagram": "tsx scripts/generate-diagram.ts",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
     "flow-weaver",

package/scripts/postinstall.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Postinstall welcome message — context-aware, shown after npm install.
+ *
+ * This is a standalone CJS script (no build step, no ESM, no dependencies).
+ * The logic is duplicated from src/cli/postinstall.ts which has full test coverage.
+ *
+ * Silent in CI. No telemetry. No file modifications. No dark patterns.
+ * Never fails the install.
+ */
+'use strict';
+
+try {
+  const fs = require('fs');
+  const path = require('path');
+
+  const CI_VARS = ['CI', 'CONTINUOUS_INTEGRATION', 'BUILD_NUMBER', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'JENKINS_URL', 'CODEBUILD_BUILD_ID'];
+  if (CI_VARS.some(v => process.env[v])) process.exit(0);
+
+  const cwd = process.env.INIT_CWD || process.cwd();
+
+  function hasPkg() { try { return fs.existsSync(path.join(cwd, 'package.json')); } catch { return false; } }
+  function hasTsConfig() { try { return fs.existsSync(path.join(cwd, 'tsconfig.json')); } catch { return false; } }
+
+  function dirHasTs(dir) {
+    try { return fs.readdirSync(dir).some(f => f.endsWith('.ts') && !f.endsWith('.d.ts')); }
+    catch { return false; }
+  }
+
+  function dirHasFlowWeaver(dir) {
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith('.ts') || f.endsWith('.d.ts')) continue;
+        try { if (fs.readFileSync(path.join(dir, f), 'utf8').includes('@flowWeaver')) return true; }
+        catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+    return false;
+  }
+
+  let msg;
+
+  if (!hasPkg()) {
+    // Global install or outside a project
+    msg = [
+      '',
+      '  flow-weaver installed \u2713',
+      '',
+      '  Create a project:  fw init my-project',
+      '  Or try it now:     fw create workflow hello-world',
+      '',
+    ].join('\n');
+  } else if (!hasTsConfig()) {
+    // Project without TypeScript
+    msg = [
+      '',
+      '  flow-weaver installed \u2713',
+      '',
+      '  Get started:  fw init',
+      '',
+    ].join('\n');
+  } else if (dirHasFlowWeaver(cwd) || dirHasFlowWeaver(path.join(cwd, 'src'))) {
+    // Existing flow-weaver project
+    msg = [
+      '',
+      '  flow-weaver updated \u2713',
+      '',
+      '  Check health:  fw doctor',
+      '',
+    ].join('\n');
+  } else {
+    // TypeScript project, no @flowWeaver yet
+    msg = [
+      '',
+      '  flow-weaver installed \u2713',
+      '',
+      '  Add above any function:  /** @flowWeaver nodeType */',
+      '  Then compile:            fw compile src/',
+      '',
+    ].join('\n');
+  }
+
+  process.stderr.write(msg);
+} catch {
+  // Never fail the install
+}