@pikku/cli 0.12.0 → 0.12.2

package/dist/src/utils/openapi/codegen.js

@@ -0,0 +1,288 @@
+import { schemaToZod, schemaVarName, createContext, } from './zod-codegen.js';
+import { generateOperationNames, detectCommonPrefix, } from './naming.js';
+const GENERIC_SUMMARIES = new Set([
+    'index', 'show', 'create', 'update', 'destroy', 'delete', 'list',
+]);
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function humanDescription(named, parsed) {
+    if (parsed.responseDescription) {
+        return capitalize(parsed.responseDescription);
+    }
+    const summary = parsed.summary?.trim();
+    if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+        return capitalize(summary);
+    }
+    if (parsed.description && !GENERIC_SUMMARIES.has(parsed.description.trim().toLowerCase())) {
+        return capitalize(parsed.description.trim());
+    }
+    const words = named.functionName
+        .replace(/([A-Z])/g, ' $1')
+        .trim()
+        .toLowerCase();
+    return capitalize(words);
+}
+export function generateAddonFromOpenAPI(spec, vars, flags) {
+    const files = {};
+    const { name } = vars;
+    // Build context for Zod codegen with component schema refs
+    const schemaRefs = new Map();
+    for (const schemaName of Object.keys(spec.componentSchemas)) {
+        schemaRefs.set(schemaName, schemaVarName(schemaName));
+    }
+    const ctx = createContext(schemaRefs);
+    // Generate operation names
+    const paths = spec.operations.map((op) => op.path);
+    const commonPrefix = detectCommonPrefix(paths);
+    const namedOps = generateOperationNames(spec.operations.map((op) => ({
+        method: op.method,
+        path: op.path,
+        operationId: op.operationId,
+    })), commonPrefix);
+    // Pair named operations with their parsed data
+    const opPairs = namedOps.map((named, i) => ({ named, parsed: spec.operations[i] }));
+    // Generate types file with shared schemas (only if there are any)
+    if (Object.keys(spec.componentSchemas).length > 0) {
+        files[`src/${name}.types.ts`] = generateTypesFile(spec, ctx);
+    }
+    // Generate function files
+    const functionExports = [];
+    for (const { named, parsed } of opPairs) {
+        const funcCtx = createContext(schemaRefs);
+        const funcCode = generateFunctionFile(named, parsed, vars, funcCtx);
+        files[`src/functions/${named.functionName}.function.ts`] = funcCode;
+        functionExports.push(named.functionName);
+    }
+    // Generate index.ts with all exports
+    files['src/index.ts'] = generateIndexFile(functionExports);
+    // Generate typed API service class with route map
+    files[`src/${name}-api.service.ts`] = generateServiceFile(spec, opPairs, vars, flags);
+    return files;
+}
+function generateTypesFile(spec, ctx) {
+    const lines = [];
+    lines.push("import { z } from 'zod'");
+    lines.push('');
+    lines.push(`// Shared schemas from ${spec.info.title} v${spec.info.version}`);
+    lines.push('');
+    for (const [name, schema] of Object.entries(spec.componentSchemas)) {
+        const varName = schemaVarName(name);
+        const zodCode = schemaToZod(schema, ctx);
+        lines.push(`export const ${varName} = ${zodCode}`);
+        lines.push(`export type ${name} = z.infer<typeof ${varName}>`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function generateFunctionFile(named, parsed, vars, ctx) {
+    const lines = [];
+    const { camelName } = vars;
+    const hasInput = parsed.pathParams.length > 0 ||
+        parsed.queryParams.length > 0 ||
+        parsed.requestBody;
+    const pascalName = named.functionName.charAt(0).toUpperCase() + named.functionName.slice(1);
+    const inputName = `${pascalName}Input`;
+    const outputName = `${pascalName}Output`;
+    lines.push("import { z } from 'zod'");
+    lines.push("import { pikkuSessionlessFunc } from '#pikku'");
+    lines.push('');
+    // Build Input schema (exported for pikku schema discovery)
+    if (hasInput) {
+        const inputCode = buildInputSchema(parsed, ctx);
+        lines.push(`export const ${inputName} = ${inputCode}`);
+        lines.push('');
+    }
+    // Build Output schema (exported for pikku schema discovery)
+    if (parsed.responseSchema) {
+        const outputCode = schemaToZod(parsed.responseSchema, ctx);
+        lines.push(`export const ${outputName} = ${outputCode}`);
+        lines.push('');
+    }
+    const description = humanDescription(named, parsed);
+    const method = parsed.method.toUpperCase();
+    const funcConfig = [];
+    funcConfig.push(`  description: ${JSON.stringify(description)},`);
+    if (hasInput)
+        funcConfig.push(`  input: ${inputName},`);
+    if (parsed.responseSchema)
+        funcConfig.push(`  output: ${outputName},`);
+    const funcParams = hasInput
+        ? `{ ${camelName} }, data`
+        : `{ ${camelName} }`;
+    const returnCast = parsed.responseSchema ? ' as any' : '';
+    funcConfig.push(`  func: async (${funcParams}) => {`, `    return ${camelName}.call('${method}', '${parsed.path}'${hasInput ? ', data' : ''})${returnCast}`, '  },');
+    lines.push(`export const ${named.functionName} = pikkuSessionlessFunc({`);
+    lines.push(funcConfig.join('\n'));
+    lines.push('})');
+    lines.push('');
+    return lines.join('\n');
+}
+function buildInputSchema(parsed, ctx) {
+    const props = [];
+    for (const param of parsed.pathParams) {
+        const zodCode = schemaToZod(param.schema, ctx, { optional: !param.required });
+        const desc = param.description
+            ? `${zodCode}.describe(${JSON.stringify(param.description)})`
+            : zodCode;
+        props.push(`  ${param.name}: ${desc},`);
+    }
+    for (const param of parsed.queryParams) {
+        const zodCode = schemaToZod(param.schema, ctx, { optional: !param.required });
+        const desc = param.description
+            ? `${zodCode}.describe(${JSON.stringify(param.description)})`
+            : zodCode;
+        props.push(`  ${param.name}: ${desc},`);
+    }
+    if (parsed.requestBody) {
+        if (parsed.requestBody.properties) {
+            const requiredSet = new Set(parsed.requestBody.required ?? []);
+            for (const [key, propSchema] of Object.entries(parsed.requestBody.properties)) {
+                const isOptional = !requiredSet.has(key);
+                const zodCode = schemaToZod(propSchema, ctx, { optional: isOptional });
+                props.push(`  ${key}: ${zodCode},`);
+            }
+        }
+        else {
+            const bodyZod = schemaToZod(parsed.requestBody, ctx);
+            props.push(`  body: ${bodyZod},`);
+        }
+    }
+    return `z.object({\n${props.join('\n')}\n})`;
+}
+function generateIndexFile(functionExports) {
+    const lines = [];
+    for (const name of functionExports) {
+        lines.push(`export { ${name} } from './functions/${name}.function.js'`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function generateServiceFile(spec, opPairs, vars, flags) {
+    const { name, pascalName, screamingName, displayName } = vars;
+    const lines = [];
+    const baseUrl = spec.baseUrl || 'https://api.example.com';
+    if (flags.oauth) {
+        lines.push("import { OAuth2Client } from '@pikku/core/oauth2'");
+        lines.push("import type { TypedSecretService } from '#pikku/secrets/pikku-secrets.gen.js'");
+    }
+    else if (flags.secret) {
+        lines.push(`import type { ${pascalName}Secrets } from './${name}.secret.js'`);
+    }
+    lines.push('');
+    lines.push(`const BASE_URL = ${JSON.stringify(baseUrl)}`);
+    lines.push('');
+    if (flags.oauth) {
+        lines.push(`export const ${screamingName}_OAUTH2_CONFIG = {`);
+        lines.push(`  tokenSecretId: '${screamingName}_TOKENS',`);
+        lines.push(`  authorizationUrl: 'https://example.com/oauth2/authorize',`);
+        lines.push(`  tokenUrl: 'https://example.com/oauth2/token',`);
+        lines.push("  scopes: ['read', 'write'],");
+        lines.push('}');
+        lines.push('');
+    }
+    // Generate route map from parsed operations
+    const routes = {};
+    for (const { parsed } of opPairs) {
+        const key = `${parsed.method.toUpperCase()} ${parsed.path}`;
+        routes[key] = {
+            path: parsed.pathParams.map((p) => p.name),
+            query: parsed.queryParams.map((p) => p.name),
+        };
+    }
+    lines.push(`const ROUTES: Record<string, { path: string[], query: string[] }> = ${JSON.stringify(routes, null, 2)}`);
+    lines.push('');
+    // Class declaration
+    lines.push(`export class ${pascalName}Service {`);
+    if (flags.oauth) {
+        lines.push('  private oauth: OAuth2Client');
+        lines.push('');
+        lines.push(`  constructor(secrets: TypedSecretService) {`);
+        lines.push('    this.oauth = new OAuth2Client(');
+        lines.push(`      ${screamingName}_OAUTH2_CONFIG,`);
+        lines.push(`      '${screamingName}_APP_CREDENTIALS',`);
+        lines.push('      secrets');
+        lines.push('    )');
+        lines.push('  }');
+    }
+    else if (flags.secret) {
+        lines.push(`  constructor(private creds: ${pascalName}Secrets) {}`);
+    }
+    lines.push('');
+    // call() method — splits data into path/query/body using route map
+    lines.push('  async call<T>(');
+    lines.push("    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',");
+    lines.push('    path: string,');
+    lines.push('    data?: Record<string, unknown>');
+    lines.push('  ): Promise<T> {');
+    lines.push('    const route = ROUTES[`${method} ${path}`]');
+    lines.push('    let endpoint = path');
+    lines.push('    let body: Record<string, unknown> | undefined');
+    lines.push('    const query: Record<string, string> = {}');
+    lines.push('');
+    lines.push('    if (data && route) {');
+    lines.push('      // Interpolate path params');
+    lines.push('      for (const param of route.path) {');
+    lines.push('        if (data[param] !== undefined) {');
+    lines.push('          endpoint = endpoint.replace(`{${param}}`, String(data[param]))');
+    lines.push('        }');
+    lines.push('      }');
+    lines.push('      // Extract query params');
+    lines.push('      for (const param of route.query) {');
+    lines.push('        if (data[param] !== undefined) {');
+    lines.push('          query[param] = String(data[param])');
+    lines.push('        }');
+    lines.push('      }');
+    lines.push('      // Everything else goes into body');
+    lines.push('      const pathAndQuery = new Set([...route.path, ...route.query])');
+    lines.push('      const remaining = Object.fromEntries(');
+    lines.push('        Object.entries(data).filter(([k]) => !pathAndQuery.has(k))');
+    lines.push('      )');
+    lines.push('      if (Object.keys(remaining).length > 0) {');
+    lines.push('        body = remaining');
+    lines.push('      }');
+    lines.push('    }');
+    lines.push('');
+    lines.push('    const url = new URL(`${BASE_URL}${endpoint}`)');
+    lines.push('    for (const [key, value] of Object.entries(query)) {');
+    lines.push('      url.searchParams.set(key, value)');
+    lines.push('    }');
+    lines.push('');
+    if (flags.oauth) {
+        lines.push('    const response = await this.oauth.request(url.toString(), {');
+        lines.push('      method,');
+        lines.push("      headers: { 'Content-Type': 'application/json' },");
+        lines.push('      body: body ? JSON.stringify(body) : undefined,');
+        lines.push('    })');
+    }
+    else if (flags.secret) {
+        lines.push('    const response = await fetch(url.toString(), {');
+        lines.push('      method,');
+        lines.push('      headers: {');
+        lines.push("        'Content-Type': 'application/json',");
+        lines.push('        Authorization: `Bearer ${this.creds.apiKey}`,');
+        lines.push('      },');
+        lines.push('      body: body ? JSON.stringify(body) : undefined,');
+        lines.push('    })');
+    }
+    else {
+        lines.push('    const response = await fetch(url.toString(), {');
+        lines.push('      method,');
+        lines.push("      headers: { 'Content-Type': 'application/json' },");
+        lines.push('      body: body ? JSON.stringify(body) : undefined,');
+        lines.push('    })');
+    }
+    lines.push('');
+    lines.push('    if (!response.ok) {');
+    lines.push('      const errorText = await response.text()');
+    lines.push(`      throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)`);
+    lines.push('    }');
+    lines.push('');
+    lines.push('    const text = await response.text()');
+    lines.push("    if (!text) return {} as T");
+    lines.push('    return JSON.parse(text) as T');
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/src/utils/openapi/naming.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Derives function/method names from HTTP method + path.
+ * Uses operationId when available, otherwise generates from path segments.
+ */
+export declare function singularize(word: string): string;
+export declare function toCamelCase(str: string): string;
+export declare function toPascalCase(str: string): string;
+/**
+ * Strip common API prefix from paths (e.g. /api/v2/).
+ * Uses majority voting — a prefix shared by >75% of paths is stripped,
+ * so a few outlier paths (e.g. /oauth/...) don't break detection.
+ */
+export declare function detectCommonPrefix(paths: string[]): string;
+interface OperationForNaming {
+    method: string;
+    path: string;
+    operationId?: string;
+}
+export interface NamedOperation {
+    method: string;
+    path: string;
+    functionName: string;
+    methodName: string;
+}
+/**
+ * Generate function names for a list of operations.
+ * Handles collision detection and auto-deduplication.
+ */
+export declare function generateOperationNames(operations: OperationForNaming[], commonPrefix: string): NamedOperation[];
+export {};

package/dist/src/utils/openapi/naming.js

@@ -0,0 +1,167 @@
+/**
+ * Derives function/method names from HTTP method + path.
+ * Uses operationId when available, otherwise generates from path segments.
+ */
+const IRREGULAR_PLURALS = {
+    addresses: 'address',
+    statuses: 'status',
+    indices: 'index',
+    analyses: 'analysis',
+    quizzes: 'quiz',
+    matrices: 'matrix',
+    vertices: 'vertex',
+    aliases: 'alias',
+    buses: 'bus',
+};
+export function singularize(word) {
+    const lower = word.toLowerCase();
+    if (IRREGULAR_PLURALS[lower]) {
+        const singular = IRREGULAR_PLURALS[lower];
+        return word[0] === word[0].toUpperCase()
+            ? singular.charAt(0).toUpperCase() + singular.slice(1)
+            : singular;
+    }
+    if (lower.endsWith('ies') && lower.length > 4) {
+        return word.slice(0, -3) + 'y';
+    }
+    // -shes, -ches, -xes, -zes, -sses → drop "es"
+    if (lower.endsWith('shes') || lower.endsWith('ches') || lower.endsWith('xes') || lower.endsWith('zes') || lower.endsWith('sses')) {
+        return word.slice(0, -2);
+    }
+    // General: drop trailing "s" (covers courses→course, products→product, etc.)
+    if (lower.endsWith('s') && !lower.endsWith('ss') && !lower.endsWith('us') && lower.length > 2) {
+        return word.slice(0, -1);
+    }
+    return word;
+}
+export function toCamelCase(str) {
+    return str
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+        .replace(/^[A-Z]/, (c) => c.toLowerCase());
+}
+export function toPascalCase(str) {
+    const camel = toCamelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+/**
+ * Strip common API prefix from paths (e.g. /api/v2/).
+ * Uses majority voting — a prefix shared by >75% of paths is stripped,
+ * so a few outlier paths (e.g. /oauth/...) don't break detection.
+ */
+export function detectCommonPrefix(paths) {
+    if (paths.length === 0)
+        return '';
+    const segments = paths.map((p) => p.replace(/^\//, '').split('/'));
+    const threshold = Math.ceil(paths.length * 0.75);
+    // Find the longest prefix shared by at least `threshold` paths
+    let prefixLen = 0;
+    for (let i = 0; i < 10; i++) {
+        // Count how many paths have the same segment at position i as the first path
+        const candidateSeg = segments[0][i];
+        if (!candidateSeg || candidateSeg.startsWith('{'))
+            break;
+        const count = segments.filter((s) => s.length > i + 1 && s[i] === candidateSeg).length;
+        if (count >= threshold) {
+            prefixLen = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    if (prefixLen === 0)
+        return '';
+    return '/' + segments[0].slice(0, prefixLen).join('/') + '/';
+}
+/** Convert operationId to camelCase function name */
+function fromOperationId(operationId) {
+    // operationId might be snake_case, camelCase, PascalCase, or kebab-case
+    return toCamelCase(operationId
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, ''));
+}
+const METHOD_PREFIXES = {
+    get: 'get',
+    post: 'create',
+    put: 'update',
+    patch: 'update',
+    delete: 'delete',
+};
+/**
+ * Generate function names for a list of operations.
+ * Handles collision detection and auto-deduplication.
+ */
+export function generateOperationNames(operations, commonPrefix) {
+    const results = [];
+    const usedNames = new Map();
+    for (const op of operations) {
+        let name;
+        if (op.operationId) {
+            name = fromOperationId(op.operationId);
+        }
+        else {
+            name = deriveNameFromPath(op.method, op.path, commonPrefix);
+        }
+        // Handle collisions
+        const existing = usedNames.get(name) ?? 0;
+        if (existing > 0) {
+            usedNames.set(name, existing + 1);
+            name = `${name}${existing + 1}`;
+        }
+        usedNames.set(name, (usedNames.get(name) ?? 0) || 1);
+        results.push({
+            method: op.method,
+            path: op.path,
+            functionName: name,
+            methodName: name,
+        });
+    }
+    return results;
+}
+function deriveNameFromPath(method, path, commonPrefix) {
+    // Strip common prefix
+    let cleanPath = path;
+    if (commonPrefix && cleanPath.startsWith(commonPrefix)) {
+        cleanPath = '/' + cleanPath.slice(commonPrefix.length);
+    }
+    const segments = cleanPath
+        .replace(/^\//, '')
+        .split('/')
+        .filter(Boolean);
+    const methodLower = method.toLowerCase();
+    const prefix = METHOD_PREFIXES[methodLower] || methodLower;
+    // Separate param and non-param segments
+    const nonParams = [];
+    let hasTrailingParam = false;
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i].startsWith('{')) {
+            if (i === segments.length - 1) {
+                hasTrailingParam = true;
+            }
+        }
+        else {
+            nonParams.push(segments[i]);
+        }
+    }
+    if (nonParams.length === 0) {
+        return prefix;
+    }
+    // For GET with trailing param: singularize the last non-param segment
+    // For GET without trailing param: keep plural (list)
+    // For POST without trailing param: use prefix (create)
+    const parts = nonParams.map((seg, i) => {
+        const isLast = i === nonParams.length - 1;
+        let word = seg;
+        if (isLast && hasTrailingParam) {
+            word = singularize(word);
+        }
+        // For GET on collection (no trailing param), use "list" prefix instead of "get"
+        return toPascalCase(word);
+    });
+    // For GET on collection, use "list" instead of "get"
+    let finalPrefix = prefix;
+    if (methodLower === 'get' && !hasTrailingParam) {
+        finalPrefix = 'list';
+    }
+    return finalPrefix + parts.join('');
+}

package/dist/src/utils/openapi/parse-openapi.d.ts

@@ -0,0 +1,36 @@
+import type { OpenAPISchema } from './zod-codegen.js';
+export interface ParsedSpec {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    baseUrl: string;
+    authType: 'bearer' | 'oauth2' | 'apiKey' | 'none';
+    operations: ParsedOperation[];
+    componentSchemas: Record<string, OpenAPISchema>;
+}
+export interface ParsedOperation {
+    operationId?: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    pathParams: ParsedParam[];
+    queryParams: ParsedParam[];
+    requestBody?: OpenAPISchema;
+    responseSchema?: OpenAPISchema;
+    responseDescription?: string;
+}
+export interface ParsedParam {
+    name: string;
+    required: boolean;
+    schema: OpenAPISchema;
+    description?: string;
+}
+/**
+ * Read and parse an OpenAPI spec from a file path.
+ * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ */
+export declare function parseOpenAPISpec(filePath: string): Promise<ParsedSpec>;