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

package/src/schema-extraction/TypeScriptTokenizer.ts

@@ -0,0 +1,205 @@
+/**
+ * Simple TypeScript tokenizer for robust bracket matching.
+ *
+ * Properly handles:
+ * - String literals with all quote types
+ * - Escape sequences in strings
+ * - Line comments
+ * - Block comments
+ * - Nested brackets
+ *
+ * This prevents bracket counting errors when special characters
+ * appear inside strings or comments.
+ */
+
+export interface Token {
+    type: 'string' | 'comment' | 'bracket' | 'char';
+    value: string;
+    startPos: number;
+    endPos: number;
+}
+
+export class TypeScriptTokenizer {
+    private text: string;
+    private pos: number = 0;
+
+    constructor(text: string) {
+        this.text = text;
+    }
+
+    /**
+     * Find matching closing bracket from current position.
+     * Properly handles strings and comments.
+     *
+     * @param openChar Opening bracket character
+     * @returns Position of matching closing bracket, or -1 if not found
+     */
+    findMatchingBracket(openChar: '{' | '<' | '(' | '['): number {
+        const closeChar = this.getClosingBracket(openChar);
+        let depth = 1;
+        let i = this.pos + 1;
+
+        while (i < this.text.length && depth > 0) {
+            const token = this.getNextToken(i);
+
+            // Only count brackets outside strings and comments
+            if (token.type === 'bracket') {
+                if (token.value === openChar) {
+                    depth++;
+                } else if (token.value === closeChar) {
+                    depth--;
+                }
+            }
+
+            i = token.endPos;
+        }
+
+        return depth === 0 ? i - 1 : -1;
+    }
+
+    /**
+     * Find matching closing bracket from a specific start position.
+     */
+    findMatchingBracketAt(startPos: number, openChar: '{' | '<' | '(' | '['): number {
+        this.pos = startPos;
+        return this.findMatchingBracket(openChar);
+    }
+
+    /**
+     * Get next meaningful token, properly handling strings and comments.
+     * Public for use in other parsing utilities.
+     */
+    getNextToken(startPos: number): Token {
+        const char = this.text[startPos];
+
+        // String literal (single, double, or backtick quotes)
+        if (char === '"' || char === "'" || char === '`') {
+            return this.parseStringLiteral(startPos, char);
+        }
+
+        // Line comment
+        if (char === '/' && this.text[startPos + 1] === '/') {
+            return this.parseLineComment(startPos);
+        }
+
+        // Block comment
+        if (char === '/' && this.text[startPos + 1] === '*') {
+            return this.parseBlockComment(startPos);
+        }
+
+        // Bracket characters
+        if ('{}<>()[]'.includes(char)) {
+            return {
+                type: 'bracket',
+                value: char,
+                startPos,
+                endPos: startPos + 1,
+            };
+        }
+
+        // Other character (not important for bracket matching)
+        return {
+            type: 'char',
+            value: char,
+            startPos,
+            endPos: startPos + 1,
+        };
+    }
+
+    /**
+     * Parse string literal, handling escape sequences.
+     */
+    private parseStringLiteral(startPos: number, quoteChar: string): Token {
+        let i = startPos + 1;
+        let escaped = false;
+
+        while (i < this.text.length) {
+            if (escaped) {
+                // Skip escaped character
+                escaped = false;
+                i++;
+                continue;
+            }
+
+            if (this.text[i] === '\\') {
+                // Found escape sequence
+                escaped = true;
+                i++;
+                continue;
+            }
+
+            if (this.text[i] === quoteChar) {
+                // Found closing quote
+                return {
+                    type: 'string',
+                    value: this.text.slice(startPos, i + 1),
+                    startPos,
+                    endPos: i + 1,
+                };
+            }
+
+            i++;
+        }
+
+        // Unclosed string - return what we have
+        // (Let TypeScript compiler handle the error)
+        return {
+            type: 'string',
+            value: this.text.slice(startPos),
+            startPos,
+            endPos: this.text.length,
+        };
+    }
+
+    /**
+     * Parse line comment (// ... \n).
+     */
+    private parseLineComment(startPos: number): Token {
+        const newlinePos = this.text.indexOf('\n', startPos);
+        const endPos = newlinePos === -1 ? this.text.length : newlinePos + 1;
+
+        return {
+            type: 'comment',
+            value: this.text.slice(startPos, endPos),
+            startPos,
+            endPos,
+        };
+    }
+
+    /**
+     * Parse block comment (/* ... *\/).
+     */
+    private parseBlockComment(startPos: number): Token {
+        const endPos = this.text.indexOf('*/', startPos + 2);
+
+        if (endPos === -1) {
+            // Unclosed block comment - return what we have
+            return {
+                type: 'comment',
+                value: this.text.slice(startPos),
+                startPos,
+                endPos: this.text.length,
+            };
+        }
+
+        return {
+            type: 'comment',
+            value: this.text.slice(startPos, endPos + 2),
+            startPos,
+            endPos: endPos + 2,
+        };
+    }
+
+    /**
+     * Get closing bracket character for an opening bracket.
+     */
+    private getClosingBracket(open: string): string {
+        const pairs: Record<string, string> = {
+            '{': '}',
+            '<': '>',
+            '(': ')',
+            '[': ']',
+        };
+        return pairs[open];
+    }
+}

package/src/schema-extraction/index.ts

@@ -0,0 +1,2 @@
+export { TypeScriptSourceParser } from "./TypeScriptSourceParser";
+export * from "./types";

package/src/schema-extraction/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Schema type detection result
+ */
+export interface SchemaTypeDetection {
+    hasZodSchemas: boolean;
+    hasJsonSchemas: boolean;
+    shouldSkipTypeScriptExtraction: boolean;
+}
+
+/**
+ * FlinkTool type arguments extracted from source
+ */
+export interface FlinkToolTypeArgs {
+    contextType: string;
+    inputType: string;
+    outputType: string;
+}
+
+/**
+ * Result of type definition search
+ */
+export interface TypeDefinition {
+    name: string;
+    definition: string;
+    kind: 'interface' | 'type';
+}
+
+/**
+ * Metadata for a single property (parameter or query field)
+ */
+export interface PropertyMetadata {
+    name: string;
+    description: string;
+}

package/src/utils/loadFlinkConfig.ts

@@ -0,0 +1,89 @@
+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[];
+    /** Disable auto-discovery of services from src/services/. Default: false */
+    disableServices?: boolean;
+}
+
+/**
+ * Load Flink configuration from flink.config.js in current working directory
+ *
+ * @returns FlinkConfig object or undefined if not found/invalid
+ *
+ * @example
+ * ```javascript
+ * // flink.config.js
+ * module.exports = {
+ *   logging: {
+ *     global: "info",
+ *     showTimestamps: true,
+ *     components: {
+ *       "flink.ai.openai": "trace",
+ *       "flink.ai.*": "debug",
+ *       "flink.database.**": "warn"
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export function loadFlinkConfig(cwd?: string): FlinkConfig | undefined {
+    try {
+        // 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)) {
+            return undefined;
+        }
+
+        // Load config using require (CommonJS)
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const config = require(configPath);
+
+        // Validate structure
+        if (!config || typeof config !== "object") {
+            console.warn(`[flink] Warning: flink.config.js exists but does not export an object`);
+            return undefined;
+        }
+
+        // Validate logging config if present
+        if (config.logging && typeof config.logging !== "object") {
+            console.warn(`[flink] Warning: flink.config.js has invalid logging config (must be object)`);
+            return undefined;
+        }
+
+        return config as FlinkConfig;
+    } catch (error) {
+        console.warn(`[flink] Warning: Failed to load flink.config.js:`, error);
+        return undefined;
+    }
+}

package/src/utils.ts

@@ -59,6 +59,45 @@ export function getRepoInstanceName(fn: string) {
     return name.charAt(0).toLowerCase() + name.substr(1);
 }
 
+/**
+ * Convert PascalCase or camelCase to kebab-case
+ *
+ * Examples:
+ * - FooBarBaz → foo-bar-baz
+ * - CarAgent → car-agent
+ * - APIAgent → api-agent
+ * - HTMLParser → html-parser
+ * - IOManager → io-manager
+ *
+ * Handles:
+ * - Single uppercase followed by lowercase: CarAgent → car-agent
+ * - Multiple consecutive uppercase: APIAgent → api-agent
+ * - All caps: HTML → html
+ */
+export function toKebabCase(str: string): string {
+    return str
+        // Insert hyphen before uppercase letters that follow lowercase letters
+        // CarAgent → Car-Agent
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        // Insert hyphen before uppercase letter that follows uppercase and precedes lowercase
+        // APIAgent → API-Agent
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        // Convert to lowercase
+        .toLowerCase();
+}
+
+/**
+ * Convert kebab-case to snake_case
+ *
+ * Examples:
+ * - car-agent → car_agent
+ * - api-agent → api_agent
+ * - html-parser → html_parser
+ */
+export function toSnakeCase(str: string): string {
+    return str.replace(/-/g, "_");
+}
+
 /**
  * Get http method from props or convention based on file name
  * if it starts with i.e "GetFoo"
@@ -177,3 +216,16 @@ export function formatValidationErrors(errors: any[] | null | undefined, data: a
 
     return formatted.join("\n");
 }
+
+/**
+ * Generate a short random ID for nested conversations
+ * Format: 8 character alphanumeric string (e.g., "a3b7c9d2")
+ */
+export function generateShortId(): string {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < 8; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}

package/tsconfig.json

@@ -16,7 +16,12 @@
     "checkJs": false,
     "typeRoots": ["./typings", "./node_modules/@types"],
     "declaration": true,
-    "outDir": "dist"
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@flink-app/flink": ["./src/index.ts"],
+      "@flink-app/flink/*": ["./src/*"]
+    }
   },
   "include": ["./src/**/*.ts", "./bin/*", "./cli/*", "./spec/**/*.ts"],
   "exclude": ["./node_modules/*", "./spec/mock-project/*"]