@pikku/cli 0.12.2 → 0.12.3

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

@@ -1,21 +1,48 @@
 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',
+    'index',
+    'show',
+    'create',
+    'update',
+    'destroy',
+    'delete',
+    'list',
 ]);
+/** Map from HTTP status code to pikku error class name */
+const STATUS_TO_ERROR = {
+    400: 'BadRequestError',
+    401: 'UnauthorizedError',
+    403: 'ForbiddenError',
+    404: 'NotFoundError',
+    405: 'MethodNotAllowedError',
+    409: 'ConflictError',
+    422: 'UnprocessableContentError',
+    429: 'TooManyRequestsError',
+    500: 'InternalServerError',
+};
 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();
+    const description = parsed.description?.trim();
+    // Summary is preferred — it's the operation's intent
     if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+        // If description adds info beyond summary, combine them
+        if (description &&
+            !GENERIC_SUMMARIES.has(description.toLowerCase()) &&
+            description.toLowerCase() !== summary.toLowerCase()) {
+            const sep = summary.endsWith('.') ? ' ' : '. ';
+            return `${capitalize(summary)}${sep}${capitalize(description)}`;
+        }
         return capitalize(summary);
     }
-    if (parsed.description && !GENERIC_SUMMARIES.has(parsed.description.trim().toLowerCase())) {
-        return capitalize(parsed.description.trim());
+    if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
+        return capitalize(description);
+    }
+    if (parsed.responseDescription) {
+        return capitalize(parsed.responseDescription);
     }
     const words = named.functionName
         .replace(/([A-Z])/g, ' $1')
@@ -23,6 +50,16 @@ function humanDescription(named, parsed) {
         .toLowerCase();
     return capitalize(words);
 }
+function getErrorClassesForResponses(errorResponses) {
+    const classes = [];
+    for (const err of errorResponses) {
+        const cls = STATUS_TO_ERROR[err.statusCode];
+        if (cls && !classes.includes(cls)) {
+            classes.push(cls);
+        }
+    }
+    return classes;
+}
 export function generateAddonFromOpenAPI(spec, vars, flags) {
     const files = {};
     const { name } = vars;
@@ -50,7 +87,7 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     const functionExports = [];
     for (const { named, parsed } of opPairs) {
         const funcCtx = createContext(schemaRefs);
-        const funcCode = generateFunctionFile(named, parsed, vars, funcCtx);
+        const funcCode = generateFunctionFile(named, parsed, vars, funcCtx, spec, flags);
         files[`src/functions/${named.functionName}.function.ts`] = funcCode;
         functionExports.push(named.functionName);
     }
@@ -58,6 +95,8 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     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);
+    // Generate variable file for BASE_URL
+    files[`src/${name}.variable.ts`] = generateVariableFile(spec, vars);
     return files;
 }
 function generateTypesFile(spec, ctx) {
@@ -75,17 +114,32 @@ function generateTypesFile(spec, ctx) {
     }
     return lines.join('\n');
 }
-function generateFunctionFile(named, parsed, vars, ctx) {
+function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
     const lines = [];
     const { camelName } = vars;
+    // Tag description as file header
+    if (parsed.tags.length > 0) {
+        const tag = parsed.tags[0];
+        const tagDesc = spec.tagDescriptions[tag];
+        if (tagDesc) {
+            lines.push(`// ${tag} — ${tagDesc}`);
+            lines.push('');
+        }
+    }
     const hasInput = parsed.pathParams.length > 0 ||
         parsed.queryParams.length > 0 ||
+        parsed.headerParams.length > 0 ||
         parsed.requestBody;
     const pascalName = named.functionName.charAt(0).toUpperCase() + named.functionName.slice(1);
     const inputName = `${pascalName}Input`;
     const outputName = `${pascalName}Output`;
+    // Determine error imports needed
+    const errorClasses = getErrorClassesForResponses(parsed.errorResponses);
     lines.push("import { z } from 'zod'");
     lines.push("import { pikkuSessionlessFunc } from '#pikku'");
+    if (errorClasses.length > 0) {
+        lines.push(`import { ${errorClasses.join(', ')} } from '@pikku/core/errors'`);
+    }
     lines.push('');
     // Build Input schema (exported for pikku schema discovery)
     if (hasInput) {
@@ -95,7 +149,7 @@ function generateFunctionFile(named, parsed, vars, ctx) {
     }
     // Build Output schema (exported for pikku schema discovery)
     if (parsed.responseSchema) {
-        const outputCode = schemaToZod(parsed.responseSchema, ctx);
+        const outputCode = buildOutputSchema(parsed.responseSchema, ctx);
         lines.push(`export const ${outputName} = ${outputCode}`);
         lines.push('');
     }
@@ -105,11 +159,19 @@ function generateFunctionFile(named, parsed, vars, ctx) {
     funcConfig.push(`  description: ${JSON.stringify(description)},`);
     if (hasInput)
         funcConfig.push(`  input: ${inputName},`);
-    if (parsed.responseSchema)
+    if (parsed.responseSchema) {
         funcConfig.push(`  output: ${outputName},`);
-    const funcParams = hasInput
-        ? `{ ${camelName} }, data`
-        : `{ ${camelName} }`;
+    }
+    else {
+        funcConfig.push('  output: z.void(),');
+    }
+    if (errorClasses.length > 0) {
+        funcConfig.push(`  errors: [${errorClasses.join(', ')}],`);
+    }
+    if (flags.mcp) {
+        funcConfig.push('  mcp: true,');
+    }
+    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({`);
@@ -121,26 +183,27 @@ function generateFunctionFile(named, parsed, vars, ctx) {
 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},`);
+        props.push(formatParamProp(param, ctx));
     }
     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},`);
+        props.push(formatParamProp(param, ctx));
+    }
+    for (const param of parsed.headerParams) {
+        props.push(formatParamProp(param, ctx));
     }
     if (parsed.requestBody) {
         if (parsed.requestBody.properties) {
             const requiredSet = new Set(parsed.requestBody.required ?? []);
             for (const [key, propSchema] of Object.entries(parsed.requestBody.properties)) {
+                // Skip readOnly properties from input
+                if (propSchema.readOnly)
+                    continue;
                 const isOptional = !requiredSet.has(key);
                 const zodCode = schemaToZod(propSchema, ctx, { optional: isOptional });
-                props.push(`  ${key}: ${zodCode},`);
+                const withDesc = propSchema.description
+                    ? `${zodCode}.describe(${JSON.stringify(propSchema.description)})`
+                    : zodCode;
+                props.push(`  ${key}: ${withDesc},`);
             }
         }
         else {
@@ -150,6 +213,32 @@ function buildInputSchema(parsed, ctx) {
     }
     return `z.object({\n${props.join('\n')}\n})`;
 }
+function formatParamProp(param, ctx) {
+    const zodCode = schemaToZod(param.schema, ctx, { optional: !param.required });
+    let descParts = [];
+    if (param.description)
+        descParts.push(param.description);
+    if (param.example !== undefined)
+        descParts.push(`Example: ${JSON.stringify(param.example)}`);
+    const desc = descParts.length > 0
+        ? `${zodCode}.describe(${JSON.stringify(descParts.join('. '))})`
+        : zodCode;
+    return `  ${param.name}: ${desc},`;
+}
+function buildOutputSchema(schema, ctx) {
+    // For output schemas, filter out writeOnly properties
+    if (schema.properties) {
+        const filteredProps = {};
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+            if (!propSchema.writeOnly) {
+                filteredProps[key] = propSchema;
+            }
+        }
+        const filteredSchema = { ...schema, properties: filteredProps };
+        return schemaToZod(filteredSchema, ctx);
+    }
+    return schemaToZod(schema, ctx);
+}
 function generateIndexFile(functionExports) {
     const lines = [];
     for (const name of functionExports) {
@@ -161,7 +250,8 @@ function generateIndexFile(functionExports) {
 function generateServiceFile(spec, opPairs, vars, flags) {
     const { name, pascalName, screamingName, displayName } = vars;
     const lines = [];
-    const baseUrl = spec.baseUrl || 'https://api.example.com';
+    // Always import all error classes used in the switch statement
+    const allErrorClasses = new Set(Object.values(STATUS_TO_ERROR));
     if (flags.oauth) {
         lines.push("import { OAuth2Client } from '@pikku/core/oauth2'");
         lines.push("import type { TypedSecretService } from '#pikku/secrets/pikku-secrets.gen.js'");
@@ -169,15 +259,25 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     else if (flags.secret) {
         lines.push(`import type { ${pascalName}Secrets } from './${name}.secret.js'`);
     }
-    lines.push('');
-    lines.push(`const BASE_URL = ${JSON.stringify(baseUrl)}`);
+    if (allErrorClasses.size > 0) {
+        lines.push(`import { ${[...allErrorClasses].sort().join(', ')} } from '@pikku/core/errors'`);
+    }
+    lines.push(`import type { TypedVariablesService } from '#pikku/variables/pikku-variables.gen.js'`);
     lines.push('');
     if (flags.oauth) {
+        // Use OAuth2 details from spec if available
+        const oauthScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'oauth2');
+        const authUrl = oauthScheme?.flows?.authorizationUrl ??
+            'https://example.com/oauth2/authorize';
+        const tokenUrl = oauthScheme?.flows?.tokenUrl ?? 'https://example.com/oauth2/token';
+        const scopes = oauthScheme?.flows?.scopes
+            ? Object.keys(oauthScheme.flows.scopes)
+            : ['read', 'write'];
         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(`  authorizationUrl: ${JSON.stringify(authUrl)},`);
+        lines.push(`  tokenUrl: ${JSON.stringify(tokenUrl)},`);
+        lines.push(`  scopes: ${JSON.stringify(scopes)},`);
         lines.push('}');
         lines.push('');
     }
@@ -185,19 +285,29 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     const routes = {};
     for (const { parsed } of opPairs) {
         const key = `${parsed.method.toUpperCase()} ${parsed.path}`;
-        routes[key] = {
+        const route = {
             path: parsed.pathParams.map((p) => p.name),
             query: parsed.queryParams.map((p) => p.name),
+            headers: parsed.headerParams.map((p) => p.name),
         };
+        if (parsed.errorResponses.length > 0) {
+            route.errors = {};
+            for (const err of parsed.errorResponses) {
+                route.errors[err.statusCode] = err.description;
+            }
+        }
+        routes[key] = route;
     }
-    lines.push(`const ROUTES: Record<string, { path: string[], query: string[] }> = ${JSON.stringify(routes, null, 2)}`);
+    lines.push(`const ROUTES: Record<string, { path: string[], query: string[], headers: string[], errors?: Record<number, string> }> = ${JSON.stringify(routes, null, 2)}`);
     lines.push('');
     // Class declaration
     lines.push(`export class ${pascalName}Service {`);
+    lines.push('  private baseUrl: string');
     if (flags.oauth) {
         lines.push('  private oauth: OAuth2Client');
         lines.push('');
-        lines.push(`  constructor(secrets: TypedSecretService) {`);
+        lines.push(`  constructor(secrets: TypedSecretService, variables: TypedVariablesService) {`);
+        lines.push(`    this.baseUrl = variables.get('${screamingName}_BASE_URL') as string`);
         lines.push('    this.oauth = new OAuth2Client(');
         lines.push(`      ${screamingName}_OAUTH2_CONFIG,`);
         lines.push(`      '${screamingName}_APP_CREDENTIALS',`);
@@ -206,10 +316,19 @@ function generateServiceFile(spec, opPairs, vars, flags) {
         lines.push('  }');
     }
     else if (flags.secret) {
-        lines.push(`  constructor(private creds: ${pascalName}Secrets) {}`);
+        lines.push('');
+        lines.push(`  constructor(private creds: ${pascalName}Secrets, variables: TypedVariablesService) {`);
+        lines.push(`    this.baseUrl = variables.get('${screamingName}_BASE_URL') as string`);
+        lines.push('  }');
+    }
+    else {
+        lines.push('');
+        lines.push(`  constructor(variables: TypedVariablesService) {`);
+        lines.push(`    this.baseUrl = variables.get('${screamingName}_BASE_URL') as string`);
+        lines.push('  }');
     }
     lines.push('');
-    // call() method — splits data into path/query/body using route map
+    // call() method — splits data into path/query/headers/body using route map
     lines.push('  async call<T>(');
     lines.push("    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',");
     lines.push('    path: string,');
@@ -219,6 +338,9 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push('    let endpoint = path');
     lines.push('    let body: Record<string, unknown> | undefined');
     lines.push('    const query: Record<string, string> = {}');
+    lines.push('    const headers: Record<string, string> = {');
+    lines.push("      'Content-Type': 'application/json',");
+    lines.push('    }');
     lines.push('');
     lines.push('    if (data && route) {');
     lines.push('      // Interpolate path params');
@@ -233,17 +355,23 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push('          query[param] = String(data[param])');
     lines.push('        }');
     lines.push('      }');
+    lines.push('      // Extract header params');
+    lines.push('      for (const param of route.headers) {');
+    lines.push('        if (data[param] !== undefined) {');
+    lines.push('          headers[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 pathQueryHeaders = new Set([...route.path, ...route.query, ...route.headers])');
     lines.push('      const remaining = Object.fromEntries(');
-    lines.push('        Object.entries(data).filter(([k]) => !pathAndQuery.has(k))');
+    lines.push('        Object.entries(data).filter(([k]) => !pathQueryHeaders.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('    const url = new URL(`${this.baseUrl}${endpoint}`)');
     lines.push('    for (const [key, value] of Object.entries(query)) {');
     lines.push('      url.searchParams.set(key, value)');
     lines.push('    }');
@@ -251,38 +379,78 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     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('      headers,');
         lines.push('      body: body ? JSON.stringify(body) : undefined,');
         lines.push('    })');
     }
     else if (flags.secret) {
+        // Use apiKey details from spec if available
+        const apiKeyScheme = Object.values(spec.securitySchemes).find((s) => s.type === 'apiKey');
+        if (apiKeyScheme?.name && apiKeyScheme?.in === 'header') {
+            lines.push(`    headers[${JSON.stringify(apiKeyScheme.name)}] = this.creds.apiKey`);
+        }
+        else {
+            lines.push('    headers.Authorization = `Bearer ${this.creds.apiKey}`');
+        }
+        lines.push('');
         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('      headers,');
         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('      headers,');
         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('      const errorMessage = route?.errors?.[response.status] ?? errorText');
+    lines.push('      switch (response.status) {');
+    lines.push('        case 400: throw new BadRequestError(errorMessage)');
+    lines.push('        case 401: throw new UnauthorizedError(errorMessage)');
+    lines.push('        case 403: throw new ForbiddenError(errorMessage)');
+    lines.push('        case 404: throw new NotFoundError(errorMessage)');
+    lines.push('        case 405: throw new MethodNotAllowedError(errorMessage)');
+    lines.push('        case 409: throw new ConflictError(errorMessage)');
+    lines.push('        case 422: throw new UnprocessableContentError(errorMessage)');
+    lines.push('        case 429: throw new TooManyRequestsError(errorMessage)');
+    lines.push('        case 500: throw new InternalServerError(errorMessage)');
+    lines.push(`        default: throw new Error(\`${displayName} API error (\${response.status}): \${errorText}\`)`);
+    lines.push('      }');
     lines.push('    }');
     lines.push('');
     lines.push('    const text = await response.text()');
-    lines.push("    if (!text) return {} as T");
+    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');
 }
+function generateVariableFile(spec, vars) {
+    const { camelName, screamingName, displayName } = vars;
+    const serverUrls = spec.serverUrls.length > 0 ? spec.serverUrls : [];
+    const defaultUrl = serverUrls[0];
+    const lines = [];
+    lines.push("import { z } from 'zod'");
+    lines.push("import { wireVariable } from '@pikku/core/variable'");
+    lines.push('');
+    const schemaVarName = `${camelName}BaseUrlSchema`;
+    const urlsLiteral = serverUrls.map((u) => JSON.stringify(u)).join(', ');
+    lines.push(`export const ${schemaVarName} = z.enum([${urlsLiteral}]).default(${JSON.stringify(defaultUrl)})`);
+    lines.push('');
+    lines.push(`wireVariable({`);
+    lines.push(`  name: '${screamingName}_BASE_URL',`);
+    lines.push(`  displayName: '${displayName} Base URL',`);
+    lines.push(`  description: 'The base URL for the ${displayName} API.',`);
+    lines.push(`  variableId: '${screamingName}_BASE_URL',`);
+    lines.push(`  schema: ${schemaVarName},`);
+    lines.push(`})`);
+    lines.push('');
+    return lines.join('\n');
+}

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

@@ -1,4 +1,20 @@
 import type { OpenAPISchema } from './zod-codegen.js';
+export interface ErrorResponse {
+    statusCode: number;
+    description: string;
+}
+export interface SecuritySchemeInfo {
+    type: 'oauth2' | 'http' | 'apiKey';
+    scheme?: string;
+    bearerFormat?: string;
+    name?: string;
+    in?: string;
+    flows?: {
+        authorizationUrl?: string;
+        tokenUrl?: string;
+        scopes?: Record<string, string>;
+    };
+}
 export interface ParsedSpec {
     info: {
         title: string;
@@ -6,9 +22,12 @@ export interface ParsedSpec {
         description?: string;
     };
     baseUrl: string;
+    serverUrls: string[];
     authType: 'bearer' | 'oauth2' | 'apiKey' | 'none';
     operations: ParsedOperation[];
     componentSchemas: Record<string, OpenAPISchema>;
+    securitySchemes: Record<string, SecuritySchemeInfo>;
+    tagDescriptions: Record<string, string>;
 }
 export interface ParsedOperation {
     operationId?: string;
@@ -19,15 +38,21 @@ export interface ParsedOperation {
     tags: string[];
     pathParams: ParsedParam[];
     queryParams: ParsedParam[];
+    headerParams: ParsedParam[];
     requestBody?: OpenAPISchema;
+    requestBodyDescription?: string;
+    requestBodyRequired?: boolean;
     responseSchema?: OpenAPISchema;
     responseDescription?: string;
+    errorResponses: ErrorResponse[];
+    deprecated: boolean;
 }
 export interface ParsedParam {
     name: string;
     required: boolean;
     schema: OpenAPISchema;
     description?: string;
+    example?: unknown;
 }
 /**
  * Read and parse an OpenAPI spec from a file path.