nuxt-openapi-hyperfetch 0.3.81-beta → 1.0.0

package/dist/index.js

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import * as p from '@clack/prompts';
-import { existsSync } from 'fs';
-import * as path from 'path';
 import { generateOpenApiFiles, generateHeyApiFiles, checkJavaInstalled } from './generate.js';
 import { generateUseFetchComposables } from './generators/use-fetch/generator.js';
 import { generateUseAsyncDataComposables } from './generators/use-async-data/generator.js';
 import { generateNuxtServerRoutes } from './generators/nuxt-server/generator.js';
-import { generateConnectors } from './generators/components/connector-generator/generator.js';
+import { generateConnectors } from './generators/connectors/generator.js';
 import { promptInitialInputs, promptInputPath, promptComposablesSelection, promptServerRoutePath, promptBffConfig, promptGeneratorBackend, promptConnectors, } from './cli/prompts.js';
 import { MESSAGES } from './cli/messages.js';
 import { displayLogo } from './cli/logo.js';
@@ -77,7 +75,6 @@ program
             : config.generator === 'heyapi'
                 ? 'heyapi'
                 : config.backend;
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const backend = await promptGeneratorBackend(resolvedBackend);
         // Check Java availability when official backend is selected
         if (backend === 'official' && !checkJavaInstalled()) {
@@ -158,7 +155,6 @@ program
         for (const composable of composables) {
             const spinner = p.spinner();
             spinner.start(`Generating ${composable}...`);
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
             const generateOptions = { baseUrl: config.baseUrl, backend };
             try {
                 switch (composable) {
@@ -182,7 +178,6 @@ program
                         break;
                     case 'nuxtServer':
                         if (!config.dryRun) {
-                            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
                             await generateNuxtServerRoutes(outputPath, serverRoutePath, { enableBff, backend });
                             spinner.stop(`✓ Generated Nuxt server routes`);
                         }
@@ -198,16 +193,6 @@ program
             }
         }
         // Generate headless connectors if requested (requires useAsyncData)
-        if (generateConnectorsFlag) {
-            // Check zod is available in the user's project by probing their node_modules,
-            // not via import() which resolves from the CLI's own context (npx sandbox).
-            const zodPath = path.resolve(process.cwd(), 'node_modules', 'zod');
-            if (!existsSync(zodPath)) {
-                p.log.warn('Skipping connectors: "zod" is not installed in this project.\n' +
-                    '  Run: npm install zod');
-                generateConnectorsFlag = false;
-            }
-        }
         if (generateConnectorsFlag) {
             const spinner = p.spinner();
             spinner.start('Generating headless UI connectors...');

package/dist/module/index.js

@@ -5,7 +5,7 @@ import { checkJavaInstalled } from '../generate.js';
 import { generateUseFetchComposables } from '../generators/use-fetch/generator.js';
 import { generateUseAsyncDataComposables } from '../generators/use-async-data/generator.js';
 import { generateNuxtServerRoutes } from '../generators/nuxt-server/generator.js';
-import { generateConnectors } from '../generators/components/connector-generator/generator.js';
+import { generateConnectors } from '../generators/connectors/generator.js';
 import { createConsoleLogger } from '../cli/logger.js';
 export default defineNuxtModule({
     meta: {
@@ -67,8 +67,7 @@ export default defineNuxtModule({
                 await generateNuxtServerRoutes(resolvedOutput, serverRoutePath, { enableBff: options.enableBff, backend }, logger);
             }
             // 3. Generate headless connectors if requested (requires useAsyncData)
-            if (options.createUseAsyncDataConnectors &&
-                selectedGenerators.includes('useAsyncData')) {
+            if (options.createUseAsyncDataConnectors && selectedGenerators.includes('useAsyncData')) {
                 const connectorsOutputDir = path.join(composablesOutputDir, 'connectors');
                 await generateConnectors({
                     inputSpec: resolvedInput,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-openapi-hyperfetch",
-  "version": "0.3.81-beta",
-  "description": "Nuxt useFetch, useAsyncData and Nuxt server OpenAPI generator",
+  "version": "1.0.0",
+  "description": "Nuxt useFetch, useAsyncData, Nuxt server & Headless UI connectors OpenAPI generator",
   "type": "module",
   "author": "",
   "license": "Apache-2.0",
@@ -74,7 +74,8 @@
     "eslint-plugin-prettier": "^5.5.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1"
+    "typescript-eslint": "^8.57.1",
+    "zod": "^4.3.6"
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",

package/src/cli/prompts.ts

@@ -5,13 +5,7 @@
 import * as p from '@clack/prompts';
 import { checkCancellation, validateNonEmpty } from './utils.js';
 import { MESSAGES, CHOICES, DEFAULTS } from './messages.js';
-import type {
-  InitialInputs,
-  ComposablesSelection,
-  BffConfig,
-  ComposableType,
-  GeneratorBackend,
-} from './types.js';
+import type { InitialInputs, ComposablesSelection, BffConfig, GeneratorBackend } from './types.js';
 
 /**
  * Ask which OpenAPI generator backend to use

package/src/generators/components/connector-generator/templates.ts

@@ -29,8 +29,8 @@ function toAsyncDataName(operationId: string): string {
 }
 
 /**
- * composable name → PascalCase file name (without .ts), matching useAsyncData generator output.
- * 'useAsyncDataGetPets' → 'useAsyncDataGetPets'
+ * composable name → kebab-case file name (without .ts).
+ * 'useAsyncDataGetPets' → 'use-async-data-get-pets'
  */
 function toFileName(composableName: string): string {
   return composableName;
@@ -41,19 +41,32 @@ function toFileName(composableName: string): string {
 /**
  * Build all `import` lines for a resource connector.
  */
-function buildImports(resource: ResourceInfo, composablesRelDir: string, sdkRelDir: string, runtimeRelDir: string): string {
+function buildImports(
+  resource: ResourceInfo,
+  composablesRelDir: string,
+  sdkRelDir: string,
+  runtimeRelDir: string
+): string {
   const lines: string[] = [];
 
+  // vue — shallowRef needed when form, delete, or detail endpoints exist
+  const needsShallowRef = !!(
+    resource.createEndpoint ||
+    resource.updateEndpoint ||
+    resource.deleteEndpoint ||
+    resource.detailEndpoint
+  );
+  const needsComputed = !!resource.detailEndpoint;
+  if (needsShallowRef) {
+    const vueImports = needsComputed ? `shallowRef, computed` : `shallowRef`;
+    lines.push(`import { ${vueImports} } from 'vue';`);
+    lines.push('');
+  }
+
   // zod
   lines.push(`import { z } from 'zod';`);
   lines.push('');
 
-  // Vue — computed needed for the detail connector wrapper
-  if (resource.detailEndpoint) {
-    lines.push(`import { computed } from 'vue';`);
-    lines.push('');
-  }
-
   // connector-types — structural interfaces for return types
   const connectorTypeImports: string[] = ['ListConnectorReturn'];
   if (resource.detailEndpoint) {
@@ -65,7 +78,9 @@ function buildImports(resource: ResourceInfo, composablesRelDir: string, sdkRelD
   if (resource.deleteEndpoint) {
     connectorTypeImports.push('DeleteConnectorReturn');
   }
-  lines.push(`import type { ${connectorTypeImports.join(', ')} } from '${runtimeRelDir}/connector-types';`);
+  lines.push(
+    `import type { ${connectorTypeImports.join(', ')} } from '${runtimeRelDir}/connector-types';`
+  );
   lines.push('');
 
   // SDK request/response types (for the params overload signature)
@@ -184,6 +199,12 @@ function buildOptionsInterface(resource: ResourceInfo): string {
   if (resource.updateEndpoint && resource.zodSchemas.update) {
     fields.push(`  updateSchema?: z.ZodTypeAny | ((base: z.ZodTypeAny) => z.ZodTypeAny);`);
   }
+  if (resource.createEndpoint || resource.updateEndpoint || resource.deleteEndpoint) {
+    fields.push(`  onRequest?: (ctx: any) => void | Promise<void>;`);
+    fields.push(`  onSuccess?: (data: any) => void;`);
+    fields.push(`  onError?: (err: any) => void;`);
+    fields.push(`  onFinish?: () => void;`);
+  }
 
   if (fields.length === 0) {
     return `type ${typeName} = Record<string, never>;`;
@@ -213,11 +234,15 @@ function buildReturnType(resource: ResourceInfo): string {
     fields.push(`  detail: DetailConnectorReturn<${pascal}>;`);
   }
   if (resource.createEndpoint) {
-    const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
+    const inputType = resource.zodSchemas.create
+      ? `${pascal}CreateInput`
+      : `Record<string, unknown>`;
     fields.push(`  createForm: FormConnectorReturn<${inputType}>;`);
   }
   if (resource.updateEndpoint) {
-    const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
+    const inputType = resource.zodSchemas.update
+      ? `${pascal}UpdateInput`
+      : `Record<string, unknown>`;
     fields.push(`  updateForm: FormConnectorReturn<${inputType}>;`);
   }
   if (resource.deleteEndpoint) {
@@ -227,6 +252,18 @@ function buildReturnType(resource: ResourceInfo): string {
   return [`type ${typeName} = {`, ...fields, `};`].join('\n');
 }
 
+/**
+ * Build the 3 generated lines for a composable that is keyed by a single path param
+ * (detail, delete). Uses computed(() => ({ param: ref.value })) so that p.value is
+ * always an object during setup — avoids `null.param` crash when Nuxt evaluates computedKey.
+ */
+function buildPathParamComposableLines(prefix: string, fn: string, pathParam: string): string[] {
+  return [
+    `  const ${prefix}Ref = shallowRef(null);`,
+    `  const ${prefix}Composable = ${fn}(computed(() => ({ ${pathParam}: ${prefix}Ref.value })) as any, { immediate: false });`,
+  ];
+}
+
 /**
  * Build the body of the exported connector function.
  */
@@ -255,6 +292,14 @@ function buildFunctionBody(resource: ResourceInfo): string {
   if (resource.updateEndpoint && resource.zodSchemas.update) {
     optionKeys.push('updateSchema');
   }
+  const hasMutations = !!(
+    resource.createEndpoint ||
+    resource.updateEndpoint ||
+    resource.deleteEndpoint
+  );
+  if (hasMutations) {
+    optionKeys.push('onRequest', 'onSuccess', 'onError', 'onFinish');
+  }
 
   const optionsDestructure =
     optionKeys.length > 0 ? `  const { ${optionKeys.join(', ')} } = options;\n` : '';
@@ -289,29 +334,36 @@ function buildFunctionBody(resource: ResourceInfo): string {
 
   if (resource.detailEndpoint) {
     const fn = toAsyncDataName(resource.detailEndpoint.operationId);
-    // Wrap the composable to map the generic idRef to the actual path param name.
-    // useDetailConnector passes a ref<id> and calls refresh() after updating it.
     const pathParam = resource.detailEndpoint.pathParams[0] ?? 'id';
+    subConnectors.push(...buildPathParamComposableLines('_detail', fn, pathParam));
     subConnectors.push(
-      `  const detail = useDetailConnector(`,
-      `    (idRef, opts) => ${fn}(computed(() => ({ ${pathParam}: idRef.value })) as any, opts),`,
-      `  ) as unknown as DetailConnectorReturn<${pascal}>;`
+      `  const detail = useDetailConnector((id: any) => { _detailRef.value = id; return _detailComposable; }) as unknown as DetailConnectorReturn<${pascal}>;`
     );
   }
 
   if (resource.createEndpoint) {
     const fn = toAsyncDataName(resource.createEndpoint.operationId);
-    const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
+    const inputType = resource.zodSchemas.create
+      ? `${pascal}CreateInput`
+      : `Record<string, unknown>`;
     const schemaArg = resource.zodSchemas.create
       ? `{ schema: ${pascal}CreateSchema, schemaOverride: createSchema }`
       : '{}';
-    subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
+    subConnectors.push(`  const _createRef = shallowRef({});`);
+    subConnectors.push(
+      `  const _createComposable = ${fn}(_createRef as any, { immediate: false, onRequest, onSuccess, onError, onFinish });`
+    );
+    subConnectors.push(
+      `  const createForm = useFormConnector((p: any) => { _createRef.value = p; return _createComposable; }, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`
+    );
   }
 
   if (resource.updateEndpoint) {
     const fn = toAsyncDataName(resource.updateEndpoint.operationId);
     const hasDetail = !!resource.detailEndpoint;
-    const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
+    const inputType = resource.zodSchemas.update
+      ? `${pascal}UpdateInput`
+      : `Record<string, unknown>`;
 
     let schemaArg = '{}';
     if (resource.zodSchemas.update && hasDetail) {
@@ -321,12 +373,35 @@ function buildFunctionBody(resource: ResourceInfo): string {
     } else if (hasDetail) {
       schemaArg = `{ loadWith: detail }`;
     }
-    subConnectors.push(`  const updateForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
+    subConnectors.push(`  const _updateRef = shallowRef({});`);
+    subConnectors.push(
+      `  const _updateComposable = ${fn}(_updateRef as any, { immediate: false, onRequest, onSuccess, onError, onFinish });`
+    );
+    subConnectors.push(
+      `  const updateForm = useFormConnector((p: any) => { _updateRef.value = p; return _updateComposable; }, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`
+    );
   }
 
   if (resource.deleteEndpoint) {
     const fn = toAsyncDataName(resource.deleteEndpoint.operationId);
-    subConnectors.push(`  const deleteAction = useDeleteConnector(${fn}) as unknown as DeleteConnectorReturn<${pascal}>;`);
+    const pathParam = resource.deleteEndpoint.pathParams[0];
+    if (pathParam) {
+      subConnectors.push(...buildPathParamComposableLines('_delete', fn, pathParam));
+      subConnectors.push(
+        `  const _deleteComposableWithHooks = ${fn}(computed(() => ({ ${pathParam}: _deleteRef.value })) as any, { immediate: false, onRequest, onSuccess, onError, onFinish });`
+      );
+      subConnectors.push(
+        `  const deleteAction = useDeleteConnector((item: any) => { _deleteRef.value = item?.${pathParam} ?? item?.id ?? item; return _deleteComposableWithHooks; }) as unknown as DeleteConnectorReturn<${pascal}>;`
+      );
+    } else {
+      subConnectors.push(`  const _deleteRef = shallowRef({});`);
+      subConnectors.push(
+        `  const _deleteComposable = ${fn}(_deleteRef as any, { immediate: false, onRequest, onSuccess, onError, onFinish });`
+      );
+      subConnectors.push(
+        `  const deleteAction = useDeleteConnector((p: any) => { _deleteRef.value = p; return _deleteComposable; }) as unknown as DeleteConnectorReturn<${pascal}>;`
+      );
+    }
   }
 
   // Return object — always includes table (undefined when no list + no factory)

package/src/generators/components/schema-analyzer/intent-detector.ts

@@ -49,16 +49,6 @@ function isArraySchema(schema: OpenApiPropertySchema): boolean {
   return schema.type === 'array' || schema.items !== undefined;
 }
 
-/** True when schema is a primitive scalar (string, number, integer, boolean) — not a resource */
-function isPrimitiveSchema(schema: OpenApiPropertySchema): boolean {
-  return (
-    schema.type === 'string' ||
-    schema.type === 'number' ||
-    schema.type === 'integer' ||
-    schema.type === 'boolean'
-  );
-}
-
 // ─── Request body schema ──────────────────────────────────────────────────────
 
 function getRequestBodySchema(operation: OpenApiOperation): OpenApiPropertySchema | undefined {
@@ -123,12 +113,6 @@ export function detectIntent(
         return 'list';
       }
 
-      // Primitive response (string, number, boolean) → not a CRUD resource
-      // e.g. GET /user/login returns a string token — not a list or detail
-      if (isPrimitiveSchema(responseSchema)) {
-        return 'unknown';
-      }
-
       // Object response — distinguish list vs detail by path structure:
       //   GET /pets/{id}  → has path param → detail (single item fetch)
       //   GET /pets       → no path param  → list (likely paginated envelope: { data: [], total: n })
@@ -178,6 +162,7 @@ export function extractEndpoints(
       intent,
       hasPathParams: pathParams.length > 0,
       pathParams,
+      hasQueryParams: (operation.parameters ?? []).some((p) => p.in === 'query'),
     };
 
     // Attach response schema for GET intents

package/src/generators/components/schema-analyzer/openapi-reader.ts

@@ -51,7 +51,20 @@ function resolveRefs(node: unknown, root: OpenApiSpec, visited = new Set<string>
     const resolved = resolvePointer(root, ref);
     const newVisited = new Set(visited);
     newVisited.add(ref);
-    return resolveRefs(resolved, root, newVisited);
+    const resolvedFull = resolveRefs(resolved, root, newVisited);
+
+    // Annotate resolved schemas from #/components/schemas/Xxx with the original
+    // component name so downstream consumers can recover the model type name.
+    if (
+      typeof resolvedFull === 'object' &&
+      resolvedFull !== null &&
+      ref.startsWith('#/components/schemas/')
+    ) {
+      const refName = ref.split('/').pop()!;
+      return { ...resolvedFull, 'x-ref-name': refName };
+    }
+
+    return resolvedFull;
   }
 
   const result: Record<string, unknown> = {};

package/src/generators/components/schema-analyzer/resource-grouper.ts

@@ -112,10 +112,19 @@ export function buildResourceMap(spec: OpenApiSpec): ResourceMap {
 
     const resourceName = pascalCase(tag);
 
+    // Infer the SDK model type name from the original $ref component name.
+    // Priority: detail response > list items > list response (may be envelope object).
+    const itemTypeName =
+      (detailEp?.responseSchema as any)?.['x-ref-name'] ??
+      (listEp?.responseSchema as any)?.items?.['x-ref-name'] ??
+      (listEp?.responseSchema as any)?.['x-ref-name'] ??
+      undefined;
+
     const info: ResourceInfo = {
       name: resourceName,
       tag,
       composableName: toConnectorName(tag),
+      itemTypeName,
       endpoints,
       listEndpoint: listEp,
       detailEndpoint: detailEp,

package/src/generators/components/schema-analyzer/schema-field-mapper.ts

@@ -167,7 +167,7 @@ function baseZodExpr(prop: OpenApiPropertySchema): string {
       return arrayZodExpr(prop);
 
     case 'object':
-      return objectZodExpr(prop);
+      return 'z.record(z.string(), z.unknown())';
 
     default:
       // $ref already resolved, unknown type → permissive
@@ -224,31 +224,6 @@ function numberZodExpr(prop: OpenApiPropertySchema): string {
   return expr;
 }
 
-function objectZodExpr(prop: OpenApiPropertySchema): string {
-  const { additionalProperties } = prop;
-
-  // additionalProperties: false or undefined → plain object
-  if (!additionalProperties || additionalProperties === true) {
-    return 'z.record(z.unknown())';
-  }
-
-  // additionalProperties has a known primitive type → typed record
-  const valueExpr = additionalPropsZodExpr(additionalProperties);
-  return `z.record(${valueExpr})`;
-}
-
-function additionalPropsZodExpr(schema: OpenApiPropertySchema): string {
-  switch (schema.type) {
-    case 'string':   return stringZodExpr(schema);
-    case 'integer':  return integerZodExpr(schema);
-    case 'number':   return numberZodExpr(schema);
-    case 'boolean':  return 'z.boolean()';
-    case 'array':    return arrayZodExpr(schema);
-    case 'object':   return objectZodExpr(schema);
-    default:         return 'z.unknown()';
-  }
-}
-
 function arrayZodExpr(prop: OpenApiPropertySchema): string {
   const itemExpr = prop.items ? baseZodExpr(prop.items) : 'z.unknown()';
   let expr = `z.array(${itemExpr})`;

package/src/generators/components/schema-analyzer/types.ts

@@ -33,6 +33,8 @@ export interface OpenApiPropertySchema {
   allOf?: OpenApiPropertySchema[];
   oneOf?: OpenApiPropertySchema[];
   anyOf?: OpenApiPropertySchema[];
+  /** Injected by the $ref resolver — original component schema name, e.g. 'Pet' */
+  'x-ref-name'?: string;
 }
 
 export interface OpenApiSchema extends OpenApiPropertySchema {
@@ -103,6 +105,8 @@ export interface EndpointInfo {
   responseSchema?: OpenApiSchema;
   hasPathParams: boolean;
   pathParams: string[];
+  /** True when the operation has at least one query parameter */
+  hasQueryParams: boolean;
 }
 
 // ─── Form field definition ───────────────────────────────────────────────────
@@ -154,6 +158,13 @@ export interface ResourceInfo {
   /** The one endpoint detected as delete (DELETE) */
   deleteEndpoint?: EndpointInfo;
 
+  /**
+   * Inferred item model type name (e.g. 'Pet', 'Order') derived from the
+   * response schema's original $ref component name. Used for SDK type imports.
+   * Undefined when the response type is anonymous/primitive.
+   */
+  itemTypeName?: string;
+
   /** Columns inferred from the list/detail response schema */
   columns: ColumnDef[];
 

package/src/generators/connectors/generator.ts

@@ -0,0 +1,137 @@
+import * as path from 'path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+import { format } from 'prettier';
+import { analyzeSpec } from '../components/schema-analyzer/index.js';
+import {
+  generateConnectorFile,
+  connectorFileName,
+  generateConnectorIndexFile,
+} from './templates.js';
+import type { ConnectorGeneratorOptions } from './types.js';
+import { type Logger, createClackLogger } from '../../cli/logger.js';
+
+// Runtime files that must be copied to the user's project
+const RUNTIME_FILES = [
+  'connector-types.ts',
+  'useGetAllConnector.ts',
+  'useGetConnector.ts',
+  'useCreateConnector.ts',
+  'useUpdateConnector.ts',
+  'useDeleteConnector.ts',
+  'zod-error-merger.ts',
+] as const;
+
+/**
+ * Format TypeScript source with Prettier.
+ * Falls back to unformatted code on error.
+ */
+async function formatCode(code: string, logger: Logger): Promise<string> {
+  try {
+    return await format(code, { parser: 'typescript' });
+  } catch (error) {
+    logger.log.warn(`Prettier formatting failed: ${String(error)}`);
+    return code;
+  }
+}
+
+/**
+ * Generate headless connector composables from an OpenAPI spec.
+ *
+ * Steps:
+ *  1. Analyze the spec → ResourceMap (Schema Analyzer)
+ *  2. For each resource: generate connector source, format, write
+ *  3. Write an index barrel file
+ *  4. Copy runtime helpers to the user's project
+ */
+export async function generateConnectors(
+  options: ConnectorGeneratorOptions,
+  logger: Logger = createClackLogger()
+): Promise<void> {
+  const spinner = logger.spinner();
+
+  const outputDir = path.resolve(options.outputDir);
+  const composablesRelDir = options.composablesRelDir ?? '../use-async-data';
+  const runtimeRelDir = options.runtimeRelDir ?? '../runtime';
+
+  // ── 1. Analyze spec ───────────────────────────────────────────────────────
+  spinner.start('Analyzing OpenAPI spec');
+  const resourceMap = analyzeSpec(options.inputSpec);
+  spinner.stop(`Found ${resourceMap.size} resource(s)`);
+
+  if (resourceMap.size === 0) {
+    logger.log.warn('No resources found in spec — nothing to generate');
+    return;
+  }
+
+  // ── 2. Prepare output directory ───────────────────────────────────────────
+  // emptyDir (not ensureDir) so stale connectors from previous runs are removed.
+  spinner.start('Preparing output directory');
+  await fs.emptyDir(outputDir);
+  spinner.stop('Output directory ready');
+
+  // ── 3. Generate connector files ───────────────────────────────────────────
+  spinner.start('Generating connector composables');
+  let successCount = 0;
+  let errorCount = 0;
+  const generatedNames: string[] = [];
+
+  for (const resource of resourceMap.values()) {
+    try {
+      const code = generateConnectorFile(resource, composablesRelDir, '../..', runtimeRelDir);
+      const formatted = await formatCode(code, logger);
+      const fileName = connectorFileName(resource.composableName);
+      const filePath = path.join(outputDir, fileName);
+
+      await fs.writeFile(filePath, formatted, 'utf-8');
+      generatedNames.push(resource.composableName);
+      successCount++;
+    } catch (error) {
+      logger.log.error(`Error generating ${resource.composableName}: ${String(error)}`);
+      errorCount++;
+    }
+  }
+
+  spinner.stop(`Generated ${successCount} connector(s)`);
+
+  // ── 4. Write barrel index ─────────────────────────────────────────────────
+  if (generatedNames.length > 0) {
+    try {
+      const indexCode = generateConnectorIndexFile(generatedNames);
+      const formattedIndex = await formatCode(indexCode, logger);
+      await fs.writeFile(path.join(outputDir, 'index.ts'), formattedIndex, 'utf-8');
+    } catch (error) {
+      logger.log.warn(`Could not write connector index: ${String(error)}`);
+    }
+  }
+
+  // ── 5. Copy runtime helpers ───────────────────────────────────────────────
+  // Runtime files live in src/ and must be physical .ts files in the user's project
+  // so Nuxt/Vite can type-check them.
+  //
+  // Path resolution trick:
+  //   •  During development (ts-node / tsx):  __dirname ≈ src/generators/connectors/
+  //   •  After `tsc` build:                   __dirname ≈ dist/generators/connectors/
+  //
+  // In both cases we step up 3 levels and re-enter src/ to find the runtime sources.
+  spinner.start('Copying runtime files');
+  const runtimeDir = path.resolve(outputDir, runtimeRelDir);
+  await fs.ensureDir(runtimeDir); // ensureDir — other runtime files may live here too
+
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const runtimeSrcDir = path.resolve(__dirname, '../../../src/generators/connectors/runtime');
+
+  for (const file of RUNTIME_FILES) {
+    const src = path.join(runtimeSrcDir, file);
+    const dest = path.join(runtimeDir, file);
+    await fs.copyFile(src, dest);
+  }
+
+  spinner.stop('Runtime files copied');
+
+  // ── 6. Summary ────────────────────────────────────────────────────────────
+  if (errorCount > 0) {
+    logger.log.warn(`Completed with ${errorCount} error(s)`);
+  }
+  logger.log.success(`Generated ${successCount} connector(s) in ${outputDir}`);
+}