@flink-app/flink 2.0.0-alpha.58 → 2.0.0-alpha.60

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.60
+
+## 2.0.0-alpha.59
+
+### Minor Changes
+
+-   dbc2119: feat: add generic compiler extension system and @flink-app/inbound-email-plugin
+
+    Add `compilerPlugins` to `FlinkConfig` and `FlinkCompilerPlugin` interface so plugins can declare custom scan directories for auto-discovery. The TypeScript compiler reads these at build time, generates the corresponding `.flink/generatedXxx.ts` registration files, and includes them in the start script.
+
+    Introduce `@flink-app/inbound-email-plugin` as the first consumer of this system. It starts an SMTP server and automatically routes inbound emails to matching `EmailHandler` files discovered in `src/email-handlers/`. User and permission context are injected via `AsyncLocalStorage` for seamless integration with Flink tools and agents.
+
 ## 2.0.0-alpha.58
 
 ### Patch Changes

package/cli/cli-utils.ts

@@ -116,6 +116,7 @@ export async function compile(opts: CompileOptions): Promise<void> {
     await compiler.parseTools();
     await compiler.parseAgents();
     await compiler.parseJobs();
+    await compiler.parseAllExtensionDirs();
     await compiler.parseHandlers();
     await compiler.generateStartScript(entry);
     await compiler.generateAllSchemas();

package/cli/dev.ts

@@ -6,6 +6,7 @@ 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();
@@ -16,6 +17,19 @@ 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:
@@ -181,15 +195,24 @@ function startTscWatch(dir: string): ChildProcess {
 
             if (!trimmed) continue;
 
-            if (trimmed.includes("Starting compilation") || trimmed.includes("File change detected")) {
+            // 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.includes("Found") && trimmed.includes("error")) {
-                console.log(`[tsc] ${trimmed}`);
-            } else if (trimmed.includes("error TS")) {
+            } 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}`);
             }
         }

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 };
+}

package/cli/run.ts

@@ -2,6 +2,7 @@
 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();
@@ -10,6 +11,19 @@ FlinkLogFactory.configure(flinkConfig?.logging);
 module.exports = async function run(args: string[]) {
     const parsed = parseArgs(args);
 
+    // Load .env files before anything else so all env vars are available at startup.
+    // NODE_ENV defaults to "production" when not explicitly set.
+    if (!process.env.NODE_ENV) {
+        process.env.NODE_ENV = "production";
+    }
+
+    const initLogger = FlinkLogFactory.createLogger("flink.init");
+    const { loaded, injected } = loadEnvFiles(parsed.dir, "production");
+
+    if (loaded.length > 0) {
+        initLogger.info(`Loaded env files: ${loaded.join(", ")} (${injected} vars injected)`);
+    }
+
     if (hasFlag(parsed, "help")) {
         printHelp({
             description: "Compiles and starts the application.",

package/dist/cli/cli-utils.js

@@ -125,17 +125,20 @@ function compile(opts) {
                     return [4 /*yield*/, compiler.parseJobs()];
                 case 5:
                     _c.sent();
-                    return [4 /*yield*/, compiler.parseHandlers()];
+                    return [4 /*yield*/, compiler.parseAllExtensionDirs()];
                 case 6:
                     _c.sent();
-                    return [4 /*yield*/, compiler.generateStartScript(entry)];
+                    return [4 /*yield*/, compiler.parseHandlers()];
                 case 7:
                     _c.sent();
-                    return [4 /*yield*/, compiler.generateAllSchemas()];
+                    return [4 /*yield*/, compiler.generateStartScript(entry)];
                 case 8:
                     _c.sent();
-                    return [4 /*yield*/, compiler.saveAllModifiedFiles()];
+                    return [4 /*yield*/, compiler.generateAllSchemas()];
                 case 9:
+                    _c.sent();
+                    return [4 /*yield*/, compiler.saveAllModifiedFiles()];
+                case 10:
                     _c.sent();
                     if (typeCheck) {
                         stepStart = Date.now();
@@ -145,14 +148,14 @@ function compile(opts) {
                         time("Type checking (getPreEmitDiagnostics)", stepStart);
                     }
                     stepStart = Date.now();
-                    if (!(process.env.FLINK_USE_TSC === "true")) return [3 /*break*/, 10];
+                    if (!(process.env.FLINK_USE_TSC === "true")) return [3 /*break*/, 11];
                     compiler.emitWithTsc();
-                    return [3 /*break*/, 12];
-                case 10: return [4 /*yield*/, compiler.emit()];
-                case 11:
-                    _c.sent();
-                    _c.label = 12;
+                    return [3 /*break*/, 13];
+                case 11: return [4 /*yield*/, compiler.emit()];
                 case 12:
+                    _c.sent();
+                    _c.label = 13;
+                case 13:
                     time("Transpilation (".concat(process.env.FLINK_USE_TSC === "true" ? "tsc" : "swc", ")"), stepStart);
                     if (timingLogs) {
                         console.log("Compilation done in ".concat(Date.now() - start, "ms"));

package/dist/cli/dev.js

@@ -47,18 +47,29 @@ var fs_1 = require("fs");
 var cli_utils_1 = require("./cli-utils");
 var FlinkLogFactory_1 = require("../src/FlinkLogFactory");
 var loadFlinkConfig_1 = require("../src/utils/loadFlinkConfig");
+var loadEnvFiles_1 = require("./loadEnvFiles");
 // Load config BEFORE creating logger
 var flinkConfig = (0, loadFlinkConfig_1.loadFlinkConfig)();
 FlinkLogFactory_1.FlinkLogFactory.configure(flinkConfig === null || flinkConfig === void 0 ? void 0 : flinkConfig.logging);
 var logger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.dev");
 module.exports = function dev(args) {
     return __awaiter(this, void 0, void 0, function () {
-        var parsed, dir, entry, typecheck, noTypecheck, serverProcess, tscProcess, isRebuilding, pendingRebuild, watcher;
+        var parsed, initLogger, _a, loaded, injected, dir, entry, typecheck, noTypecheck, serverProcess, tscProcess, isRebuilding, pendingRebuild, watcher;
         var _this = this;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        return __generator(this, function (_b) {
+            switch (_b.label) {
                 case 0:
                     parsed = (0, cli_utils_1.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";
+                    }
+                    initLogger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
+                    _a = (0, loadEnvFiles_1.loadEnvFiles)(parsed.dir, "development"), loaded = _a.loaded, injected = _a.injected;
+                    if (loaded.length > 0) {
+                        initLogger.info("Loaded env files: ".concat(loaded.join(", "), " (").concat(injected, " vars injected)"));
+                    }
                     if ((0, cli_utils_1.hasFlag)(parsed, "help")) {
                         (0, cli_utils_1.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.",
@@ -81,7 +92,7 @@ module.exports = function dev(args) {
                     console.log("\uD83D\uDCE6 Initial build ".concat(typecheck ? "(with type checking)" : "(fast mode, skipping type check)", "..."));
                     return [4 /*yield*/, (0, cli_utils_1.compile)({ dir: dir, entry: entry, typeCheck: typecheck })];
                 case 1:
-                    _a.sent();
+                    _b.sent();
                     serverProcess = null;
                     tscProcess = null;
                     isRebuilding = false;
@@ -215,16 +226,23 @@ function startTscWatch(dir) {
             var trimmed = line.replace(/\x1Bc/g, "").trim();
             if (!trimmed)
                 continue;
-            if (trimmed.includes("Starting compilation") || trimmed.includes("File change detected")) {
+            // 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] \u2713 No type errors");
             }
-            else if (trimmed.includes("Found") && trimmed.includes("error")) {
-                console.log("[tsc] ".concat(trimmed));
+            else if (trimmed.match(/Found \d+ errors?/)) {
+                // Pretty-print the error count summary
+                var match = trimmed.match(/Found (\d+) errors?/);
+                var count = match === null || match === void 0 ? void 0 : match[1];
+                console.log("[tsc] \u274C Found ".concat(count, " type error").concat(count === "1" ? "" : "s", " \u2014 see details above"));
             }
-            else if (trimmed.includes("error TS")) {
+            else {
+                // Show everything else: error details, file paths, code context, etc.
                 console.log("[tsc] ".concat(trimmed));
             }
         }

package/dist/cli/loadEnvFiles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function parseEnvContent(content: string): Record<string, string>;
+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 declare function loadEnvFiles(dir: string, environment: "development" | "production" | "test"): LoadEnvFilesResult;

package/dist/cli/loadEnvFiles.js

@@ -0,0 +1,113 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvContent = parseEnvContent;
+exports.loadEnvFiles = loadEnvFiles;
+var fs_1 = require("fs");
+var path_1 = require("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"
+ */
+function parseEnvContent(content) {
+    var result = {};
+    for (var _i = 0, _a = content.split("\n"); _i < _a.length; _i++) {
+        var rawLine = _a[_i];
+        var 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();
+        }
+        var eqIdx = line.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        var key = line.slice(0, eqIdx).trim();
+        if (!key)
+            continue;
+        var 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
+            var commentIdx = value.search(/ #/);
+            if (commentIdx !== -1) {
+                value = value.slice(0, commentIdx);
+            }
+            value = value.trim();
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function readEnvFile(filepath) {
+    if (!(0, fs_1.existsSync)(filepath))
+        return null;
+    try {
+        return parseEnvContent((0, fs_1.readFileSync)(filepath, "utf-8"));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * 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"
+ */
+function loadEnvFiles(dir, environment) {
+    var absoluteDir = (0, path_1.resolve)(dir);
+    // Files listed from lowest to highest priority so that Object.assign
+    // naturally lets later files override earlier ones.
+    var candidates = __spreadArray(__spreadArray([
+        ".env",
+        ".env.".concat(environment)
+    ], (environment !== "test" ? [".env.local"] : []), true), [
+        ".env.".concat(environment, ".local"),
+    ], false);
+    var loaded = [];
+    var merged = {};
+    for (var _i = 0, candidates_1 = candidates; _i < candidates_1.length; _i++) {
+        var filename = candidates_1[_i];
+        var parsed = readEnvFile((0, path_1.join)(absoluteDir, filename));
+        if (parsed !== null) {
+            loaded.push(filename);
+            Object.assign(merged, parsed);
+        }
+    }
+    // Inject into process.env — existing values always win
+    var injected = 0;
+    for (var _a = 0, _b = Object.entries(merged); _a < _b.length; _a++) {
+        var _c = _b[_a], key = _c[0], value = _c[1];
+        if (!(key in process.env)) {
+            process.env[key] = value;
+            injected++;
+        }
+    }
+    return { loaded: loaded, injected: injected };
+}

package/dist/cli/run.js

@@ -40,16 +40,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var cli_utils_1 = require("./cli-utils");
 var FlinkLogFactory_1 = require("../src/FlinkLogFactory");
 var loadFlinkConfig_1 = require("../src/utils/loadFlinkConfig");
+var loadEnvFiles_1 = require("./loadEnvFiles");
 // Load config BEFORE creating logger
 var flinkConfig = (0, loadFlinkConfig_1.loadFlinkConfig)();
 FlinkLogFactory_1.FlinkLogFactory.configure(flinkConfig === null || flinkConfig === void 0 ? void 0 : flinkConfig.logging);
 module.exports = function run(args) {
     return __awaiter(this, void 0, void 0, function () {
-        var parsed, entry;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        var parsed, initLogger, _a, loaded, injected, entry;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
                 case 0:
                     parsed = (0, cli_utils_1.parseArgs)(args);
+                    // Load .env files before anything else so all env vars are available at startup.
+                    // NODE_ENV defaults to "production" when not explicitly set.
+                    if (!process.env.NODE_ENV) {
+                        process.env.NODE_ENV = "production";
+                    }
+                    initLogger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
+                    _a = (0, loadEnvFiles_1.loadEnvFiles)(parsed.dir, "production"), loaded = _a.loaded, injected = _a.injected;
+                    if (loaded.length > 0) {
+                        initLogger.info("Loaded env files: ".concat(loaded.join(", "), " (").concat(injected, " vars injected)"));
+                    }
                     if ((0, cli_utils_1.hasFlag)(parsed, "help")) {
                         (0, cli_utils_1.printHelp)({
                             description: "Compiles and starts the application.",
@@ -80,7 +91,7 @@ module.exports = function run(args) {
                             typeCheck: true,
                         })];
                 case 1:
-                    _a.sent();
+                    _b.sent();
                     (0, cli_utils_1.forkApp)({
                         dir: parsed.dir,
                         args: args,

package/dist/src/TypeScriptCompiler.d.ts

@@ -1,4 +1,5 @@
 import { SourceFile } from "ts-morph";
+import { FlinkCompilerPlugin } from "./utils/loadFlinkConfig";
 declare class TypeScriptCompiler {
     private cwd;
     private project;
@@ -24,6 +25,14 @@ declare class TypeScriptCompiler {
      * Tool ID registry for agent validation (built during segmentation)
      */
     private toolIdRegistry;
+    /**
+     * Compiler plugins loaded from flink.config.js
+     */
+    private compilerPlugins;
+    /**
+     * Extension files collected during segmentation, keyed by generatedFile name
+     */
+    private extensionFiles;
     /**
      * Generates a schema $id from a file path and type name using the same algorithm
      * as the schema generator's defineId callback.
@@ -206,5 +215,16 @@ declare class TypeScriptCompiler {
      * Scans project for jobs so they can be registered during start.
      */
     parseJobs(): Promise<SourceFile>;
+    /**
+     * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
+     * Mirrors the same namespace-import + spread pattern used by parseJobs.
+     */
+    parseExtensionDir(ext: FlinkCompilerPlugin): Promise<SourceFile>;
+    /**
+     * Iterates all compilerPlugins from flink.config.js and generates
+     * a .flink/generatedXxx.ts file for each one.
+     * Call this after parseJobs() and before generateStartScript().
+     */
+    parseAllExtensionDirs(): Promise<void>;
 }
 export default TypeScriptCompiler;