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

package/dist/src/index.d.ts

@@ -1,12 +1,26 @@
 export * from "./FlinkLog";
+export * from "./FlinkLogFactory";
 export * from "./FlinkApp";
+export * from "./utils/loadFlinkConfig";
 export * from "./FlinkHttpHandler";
 export * from "./FlinkContext";
 export * from "./FlinkRepo";
 export * from "./FlinkResponse";
+export * from "./FlinkRequestContext";
 export * from "./FlinkErrors";
 export * from "./FlinkPlugin";
 export * from "./FlinkJob";
+export * from "./FlinkService";
+export { LeaderElection } from "./LeaderElection";
+export type { LeaderElectionOptions } from "./LeaderElection";
 export * from "./auth/FlinkAuthUser";
 export * from "./auth/FlinkAuthPlugin";
+export * from "./ai/FlinkTool";
+export * from "./ai/FlinkAgent";
+export * from "./ai/ConversationAgent";
+export * from "./ai/InMemoryConversationAgent";
+export * from "./ai/ToolExecutor";
+export * from "./ai/LLMAdapter";
+export { agentInstructions } from "./ai/agentInstructions";
+export { loadPluginSchemas } from "./loadPluginSchemas";
 export type { Request as ExpressRequest, Response as ExpressResponse, NextFunction as ExpressNextFunction, RequestHandler as ExpressRequestHandler, ErrorRequestHandler as ExpressErrorRequestHandler, Express, static as expressStatic, } from "express";

package/dist/src/index.js

@@ -14,14 +14,31 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPluginSchemas = exports.agentInstructions = exports.LeaderElection = void 0;
 __exportStar(require("./FlinkLog"), exports);
+__exportStar(require("./FlinkLogFactory"), exports);
 __exportStar(require("./FlinkApp"), exports);
+__exportStar(require("./utils/loadFlinkConfig"), exports);
 __exportStar(require("./FlinkHttpHandler"), exports);
 __exportStar(require("./FlinkContext"), exports);
 __exportStar(require("./FlinkRepo"), exports);
 __exportStar(require("./FlinkResponse"), exports);
+__exportStar(require("./FlinkRequestContext"), exports);
 __exportStar(require("./FlinkErrors"), exports);
 __exportStar(require("./FlinkPlugin"), exports);
 __exportStar(require("./FlinkJob"), exports);
+__exportStar(require("./FlinkService"), exports);
+var LeaderElection_1 = require("./LeaderElection");
+Object.defineProperty(exports, "LeaderElection", { enumerable: true, get: function () { return LeaderElection_1.LeaderElection; } });
 __exportStar(require("./auth/FlinkAuthUser"), exports);
 __exportStar(require("./auth/FlinkAuthPlugin"), exports);
+__exportStar(require("./ai/FlinkTool"), exports);
+__exportStar(require("./ai/FlinkAgent"), exports);
+__exportStar(require("./ai/ConversationAgent"), exports);
+__exportStar(require("./ai/InMemoryConversationAgent"), exports);
+__exportStar(require("./ai/ToolExecutor"), exports);
+__exportStar(require("./ai/LLMAdapter"), exports);
+var agentInstructions_1 = require("./ai/agentInstructions");
+Object.defineProperty(exports, "agentInstructions", { enumerable: true, get: function () { return agentInstructions_1.agentInstructions; } });
+var loadPluginSchemas_1 = require("./loadPluginSchemas");
+Object.defineProperty(exports, "loadPluginSchemas", { enumerable: true, get: function () { return loadPluginSchemas_1.loadPluginSchemas; } });

package/dist/src/loadPluginSchemas.d.ts

@@ -0,0 +1,45 @@
+interface SchemaManifest {
+    version?: string;
+    schemas?: Record<string, any>;
+    definitions?: Record<string, any>;
+    handlers: Record<string, {
+        reqSchemaName?: string;
+        resSchemaName?: string;
+        queryMetadata?: any[];
+        paramsMetadata?: any[];
+        assumedMethod?: string;
+    }>;
+    tools: Record<string, any>;
+}
+/**
+ * Load a plugin's schema manifest and provide helpers for getting
+ * namespaced schemas suitable for use with `app.registerSchemas()` and `addHandler()`.
+ *
+ * @param packageName The npm package name (e.g., "@flink-app/generic-auth-plugin").
+ *                    The package's `dist/.flink/schema-manifest.json` will be loaded.
+ * @returns Object with helper methods for retrieving prefixed schemas.
+ */
+export declare function loadPluginSchemas(packageName: string): {
+    /**
+     * Get prefixed req/res schemas for a specific handler file path.
+     *
+     * @param pluginId Plugin instance ID used as namespace prefix
+     * @param filePath Handler file path as it appears in the manifest (e.g., "src/handlers/UserLogin.ts")
+     */
+    getHandlerSchemas(pluginId: string, filePath: string): {
+        reqSchema?: object;
+        resSchema?: object;
+    };
+    /**
+     * Get all schemas from the plugin's manifest, prefixed with the plugin namespace.
+     * Pass the result to `app.registerSchemas()` for $ref resolution.
+     *
+     * @param pluginId Plugin instance ID used as namespace prefix
+     */
+    getAllSchemas(pluginId: string): Record<string, any>;
+    /**
+     * Get the raw manifest (for inspection/debugging).
+     */
+    getManifest(): SchemaManifest;
+};
+export {};

package/dist/src/loadPluginSchemas.js

@@ -0,0 +1,143 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPluginSchemas = loadPluginSchemas;
+var fs = __importStar(require("fs"));
+var path = __importStar(require("path"));
+/**
+ * Prefix a schema $id or $ref value with the plugin namespace.
+ */
+function prefixId(pluginId, id) {
+    return "".concat(pluginId, "::").concat(id);
+}
+/**
+ * Deep-clone a schema and prefix all $id and $ref values with the plugin namespace.
+ * Only prefixes $ref values that refer to schemas within this plugin's universe.
+ */
+function prefixSchema(pluginId, schema, knownIds) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    if (Array.isArray(schema)) {
+        return schema.map(function (item) { return prefixSchema(pluginId, item, knownIds); });
+    }
+    var result = {};
+    for (var _i = 0, _a = Object.entries(schema); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], value = _b[1];
+        if (key === "$id" && typeof value === "string") {
+            result[key] = prefixId(pluginId, value);
+        }
+        else if (key === "$ref" && typeof value === "string") {
+            // Only prefix refs that point to known plugin schemas
+            if (knownIds.has(value)) {
+                result[key] = prefixId(pluginId, value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        else if (typeof value === "object") {
+            result[key] = prefixSchema(pluginId, value, knownIds);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Load a plugin's schema manifest and provide helpers for getting
+ * namespaced schemas suitable for use with `app.registerSchemas()` and `addHandler()`.
+ *
+ * @param packageName The npm package name (e.g., "@flink-app/generic-auth-plugin").
+ *                    The package's `dist/.flink/schema-manifest.json` will be loaded.
+ * @returns Object with helper methods for retrieving prefixed schemas.
+ */
+function loadPluginSchemas(packageName) {
+    var manifest;
+    // Resolve the package directory
+    var packageDir = path.dirname(require.resolve(path.join(packageName, "package.json")));
+    var manifestPath = path.join(packageDir, "dist/.flink/schema-manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+        // No manifest — return empty helpers
+        manifest = { handlers: {}, tools: {} };
+    }
+    else {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    // Collect all known schema $ids for ref resolution
+    var schemas = manifest.schemas || manifest.definitions || {};
+    var knownIds = new Set();
+    for (var _i = 0, _a = Object.values(schemas); _i < _a.length; _i++) {
+        var schema = _a[_i];
+        if (schema && typeof schema === "object" && schema.$id) {
+            knownIds.add(schema.$id);
+        }
+    }
+    return {
+        /**
+         * Get prefixed req/res schemas for a specific handler file path.
+         *
+         * @param pluginId Plugin instance ID used as namespace prefix
+         * @param filePath Handler file path as it appears in the manifest (e.g., "src/handlers/UserLogin.ts")
+         */
+        getHandlerSchemas: function (pluginId, filePath) {
+            var metadata = manifest.handlers[filePath];
+            if (!metadata)
+                return {};
+            var result = {};
+            if (metadata.reqSchemaName && schemas[metadata.reqSchemaName]) {
+                result.reqSchema = prefixSchema(pluginId, schemas[metadata.reqSchemaName], knownIds);
+            }
+            if (metadata.resSchemaName && schemas[metadata.resSchemaName]) {
+                result.resSchema = prefixSchema(pluginId, schemas[metadata.resSchemaName], knownIds);
+            }
+            return result;
+        },
+        /**
+         * Get all schemas from the plugin's manifest, prefixed with the plugin namespace.
+         * Pass the result to `app.registerSchemas()` for $ref resolution.
+         *
+         * @param pluginId Plugin instance ID used as namespace prefix
+         */
+        getAllSchemas: function (pluginId) {
+            var prefixed = {};
+            for (var _i = 0, _a = Object.entries(schemas); _i < _a.length; _i++) {
+                var _b = _a[_i], name = _b[0], schema = _b[1];
+                if (schema && typeof schema === "object") {
+                    var prefixedSchema = prefixSchema(pluginId, schema, knownIds);
+                    var prefixedName = prefixId(pluginId, name);
+                    prefixed[prefixedName] = prefixedSchema;
+                }
+            }
+            return prefixed;
+        },
+        /**
+         * Get the raw manifest (for inspection/debugging).
+         */
+        getManifest: function () {
+            return manifest;
+        },
+    };
+}

package/dist/src/schema-extraction/ComplexTypeDetection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Detection utilities for complex TypeScript features that are difficult
+ * to parse with text-based extraction.
+ *
+ * These functions identify TypeScript features that should use ts-morph
+ * fallback for safety and correctness.
+ */
+/**
+ * Detect template literal types.
+ * Example: type Route = `/${string}`;
+ */
+export declare function hasTemplateLiteralType(text: string): boolean;
+/**
+ * Detect conditional types.
+ * Example: type Extract<T> = T extends string ? T : never;
+ */
+export declare function hasConditionalType(text: string): boolean;
+/**
+ * Detect mapped types.
+ * Example: type Readonly<T> = { readonly [P in keyof T]: T[P] };
+ */
+export declare function hasMappedType(text: string): boolean;
+/**
+ * Detect string literals with brackets that might confuse parser.
+ * Example: interface Config { pattern: "{user:id}"; }
+ *
+ * Note: With enhanced tokenizer (Phase 1), this is now handled correctly.
+ * This detection is kept for monitoring and potential special handling.
+ */
+export declare function hasComplexStringLiterals(text: string): boolean;
+/**
+ * Check if text contains any complex TypeScript features that require
+ * ts-morph fallback for safe extraction.
+ */
+export declare function hasComplexTypeFeatures(text: string): boolean;
+/**
+ * Get a human-readable description of which complex features were detected.
+ * Useful for logging and debugging.
+ */
+export declare function describeComplexFeatures(text: string): string[];

package/dist/src/schema-extraction/ComplexTypeDetection.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Detection utilities for complex TypeScript features that are difficult
+ * to parse with text-based extraction.
+ *
+ * These functions identify TypeScript features that should use ts-morph
+ * fallback for safety and correctness.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasTemplateLiteralType = hasTemplateLiteralType;
+exports.hasConditionalType = hasConditionalType;
+exports.hasMappedType = hasMappedType;
+exports.hasComplexStringLiterals = hasComplexStringLiterals;
+exports.hasComplexTypeFeatures = hasComplexTypeFeatures;
+exports.describeComplexFeatures = describeComplexFeatures;
+/**
+ * Detect template literal types.
+ * Example: type Route = `/${string}`;
+ */
+function hasTemplateLiteralType(text) {
+    // Match: type Name = `...`
+    return /type\s+\w+\s*=\s*`/.test(text);
+}
+/**
+ * Detect conditional types.
+ * Example: type Extract<T> = T extends string ? T : never;
+ */
+function hasConditionalType(text) {
+    // Match: T extends U ? A : B pattern
+    // Look for extends keyword followed by ? and : (conditional type pattern)
+    return /\bextends\b.*?\?.*?:/.test(text);
+}
+/**
+ * Detect mapped types.
+ * Example: type Readonly<T> = { readonly [P in keyof T]: T[P] };
+ */
+function hasMappedType(text) {
+    // Match: [K in keyof T] pattern
+    return /\[\s*\w+\s+in\s+keyof\s+/.test(text);
+}
+/**
+ * Detect string literals with brackets that might confuse parser.
+ * Example: interface Config { pattern: "{user:id}"; }
+ *
+ * Note: With enhanced tokenizer (Phase 1), this is now handled correctly.
+ * This detection is kept for monitoring and potential special handling.
+ */
+function hasComplexStringLiterals(text) {
+    // Match: quotes containing bracket characters
+    return /["'`].*?[{}<>].*?["'`]/.test(text);
+}
+/**
+ * Check if text contains any complex TypeScript features that require
+ * ts-morph fallback for safe extraction.
+ */
+function hasComplexTypeFeatures(text) {
+    return hasTemplateLiteralType(text) || hasConditionalType(text) || hasMappedType(text);
+}
+/**
+ * Get a human-readable description of which complex features were detected.
+ * Useful for logging and debugging.
+ */
+function describeComplexFeatures(text) {
+    var features = [];
+    if (hasTemplateLiteralType(text)) {
+        features.push("template literal types");
+    }
+    if (hasConditionalType(text)) {
+        features.push("conditional types");
+    }
+    if (hasMappedType(text)) {
+        features.push("mapped types");
+    }
+    return features;
+}

package/dist/src/schema-extraction/TypeScriptSourceParser.d.ts

@@ -0,0 +1,321 @@
+import { FlinkToolTypeArgs, PropertyMetadata, SchemaTypeDetection, TypeDefinition } from "./types";
+/**
+ * Pure utility class for parsing TypeScript source code as text.
+ * All methods are static and side-effect free for easy testing.
+ *
+ * This class provides fast, regex-based parsing without using ts-morph
+ * or the TypeScript compiler, making it suitable for performance-critical
+ * schema extraction.
+ */
+export declare class TypeScriptSourceParser {
+    /**
+     * Remove comments from source code to avoid false positives in schema detection.
+     * Handles both single-line (//) and multi-line (/* *\/) comments.
+     */
+    private static removeComments;
+    /**
+     * Detect if a tool source file uses Zod or JSON schemas.
+     * If true, TypeScript schema extraction should be skipped.
+     *
+     * Note: Strips comments first to avoid false positives from commented-out schemas.
+     */
+    static detectSchemaType(sourceText: string): SchemaTypeDetection;
+    /**
+     * Extract type arguments from Handler<Ctx, Req, Res, Params, Query> declaration.
+     *
+     * @example
+     * ```typescript
+     * parseHandlerTypeArgs('const handler: Handler<AppCtx, LoginReq, LoginRes>')
+     * // Returns: { contextType: 'AppCtx', reqType: 'LoginReq', resType: 'LoginRes' }
+     * ```
+     */
+    static parseHandlerTypeArgs(sourceText: string): {
+        contextType: string;
+        reqType?: string;
+        resType?: string;
+        paramsType?: string;
+        queryType?: string;
+    } | null;
+    /**
+     * Extract type arguments from FlinkTool<Ctx, Input, Output> declaration.
+     *
+     * @example
+     * ```typescript
+     * parseFlinkToolTypeArgs('const handler: FlinkTool<Ctx, CreateDocInput, ToolResult<DocOutput>>')
+     * // Returns: { contextType: 'Ctx', inputType: 'CreateDocInput', outputType: 'ToolResult<DocOutput>' }
+     * ```
+     */
+    static parseFlinkToolTypeArgs(sourceText: string): FlinkToolTypeArgs | null;
+    /**
+     * Split a string by commas, but only at the top level (not inside angle brackets).
+     * Helper for parsing generic type arguments like "Ctx, Input, ToolResult<Output>"
+     */
+    private static splitTopLevelCommas;
+    /**
+     * Check if a type should generate a schema.
+     * Returns false for primitives and special types, true for named types and inline objects.
+     */
+    static shouldGenerateSchema(typeName: string): boolean;
+    /**
+     * Check if a type is a built-in TypeScript type.
+     */
+    static isBuiltInType(typeName: string): boolean;
+    /**
+     * Extract T from ToolResult<T> type name.
+     *
+     * @example
+     * ```typescript
+     * unwrapToolResultType('ToolResult<DocOutput>')  // Returns: 'DocOutput'
+     * unwrapToolResultType('DocOutput')              // Returns: 'DocOutput'
+     * ```
+     */
+    static unwrapToolResultType(typeName: string): string;
+    /**
+     * Convert inline object type to interface definition.
+     *
+     * @example
+     * ```typescript
+     * convertInlineObjectToInterface('{}', 'MyInput')
+     * // Returns: 'export interface MyInput {}'
+     *
+     * convertInlineObjectToInterface('{ foo: string }', 'MyInput')
+     * // Returns: 'export interface MyInput {\n  foo: string;\n}'
+     * ```
+     */
+    static convertInlineObjectToInterface(inlineType: string, interfaceName: string): string;
+    /**
+     * Find an interface or type definition in source text.
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   interface User {
+     *     name: string;
+     *   }
+     * `;
+     * findTypeDefinition(source, 'User')
+     * // Returns: { name: 'User', definition: 'interface User { ... }', kind: 'interface' }
+     * ```
+     */
+    static findTypeDefinition(sourceText: string, typeName: string): TypeDefinition | null;
+    /**
+     * Peek at the next non-whitespace, non-comment character starting at `fromPos`.
+     * Returns the character, or undefined if only whitespace/comments remain.
+     */
+    private static peekNextSignificantChar;
+    /**
+     * Determine whether a type expression continues after `fromPos`, i.e. whether
+     * the character that follows is a type-combinator/continuation operator
+     * (`|`, `&`, `[`, `.`, etc.) rather than the start of an unrelated statement.
+     *
+     * Used to decide if a top-level closing bracket terminates a semicolon-free
+     * type alias or whether the alias keeps going (e.g. a union of object types).
+     */
+    private static typeContinuesAfter;
+    /**
+     * Rename an interface or type definition.
+     *
+     * @example
+     * ```typescript
+     * renameTypeDefinition('interface User { name: string }', 'User', 'Person')
+     * // Returns: 'export interface Person { name: string }'
+     * ```
+     */
+    static renameTypeDefinition(definition: string, oldName: string, newName: string, exportIt?: boolean): string;
+    /**
+     * Extract all type names referenced in a type definition.
+     * Excludes JSDoc comments and string literals.
+     *
+     * @example
+     * ```typescript
+     * extractReferencedTypes('interface Doc { author: User; tags: Tag[] }')
+     * // Returns: ['User', 'Tag']
+     * extractReferencedTypes('PaginatedResponse<Car>')
+     * // Returns: ['PaginatedResponse', 'Car']
+     * ```
+     */
+    static extractReferencedTypes(typeDefinition: string): string[];
+    /**
+     * Check if a type name is an inline object type.
+     */
+    static isInlineObjectType(typeName: string): boolean;
+    /**
+     * Parse JSDoc comment text to extract description.
+     * Strips JSDoc comment markers and leading asterisks.
+     *
+     * @example
+     * ```typescript
+     * parseJsDocDescription('/** Max cars to retrieve *\/')
+     * // Returns: "Max cars to retrieve"
+     *
+     * parseJsDocDescription('/**\n * Max cars to retrieve\n * from the database\n *\/')
+     * // Returns: "Max cars to retrieve from the database"
+     *
+     * parseJsDocDescription('')
+     * // Returns: ""
+     * ```
+     */
+    static parseJsDocDescription(jsDocText: string): string;
+    /**
+     * Extract property metadata from an object type body.
+     * Parses properties with optional JSDoc comments.
+     * Only extracts top-level properties (not nested object properties).
+     *
+     * @param objectBody The content between { and } in an object type
+     * @returns Array of property metadata (name + description)
+     *
+     * @example
+     * ```typescript
+     * const body = `
+     *   /** Max cars to retrieve *\/
+     *   limit: string;
+     *   page?: number;
+     * `;
+     * extractPropertiesFromObjectType(body)
+     * // Returns: [
+     * //   { name: "limit", description: "Max cars to retrieve" },
+     * //   { name: "page", description: "" }
+     * // ]
+     * ```
+     */
+    static extractPropertiesFromObjectType(objectBody: string): PropertyMetadata[];
+    /**
+     * Copy a type definition and recursively find all its dependencies.
+     * Returns structured data without side effects.
+     *
+     * @param sourceText Full source file text to search for types
+     * @param typeName Name of the type to copy
+     * @param newName New name for the type (use same name for dependencies)
+     * @param copiedTypes Set of already-copied type names to avoid duplication
+     * @returns Object containing the main definition, dependency definitions, and import statements
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   import { Address } from './Address';
+     *   interface User {
+     *     profile: Profile;
+     *     address: Address;
+     *   }
+     *   interface Profile {
+     *     name: string;
+     *   }
+     * `;
+     * const result = copyTypeWithDependencies(source, 'User', 'UserSchema', new Set());
+     * // Returns: {
+     * //   mainDefinition: 'export interface UserSchema { profile: Profile; address: Address; }',
+     * //   dependencies: ['export interface Profile { name: string; }'],
+     * //   imports: ['import { Address } from "./Address"'],
+     * //   copiedTypes: Set(['User', 'Profile'])
+     * // }
+     * ```
+     */
+    static copyTypeWithDependencies(sourceText: string, typeName: string, newName: string, copiedTypes: Set<string>): {
+        mainDefinition: string | null;
+        dependencies: string[];
+        imports: string[];
+        copiedTypes: Set<string>;
+    };
+    /**
+     * Extract import statement for a specific type from source text.
+     *
+     * @param sourceText Full source file text
+     * @param typeName Name of the type to find import for
+     * @returns Import statement or null if not found
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   import { User } from '../schemas/User';
+     *   import type { Profile } from '../schemas/Profile';
+     *   import Foo from '../schemas/Foo';
+     * `;
+     * extractImportForType(source, 'User')
+     * // Returns: "import { User } from '../schemas/User'"
+     *
+     * extractImportForType(source, 'Profile')
+     * // Returns: "import type { Profile } from '../schemas/Profile'"
+     *
+     * extractImportForType(source, 'Foo')
+     * // Returns: "import Foo from '../schemas/Foo'"
+     * ```
+     */
+    static extractImportForType(sourceText: string, typeName: string): string | null;
+    /**
+     * Extract all imports from a source file.
+     * Used to get transitive dependencies when importing a type.
+     *
+     * @param sourceText Source code to extract imports from
+     * @returns Array of import statements
+     */
+    static extractAllImports(sourceText: string): string[];
+    /**
+     * Adjust import path to be relative to .flink/schemas/ directory.
+     *
+     * @param importStatement Original import statement
+     * @returns Adjusted import statement with corrected path
+     *
+     * @example
+     * ```typescript
+     * adjustImportPathForSchemas('import { User } from "../schemas/User"')
+     * // Returns: 'import { User } from "../../src/schemas/User"'
+     *
+     * adjustImportPathForSchemas('import Profile from "../../schemas/Profile"')
+     * // Returns: 'import Profile from "../../src/schemas/Profile"'
+     *
+     * adjustImportPathForSchemas('import { Req } from "../clients/SupermetricsClient"')
+     * // Returns: 'import { Req } from "../../src/clients/SupermetricsClient"'
+     *
+     * adjustImportPathForSchemas('import { Foo } from "@company/shared"')
+     * // Returns: 'import { Foo } from "@company/shared"' (unchanged - not relative)
+     * ```
+     */
+    static adjustImportPathForSchemas(importStatement: string): string;
+    /**
+     * Extract property metadata from a named type definition.
+     * Searches for the type definition and parses its properties.
+     *
+     * @param sourceText Full source file text
+     * @param typeName Name of the type to extract properties from
+     * @returns Array of property metadata, or null if type not found
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   interface Query {
+     *     /** Max items *\/
+     *     limit: string;
+     *     page?: number;
+     *   }
+     * `;
+     * extractPropertyMetadata(source, 'Query')
+     * // Returns: [
+     * //   { name: "limit", description: "Max items" },
+     * //   { name: "page", description: "" }
+     * // ]
+     * ```
+     */
+    static extractPropertyMetadata(sourceText: string, typeName: string): PropertyMetadata[] | null;
+    /**
+     * Consolidates duplicate imports from the same module.
+     * Merges named imports and preserves default imports.
+     *
+     * @param imports Array of import statements
+     * @returns Consolidated import statements with duplicates merged
+     *
+     * @example
+     * ```typescript
+     * const imports = [
+     *   'import { Ad } from "../../src/schemas/Ad"',
+     *   'import { AdStatus } from "../../src/schemas/Ad"',
+     *   'import { User } from "../../src/schemas/User"'
+     * ];
+     * consolidateImports(imports)
+     * // Returns: [
+     * //   'import { Ad, AdStatus } from "../../src/schemas/Ad"',
+     * //   'import { User } from "../../src/schemas/User"'
+     * // ]
+     * ```
+     */
+    static consolidateImports(imports: string[]): string[];
+}