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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @flink-app/flink
 
+## 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

@@ -181,15 +181,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/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

@@ -215,16 +215,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/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;

package/dist/src/TypeScriptCompiler.js

@@ -90,11 +90,12 @@ var FlinkLogFactory_1 = require("./FlinkLogFactory");
 var FsUtils_1 = require("./FsUtils");
 var schema_extraction_1 = require("./schema-extraction");
 var utils_1 = require("./utils");
+var loadFlinkConfig_1 = require("./utils/loadFlinkConfig");
 var perfLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.perf");
 var initLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
 var TypeScriptCompiler = /** @class */ (function () {
     function TypeScriptCompiler(cwd) {
-        var _a, _b;
+        var _a, _b, _c;
         /**
          * Handler schemas collected during parseHandlers, to be generated later
          */
@@ -115,6 +116,14 @@ var TypeScriptCompiler = /** @class */ (function () {
          * Tool ID registry for agent validation (built during segmentation)
          */
         this.toolIdRegistry = new Set();
+        /**
+         * Compiler plugins loaded from flink.config.js
+         */
+        this.compilerPlugins = [];
+        /**
+         * Extension files collected during segmentation, keyed by generatedFile name
+         */
+        this.extensionFiles = new Map();
         var path = require("path");
         // Convert to absolute path to ensure consistent path comparisons
         this.cwd = path.resolve(cwd);
@@ -189,6 +198,15 @@ var TypeScriptCompiler = /** @class */ (function () {
         var loadTime = Date.now() - loadStartTime;
         var fileCount = this.project.getSourceFiles().length;
         perfLog.debug("\u2713 All source files loaded in ".concat(loadTime, "ms (").concat(fileCount, " files)"));
+        // Load compiler plugins from flink.config.js
+        var flinkCfg = (0, loadFlinkConfig_1.loadFlinkConfig)(this.cwd);
+        this.compilerPlugins = (_c = flinkCfg === null || flinkCfg === void 0 ? void 0 : flinkCfg.compilerPlugins) !== null && _c !== void 0 ? _c : [];
+        if (this.compilerPlugins.length > 0) {
+            initLog.info("Compiler plugins loaded (".concat(this.compilerPlugins.length, "):"), this.compilerPlugins.map(function (p) { return "".concat(p.package, " \u2192 ").concat(p.scanDir); }).join(", "));
+        }
+        else {
+            initLog.info("No compiler plugins configured");
+        }
         // Segment files by type for efficient processing
         this.segmentSourceFiles();
         console.log("Loaded", this.project.getSourceFiles().length, "source file(s) from", cwd);
@@ -423,6 +441,7 @@ var TypeScriptCompiler = /** @class */ (function () {
      * multiple full-file iterations during parse methods.
      */
     TypeScriptCompiler.prototype.segmentSourceFiles = function () {
+        var _a;
         var startTime = Date.now();
         var allFiles = this.project.getSourceFiles();
         var handlerTime = 0, repoTime = 0, toolTime = 0, agentTime = 0, jobTime = 0;
@@ -470,7 +489,19 @@ var TypeScriptCompiler = /** @class */ (function () {
             if (filePath.includes("src/jobs/")) {
                 this.jobFiles.push(sf);
                 jobTime += Date.now() - fileStartTime;
-                // No continue needed (last check)
+                continue;
+            }
+            // Extension dirs from compiler plugins
+            for (var _b = 0, _c = this.compilerPlugins; _b < _c.length; _b++) {
+                var ext = _c[_b];
+                if (filePath.includes(ext.scanDir)) {
+                    if (!ext.detectBy || ext.detectBy(sf.getFullText(), filePath)) {
+                        var list = (_a = this.extensionFiles.get(ext.generatedFile)) !== null && _a !== void 0 ? _a : [];
+                        list.push(sf);
+                        this.extensionFiles.set(ext.generatedFile, list);
+                    }
+                    break;
+                }
             }
         }
         var segmentTime = Date.now() - startTime;
@@ -1112,7 +1143,8 @@ var TypeScriptCompiler = /** @class */ (function () {
      */
     TypeScriptCompiler.prototype.generateStartScript = function () {
         return __awaiter(this, arguments, void 0, function (appEntryScript) {
-            var path, entryScriptPath, specFiles, sf;
+            var path, entryScriptPath, specFiles, extensionImports, sf;
+            var _this = this;
             if (appEntryScript === void 0) { appEntryScript = "/src/index.ts"; }
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -1137,7 +1169,10 @@ var TypeScriptCompiler = /** @class */ (function () {
                         this.resolveImportedFiles();
                         _a.label = 3;
                     case 3:
-                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedTools").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedAgents").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\nimport \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
+                        extensionImports = this.compilerPlugins
+                            .map(function (ext) { return "import \"./".concat(ext.generatedFile).concat(_this.isEsm ? ".js" : "", "\";"); })
+                            .join("\n");
+                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedTools").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedAgents").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\n").concat(extensionImports ? extensionImports + "\n" : "", "import \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
                         // Defer save until batch save at end (performance optimization)
                         return [2 /*return*/, sf];
                 }
@@ -1482,6 +1517,66 @@ var TypeScriptCompiler = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
+     * Mirrors the same namespace-import + spread pattern used by parseJobs.
+     */
+    TypeScriptCompiler.prototype.parseExtensionDir = function (ext) {
+        return __awaiter(this, void 0, void 0, function () {
+            var startTime, files, generatedFile, itemsArr, imports, itemElements, elapsed;
+            var _this = this;
+            var _a;
+            return __generator(this, function (_b) {
+                startTime = Date.now();
+                files = (_a = this.extensionFiles.get(ext.generatedFile)) !== null && _a !== void 0 ? _a : [];
+                generatedFile = this.createSourceFile(["".concat(ext.generatedFile, ".ts")], "// Generated ".concat(new Date(), "\nimport { ").concat(ext.registrationVar, " } from \"").concat(ext.package, "\";\nexport const items: any[] = [];\n").concat(ext.registrationVar, ".push(...items);\n"));
+                itemsArr = generatedFile.getVariableDeclarationOrThrow("items").getFirstDescendantByKindOrThrow(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                imports = [];
+                itemElements = [];
+                files.forEach(function (sf, i) {
+                    var namespaceImport = sf.getBaseNameWithoutExtension().replace(/\./g, "_") + "_" + i;
+                    imports.push({
+                        defaultImport: "* as " + namespaceImport,
+                        moduleSpecifier: _this.getModuleSpecifier(generatedFile, sf),
+                    });
+                    itemElements.push("{...".concat(namespaceImport, ", __file: \"").concat(_this.getRelativePath(sf), "\"}"));
+                });
+                itemsArr.addElements(itemElements);
+                generatedFile.addImportDeclarations(imports);
+                elapsed = Date.now() - startTime;
+                initLog.info("\u2713 Extension dir \"".concat(ext.scanDir, "\" parsed in ").concat(elapsed, "ms (").concat(files.length, " files)"));
+                return [2 /*return*/, generatedFile];
+            });
+        });
+    };
+    /**
+     * Iterates all compilerPlugins from flink.config.js and generates
+     * a .flink/generatedXxx.ts file for each one.
+     * Call this after parseJobs() and before generateStartScript().
+     */
+    TypeScriptCompiler.prototype.parseAllExtensionDirs = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _i, _a, ext;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _i = 0, _a = this.compilerPlugins;
+                        _b.label = 1;
+                    case 1:
+                        if (!(_i < _a.length)) return [3 /*break*/, 4];
+                        ext = _a[_i];
+                        return [4 /*yield*/, this.parseExtensionDir(ext)];
+                    case 2:
+                        _b.sent();
+                        _b.label = 3;
+                    case 3:
+                        _i++;
+                        return [3 /*break*/, 1];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
     return TypeScriptCompiler;
 }());
 exports.default = TypeScriptCompiler;

package/dist/src/utils/loadFlinkConfig.d.ts

@@ -1,9 +1,31 @@
 import { LoggingConfig } from "../FlinkLogFactory";
+/**
+ * Compiler plugin descriptor — declared in flink.config.js, consumed by the TypeScript compiler.
+ * Plugin packages export a compilerPlugin() factory that returns this shape.
+ */
+export interface FlinkCompilerPlugin {
+    /** npm package name, e.g. "@flink-app/inbound-email-plugin" */
+    package: string;
+    /** Directory to scan for handler files, e.g. "src/email-handlers" */
+    scanDir: string;
+    /** Base name for the generated .flink/generatedXxx.ts file, e.g. "generatedEmailHandlers" */
+    generatedFile: string;
+    /** Name of the singleton array exported by the plugin package, e.g. "autoRegisteredEmailHandlers" */
+    registrationVar: string;
+    /**
+     * Optional callback to confirm a file should be registered.
+     * Receives the raw file content and the absolute file path.
+     * Return true to include the file, false to skip it.
+     */
+    detectBy?: (fileContent: string, filePath: string) => boolean;
+}
 /**
  * Flink configuration file structure
  */
 export interface FlinkConfig {
     logging?: LoggingConfig;
+    /** Compiler plugins that extend auto-discovery to custom directories */
+    compilerPlugins?: FlinkCompilerPlugin[];
 }
 /**
  * Load Flink configuration from flink.config.js in current working directory
@@ -26,4 +48,4 @@ export interface FlinkConfig {
  * };
  * ```
  */
-export declare function loadFlinkConfig(): FlinkConfig | undefined;
+export declare function loadFlinkConfig(cwd?: string): FlinkConfig | undefined;

package/dist/src/utils/loadFlinkConfig.js

@@ -47,10 +47,10 @@ var fs = __importStar(require("fs"));
  * };
  * ```
  */
-function loadFlinkConfig() {
+function loadFlinkConfig(cwd) {
     try {
-        // Look for flink.config.js in current working directory
-        var configPath = path.join(process.cwd(), "flink.config.js");
+        // Look for flink.config.js in current working directory (or provided cwd)
+        var configPath = path.join(cwd !== null && cwd !== void 0 ? cwd : process.cwd(), "flink.config.js");
         // Check if file exists
         if (!fs.existsSync(configPath)) {
             return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.58",
+  "version": "2.0.0-alpha.59",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/src/TypeScriptCompiler.ts

@@ -6,6 +6,7 @@ import { FlinkLogFactory } from "./FlinkLogFactory";
 import { writeJsonFile } from "./FsUtils";
 import { TypeScriptSourceParser } from "./schema-extraction";
 import { getCollectionNameForRepo, getHttpMethodFromHandlerName, getRepoInstanceName } from "./utils";
+import { FlinkCompilerPlugin, loadFlinkConfig } from "./utils/loadFlinkConfig";
 
 const perfLog = FlinkLogFactory.createLogger("flink.perf");
 const initLog = FlinkLogFactory.createLogger("flink.init");
@@ -50,6 +51,16 @@ class TypeScriptCompiler {
      */
     private toolIdRegistry: Set<string> = new Set();
 
+    /**
+     * Compiler plugins loaded from flink.config.js
+     */
+    private compilerPlugins: FlinkCompilerPlugin[] = [];
+
+    /**
+     * Extension files collected during segmentation, keyed by generatedFile name
+     */
+    private extensionFiles: Map<string, SourceFile[]> = new Map();
+
     /**
      * Generates a schema $id from a file path and type name using the same algorithm
      * as the schema generator's defineId callback.
@@ -216,6 +227,19 @@ class TypeScriptCompiler {
         const fileCount = this.project.getSourceFiles().length;
         perfLog.debug(`✓ All source files loaded in ${loadTime}ms (${fileCount} files)`);
 
+        // Load compiler plugins from flink.config.js
+        const flinkCfg = loadFlinkConfig(this.cwd);
+        this.compilerPlugins = flinkCfg?.compilerPlugins ?? [];
+
+        if (this.compilerPlugins.length > 0) {
+            initLog.info(
+                `Compiler plugins loaded (${this.compilerPlugins.length}):`,
+                this.compilerPlugins.map((p) => `${p.package} → ${p.scanDir}`).join(", ")
+            );
+        } else {
+            initLog.info("No compiler plugins configured");
+        }
+
         // Segment files by type for efficient processing
         this.segmentSourceFiles();
 
@@ -457,7 +481,19 @@ class TypeScriptCompiler {
             if (filePath.includes("src/jobs/")) {
                 this.jobFiles.push(sf);
                 jobTime += Date.now() - fileStartTime;
-                // No continue needed (last check)
+                continue;
+            }
+
+            // Extension dirs from compiler plugins
+            for (const ext of this.compilerPlugins) {
+                if (filePath.includes(ext.scanDir)) {
+                    if (!ext.detectBy || ext.detectBy(sf.getFullText(), filePath)) {
+                        const list = this.extensionFiles.get(ext.generatedFile) ?? [];
+                        list.push(sf);
+                        this.extensionFiles.set(ext.generatedFile, list);
+                    }
+                    break;
+                }
             }
         }
 
@@ -1157,6 +1193,10 @@ autoRegisteredAgents.push(...agents);
             this.resolveImportedFiles();
         }
 
+        const extensionImports = this.compilerPlugins
+            .map((ext) => `import "./${ext.generatedFile}${this.isEsm ? ".js" : ""}";`)
+            .join("\n");
+
         const sf = this.createSourceFile(
             ["start.ts"],
             `// Generated ${new Date()}
@@ -1165,7 +1205,7 @@ import "./generatedRepos${this.isEsm ? ".js" : ""}";
 import "./generatedTools${this.isEsm ? ".js" : ""}";
 import "./generatedAgents${this.isEsm ? ".js" : ""}";
 import "./generatedJobs${this.isEsm ? ".js" : ""}";
-import "..${appEntryScript.replace(/\.ts/g, "")}${this.isEsm ? ".js" : ""}";
+${extensionImports ? extensionImports + "\n" : ""}import "..${appEntryScript.replace(/\.ts/g, "")}${this.isEsm ? ".js" : ""}";
 export default {}; // Export an empty object to make it a module
 `
         );
@@ -1560,6 +1600,57 @@ autoRegisteredJobs.push(...jobs);
 
         return generatedFile;
     }
+
+    /**
+     * Generates a .flink/generatedXxx.ts file for a single compiler plugin extension.
+     * Mirrors the same namespace-import + spread pattern used by parseJobs.
+     */
+    async parseExtensionDir(ext: FlinkCompilerPlugin): Promise<SourceFile> {
+        const startTime = Date.now();
+        const files = this.extensionFiles.get(ext.generatedFile) ?? [];
+
+        const generatedFile = this.createSourceFile(
+            [`${ext.generatedFile}.ts`],
+            `// Generated ${new Date()}
+import { ${ext.registrationVar} } from "${ext.package}";
+export const items: any[] = [];
+${ext.registrationVar}.push(...items);
+`
+        );
+
+        const itemsArr = generatedFile.getVariableDeclarationOrThrow("items").getFirstDescendantByKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+
+        const imports: OptionalKind<ImportDeclarationStructure>[] = [];
+        const itemElements: string[] = [];
+
+        files.forEach((sf, i) => {
+            const namespaceImport = sf.getBaseNameWithoutExtension().replace(/\./g, "_") + "_" + i;
+            imports.push({
+                defaultImport: "* as " + namespaceImport,
+                moduleSpecifier: this.getModuleSpecifier(generatedFile, sf),
+            });
+            itemElements.push(`{...${namespaceImport}, __file: "${this.getRelativePath(sf)}"}`);
+        });
+
+        itemsArr.addElements(itemElements);
+        generatedFile.addImportDeclarations(imports);
+
+        const elapsed = Date.now() - startTime;
+        initLog.info(`✓ Extension dir "${ext.scanDir}" parsed in ${elapsed}ms (${files.length} files)`);
+
+        return generatedFile;
+    }
+
+    /**
+     * Iterates all compilerPlugins from flink.config.js and generates
+     * a .flink/generatedXxx.ts file for each one.
+     * Call this after parseJobs() and before generateStartScript().
+     */
+    public async parseAllExtensionDirs(): Promise<void> {
+        for (const ext of this.compilerPlugins) {
+            await this.parseExtensionDir(ext);
+        }
+    }
 }
 
 export default TypeScriptCompiler;

package/src/utils/loadFlinkConfig.ts

@@ -2,11 +2,34 @@ import * as path from "path";
 import * as fs from "fs";
 import { LoggingConfig } from "../FlinkLogFactory";
 
+/**
+ * Compiler plugin descriptor — declared in flink.config.js, consumed by the TypeScript compiler.
+ * Plugin packages export a compilerPlugin() factory that returns this shape.
+ */
+export interface FlinkCompilerPlugin {
+    /** npm package name, e.g. "@flink-app/inbound-email-plugin" */
+    package: string;
+    /** Directory to scan for handler files, e.g. "src/email-handlers" */
+    scanDir: string;
+    /** Base name for the generated .flink/generatedXxx.ts file, e.g. "generatedEmailHandlers" */
+    generatedFile: string;
+    /** Name of the singleton array exported by the plugin package, e.g. "autoRegisteredEmailHandlers" */
+    registrationVar: string;
+    /**
+     * Optional callback to confirm a file should be registered.
+     * Receives the raw file content and the absolute file path.
+     * Return true to include the file, false to skip it.
+     */
+    detectBy?: (fileContent: string, filePath: string) => boolean;
+}
+
 /**
  * Flink configuration file structure
  */
 export interface FlinkConfig {
     logging?: LoggingConfig;
+    /** Compiler plugins that extend auto-discovery to custom directories */
+    compilerPlugins?: FlinkCompilerPlugin[];
 }
 
 /**
@@ -30,10 +53,10 @@ export interface FlinkConfig {
  * };
  * ```
  */
-export function loadFlinkConfig(): FlinkConfig | undefined {
+export function loadFlinkConfig(cwd?: string): FlinkConfig | undefined {
     try {
-        // Look for flink.config.js in current working directory
-        const configPath = path.join(process.cwd(), "flink.config.js");
+        // Look for flink.config.js in current working directory (or provided cwd)
+        const configPath = path.join(cwd ?? process.cwd(), "flink.config.js");
 
         // Check if file exists
         if (!fs.existsSync(configPath)) {