glirastes 0.3.0 → 0.3.1

package/dist/cjs/codegen/module-generator.d.ts

@@ -0,0 +1,11 @@
+import type { GenerateOptions } from './types.js';
+/**
+ * Generate the modules registry file.
+ *
+ * Groups all tools by their module (including sharedWith expansion),
+ * and generates a mapping from module → toolNames[].
+ */
+export declare function generateModuleRegistry(options: GenerateOptions, moduleMetaImportPath?: string): Promise<{
+    outputPath: string;
+    moduleCount: number;
+}>;

package/dist/cjs/codegen/module-generator.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateModuleRegistry = generateModuleRegistry;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const fs_utils_js_1 = require("./fs-utils.js");
+const endpoint_scanner_js_1 = require("./endpoint-scanner.js");
+const ui_scanner_js_1 = require("./ui-scanner.js");
+const nestjs_scanner_js_1 = require("./nestjs-scanner.js");
+const types_js_1 = require("./types.js");
+/**
+ * Extract tool metadata (toolName, module, sharedWith) from a source file using regex.
+ */
+async function extractToolMeta(absolutePath, relativePath) {
+    const content = await (0, fs_utils_js_1.readFileSafe)(absolutePath);
+    const tools = [];
+    // Match define*Tool blocks (brace-balanced)
+    const blocks = (0, fs_utils_js_1.extractBalancedBlocks)(content, /define(?:Ai)?(?:Endpoint|Ui)Tool\(\s*/);
+    for (const block of blocks) {
+        const toolNameMatch = block.match(/toolName\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (!toolNameMatch)
+            continue;
+        const moduleMatch = block.match(/module\s*:\s*['"`]([^'"`]+)['"`]/);
+        // Extract sharedWith array
+        const sharedWithMatch = block.match(/sharedWith\s*:\s*\[([^\]]*)\]/);
+        let sharedWith;
+        if (sharedWithMatch) {
+            sharedWith = sharedWithMatch[1]
+                .match(/['"`]([^'"`]+)['"`]/g)
+                ?.map((s) => s.replace(/['"`]/g, ''));
+        }
+        tools.push({
+            toolName: toolNameMatch[1],
+            module: moduleMatch?.[1],
+            sharedWith,
+            sourceFile: relativePath,
+        });
+    }
+    return tools;
+}
+/**
+ * Generate the modules registry file.
+ *
+ * Groups all tools by their module (including sharedWith expansion),
+ * and generates a mapping from module → toolNames[].
+ */
+async function generateModuleRegistry(options, moduleMetaImportPath) {
+    const opts = (0, types_js_1.resolveDefaults)(options);
+    // Scan all tool files (ai-tool.ts + ai-ui-tool.ts)
+    const endpointScan = await (0, endpoint_scanner_js_1.scanEndpointTools)(options);
+    const uiScan = await (0, ui_scanner_js_1.scanUiTools)(options);
+    // Extract metadata from standalone tool files
+    const allToolMeta = [];
+    for (const file of [...endpointScan.files, ...uiScan.files]) {
+        const meta = await extractToolMeta(file.absolutePath, file.relativePath);
+        allToolMeta.push(...meta);
+    }
+    // Also include NestJS @AiTool decorated controllers
+    if (opts.nestjsDirs.length > 0) {
+        const nestScan = await (0, nestjs_scanner_js_1.scanNestControllers)(opts.nestjsDirs, opts.nestjsApiPrefix);
+        for (const tool of nestScan.tools) {
+            if (tool.module) {
+                allToolMeta.push({
+                    toolName: tool.name,
+                    module: tool.module,
+                    sharedWith: undefined,
+                    sourceFile: tool.controllerFile,
+                });
+            }
+        }
+    }
+    // Group by module (with sharedWith expansion)
+    const moduleTools = new Map();
+    for (const tool of allToolMeta) {
+        if (!tool.module)
+            continue;
+        // Primary module
+        if (!moduleTools.has(tool.module)) {
+            moduleTools.set(tool.module, new Set());
+        }
+        moduleTools.get(tool.module).add(tool.toolName);
+        // Shared modules
+        if (tool.sharedWith) {
+            for (const sharedModule of tool.sharedWith) {
+                if (!moduleTools.has(sharedModule)) {
+                    moduleTools.set(sharedModule, new Set());
+                }
+                moduleTools.get(sharedModule).add(tool.toolName);
+            }
+        }
+    }
+    // Sort modules and tools for deterministic output
+    const sortedModules = Array.from(moduleTools.keys()).sort();
+    // Generate toolsByModule mapping
+    const toolsByModuleEntries = [];
+    for (const module of sortedModules) {
+        const tools = Array.from(moduleTools.get(module)).sort();
+        const toolsStr = tools.map((t) => `'${t}'`).join(', ');
+        toolsByModuleEntries.push(`  '${module}': [${toolsStr}]`);
+    }
+    // Generate module type union
+    const moduleTypeUnion = sortedModules.map((m) => `'${m}'`).join(' | ');
+    // Optional module meta integration
+    const metaImport = moduleMetaImportPath
+        ? `import { moduleMeta } from '${moduleMetaImportPath}';\n`
+        : '';
+    const metaExport = moduleMetaImportPath
+        ? `\nexport { moduleMeta };\n`
+        : '';
+    // Generate CLASSIFICATION_PROMPT + intent modules when module meta is available
+    let classificationPromptCode = '';
+    let intentModulesCode = '';
+    const metaContent = moduleMetaImportPath
+        ? await readModuleMeta(opts.rootDir, moduleMetaImportPath)
+        : null;
+    if (metaContent) {
+        classificationPromptCode = generateClassificationPrompt(sortedModules, metaContent);
+        intentModulesCode = generateIntentModules(sortedModules, metaContent, moduleTools);
+    }
+    const code = `/* eslint-disable */
+/**
+ * AUTO-GENERATED FILE — do not edit manually.
+ * Generated by glirastes
+ *
+ * Modules: ${sortedModules.length}
+ * Total tool assignments: ${allToolMeta.length}
+ */
+
+import { z } from 'zod';
+import type { IntentModule, ModuleMeta } from 'glirastes';
+import { EXECUTION_DEFAULTS } from 'glirastes';
+${metaImport}export type IntentType = ${moduleTypeUnion || 'string'};
+
+export const IntentSchema = z.object({
+  intent: z.enum([${sortedModules.map((m) => `'${m}'`).join(', ')}, 'ambiguous']),
+  confidence: z.number().min(0).max(1),
+});
+
+export type IntentClassification = z.infer<typeof IntentSchema>;
+
+export const toolsByModule: Record<IntentType, readonly string[]> = {
+${toolsByModuleEntries.join(',\n')}
+};
+
+export const moduleTypes: readonly IntentType[] = [${sortedModules.map((m) => `'${m}'`).join(', ')}] as const;
+
+${generateRelatedModules(sortedModules, moduleTools)}
+/**
+ * Build an IntentModule by merging module meta execution config
+ * with EXECUTION_DEFAULTS and auto-collected toolNames.
+ */
+export function buildIntentModule(
+  type: IntentType,
+  toolNames: readonly string[],
+  meta: ModuleMeta,
+): IntentModule {
+  const exec = { ...EXECUTION_DEFAULTS, ...meta.execution };
+  return {
+    type,
+    toolNames: [...toolNames],
+    systemPromptAddition: meta.systemPrompt,
+    maxSteps: exec.maxSteps,
+    contextWindow: exec.contextWindow,
+    modelTier: exec.modelTier,
+    meta,
+  };
+}
+${intentModulesCode}${classificationPromptCode}${metaExport}`;
+    const outputPath = (0, node_path_1.join)(opts.rootDir, opts.outputDir, 'modules.generated.ts');
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    await (0, promises_1.writeFile)(outputPath, code, 'utf-8');
+    if (!opts.quiet) {
+        console.log(`✓ Generated ${outputPath} (${sortedModules.length} modules)`);
+    }
+    return { outputPath, moduleCount: sortedModules.length };
+}
+/**
+ * Attempt to read and parse module metadata from a source file.
+ * Returns a map of module → { hint, examples, execution?, systemPrompt? } extracted via regex.
+ */
+async function readModuleMeta(rootDir, metaImportPath) {
+    // Resolve import path to absolute path
+    const resolved = metaImportPath
+        .replace(/^@\//, 'src/')
+        .replace(/^\.\//, '');
+    const candidates = [
+        (0, node_path_1.join)(rootDir, resolved + '.ts'),
+        (0, node_path_1.join)(rootDir, resolved + '/index.ts'),
+        (0, node_path_1.join)(rootDir, resolved),
+    ];
+    let content = '';
+    for (const candidate of candidates) {
+        content = await (0, fs_utils_js_1.readFileSafe)(candidate);
+        if (content)
+            break;
+    }
+    if (!content)
+        return null;
+    const result = new Map();
+    // Match module entries like: task_query: { classification: { hint: '...', examples: [...] }, execution: {...}, systemPrompt: `...` }
+    const moduleBlocks = content.matchAll(/(\w+)\s*:\s*\{[\s\S]*?classification\s*:\s*\{([\s\S]*?)\}[\s\S]*?(?:execution|systemPrompt)/g);
+    for (const match of moduleBlocks) {
+        const moduleName = match[1];
+        const classBlock = match[2];
+        const hintMatch = classBlock.match(/hint\s*:\s*['"`]([^'"`]+)['"`]/);
+        const examplesMatch = classBlock.match(/examples\s*:\s*\[([\s\S]*?)\]/);
+        const hint = hintMatch?.[1] ?? '';
+        const examples = [];
+        if (examplesMatch) {
+            const exampleStrings = examplesMatch[1].matchAll(/['"`]([^'"`]+)['"`]/g);
+            for (const ex of exampleStrings) {
+                examples.push(ex[1]);
+            }
+        }
+        // Extract execution config from the full match
+        const fullBlock = match[0];
+        const execMatch = fullBlock.match(/execution\s*:\s*\{([\s\S]*?)\}/);
+        let execution;
+        if (execMatch) {
+            const execBlock = execMatch[1];
+            const maxStepsMatch = execBlock.match(/maxSteps\s*:\s*(\d+)/);
+            const contextWindowMatch = execBlock.match(/contextWindow\s*:\s*(\d+)/);
+            const modelTierMatch = execBlock.match(/modelTier\s*:\s*['"`]([^'"`]+)['"`]/);
+            if (maxStepsMatch || contextWindowMatch || modelTierMatch) {
+                execution = {};
+                if (maxStepsMatch)
+                    execution.maxSteps = parseInt(maxStepsMatch[1], 10);
+                if (contextWindowMatch)
+                    execution.contextWindow = parseInt(contextWindowMatch[1], 10);
+                if (modelTierMatch)
+                    execution.modelTier = modelTierMatch[1];
+            }
+        }
+        // Extract systemPrompt
+        const sysPromptMatch = fullBlock.match(/systemPrompt\s*:\s*(?:`([\s\S]*?)`|'([^']*)'|"([^"]*)")/);
+        const systemPrompt = sysPromptMatch
+            ? (sysPromptMatch[1] ?? sysPromptMatch[2] ?? sysPromptMatch[3])?.trim()
+            : undefined;
+        if (hint || examples.length > 0) {
+            result.set(moduleName, { hint, examples, execution, systemPrompt });
+        }
+    }
+    return result.size > 0 ? result : null;
+}
+/**
+ * Generate intentModules record + getModuleForIntent / getAllModules helpers.
+ * Only emitted when module meta is available (has execution/systemPrompt data).
+ */
+function generateIntentModules(modules, meta, moduleTools) {
+    const entries = [];
+    for (const mod of modules) {
+        const info = meta.get(mod);
+        const tools = moduleTools.get(mod);
+        if (!tools)
+            continue;
+        // Build meta object literal
+        const hint = info?.hint ?? '';
+        const examples = info?.examples ?? [];
+        const exStr = examples.map((e) => `'${e.replace(/'/g, "\\'")}'`).join(', ');
+        // Execution overrides (only non-default values)
+        let execStr = '';
+        if (info?.execution) {
+            const parts = [];
+            if (info.execution.maxSteps !== undefined)
+                parts.push(`maxSteps: ${info.execution.maxSteps}`);
+            if (info.execution.contextWindow !== undefined)
+                parts.push(`contextWindow: ${info.execution.contextWindow}`);
+            if (info.execution.modelTier !== undefined)
+                parts.push(`modelTier: '${info.execution.modelTier}'`);
+            if (parts.length > 0)
+                execStr = `    execution: { ${parts.join(', ')} },\n`;
+        }
+        const sysPrompt = info?.systemPrompt
+            ? `    systemPrompt: \`${info.systemPrompt.replace(/`/g, '\\`')}\`,\n`
+            : '';
+        entries.push(`  '${mod}': buildIntentModule('${mod}', toolsByModule['${mod}'], {
+    classification: { hint: '${hint.replace(/'/g, "\\'")}', examples: [${exStr}] },
+${execStr}${sysPrompt}  })`);
+    }
+    if (entries.length === 0)
+        return '';
+    return `
+export const intentModules: Record<IntentType, IntentModule> = {
+${entries.join(',\n')}
+};
+
+export function getModuleForIntent(intent: IntentType): IntentModule | undefined {
+  return intentModules[intent];
+}
+
+export function getAllModules(): IntentModule[] {
+  return Object.values(intentModules);
+}
+`;
+}
+/**
+ * Generate the CLASSIFICATION_PROMPT constant from module metadata.
+ */
+function generateClassificationPrompt(modules, meta) {
+    const moduleDescriptions = [];
+    for (const mod of modules) {
+        const info = meta.get(mod);
+        if (!info) {
+            moduleDescriptions.push(`- ${mod}: (no classification metadata)`);
+            continue;
+        }
+        const examplesStr = info.examples.length > 0
+            ? `\n  Examples: ${info.examples.map((e) => `"${e}"`).join(', ')}`
+            : '';
+        moduleDescriptions.push(`- ${mod}: ${info.hint}${examplesStr}`);
+    }
+    const prompt = `Classify the user request into ONE of these categories:\\n\\n${moduleDescriptions.join('\\n\\n')}\\n\\n- ambiguous: Unclear, multiple areas, or small talk\\n\\nRespond with high confidence (0.8-1.0) when clear, lower (0.4-0.7) when uncertain.`;
+    return `\nexport const CLASSIFICATION_PROMPT = \`${prompt}\`;\n`;
+}
+/**
+ * Generate relatedModules — derived from tool overlap between modules.
+ * Two modules are related when they share at least one tool (via sharedWith).
+ */
+function generateRelatedModules(modules, moduleTools) {
+    const entries = [];
+    for (const modA of modules) {
+        const toolsA = moduleTools.get(modA);
+        if (!toolsA)
+            continue;
+        const related = [];
+        for (const modB of modules) {
+            if (modA === modB)
+                continue;
+            const toolsB = moduleTools.get(modB);
+            if (!toolsB)
+                continue;
+            for (const tool of toolsA) {
+                if (toolsB.has(tool)) {
+                    related.push(modB);
+                    break;
+                }
+            }
+        }
+        if (related.length > 0) {
+            entries.push(`  '${modA}': [${related.map((r) => `'${r}'`).join(', ')}]`);
+        }
+    }
+    if (entries.length === 0)
+        return '';
+    return `/**
+ * Derived from tool overlap — two modules are related when they share tools.
+ * Used by the pipeline router for medium-confidence tool expansion.
+ */
+export const relatedModules: Record<string, string[]> = {
+${entries.join(',\n')}
+};
+`;
+}

package/dist/cjs/codegen/nestjs-scanner.d.ts

@@ -0,0 +1,43 @@
+export interface DiscoveredNestTool {
+    name: string;
+    description: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Full path, e.g. /api/users/:id */
+    path: string;
+    /** From @AiModule intent */
+    module?: string;
+    /** Absolute path to the controller file */
+    controllerFile: string;
+    /** Extracted from route segments starting with ':' */
+    pathParams: string[];
+    /** Whether tool requires human approval (defaults to true for mutations) */
+    needsApproval?: boolean;
+    /** Roles that may call this tool (empty = all roles) */
+    allowedRoles?: string[];
+}
+export interface UncoveredNestController {
+    /** Absolute path to the controller file */
+    controllerFile: string;
+    /** Controller class name (extracted from `class XxxController`) */
+    controllerName: string;
+    /** Number of HTTP method decorators (@Get, @Post, etc.) found */
+    httpMethodCount: number;
+}
+export interface NestScanResult {
+    tools: DiscoveredNestTool[];
+    modules: Array<{
+        intent: string;
+        hint?: string;
+        examples?: string[];
+        controllerFile: string;
+    }>;
+    uncoveredControllers: UncoveredNestController[];
+}
+/**
+ * Scan NestJS controller files for `@AiTool` and `@AiModule` decorator
+ * metadata using static regex analysis (no runtime reflection).
+ *
+ * @param dirs        Directories to scan recursively for `*.controller.ts` files.
+ * @param apiPrefix   Optional global route prefix (e.g. `'api'`).
+ */
+export declare function scanNestControllers(dirs: string[], apiPrefix?: string): Promise<NestScanResult>;

package/dist/cjs/codegen/nestjs-scanner.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanNestControllers = scanNestControllers;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const fs_utils_js_1 = require("./fs-utils.js");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildPath(apiPrefix, controllerPath, methodPath) {
+    const parts = [apiPrefix, controllerPath, methodPath].filter(Boolean);
+    const joined = parts.join('/').replace(/\/+/g, '/').replace(/^\/|\/$/g, '');
+    return '/' + joined;
+}
+function extractPathParams(path) {
+    return (path.match(/:(\w+)/g) || []).map((p) => p.slice(1));
+}
+/**
+ * Recursively find all `*.controller.ts` files in a directory,
+ * skipping `node_modules` and `.git`.
+ */
+async function findControllerFiles(dir) {
+    const results = [];
+    async function walk(currentDir) {
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = (0, node_path_1.join)(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                await walk(fullPath);
+            }
+            else if (entry.name.endsWith('.controller.ts')) {
+                results.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    return results.sort();
+}
+const HTTP_DECORATOR_RE = /@(Get|Post|Put|Patch|Delete)\(\s*(?:['"]([^'"]*)['"]\s*)?\)/g;
+function findHttpDecorators(content) {
+    const matches = [];
+    const re = new RegExp(HTTP_DECORATOR_RE.source, 'g');
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        matches.push({
+            method: m[1].toUpperCase(),
+            subRoute: m[2] ?? '',
+            index: m.index,
+        });
+    }
+    return matches;
+}
+/**
+ * For a given character index in `content`, find the nearest preceding HTTP
+ * method decorator.
+ */
+function nearestHttpDecorator(decorators, position) {
+    let best;
+    for (const d of decorators) {
+        if (d.index < position) {
+            if (!best || d.index > best.index) {
+                best = d;
+            }
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+function parseControllerPath(content) {
+    const m = content.match(/@Controller\(\s*['"]([^'"]*)['"]\s*\)/);
+    return m?.[1] ?? '';
+}
+function parseAiModule(content) {
+    const blocks = (0, fs_utils_js_1.extractBalancedBlocks)(content, /@AiModule\(\s*/);
+    if (blocks.length === 0)
+        return undefined;
+    const block = blocks[0];
+    const intentMatch = block.match(/intent:\s*['"]([^'"]+)['"]/);
+    if (!intentMatch)
+        return undefined;
+    const hint = block.match(/hint:\s*['"]([^'"]+)['"]/)?.[1];
+    let examples;
+    const examplesMatch = block.match(/examples:\s*\[([^\]]*)\]/);
+    if (examplesMatch) {
+        const inner = examplesMatch[1];
+        examples = [];
+        const strRe = /['"]([^'"]+)['"]/g;
+        let sm;
+        while ((sm = strRe.exec(inner)) !== null) {
+            examples.push(sm[1]);
+        }
+    }
+    return { intent: intentMatch[1], hint, examples };
+}
+function parseAiTools(content) {
+    const tools = [];
+    // We need to know the source index of each @AiTool match.
+    // extractBalancedBlocks doesn't expose offsets, so we locate them manually.
+    const aiToolRe = /@AiTool\(\s*/g;
+    let prefixMatch;
+    while ((prefixMatch = aiToolRe.exec(content)) !== null) {
+        const searchStart = prefixMatch.index + prefixMatch[0].length;
+        const braceStart = content.indexOf('{', searchStart);
+        if (braceStart === -1)
+            continue;
+        // Balanced-brace walk
+        let depth = 0;
+        let i = braceStart;
+        for (; i < content.length; i++) {
+            if (content[i] === '{')
+                depth++;
+            else if (content[i] === '}')
+                depth--;
+            if (depth === 0)
+                break;
+        }
+        if (depth !== 0)
+            continue;
+        const inner = content.slice(braceStart + 1, i);
+        const nameMatch = inner.match(/name:\s*['"`]([^'"`]+)['"`]/);
+        const descMatch = inner.match(/description:\s*['"]([^'"]+)['"]/)
+            || inner.match(/description:\s*`([\s\S]*?)`/);
+        if (nameMatch) {
+            const description = (descMatch?.[1] ?? descMatch?.[2] ?? '').replace(/\s+/g, ' ').trim();
+            // Extract needsApproval (boolean literal)
+            const approvalMatch = inner.match(/needsApproval:\s*(true|false)/);
+            const needsApproval = approvalMatch ? approvalMatch[1] === 'true' : undefined;
+            // Extract allowedRoles (string array)
+            let allowedRoles;
+            const rolesMatch = inner.match(/allowedRoles:\s*\[([^\]]*)\]/);
+            if (rolesMatch) {
+                allowedRoles = [];
+                const roleRe = /['"`]([^'"`]+)['"`]/g;
+                let rm;
+                while ((rm = roleRe.exec(rolesMatch[1])) !== null) {
+                    allowedRoles.push(rm[1]);
+                }
+            }
+            tools.push({
+                name: nameMatch[1],
+                description,
+                needsApproval,
+                allowedRoles,
+                sourceIndex: prefixMatch.index,
+            });
+        }
+    }
+    return tools;
+}
+// ---------------------------------------------------------------------------
+// Main scanner
+// ---------------------------------------------------------------------------
+/**
+ * Scan NestJS controller files for `@AiTool` and `@AiModule` decorator
+ * metadata using static regex analysis (no runtime reflection).
+ *
+ * @param dirs        Directories to scan recursively for `*.controller.ts` files.
+ * @param apiPrefix   Optional global route prefix (e.g. `'api'`).
+ */
+async function scanNestControllers(dirs, apiPrefix = '') {
+    const result = { tools: [], modules: [], uncoveredControllers: [] };
+    // 1. Collect all controller files from every directory
+    const allFiles = [];
+    for (const dir of dirs) {
+        const files = await findControllerFiles(dir);
+        allFiles.push(...files);
+    }
+    // 2. Parse each controller
+    for (const filePath of allFiles) {
+        let content;
+        try {
+            content = await (0, promises_1.readFile)(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        // Check ignore markers — only skip file when @ai-ignore appears before
+        // the first import/class (file-level ignore). Method-level // @ai-ignore
+        // comments are fine — methods without @AiTool are already skipped.
+        const preamble = content.slice(0, content.search(/^(?:import|@Controller|@Module|export\s+class)\b/m) >>> 0 || 200);
+        if (preamble.includes('@ai-ignore'))
+            continue;
+        if (await (0, fs_utils_js_1.isDirAiIgnored)((0, node_path_1.dirname)(filePath)))
+            continue;
+        // Controller base path
+        const controllerPath = parseControllerPath(content);
+        // Module metadata
+        const moduleMeta = parseAiModule(content);
+        if (moduleMeta) {
+            result.modules.push({
+                ...moduleMeta,
+                controllerFile: filePath,
+            });
+        }
+        // Tool metadata
+        const rawTools = parseAiTools(content);
+        if (rawTools.length === 0) {
+            // Check if this controller has HTTP endpoints that should have @AiTool
+            const httpDecorators = findHttpDecorators(content);
+            if (httpDecorators.length > 0) {
+                const classMatch = content.match(/class\s+(\w+)/);
+                result.uncoveredControllers.push({
+                    controllerFile: filePath,
+                    controllerName: classMatch?.[1] ?? 'UnknownController',
+                    httpMethodCount: httpDecorators.length,
+                });
+            }
+            continue;
+        }
+        const httpDecorators = findHttpDecorators(content);
+        for (const tool of rawTools) {
+            const httpDec = nearestHttpDecorator(httpDecorators, tool.sourceIndex);
+            const method = httpDec?.method ?? 'GET';
+            const subRoute = httpDec?.subRoute ?? '';
+            const fullPath = buildPath(apiPrefix, controllerPath, subRoute);
+            const pathParams = extractPathParams(fullPath);
+            result.tools.push({
+                name: tool.name,
+                description: tool.description,
+                method,
+                path: fullPath,
+                module: moduleMeta?.intent,
+                controllerFile: filePath,
+                pathParams,
+                needsApproval: tool.needsApproval,
+                allowedRoles: tool.allowedRoles,
+            });
+        }
+    }
+    return result;
+}

package/dist/cjs/codegen/output-recommender.d.ts

@@ -0,0 +1,23 @@
+import type { AgentAuthStrategy } from '../types.js';
+export type OutputFormat = 'skill' | 'mcp' | 'both';
+export interface RecommendationInput {
+    auth: AgentAuthStrategy;
+    hasStreaming?: boolean;
+    hasWebSocket?: boolean;
+    multiAgentAccess?: boolean;
+    toolCount?: number;
+}
+/**
+ * Recommend the best output format (skill, mcp, or both) based on
+ * the project's auth strategy, transport needs, and tool count.
+ *
+ * - OAuth2 → MCP (needs persistent token management)
+ * - Streaming/WebSocket → MCP (needs persistent connection)
+ * - Multi-agent → MCP (shared server benefits)
+ * - Many tools (>20) → both (MCP for power users, skill for simple use)
+ * - Default → skill (simpler, no server process needed)
+ */
+export declare function recommendOutputFormat(input: RecommendationInput): {
+    format: OutputFormat;
+    reason: string;
+};