@timo9378/flow2code 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.5] — 2026-03-05
+
+### Security
+- **Path traversal fix** — `serveStatic` now uses `resolve()` + `startsWith()` guard with `decodeURIComponent` to prevent `../../etc/passwd` and `%2e%2e%2f` attacks
+
+### Fixed
+- **DAG swallowed errors** — `.catch(() => {})` replaced with `.catch((err) => { console.error(...) })` so concurrent promise errors are logged instead of silently discarded
+- **CLI watch sync I/O** — Watch mode now uses async `readFile`/`writeFile`/`mkdir` + 150ms debounce to prevent event loop blocking
+- **Source map brittle regex** — Replaced full-line regex with robust `indexOf`-based scanner for `[nodeId] ---` suffix tokens; survives Prettier/ESLint reformatting
+- **Compiler state mutation** — Centralized child block registration via `applyChildBlockRegistration()` helper; plugins no longer scatter-write to context
+- **env-check false positives** — `env-check` command now includes `Object.keys(process.env)` in declared vars whitelist (CI/CD injected vars)
+- **Plugin error guard** — `plugin.generate()` wrapped in try/catch with descriptive error message identifying plugin, node label, and node ID; preserves `{ cause }` chain
+
+### Added
+- **Logger system** — `src/lib/logger.ts` with picocolors, log levels (debug/info/warn/error/silent), structured output (`kv`, `kvLast`, `blank`, `raw`), `--silent` CLI flag
+- **picocolors** added as direct dependency (zero-dep, 3.8x faster than chalk)
+
+### Changed
+- Dev script switched back to Turbopack (`next dev --turbopack`), removed `--webpack` workaround
+- Server and CLI now use structured logger instead of raw `console.log`/`console.error`
+- Test count: 405 tests / 33 test files
+
 ## [0.1.0] — 2026-02-27
 
 ### Added

package/dist/cli.js

@@ -2079,7 +2079,7 @@ function generateNodeChainDAG(writer, triggerId, context) {
       generateNodeBody(writer, node, context);
     });
     writer.writeLine(`)();`);
-    writer.writeLine(`${promiseVar}.catch(() => {});`);
+    writer.writeLine(`${promiseVar}.catch((err) => { console.error("[Flow2Code DAG Error]", err); });`);
     writer.blankLine();
   }
   if (dagNodeIds.length > 0) {
@@ -2152,7 +2152,18 @@ function generateNodeBody(writer, node, context) {
   const plugin = context.pluginRegistry.get(node.nodeType);
   if (plugin) {
     const pluginCtx = createPluginContext(context);
-    plugin.generate(node, writer, pluginCtx);
+    try {
+      plugin.generate(node, writer, pluginCtx);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error ? err.stack : void 0;
+      throw new Error(
+        `[flow2code] Plugin "${node.nodeType}" threw an error while generating node "${node.label}" (${node.id}):
+  ${errMsg}` + (stack ? `
+  Stack: ${stack}` : ""),
+        { cause: err }
+      );
+    }
   } else {
     throw new Error(
       `[flow2code] Unsupported node type: "${node.nodeType}". Register a plugin via pluginRegistry.register() or use a built-in node type.`
@@ -2160,6 +2171,13 @@ function generateNodeBody(writer, node, context) {
   }
 }
 function createPluginContext(context) {
+  const pendingChildBlockIds = [];
+  const applyChildBlockRegistration = (nodeId) => {
+    pendingChildBlockIds.push(nodeId);
+    context.childBlockNodeIds.add(nodeId);
+    context.symbolTableExclusions.add(nodeId);
+    context.generatedBlockNodeIds.add(nodeId);
+  };
   return {
     ir: context.ir,
     nodeMap: context.nodeMap,
@@ -2185,9 +2203,7 @@ function createPluginContext(context) {
       return resolveEnvVars(url, context);
     },
     generateChildNode(writer, node) {
-      context.childBlockNodeIds.add(node.id);
-      context.symbolTableExclusions.add(node.id);
-      context.generatedBlockNodeIds.add(node.id);
+      applyChildBlockRegistration(node.id);
       writer.writeLine(`// --- ${node.label} (${node.nodeType}) [${node.id}] ---`);
       generateNodeBody(writer, node, context);
       generateBlockContinuation(writer, node.id, context);
@@ -2231,27 +2247,27 @@ function collectRequiredPackages(ir, context) {
 function buildSourceMap(code, ir, filePath) {
   const lines = code.split("\n");
   const mappings = {};
-  const nodeMarkerRegex = /^[\s]*\/\/ --- .+? \(.+?\) \[(.+?)\] ---$/;
+  const validNodeIds = new Set(ir.nodes.map((n) => n.id));
   let currentNodeId = null;
   let currentStartLine = 0;
   for (let i = 0; i < lines.length; i++) {
     const lineNum = i + 1;
-    const match = lines[i].match(nodeMarkerRegex);
-    if (match) {
-      if (currentNodeId) {
-        mappings[currentNodeId] = {
-          startLine: currentStartLine,
-          endLine: lineNum - 1
-        };
-      }
-      const [, nodeId] = match;
-      if (ir.nodes.some((n) => n.id === nodeId)) {
-        currentNodeId = nodeId;
-        currentStartLine = lineNum;
-      } else {
-        currentNodeId = null;
-      }
+    const line = lines[i];
+    const bracketOpen = line.indexOf("[");
+    const bracketClose = line.indexOf("] ---", bracketOpen);
+    if (bracketOpen === -1 || bracketClose === -1) continue;
+    const trimmed = line.trimStart();
+    if (!trimmed.startsWith("//")) continue;
+    const candidateId = line.slice(bracketOpen + 1, bracketClose);
+    if (!validNodeIds.has(candidateId)) continue;
+    if (currentNodeId) {
+      mappings[currentNodeId] = {
+        startLine: currentStartLine,
+        endLine: lineNum - 1
+      };
     }
+    currentNodeId = candidateId;
+    currentStartLine = lineNum;
   }
   if (currentNodeId) {
     mappings[currentNodeId] = {
@@ -2302,6 +2318,72 @@ var init_compiler = __esm({
   }
 });
 
+// src/lib/logger.ts
+import pc from "picocolors";
+var LEVEL_ORDER, Logger, logger;
+var init_logger = __esm({
+  "src/lib/logger.ts"() {
+    "use strict";
+    LEVEL_ORDER = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      silent: 4
+    };
+    Logger = class {
+      /** Minimum log level (default: "info"). Set to "silent" to suppress all output. */
+      level = "info";
+      /** Prefix for all log lines (default: "[flow2code]") */
+      prefix = "[flow2code]";
+      shouldLog(level) {
+        return LEVEL_ORDER[level] >= LEVEL_ORDER[this.level];
+      }
+      debug(...args) {
+        if (!this.shouldLog("debug")) return;
+        console.log(pc.gray(`${this.prefix} ${pc.dim("DEBUG")}`), ...args);
+      }
+      info(...args) {
+        if (!this.shouldLog("info")) return;
+        console.log(pc.blue(`${this.prefix}`), ...args);
+      }
+      success(...args) {
+        if (!this.shouldLog("info")) return;
+        console.log(pc.green(`${this.prefix} \u2705`), ...args);
+      }
+      warn(...args) {
+        if (!this.shouldLog("warn")) return;
+        console.warn(pc.yellow(`${this.prefix} \u26A0\uFE0F`), ...args);
+      }
+      error(...args) {
+        if (!this.shouldLog("error")) return;
+        console.error(pc.red(`${this.prefix} \u274C`), ...args);
+      }
+      /** Print a blank line (respects silent mode) */
+      blank() {
+        if (!this.shouldLog("info")) return;
+        console.log();
+      }
+      /** Print raw text without prefix (respects silent mode) */
+      raw(...args) {
+        if (!this.shouldLog("info")) return;
+        console.log(...args);
+      }
+      /** Formatted key-value line for startup banners */
+      kv(key, value) {
+        if (!this.shouldLog("info")) return;
+        console.log(`  ${pc.dim("\u251C\u2500")} ${pc.bold(key)}  ${value}`);
+      }
+      /** Last key-value line (uses └─) */
+      kvLast(key, value) {
+        if (!this.shouldLog("info")) return;
+        console.log(`  ${pc.dim("\u2514\u2500")} ${pc.bold(key)}  ${value}`);
+      }
+    };
+    logger = new Logger();
+  }
+});
+
 // src/lib/compiler/decompiler.ts
 var decompiler_exports = {};
 __export(decompiler_exports, {
@@ -2840,9 +2922,13 @@ function buildEdges(ctx) {
       }
     }
   }
+  const resolveTargetPort = (targetNodeId, fallback) => {
+    const tgt = ctx.nodes.get(targetNodeId);
+    return tgt?.inputs?.[0]?.id ?? fallback;
+  };
   for (const [parentId, children] of ctx.controlFlowChildren) {
     for (const child of children) {
-      addEdge(parentId, child.portId, child.nodeId, "input");
+      addEdge(parentId, child.portId, child.nodeId, resolveTargetPort(child.nodeId, "input"));
       connectedTargets.add(child.nodeId);
     }
   }
@@ -2851,7 +2937,7 @@ function buildEdges(ctx) {
     const predNode = ctx.nodes.get(predId);
     if (!predNode) continue;
     const sourcePort = predNode.outputs[0]?.id ?? "output";
-    addEdge(predId, sourcePort, nodeId, "input");
+    addEdge(predId, sourcePort, nodeId, resolveTargetPort(nodeId, "input"));
   }
 }
 function computeAuditHints(ctx) {
@@ -2983,7 +3069,9 @@ function trackVariableUses(nodeId, expression, ctx) {
     if (seen.has(ident)) continue;
     seen.add(ident);
     if (ctx.varDefs.has(ident)) {
-      uses.push({ nodeId, portId: "input", varName: ident });
+      const targetNode = ctx.nodes.get(nodeId);
+      const portId = targetNode?.inputs?.[0]?.id ?? "input";
+      uses.push({ nodeId, portId, varName: ident });
     }
   }
   if (uses.length > 0) {
@@ -3859,7 +3947,7 @@ __export(server_exports, {
 });
 import { createServer } from "http";
 import { readFile, stat } from "fs/promises";
-import { join as join3, extname as extname2, dirname as dirname3 } from "path";
+import { join as join3, extname as extname2, dirname as dirname3, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { existsSync as existsSync3 } from "fs";
 function resolveStaticDir() {
@@ -3920,7 +4008,7 @@ function sendJson(res, status, body) {
   res.end(JSON.stringify(body));
 }
 async function readBody(req) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const chunks = [];
     let totalSize = 0;
     req.on("data", (chunk) => {
@@ -3932,7 +4020,7 @@ async function readBody(req) {
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve3(Buffer.concat(chunks).toString("utf-8")));
+    req.on("end", () => resolve4(Buffer.concat(chunks).toString("utf-8")));
     req.on("error", reject);
   });
 }
@@ -3941,7 +4029,13 @@ async function parseJsonBody(req) {
   return JSON.parse(raw);
 }
 async function serveStatic(staticDir, pathname, res) {
-  let filePath = join3(staticDir, pathname === "/" ? "index.html" : pathname);
+  const decodedPath = decodeURIComponent(pathname);
+  let filePath = join3(staticDir, decodedPath === "/" ? "index.html" : decodedPath);
+  const resolvedPath = resolve2(filePath);
+  const resolvedStaticDir = resolve2(staticDir);
+  if (!resolvedPath.startsWith(resolvedStaticDir + (resolvedStaticDir.endsWith("/") || resolvedStaticDir.endsWith("\\") ? "" : process.platform === "win32" ? "\\" : "/"))) {
+    return false;
+  }
   if (!extname2(filePath)) {
     filePath += ".html";
   }
@@ -4029,7 +4123,7 @@ function startServer(options = {}) {
   const projectRoot = options.projectRoot ?? process.cwd();
   const server = createServer((req, res) => {
     handleRequest(req, res, staticDir, projectRoot).catch((err) => {
-      console.error("[flow2code] Internal error:", err);
+      logger.error("Internal error:", err);
       res.writeHead(500, { "Content-Type": "text/plain" });
       res.end("Internal Server Error");
     });
@@ -4040,20 +4134,20 @@ function startServer(options = {}) {
     if (options.onReady) {
       options.onReady(url);
     } else {
-      console.log(`
-  \u{1F680} Flow2Code Dev Server`);
-      console.log(`  \u251C\u2500 Local:   ${url}`);
-      console.log(`  \u251C\u2500 API:     ${url}/api/compile`);
-      console.log(`  \u251C\u2500 Static:  ${staticDir}`);
-      console.log(`  \u2514\u2500 Project: ${projectRoot}`);
+      logger.blank();
+      logger.info("Flow2Code Dev Server");
+      logger.kv("Local:", url);
+      logger.kv("API:", `${url}/api/compile`);
+      logger.kv("Static:", staticDir);
+      logger.kvLast("Project:", projectRoot);
       if (!hasUI) {
-        console.log();
-        console.log(`  \u26A0\uFE0F  UI files not found (out/index.html missing).`);
-        console.log(`     The API endpoints still work, but the visual editor won't load.`);
-        console.log(`     To fix: run "pnpm build:ui" in the flow2code source directory,`);
-        console.log(`     or reinstall from npm: npm i @timo9378/flow2code@latest`);
+        logger.blank();
+        logger.warn("UI files not found (out/index.html missing).");
+        logger.raw("     The API endpoints still work, but the visual editor won't load.");
+        logger.raw('     To fix: run "pnpm build:ui" in the flow2code source directory,');
+        logger.raw("     or reinstall from npm: npm i @timo9378/flow2code@latest");
       }
-      console.log();
+      logger.blank();
     }
   });
   return server;
@@ -4063,6 +4157,7 @@ var init_server = __esm({
   "src/server/index.ts"() {
     "use strict";
     init_handlers();
+    init_logger();
     init_handlers();
     __filename = fileURLToPath(import.meta.url);
     __dirname = dirname3(__filename);
@@ -4091,10 +4186,12 @@ var init_server = __esm({
 
 // src/cli/index.ts
 init_compiler();
+init_logger();
 init_validator();
 import { Command } from "commander";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync4, readdirSync as readdirSync2, rmSync as rmSync2 } from "fs";
-import { join as join4, dirname as dirname4, resolve as resolve2, basename as basename2 } from "path";
+import { readFile as readFile2, writeFile, mkdir } from "fs/promises";
+import { join as join4, dirname as dirname4, resolve as resolve3, basename as basename2 } from "path";
 import { watch } from "chokidar";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -4720,7 +4817,7 @@ var pkgJson = JSON.parse(readFileSync3(join4(__cliDirname, "..", "package.json")
 var program = new Command();
 program.name("flow2code").description("Visual AST Compiler: Compile .flow.json into native TypeScript").version(pkgJson.version);
 program.command("compile <file>").description("Compile .flow.json or YAML directory to TypeScript (auto-detects format)").option("-o, --output <path>", "Specify output path (overrides auto-detection)").option("--platform <name>", "Target platform: nextjs | express | cloudflare", "nextjs").option("--dry-run", "Display generated code without writing to file").option("--source-map", "Generate Source Map mapping file (.flow.map.json)").action((file, options) => {
-  const filePath = resolve2(file);
+  const filePath = resolve3(file);
   if (!existsSync4(filePath)) {
     console.error(`\u274C File/directory not found: ${filePath}`);
     process.exit(1);
@@ -4758,7 +4855,7 @@ program.command("compile <file>").description("Compile .flow.json or YAML direct
     process.exit(1);
   }
   const outputPath = options.output ?? result.filePath;
-  const fullOutputPath = resolve2(outputPath);
+  const fullOutputPath = resolve3(outputPath);
   const outputDir = dirname4(fullOutputPath);
   if (!existsSync4(outputDir)) {
     mkdirSync3(outputDir, { recursive: true });
@@ -4771,7 +4868,7 @@ program.command("compile <file>").description("Compile .flow.json or YAML direct
     console.log(`\u{1F5FA}\uFE0F Source Map: ${mapPath}`);
   }
   if (result.dependencies && result.dependencies.all.length > 0) {
-    const projectPkgPath = resolve2("package.json");
+    const projectPkgPath = resolve3("package.json");
     if (existsSync4(projectPkgPath)) {
       try {
         const pkgJson2 = JSON.parse(readFileSync3(projectPkgPath, "utf-8"));
@@ -4794,7 +4891,7 @@ program.command("compile <file>").description("Compile .flow.json or YAML direct
 });
 program.command("audit <file>").description("Decompile any TypeScript file into a visual FlowIR for code auditing").option("-o, --output <path>", "Write IR JSON to file instead of stdout").option("--format <fmt>", "Output format: json | mermaid | summary", "summary").option("--function <name>", "Target function name to decompile").option("--no-audit-hints", "Disable audit hints").action(async (file, options) => {
   const { decompile: decompile2 } = await Promise.resolve().then(() => (init_decompiler(), decompiler_exports));
-  const filePath = resolve2(file);
+  const filePath = resolve3(file);
   if (!existsSync4(filePath)) {
     console.error(`\u274C File not found: ${filePath}`);
     process.exit(1);
@@ -4814,7 +4911,7 @@ program.command("audit <file>").description("Decompile any TypeScript file into
   if (fmt === "json") {
     const output = JSON.stringify(result.ir, null, 2);
     if (options.output) {
-      writeFileSync3(resolve2(options.output), output, "utf-8");
+      writeFileSync3(resolve3(options.output), output, "utf-8");
       console.log(`\u2705 IR written to: ${options.output}`);
     } else {
       console.log(output);
@@ -4822,7 +4919,7 @@ program.command("audit <file>").description("Decompile any TypeScript file into
   } else if (fmt === "mermaid") {
     const mermaidOutput = irToMermaid(result.ir);
     if (options.output) {
-      writeFileSync3(resolve2(options.output), mermaidOutput, "utf-8");
+      writeFileSync3(resolve3(options.output), mermaidOutput, "utf-8");
       console.log(`\u2705 Mermaid diagram written to: ${options.output}`);
     } else {
       console.log(mermaidOutput);
@@ -4849,7 +4946,7 @@ program.command("audit <file>").description("Decompile any TypeScript file into
     console.log("");
     if (options.output) {
       const irJson = JSON.stringify(result.ir, null, 2);
-      writeFileSync3(resolve2(options.output), irJson, "utf-8");
+      writeFileSync3(resolve3(options.output), irJson, "utf-8");
       console.log(`\u2705 IR written to: ${options.output}`);
     }
   }
@@ -4883,8 +4980,8 @@ function irToMermaid(ir) {
   return lines.join("\n");
 }
 program.command("watch [dir]").description("Watch directory, auto-compile .flow.json and YAML directory changes").option("-p, --project <path>", "Next.js project root directory", ".").action((dir = ".", options) => {
-  const watchDir = resolve2(dir);
-  const projectRoot = resolve2(options.project ?? ".");
+  const watchDir = resolve3(dir);
+  const projectRoot = resolve3(options.project ?? ".");
   console.log(`\u{1F440} Watching: ${watchDir}/**/*.flow.json + **/*.yaml`);
   console.log(`\u{1F4C1} Output to: ${projectRoot}`);
   console.log("Press Ctrl+C to stop\n");
@@ -4895,17 +4992,28 @@ program.command("watch [dir]").description("Watch directory, auto-compile .flow.
       ignoreInitial: false
     }
   );
+  const pendingTimers = /* @__PURE__ */ new Map();
+  const DEBOUNCE_MS = 150;
   const handleChange = (filePath) => {
-    if (filePath.endsWith(".flow.json")) {
-      compileFile(filePath, projectRoot);
-    } else if (filePath.endsWith(".yaml")) {
+    let compileKey = filePath;
+    if (filePath.endsWith(".yaml")) {
       let dir2 = dirname4(filePath);
       if (basename2(dir2) === "nodes") dir2 = dirname4(dir2);
-      const metaPath = join4(dir2, "meta.yaml");
-      if (existsSync4(metaPath)) {
-        compileFlowDir(dir2, projectRoot);
+      compileKey = dir2;
+    }
+    const existing = pendingTimers.get(compileKey);
+    if (existing) clearTimeout(existing);
+    pendingTimers.set(compileKey, setTimeout(() => {
+      pendingTimers.delete(compileKey);
+      if (filePath.endsWith(".flow.json")) {
+        compileFileAsync(filePath, projectRoot);
+      } else if (filePath.endsWith(".yaml")) {
+        const metaPath = join4(compileKey, "meta.yaml");
+        if (existsSync4(metaPath)) {
+          compileFlowDirAsync(compileKey, projectRoot);
+        }
       }
-    }
+    }, DEBOUNCE_MS));
   };
   watcher.on("change", handleChange);
   watcher.on("add", handleChange);
@@ -4914,7 +5022,7 @@ program.command("watch [dir]").description("Watch directory, auto-compile .flow.
   });
 });
 program.command("init").description("Initialize Flow2Code in current project (Zero Pollution mode)").action(() => {
-  const flow2codeDir = resolve2(".flow2code");
+  const flow2codeDir = resolve3(".flow2code");
   const flowsDir = join4(flow2codeDir, "flows");
   if (!existsSync4(flow2codeDir)) {
     mkdirSync3(flow2codeDir, { recursive: true });
@@ -4984,7 +5092,7 @@ program.command("init").description("Initialize Flow2Code in current project (Ze
     writeFileSync3(examplePath, JSON.stringify(exampleFlow, null, 2), "utf-8");
     console.log(`\u{1F4C4} Created example: ${examplePath}`);
   }
-  const gitignorePath = resolve2(".gitignore");
+  const gitignorePath = resolve3(".gitignore");
   if (existsSync4(gitignorePath)) {
     const content = readFileSync3(gitignorePath, "utf-8");
     if (!content.includes(".flow2code/")) {
@@ -5003,7 +5111,7 @@ program.command("init").description("Initialize Flow2Code in current project (Ze
   console.log(`  npx ${pkgJson.name} watch .flow2code/flows/`);
 });
 program.command("split <file>").description("Split .flow.json into a Git-friendly YAML directory structure").option("-o, --output <dir>", "Specify output directory (default: same name as file)").action((file, options) => {
-  const filePath = resolve2(file);
+  const filePath = resolve3(file);
   if (!existsSync4(filePath)) {
     console.error(`\u274C File not found: ${filePath}`);
     process.exit(1);
@@ -5019,7 +5127,7 @@ program.command("split <file>").description("Split .flow.json into a Git-friendl
   const outputDir = options.output ?? filePath.replace(/\.flow\.json$|\.json$/, "");
   const written = splitToFileSystem(
     ir,
-    resolve2(outputDir),
+    resolve3(outputDir),
     { mkdirSync: mkdirSync3, writeFileSync: (p, c) => writeFileSync3(p, c, "utf-8") },
     { join: join4 }
   );
@@ -5027,7 +5135,7 @@ program.command("split <file>").description("Split .flow.json into a Git-friendl
   written.forEach((f) => console.log(`  \u{1F4C4} ${f}`));
 });
 program.command("merge <dir>").description("Merge YAML directory structure into a .flow.json").option("-o, --output <file>", "Specify output file path").action((dir, options) => {
-  const dirPath = resolve2(dir);
+  const dirPath = resolve3(dir);
   if (!existsSync4(dirPath)) {
     console.error(`\u274C Directory not found: ${dirPath}`);
     process.exit(1);
@@ -5039,7 +5147,7 @@ program.command("merge <dir>").description("Merge YAML directory structure into
       { join: join4 }
     );
     const outputFile = options.output ?? `${dirPath}.flow.json`;
-    writeFileSync3(resolve2(outputFile), JSON.stringify(ir, null, 2), "utf-8");
+    writeFileSync3(resolve3(outputFile), JSON.stringify(ir, null, 2), "utf-8");
     console.log(`\u2705 Merged to: ${outputFile}`);
     console.log(`   ${ir.nodes.length} nodes, ${ir.edges.length} edges`);
   } catch (err) {
@@ -5048,7 +5156,7 @@ program.command("merge <dir>").description("Merge YAML directory structure into
   }
 });
 program.command("migrate <file>").description("Migrate .flow.json to Git-friendly YAML directory (preserves original file)").option("--delete-json", "Delete original .flow.json after successful migration").action((file, options) => {
-  const filePath = resolve2(file);
+  const filePath = resolve3(file);
   if (!existsSync4(filePath)) {
     console.error(`\u274C File not found: ${filePath}`);
     process.exit(1);
@@ -5069,7 +5177,7 @@ program.command("migrate <file>").description("Migrate .flow.json to Git-friendl
   }
 });
 program.command("trace <file> <line>").description("Trace a generated code line number back to its canvas node (Source Map)").action((file, lineStr) => {
-  const filePath = resolve2(file);
+  const filePath = resolve3(file);
   const lineNum = parseInt(lineStr, 10);
   if (isNaN(lineNum) || lineNum < 1) {
     console.error("\u274C Line number must be a positive integer");
@@ -5099,8 +5207,8 @@ program.command("trace <file> <line>").description("Trace a generated code line
   }
 });
 program.command("diff <before> <after>").description("Compare semantic differences between two .flow.json files").action((beforeFile, afterFile) => {
-  const beforePath = resolve2(beforeFile);
-  const afterPath = resolve2(afterFile);
+  const beforePath = resolve3(beforeFile);
+  const afterPath = resolve3(afterFile);
   if (!existsSync4(beforePath)) {
     console.error(`\u274C File not found: ${beforePath}`);
     process.exit(1);
@@ -5122,8 +5230,8 @@ program.command("diff <before> <after>").description("Compare semantic differenc
   console.log(formatDiff(summary));
 });
 program.command("env-check <file>").description("Validate that environment variables referenced in .flow.json are declared").option("-e, --env <envFile>", "Specify .env file path", ".env").action((file, options) => {
-  const filePath = resolve2(file);
-  const envPath = resolve2(options.env);
+  const filePath = resolve3(file);
+  const envPath = resolve3(options.env);
   if (!existsSync4(filePath)) {
     console.error(`\u274C File not found: ${filePath}`);
     process.exit(1);
@@ -5140,7 +5248,7 @@ program.command("env-check <file>").description("Validate that environment varia
     const envContent = readFileSync3(envPath, "utf-8");
     declaredVars = parseEnvFile(envContent);
   } else {
-    const examplePath = resolve2(".env.example");
+    const examplePath = resolve3(".env.example");
     if (existsSync4(examplePath)) {
       const envContent = readFileSync3(examplePath, "utf-8");
       declaredVars = parseEnvFile(envContent);
@@ -5151,7 +5259,11 @@ program.command("env-check <file>").description("Validate that environment varia
 `);
     }
   }
-  const result = validateEnvVars(ir, declaredVars);
+  const systemEnvKeys = Object.keys(process.env).filter(
+    (k) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k)
+  );
+  const allDeclaredVars = [.../* @__PURE__ */ new Set([...declaredVars, ...systemEnvKeys])];
+  const result = validateEnvVars(ir, allDeclaredVars);
   console.log(formatEnvValidationReport(result));
   if (!result.valid) {
     process.exit(1);
@@ -5176,12 +5288,29 @@ async function startDevServer(options) {
     }
   });
 }
-program.command("dev").description("Start Flow2Code visual editor (standalone dev server)").option("-p, --port <port>", "Server port", "3100").option("--no-open", "Do not auto-open browser").action(startDevServer);
-program.command("ui").description("Start Flow2Code visual editor (alias for dev)").option("-p, --port <port>", "Server port", "3100").option("--no-open", "Do not auto-open browser").action(startDevServer);
-function compileFile(filePath, projectRoot) {
+program.command("dev").description("Start Flow2Code visual editor (standalone dev server)").option("-p, --port <port>", "Server port", "3100").option("--no-open", "Do not auto-open browser").option("--silent", "Suppress non-error output (for CI/CD)").action((opts) => {
+  if (opts.silent) logger.level = "silent";
+  startDevServer(opts);
+});
+program.command("ui").description("Start Flow2Code visual editor (alias for dev)").option("-p, --port <port>", "Server port", "3100").option("--no-open", "Do not auto-open browser").option("--silent", "Suppress non-error output (for CI/CD)").action((opts) => {
+  if (opts.silent) logger.level = "silent";
+  startDevServer(opts);
+});
+function generateEnvExample() {
+  const envExamplePath = resolve3(".env.example");
+  if (!existsSync4(envExamplePath)) {
+    writeFileSync3(
+      envExamplePath,
+      "# Flow2Code environment variables\n# Define API keys and sensitive information here\n",
+      "utf-8"
+    );
+    console.log("\u{1F4DD} Generated .env.example");
+  }
+}
+async function compileFileAsync(filePath, projectRoot) {
   const startTime = Date.now();
   try {
-    const raw = readFileSync3(filePath, "utf-8");
+    const raw = await readFile2(filePath, "utf-8");
     const ir = JSON.parse(raw);
     const validation = validateFlowIR(ir);
     if (!validation.valid) {
@@ -5202,9 +5331,9 @@ function compileFile(filePath, projectRoot) {
     const outputPath = join4(projectRoot, result.filePath);
     const outputDir = dirname4(outputPath);
     if (!existsSync4(outputDir)) {
-      mkdirSync3(outputDir, { recursive: true });
+      await mkdir(outputDir, { recursive: true });
     }
-    writeFileSync3(outputPath, result.code, "utf-8");
+    await writeFile(outputPath, result.code, "utf-8");
     const elapsed = Date.now() - startTime;
     console.log(`\u2705 [${elapsed}ms] ${filePath} \u2192 ${outputPath}`);
   } catch (err) {
@@ -5213,7 +5342,7 @@ function compileFile(filePath, projectRoot) {
     );
   }
 }
-function compileFlowDir(dirPath, projectRoot) {
+async function compileFlowDirAsync(dirPath, projectRoot) {
   const startTime = Date.now();
   try {
     const project = loadFlowProject(dirPath);
@@ -5237,9 +5366,9 @@ function compileFlowDir(dirPath, projectRoot) {
     const outputPath = join4(projectRoot, result.filePath);
     const outputDir = dirname4(outputPath);
     if (!existsSync4(outputDir)) {
-      mkdirSync3(outputDir, { recursive: true });
+      await mkdir(outputDir, { recursive: true });
     }
-    writeFileSync3(outputPath, result.code, "utf-8");
+    await writeFile(outputPath, result.code, "utf-8");
     const elapsed = Date.now() - startTime;
     console.log(`\u2705 [${elapsed}ms] ${dirPath}/ \u2192 ${outputPath}`);
   } catch (err) {
@@ -5248,17 +5377,6 @@ function compileFlowDir(dirPath, projectRoot) {
     );
   }
 }
-function generateEnvExample() {
-  const envExamplePath = resolve2(".env.example");
-  if (!existsSync4(envExamplePath)) {
-    writeFileSync3(
-      envExamplePath,
-      "# Flow2Code environment variables\n# Define API keys and sensitive information here\n",
-      "utf-8"
-    );
-    console.log("\u{1F4DD} Generated .env.example");
-  }
-}
 if (process.argv.length <= 2) {
   program.help();
 }