@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/cli/clean.ts

@@ -1,31 +1,19 @@
 #!/usr/bin/env node
 import TypeScriptCompiler from "../src/TypeScriptCompiler";
+import { parseArgs, hasFlag, printHelp } from "./cli-utils";
 
-module.exports = async function run(args: string[]) {
-  if (args.includes("--help")) {
-    console.log(`
-    Description
-      Removes all generated files.
+module.exports = async function clean(args: string[]) {
+    const parsed = parseArgs(args);
 
-    Usage
-      $ flink clean <dir>
+    if (hasFlag(parsed, "help")) {
+        printHelp({
+            description: "Removes all generated files.",
+            usage: "$ flink clean <dir>",
+            options: [{ name: "help", description: "Displays this message" }],
+        });
+        return;
+    }
 
-    <dir> represents the directory of the Flink application.
-    If no directory is provided, the current directory will be used.
-      
-    Options
-      --help    Displays this message
-      `);
-
-    process.exit(0);
-  }
-
-  let dir = "./";
-  if (args[0] && !args[0].startsWith("--")) {
-    dir = args[0];
-  }
-
-  const cleanedFolder = await TypeScriptCompiler.clean(dir);
-
-  console.log(`Cleaned directory ${cleanedFolder}`);
+    const cleanedFolder = await TypeScriptCompiler.clean(parsed.dir);
+    console.log(`Cleaned directory ${cleanedFolder}`);
 };

package/cli/cli-utils.ts

@@ -1,22 +1,195 @@
-export function getOption(
-  args: string[],
-  name: string,
-  defaultValue: string | boolean,
-  opts: { isBoolean?: boolean } = {}
-) {
-  const option = `--${name}`;
-  if (args.includes(option)) {
-    if (opts.isBoolean && args[args.indexOf(option) + 1] !== "false") {
-      return true;
+import TypeScriptCompiler from "../src/TypeScriptCompiler";
+
+// --- Arg Parsing ---
+
+export interface ParsedArgs {
+    dir: string;
+    flags: Set<string>;
+    options: Map<string, string>;
+}
+
+export function parseArgs(args: string[]): ParsedArgs {
+    const flags = new Set<string>();
+    const options = new Map<string, string>();
+    let dir = "./";
+
+    let i = 0;
+
+    // First non-flag arg is the directory
+    if (args[0] && !args[0].startsWith("--")) {
+        dir = args[0];
+        i = 1;
     }
 
-    const value = args[args.indexOf(option) + 1];
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            const next = args[i + 1];
+            if (next && !next.startsWith("--")) {
+                options.set(name, next);
+                i += 2;
+            } else {
+                flags.add(name);
+                i += 1;
+            }
+        } else {
+            i += 1;
+        }
+    }
+
+    return { dir, flags, options };
+}
+
+export function hasFlag(parsed: ParsedArgs, name: string): boolean {
+    return parsed.flags.has(name);
+}
+
+export function getOption(parsed: ParsedArgs, name: string, defaultValue: string): string {
+    return parsed.options.get(name) ?? defaultValue;
+}
+
+export function normalizeEntry(entry: string): string {
+    return entry.startsWith("/") ? entry : "/" + entry;
+}
+
+// --- Help ---
+
+interface HelpOption {
+    name: string;
+    description: string;
+}
+
+interface HelpConfig {
+    description: string;
+    usage: string;
+    options: HelpOption[];
+}
+
+export function printHelp(config: HelpConfig): void {
+    const optionLines = config.options
+        .map((opt) => `      --${opt.name.padEnd(14)} ${opt.description}`)
+        .join("\n");
+
+    console.log(`
+    Description
+      ${config.description}
+
+    Usage
+      ${config.usage}
+
+    <dir> represents the directory of the Flink application.
+    If no directory is provided, the current directory will be used.
+
+    Options
+${optionLines}
+`);
+}
 
-    if (!value || value.startsWith("--")) {
-      console.log("WARN: Missing value for option", option);
-      process.exit(1);
+// --- Compile ---
+
+export interface CompileOptions {
+    dir: string;
+    entry?: string;
+    typeCheck?: boolean;
+    timingLogs?: boolean;
+}
+
+export async function compile(opts: CompileOptions): Promise<void> {
+    const { dir, entry, typeCheck = true, timingLogs = false } = opts;
+
+    const start = timingLogs ? Date.now() : 0;
+    const time = (label: string, stepStart: number) => {
+        if (timingLogs) {
+            console.log(`⏱️  ${label}: ${Date.now() - stepStart}ms`);
+        }
+    };
+
+    await TypeScriptCompiler.clean(dir);
+
+    let stepStart = Date.now();
+    const compiler = new TypeScriptCompiler(dir);
+    time("Compiler initialization", stepStart);
+
+    stepStart = Date.now();
+    await compiler.parseRepos();
+    await compiler.parseTools();
+    await compiler.parseAgents();
+    await compiler.parseJobs();
+    await compiler.parseServices();
+    await compiler.parseAllExtensionDirs();
+    await compiler.parseHandlers();
+    await compiler.generateStartScript(entry);
+    await compiler.generateAllSchemas();
+    await compiler.saveAllModifiedFiles();
+
+    if (typeCheck) {
+        stepStart = Date.now();
+        if (!compiler.getPreEmitDiagnostics()) {
+            throw new Error("Type checking failed");
+        }
+        time("Type checking (getPreEmitDiagnostics)", stepStart);
+    }
+
+    stepStart = Date.now();
+    if (process.env.FLINK_USE_TSC === "true") {
+        compiler.emitWithTsc();
+    } else {
+        await compiler.emit();
     }
-    return value;
-  }
-  return defaultValue;
+    time(`Transpilation (${process.env.FLINK_USE_TSC === "true" ? "tsc" : "swc"})`, stepStart);
+
+    if (timingLogs) {
+        console.log(`Compilation done in ${Date.now() - start}ms`);
+    }
+}
+
+// --- Fork ---
+
+export interface ForkOptions {
+    dir: string;
+    args: string[];
+    cliFlags: string[];
+    stdio?: "inherit" | "pipe" | "ignore";
+}
+
+export function forkApp(opts: ForkOptions): ReturnType<typeof require> {
+    const { dir, args, cliFlags, stdio } = opts;
+
+    // Filter out CLI-specific flags and their values from args passed to child process
+    const cliSet = new Set(cliFlags.map((f) => `--${f}`));
+    const extraArgs: string[] = [];
+
+    for (let i = 0; i < args.length; i++) {
+        if (cliSet.has(args[i])) {
+            // Skip this flag and its value (if the next arg is not a flag)
+            const next = args[i + 1];
+            if (next && !next.startsWith("--")) {
+                i++; // skip value too
+            }
+            continue;
+        }
+        // Skip the dir argument (first non-flag arg)
+        if (i === 0 && !args[i].startsWith("--")) {
+            continue;
+        }
+        extraArgs.push(args[i]);
+    }
+
+    const forkOpts: any = {};
+    if (stdio) {
+        forkOpts.stdio = stdio;
+    }
+
+    const forkedProcess = require("child_process").fork(
+        dir + "/dist/.flink/start.js",
+        extraArgs,
+        forkOpts
+    );
+
+    forkedProcess.on("exit", (code: any) => {
+        process.exit(code);
+    });
+
+    return forkedProcess;
 }

package/cli/dev.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import chokidar from "chokidar";
+import { spawn, ChildProcess } from "child_process";
+import { resolve, join, dirname } from "path";
+import { existsSync } from "fs";
+import { parseArgs, hasFlag, getOption, normalizeEntry, printHelp, compile, forkApp } from "./cli-utils";
+import { FlinkLogFactory } from "../src/FlinkLogFactory";
+import { loadFlinkConfig } from "../src/utils/loadFlinkConfig";
+import { loadEnvFiles } from "./loadEnvFiles";
+
+// Load config BEFORE creating logger
+const flinkConfig = loadFlinkConfig();
+FlinkLogFactory.configure(flinkConfig?.logging);
+
+const logger = FlinkLogFactory.createLogger("flink.dev");
+
+module.exports = async function dev(args: string[]) {
+    const parsed = parseArgs(args);
+
+    // Load .env files before anything else so all env vars are available at startup.
+    // NODE_ENV defaults to "development" when not explicitly set.
+    if (!process.env.NODE_ENV) {
+        process.env.NODE_ENV = "development";
+    }
+
+    const initLogger = FlinkLogFactory.createLogger("flink.init");
+    const { loaded, injected } = loadEnvFiles(parsed.dir, "development");
+
+    if (loaded.length > 0) {
+        initLogger.info(`Loaded env files: ${loaded.join(", ")} (${injected} vars injected)`);
+    }
+
+    if (hasFlag(parsed, "help")) {
+        printHelp({
+            description:
+                "Starts development mode with watch and auto-reload.\n      Fast rebuilds with swc (skips type checking by default).\n      Runs background tsc --watch for async type error reporting.",
+            usage: "$ flink dev <dir>",
+            options: [
+                { name: "typecheck", description: "Run type checking on every rebuild (slower, disables background tsc)" },
+                { name: "no-typecheck", description: "Disable background type checking entirely" },
+                { name: "entry", description: 'Entry script for app, default "/src/index.ts"' },
+                { name: "help", description: "Displays this message" },
+            ],
+        });
+        return;
+    }
+
+    const dir = parsed.dir;
+    const entry = normalizeEntry(getOption(parsed, "entry", "/src/index.ts"));
+    const typecheck = hasFlag(parsed, "typecheck");
+    const noTypecheck = hasFlag(parsed, "no-typecheck");
+
+    console.log("🚀 Flink dev mode starting...\n");
+
+    // Initial build (skip type checking for speed unless --typecheck flag)
+    console.log(`📦 Initial build ${typecheck ? "(with type checking)" : "(fast mode, skipping type check)"}...`);
+    await compile({ dir, entry, typeCheck: typecheck });
+
+    let serverProcess: ChildProcess | null = null;
+    let tscProcess: ChildProcess | null = null;
+    let isRebuilding = false;
+    let pendingRebuild = false;
+
+    // Start server
+    serverProcess = startServer(dir);
+
+    // Start background tsc --watch for async type checking (unless --typecheck or --no-typecheck)
+    if (!typecheck && !noTypecheck) {
+        tscProcess = startTscWatch(dir);
+    }
+
+    // Watch for changes
+    const watcher = chokidar.watch([`${dir}/src/**/*.ts`, `${dir}/src/**/*.json`], {
+        ignored: ["**/.flink/**", "**/dist/**", "**/node_modules/**", "**/*.spec.ts", "**/*.test.ts"],
+        persistent: true,
+        ignoreInitial: true,
+    });
+
+    watcher.on("change", async (path) => {
+        if (isRebuilding) {
+            pendingRebuild = true;
+            return;
+        }
+
+        isRebuilding = true;
+        logger.info(`\n📝 File changed: ${path}`);
+        logger.info("🔄 Rebuilding...");
+
+        const rebuildStart = Date.now();
+
+        try {
+            await compile({ dir, entry, typeCheck: typecheck });
+
+            // Restart server — wait for old process to fully exit before binding port again
+            if (serverProcess) {
+                await killAndWait(serverProcess);
+                serverProcess = null;
+            }
+            serverProcess = startServer(dir);
+
+            const rebuildTime = Date.now() - rebuildStart;
+            logger.info(`✅ Rebuild complete in ${rebuildTime}ms\n`);
+        } catch (error: any) {
+            logger.error(`❌ Rebuild failed: ${error.message}`);
+        }
+
+        isRebuilding = false;
+
+        // If another change happened during rebuild, trigger again
+        if (pendingRebuild) {
+            pendingRebuild = false;
+            watcher.emit("change", path);
+        }
+    });
+
+    watcher.on("ready", () => {
+        console.log("\n👀 Watching for changes...");
+        if (tscProcess) {
+            console.log("   TypeScript type checking running in background");
+        }
+        console.log("   Press Ctrl+C to stop\n");
+    });
+
+    // Cleanup on exit
+    process.on("SIGINT", () => {
+        console.log("\n\n🛑 Stopping dev mode...");
+        if (serverProcess) {
+            serverProcess.kill();
+        }
+        if (tscProcess) {
+            tscProcess.kill();
+        }
+        watcher.close();
+        process.exit(0);
+    });
+};
+
+function killAndWait(proc: ChildProcess): Promise<void> {
+    return new Promise((resolve) => {
+        if (proc.exitCode !== null) {
+            // Already exited
+            resolve();
+            return;
+        }
+        proc.once("exit", () => resolve());
+        proc.kill();
+        // Safety timeout: if the process doesn't exit within 5s, force-kill it
+        const timeout = setTimeout(() => {
+            proc.kill("SIGKILL");
+        }, 5000);
+        proc.once("exit", () => clearTimeout(timeout));
+    });
+}
+
+function startServer(dir: string): ChildProcess {
+    console.log("🚀 Starting server...");
+
+    const { fork } = require("child_process");
+    const serverProcess = fork(`${dir}/dist/.flink/start.js`, [], {
+        stdio: "inherit",
+    });
+
+    serverProcess.on("exit", (code: number | null) => {
+        if (code !== null && code !== 0) {
+            logger.error(`❌ Server exited with code ${code}`);
+        }
+    });
+
+    return serverProcess;
+}
+
+function findTsc(startDir: string): string | null {
+    let current = startDir;
+    while (true) {
+        const candidate = join(current, "node_modules", ".bin", "tsc");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    return null;
+}
+
+function startTscWatch(dir: string): ChildProcess {
+    const absoluteDir = resolve(dir);
+    const tscPath = findTsc(absoluteDir);
+
+    if (!tscPath) {
+        logger.warn("Background type checking unavailable: typescript not found in node_modules");
+        const noop = spawn("node", ["-e", ""], { stdio: "ignore" });
+        return noop;
+    }
+
+    const tsBuildInfoPath = join(absoluteDir, ".flink", "tsconfig.tsbuildinfo");
+    const tsc = spawn(tscPath, ["--noEmit", "--watch", "--preserveWatchOutput", "--pretty", "--incremental", "--tsBuildInfoFile", tsBuildInfoPath], {
+        cwd: absoluteDir,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let buffer = "";
+
+    const processOutput = (data: Buffer) => {
+        buffer += data.toString();
+
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+
+        for (const line of lines) {
+            const trimmed = line.replace(/\x1Bc/g, "").trim();
+
+            if (!trimmed) continue;
+
+            // Filter out noisy watch-mode status lines
+            if (
+                trimmed.includes("Starting compilation") ||
+                trimmed.includes("File change detected") ||
+                trimmed.match(/^\[\d+:\d+:\d+\s+[AP]M\] Watching for file changes/)
+            ) {
+                continue;
+            }
+
+            if (trimmed.includes("Found 0 errors")) {
+                console.log(`[tsc] ✓ No type errors`);
+            } else if (trimmed.match(/Found \d+ errors?/)) {
+                // Pretty-print the error count summary
+                const match = trimmed.match(/Found (\d+) errors?/);
+                const count = match?.[1];
+                console.log(`[tsc] ❌ Found ${count} type error${count === "1" ? "" : "s"} — see details above`);
+            } else {
+                // Show everything else: error details, file paths, code context, etc.
+                console.log(`[tsc] ${trimmed}`);
+            }
+        }
+    };
+
+    tsc.stdout?.on("data", processOutput);
+    tsc.stderr?.on("data", processOutput);
+
+    tsc.on("error", (err) => {
+        logger.warn(`Background type checking unavailable: ${err.message}`);
+    });
+
+    tsc.on("exit", (code) => {
+        if (code !== null && code !== 0) {
+            logger.debug(`Background tsc exited with code ${code}`);
+        }
+    });
+
+    return tsc;
+}

package/cli/loadEnvFiles.ts

@@ -0,0 +1,116 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve, join } from "path";
+
+/**
+ * Parse the contents of a .env file into a key/value map.
+ *
+ * Rules:
+ * - Empty lines and lines starting with # are skipped
+ * - "export FOO=bar" is treated the same as "FOO=bar"
+ * - Quoted values (single or double) are unquoted, and their content is used as-is
+ * - Unquoted values have inline comments stripped: FOO=bar # comment → "bar"
+ */
+export function parseEnvContent(content: string): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const rawLine of content.split("\n")) {
+        let line = rawLine.trim();
+
+        // Skip empty lines and full-line comments
+        if (!line || line.startsWith("#")) continue;
+
+        // Strip "export " prefix
+        if (line.startsWith("export ")) {
+            line = line.slice(7).trim();
+        }
+
+        const eqIdx = line.indexOf("=");
+        if (eqIdx === -1) continue;
+
+        const key = line.slice(0, eqIdx).trim();
+        if (!key) continue;
+
+        let value = line.slice(eqIdx + 1);
+
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            // Quoted value — strip quotes, preserve content as-is
+            value = value.slice(1, -1);
+        } else {
+            // Unquoted — strip inline comments (" # ...") and trim
+            const commentIdx = value.search(/ #/);
+            if (commentIdx !== -1) {
+                value = value.slice(0, commentIdx);
+            }
+            value = value.trim();
+        }
+
+        result[key] = value;
+    }
+
+    return result;
+}
+
+function readEnvFile(filepath: string): Record<string, string> | null {
+    if (!existsSync(filepath)) return null;
+    try {
+        return parseEnvContent(readFileSync(filepath, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+export interface LoadEnvFilesResult {
+    /** Relative filenames that were found and loaded, in load order */
+    loaded: string[];
+    /** Number of variables injected into process.env (excludes already-set vars) */
+    injected: number;
+}
+
+/**
+ * Load .env files in Next.js-compatible order.
+ *
+ * Priority (highest wins):
+ *   1. process.env (already-set variables are never overridden)
+ *   2. .env.[environment].local
+ *   3. .env.local               (skipped when environment === "test")
+ *   4. .env.[environment]
+ *   5. .env
+ *
+ * @param dir     Root directory of the Flink app (where .env files live)
+ * @param environment  "development" | "production" | "test"
+ */
+export function loadEnvFiles(dir: string, environment: "development" | "production" | "test"): LoadEnvFilesResult {
+    const absoluteDir = resolve(dir);
+
+    // Files listed from lowest to highest priority so that Object.assign
+    // naturally lets later files override earlier ones.
+    const candidates: string[] = [
+        ".env",
+        `.env.${environment}`,
+        // .env.local is intentionally skipped in test (matches Next.js behaviour)
+        ...(environment !== "test" ? [".env.local"] : []),
+        `.env.${environment}.local`,
+    ];
+
+    const loaded: string[] = [];
+    const merged: Record<string, string> = {};
+
+    for (const filename of candidates) {
+        const parsed = readEnvFile(join(absoluteDir, filename));
+        if (parsed !== null) {
+            loaded.push(filename);
+            Object.assign(merged, parsed);
+        }
+    }
+
+    // Inject into process.env — existing values always win
+    let injected = 0;
+    for (const [key, value] of Object.entries(merged)) {
+        if (!(key in process.env)) {
+            process.env[key] = value;
+            injected++;
+        }
+    }
+
+    return { loaded, injected };
+}