glirastes 0.3.0 → 0.3.1

package/dist/cjs/codegen/output-recommender.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recommendOutputFormat = recommendOutputFormat;
+/**
+ * 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)
+ */
+function recommendOutputFormat(input) {
+    // OAuth2 → MCP (needs persistent auth state)
+    if (input.auth.type === 'oauth2') {
+        return { format: 'mcp', reason: 'OAuth2 requires persistent token management — MCP server handles refresh automatically' };
+    }
+    // Streaming/WebSocket → MCP
+    if (input.hasStreaming || input.hasWebSocket) {
+        return { format: 'mcp', reason: 'Streaming/WebSocket needs a persistent connection — MCP server is ideal' };
+    }
+    // Multi-agent → MCP
+    if (input.multiAgentAccess) {
+        return { format: 'mcp', reason: 'Multiple agents benefit from a shared MCP server instance' };
+    }
+    // Many tools → both (MCP for power users, skill for simple use)
+    if (input.toolCount && input.toolCount > 20) {
+        return { format: 'both', reason: 'Large tool count benefits from both formats — skill for quick setup, MCP for full access' };
+    }
+    // Default: skill (simpler)
+    return { format: 'skill', reason: 'Simple REST API with standard auth works well as a skill file' };
+}

package/dist/cjs/codegen/scaffolder.d.ts

@@ -0,0 +1,36 @@
+interface ScaffoldOptions {
+    /** Path to the route.ts file to scaffold from */
+    routeFile: string;
+    /** Root directory of the project */
+    rootDir: string;
+    /** File name for the tool file (default: 'ai-tool.ts') */
+    toolFileName?: string;
+    /** Overwrite existing file (default: false) */
+    force?: boolean;
+    /** Dry run — print output without writing */
+    dryRun?: boolean;
+}
+export interface ScaffoldResult {
+    code: string;
+    outputPath: string;
+    analysis: {
+        routeFile: string;
+        apiPath: string;
+        methods: string[];
+        module: string;
+        pathParams: string[];
+    };
+}
+/**
+ * Generate an ai-tool.ts scaffold from a route.ts file.
+ * Returns a structured result with code, output path, and analysis metadata.
+ */
+export declare function scaffoldAiTool(options: ScaffoldOptions): Promise<ScaffoldResult>;
+/**
+ * Format a scaffold result as a rich, color-coded human-readable string.
+ */
+export declare function formatScaffoldResult(result: ScaffoldResult, options?: {
+    dryRun?: boolean;
+    rootDir?: string;
+}): string;
+export {};

package/dist/cjs/codegen/scaffolder.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldAiTool = scaffoldAiTool;
+exports.formatScaffoldResult = formatScaffoldResult;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const fs_utils_js_1 = require("./fs-utils.js");
+const format_js_1 = require("./format.js");
+/**
+ * Analyze a route.ts file to extract HTTP methods, parameters, and body fields.
+ */
+async function analyzeRoute(routeFile, rootDir) {
+    const content = await (0, fs_utils_js_1.readFileSafe)(routeFile);
+    if (!content)
+        throw new Error(`File not found: ${routeFile}`);
+    // Extract exported HTTP methods
+    const methods = [];
+    for (const method of ['GET', 'POST', 'PATCH', 'PUT', 'DELETE']) {
+        if (new RegExp(`export\\s+(?:async\\s+)?function\\s+${method}\\b`).test(content)) {
+            methods.push(method);
+        }
+    }
+    // Extract path params from directory structure
+    const routeDir = (0, node_path_1.dirname)(routeFile);
+    const rel = (0, node_path_1.relative)(rootDir, routeDir);
+    const segments = rel.split(node_path_1.sep);
+    const pathParams = [];
+    const apiSegments = [];
+    let inApi = false;
+    for (const seg of segments) {
+        if (seg === 'api') {
+            inApi = true;
+            apiSegments.push(seg);
+            continue;
+        }
+        if (!inApi)
+            continue;
+        const paramMatch = seg.match(/^\[(\w+)\]$/);
+        if (paramMatch) {
+            pathParams.push(paramMatch[1]);
+            apiSegments.push(`:${paramMatch[1]}`);
+        }
+        else {
+            apiSegments.push(seg);
+        }
+    }
+    const apiPath = '/' + apiSegments.join('/');
+    // Extract body fields (from request.json() destructuring)
+    const bodyFields = [];
+    const bodyMatch = content.match(/(?:const|let)\s*\{([^}]+)\}\s*=\s*(?:await\s+)?(?:request|req)\.json\(\)/);
+    if (bodyMatch) {
+        const fields = bodyMatch[1].split(',').map((f) => f.trim().split(':')[0].trim());
+        bodyFields.push(...fields.filter(Boolean));
+    }
+    // Extract search params
+    const searchParams = [];
+    const spMatches = content.matchAll(/searchParams\.get\(\s*['"`](\w+)['"`]\s*\)/g);
+    for (const match of spMatches) {
+        searchParams.push(match[1]);
+    }
+    // Check for Zod schema usage
+    const hasZodSchema = /z\.object/.test(content);
+    return { methods, pathParams, bodyFields, searchParams, hasZodSchema, apiPath };
+}
+/**
+ * Derive tool name from API path.
+ * e.g., /api/tasks/:id → get_task, /api/tasks → list_tasks
+ */
+function deriveToolName(method, apiPath) {
+    const segments = apiPath
+        .split('/')
+        .filter((s) => s && s !== 'api' && !s.startsWith(':'));
+    const resource = segments[segments.length - 1] ?? 'resource';
+    const prefixMap = {
+        GET: segments.length === 1 ? 'list' : 'get',
+        POST: 'create',
+        PATCH: 'update',
+        PUT: 'update',
+        DELETE: 'delete',
+    };
+    const prefix = prefixMap[method] ?? method.toLowerCase();
+    return `${prefix}_${resource}`.replace(/-/g, '_');
+}
+/**
+ * Derive tool ID from API path.
+ * e.g., /api/tasks/:id → tasks.get
+ */
+function deriveToolId(method, apiPath) {
+    const segments = apiPath
+        .split('/')
+        .filter((s) => s && s !== 'api' && !s.startsWith(':'));
+    const actionMap = {
+        GET: segments.length === 1 ? 'list' : 'get',
+        POST: 'create',
+        PATCH: 'update',
+        PUT: 'update',
+        DELETE: 'delete',
+    };
+    const action = actionMap[method] ?? method.toLowerCase();
+    return `${segments.join('.')}.${action}`;
+}
+/**
+ * Suggest module type based on API path patterns.
+ */
+function suggestModule(method, apiPath) {
+    const path = apiPath.toLowerCase();
+    if (path.includes('/calendar') || path.includes('/events'))
+        return 'calendar';
+    if (path.includes('/group') || path.includes('/user') || path.includes('/member'))
+        return 'group_management';
+    if (path.includes('/task') || path.includes('/todo')) {
+        return method === 'GET' ? 'task_query' : 'task_mutation';
+    }
+    return method === 'GET' ? 'task_query' : 'task_mutation';
+}
+/**
+ * Build Zod input schema code from extracted parameters.
+ */
+function buildInputSchemaCode(pathParams, bodyFields, searchParams, method) {
+    const fields = [];
+    for (const param of pathParams) {
+        fields.push(`    ${param}: z.string().uuid(), // path parameter`);
+    }
+    if (method === 'GET' || method === 'DELETE') {
+        for (const param of searchParams) {
+            fields.push(`    ${param}: z.string().optional(), // search param`);
+        }
+    }
+    else {
+        for (const field of bodyFields) {
+            fields.push(`    ${field}: z.string(), // TODO: adjust type`);
+        }
+    }
+    if (fields.length === 0) {
+        return 'z.object({})';
+    }
+    return `z.object({\n${fields.join('\n')}\n  })`;
+}
+/**
+ * Generate an ai-tool.ts scaffold from a route.ts file.
+ * Returns a structured result with code, output path, and analysis metadata.
+ */
+async function scaffoldAiTool(options) {
+    const toolFileName = options.toolFileName ?? 'ai-tool.ts';
+    const analysis = await analyzeRoute(options.routeFile, options.rootDir);
+    if (analysis.methods.length === 0) {
+        throw new Error(`No exported HTTP methods found in ${options.routeFile}`);
+    }
+    const toolDir = (0, node_path_1.dirname)(options.routeFile);
+    const outputPath = (0, node_path_1.join)(toolDir, toolFileName);
+    // Check if file already exists
+    if (!options.force && !options.dryRun) {
+        try {
+            await (0, promises_1.stat)(outputPath);
+            throw new Error(`${toolFileName} already exists at ${outputPath}. Use --force to overwrite.`);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    // Determine module (use first method's suggestion as primary)
+    const primaryModule = suggestModule(analysis.methods[0], analysis.apiPath);
+    // Generate tool definitions
+    const tools = [];
+    for (const method of analysis.methods) {
+        const toolName = deriveToolName(method, analysis.apiPath);
+        const toolId = deriveToolId(method, analysis.apiPath);
+        const module = suggestModule(method, analysis.apiPath);
+        const isMutating = method !== 'GET';
+        const inputSchema = buildInputSchemaCode(analysis.pathParams, analysis.bodyFields, analysis.searchParams, method);
+        // Suggest uiAction
+        let uiActionLine = '';
+        if (isMutating) {
+            const entity = analysis.apiPath
+                .split('/')
+                .filter((s) => s && s !== 'api' && !s.startsWith(':'))[0] ?? 'entity';
+            const action = method === 'POST'
+                ? 'created'
+                : method === 'DELETE'
+                    ? 'deleted'
+                    : 'updated';
+            if (analysis.pathParams.length > 0) {
+                uiActionLine = `  uiActionOnSuccess: { type: '${entity.replace(/s$/, '')}-${action}', ${entity.replace(/s$/, '')}Id: '$${analysis.pathParams[0]}' },`;
+            }
+            else {
+                uiActionLine = `  uiActionOnSuccess: { type: '${entity.replace(/s$/, '')}-${action}', ${entity.replace(/s$/, '')}Id: '$id' },`;
+            }
+        }
+        tools.push(`defineEndpointTool({
+  id: '${toolId}',
+  toolName: '${toolName}',
+  module: '${module}',
+  // sharedWith: [], // TODO: add shared modules if needed
+  description: '${toolName.replace(/_/g, ' ')}. TODO: write a clear description for the AI.',
+  method: '${method}',
+  path: '${analysis.apiPath}',
+  inputSchema: ${inputSchema},
+  // allowedRoles: ['admin', 'user'], // Optional: specify roles, or omit to allow all roles
+  ${isMutating ? 'needsApproval: true,' : ''}
+${uiActionLine ? uiActionLine : '  // uiActionOnSuccess: { type: \'...\' },'}
+})`);
+    }
+    // Build file content
+    const isSingle = tools.length === 1;
+    const exportLine = isSingle
+        ? `export const aiTool = ${tools[0]};`
+        : `export const aiTools = [\n${tools.map((t) => `  ${t}`).join(',\n')},\n];`;
+    const code = `import { z } from 'zod';
+import { defineEndpointTool } from 'glirastes';
+
+${exportLine}
+`;
+    if (!options.dryRun) {
+        await (0, promises_1.writeFile)(outputPath, code, 'utf-8');
+    }
+    return {
+        code,
+        outputPath,
+        analysis: {
+            routeFile: options.routeFile,
+            apiPath: analysis.apiPath,
+            methods: analysis.methods,
+            module: primaryModule,
+            pathParams: analysis.pathParams,
+        },
+    };
+}
+/**
+ * Format a scaffold result as a rich, color-coded human-readable string.
+ */
+function formatScaffoldResult(result, options) {
+    const lines = [];
+    const rootDir = options?.rootDir ?? process.cwd();
+    const relRoute = (0, node_path_1.relative)(rootDir, result.analysis.routeFile);
+    const relOutput = (0, node_path_1.relative)(rootDir, result.outputPath);
+    // Header
+    lines.push((0, format_js_1.header)('Scaffold AI Tool'));
+    // Analysis summary
+    lines.push(`  ${format_js_1.colors.dim}Route:${format_js_1.colors.reset}   ${relRoute}`);
+    lines.push(`  ${format_js_1.colors.dim}Path:${format_js_1.colors.reset}    ${result.analysis.apiPath}`);
+    lines.push(`  ${format_js_1.colors.dim}Methods:${format_js_1.colors.reset} ${result.analysis.methods.join(', ')}`);
+    lines.push(`  ${format_js_1.colors.dim}Module:${format_js_1.colors.reset}  ${result.analysis.module}`);
+    if (result.analysis.pathParams.length > 0) {
+        lines.push(`  ${format_js_1.colors.dim}Params:${format_js_1.colors.reset}  ${result.analysis.pathParams.join(', ')}`);
+    }
+    lines.push('');
+    if (options?.dryRun) {
+        lines.push(`${format_js_1.colors.yellow}${format_js_1.colors.bold}--- Dry Run (not writing) ---${format_js_1.colors.reset}\n`);
+        lines.push(result.code);
+        lines.push(`${format_js_1.colors.yellow}${format_js_1.colors.bold}--- End Dry Run ---${format_js_1.colors.reset}`);
+    }
+    else {
+        lines.push(`${format_js_1.colors.green}${format_js_1.colors.bold}\u2705 Created:${format_js_1.colors.reset} ${relOutput}`);
+        lines.push('');
+        lines.push(`${format_js_1.colors.dim}Next steps:${format_js_1.colors.reset}`);
+        lines.push(`  1. Edit ${relOutput} \u2014 fill in TODO placeholders`);
+        lines.push(`  2. Run ${format_js_1.colors.cyan}glirastes generate-tools${format_js_1.colors.reset} to register`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}

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

@@ -0,0 +1,49 @@
+import type { GenerateOptions } from './types.js';
+import type { AgentSkillConfig } from '../types.js';
+export interface GenerateSkillsOptions extends GenerateOptions {
+    /** Skill configuration (app name, base URL, auth) */
+    skillConfig: AgentSkillConfig;
+    /** Output format(s) to generate */
+    formats?: Array<'markdown' | 'json'>;
+    /** Custom output directory for skill files (default: .claude/skills/generated/) */
+    skillOutputDir?: string;
+}
+export interface GenerateSkillsResult {
+    markdownPath?: string;
+    /** Paths of all generated markdown files (modular output) */
+    markdownPaths?: string[];
+    jsonPath?: string;
+    toolCount: number;
+    moduleCount: number;
+    /** Full extracted tool metadata for syncing to Glirastes */
+    tools: Array<{
+        toolName: string;
+        description: string;
+        method: string;
+        path: string;
+        module?: string;
+        allowedRoles?: string[];
+        needsApproval?: boolean;
+        inputFields: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+        outputFields: Array<{
+            name: string;
+            type: string;
+        }>;
+    }>;
+}
+/**
+ * Generate agent skill files from discovered tool definitions.
+ *
+ * Scans the project for endpoint and UI tool definitions and produces:
+ * - Modular Markdown skill files (one router SKILL.md + one file per module)
+ * - A JSON manifest (machine-readable for Codex / Agent SDK)
+ *
+ * Both formats contain the full tool catalog with auth instructions,
+ * enabling autonomous agents to interact with the platform API.
+ */
+export declare function generateAgentSkills(options: GenerateSkillsOptions): Promise<GenerateSkillsResult>;