nuxt-feathers-zod 0.1.0 → 0.2.1

package/README.md

@@ -278,6 +278,147 @@ Notes:
 
 The runtime auth bootstrap (`src/runtime/plugins/feathers-auth.ts`) re-authenticates **client-side only** to avoid SSR startup failures when the Feathers client is not yet injected.
 
+
+C’est appliqué au dépôt (zip monté), en respectant exactement l’ordre que vous avez demandé.
+
+Voici ce qui a été ajouté / modifié dans **nuxt-feathers-zod-main** :
+
+## 1) CLI Bun: `bunx nuxt-feathers-zod …`
+
+### Ajouts
+
+* `bin/nuxt-feathers-zod` (exécutable, shebang Bun)
+* `src/cli/index.ts` (implémentation complète de la CLI)
+
+### package.json
+
+* Ajout de :
+
+  * `"bin": { "nuxt-feathers-zod": "bin/nuxt-feathers-zod" }`
+  * `"files": ["dist", "bin", "src/cli"]` pour que la CLI soit bien publiée
+  * `"test": "vitest run"` (smoke tests)
+
+## 2) Commande `add service` (4 fichiers) + smoke tests
+
+### Commande
+
+```bash
+bunx nuxt-feathers-zod add service <serviceName> [--adapter mongodb|memory] [--auth] [--servicesDir <dir>] [--dry] [--force]
+```
+
+### Génération
+
+Crée automatiquement :
+
+* `services/<name>/<name>.schema.ts`
+* `services/<name>/<name>.class.ts`
+* `services/<name>/<name>.shared.ts`
+* `services/<name>/<name>.ts`
+
+Aligné sur le style déjà présent dans le repo :
+
+* Zod + `getZodValidator(...)`
+* `zodQuerySyntax(schema)`
+* `schemaHooks.validateQuery/validateData + resolveQuery/resolveData`
+* `--auth` ajoute `authenticate('jwt')` sur `find/get/patch/remove` (create reste ouvert)
+
+`--adapter mongodb` génère un `_id` ObjectId (regex 24 hex) comme le service `mongos` existant.
+`--adapter memory` génère un `id: z.number().int()` comme `messages`.
+
+Smoke test ajouté : `test/cli.spec.ts` (vérifie service + middleware).
+
+## 3) Commande `add middleware` (Nitro)
+
+### Commande
+
+```bash
+bunx nuxt-feathers-zod add middleware <name> [--target nitro|feathers] [--dry] [--force]
+```
+
+Par défaut (`--target nitro`) :
+
+* crée `server/middleware/<name>.ts` avec un template `defineEventHandler(...)`.
+
+## 4) `--target feathers` (plugin Feathers côté serveur)
+
+Si vous faites :
+
+```bash
+bunx nuxt-feathers-zod add middleware dummy --target feathers
+```
+
+Génère :
+
+* `server/feathers/dummy.ts`
+
+Template basé sur le pattern existant `playground/server/feathers/dummy.ts` :
+
+* `defineFeathersServerPlugin((app) => app.hooks({ setup: [...] }))`
+
+## 5) Options ajoutées
+
+* `--adapter mongodb|memory`
+* `--auth`
+* `--dry`
+* `--force`
+* `--servicesDir <dir>`
+* `--target nitro|feathers`
+
+
+## Changements du 25 janvier 2026
+
+### 1) `add service` : nouvelles options ROI
+
+La commande supporte désormais :
+
+```bash
+bunx nuxt-feathers-zod add service <serviceName> \
+  [--idField id|_id] \
+  [--path <customPath>] \
+  [--docs] \
+  [--adapter mongodb|memory] \
+  [--auth] \
+  [--servicesDir <dir>] \
+  [--dry] \
+  [--force]
+```
+
+#### `--idField id|_id`
+
+* Détermine le champ d’identifiant dans le schéma Zod généré.
+* Compatible avec `mongodb` (ObjectId en string 24 hex) et `memory` (number int).
+* Défauts :
+
+  * `mongodb` → `_id`
+  * `memory` → `id`
+
+#### `--path <customPath>`
+
+* Découple le **dossier service** du **path Feathers exposé**.
+* Normalise automatiquement les `/` de tête/fin (ex: `/accounts/` → `accounts`).
+* Impacte : `*.shared.ts` (path const), et donc tous les usages de `service(path)`.
+
+#### `--docs`
+
+* Injecte un bloc `docs:` (Swagger legacy) dans le `app.use(...)`.
+* Ajoute `securities: ['jwt']` si `--auth` est activé.
+
+### 2) Tests smoke mis à jour
+
+* Ajout d’un test couvrant `--path`, `--idField`, `--docs`.
+
+---
+
+## Exemple rapide (valide)
+
+```bash
+bunx nuxt-feathers-zod add service users --adapter mongodb --auth --idField id --path accounts --docs
+```
+
+Génère `services/users/*` mais expose le service sur `accounts` avec schéma `id: objectIdSchema()` + bloc `docs:`.
+
+
+
 ## License
 
 MIT

package/bin/nuxt-feathers-zod

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { runCli } from '../src/cli/index.ts'
+
+await runCli(process.argv.slice(2), { cwd: process.cwd() })

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^4.0.0"
   },
-  "version": "0.1.0",
+  "version": "0.2.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { defineNuxtModule, createResolver, addImportsDir, addTemplate, addServerPlugin, addImports, addPlugin, hasNuxtModule, installModule } from '@nuxt/kit';
 import { consola } from 'consola';
 import defu from 'defu';
+import { createRequire } from 'node:module';
 import { resolveOptions, resolveRuntimeConfig, resolvePublicRuntimeConfig } from '../dist/runtime/options/index.js';
 import { serverDefaults } from '../dist/runtime/options/server.js';
 import { getServicesImports, addServicesImports } from '../dist/runtime/services.js';
@@ -64,11 +65,22 @@ const module$1 = defineNuxtModule({
       extendDefaults: true
     },
     loadFeathersConfig: false,
-    auth: true
+    auth: true,
+    swagger: false
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     const resolvedOptions = await resolveOptions(options, nuxt);
+    if (resolvedOptions.swagger) {
+      const require = createRequire(import.meta.url);
+      try {
+        require.resolve("feathers-swagger", { paths: [nuxt.options.rootDir] });
+      } catch {
+        consola.warn(
+          "feathers.swagger is enabled but 'feathers-swagger' could not be resolved from this Nuxt project. Install it in your app (root) dependencies: bun add feathers-swagger swagger-ui-dist"
+        );
+      }
+    }
     nuxt.options.runtimeConfig._feathers = resolveRuntimeConfig(resolvedOptions);
     nuxt.options.runtimeConfig.public._feathers = resolvePublicRuntimeConfig(resolvedOptions);
     const servicesImports = await getServicesImports(resolvedOptions.servicesDirs);

package/dist/runtime/options/index.d.ts

@@ -7,6 +7,7 @@ import type { ResolvedServerOptions, ServerOptions } from './server.js';
 import type { ServicesDir, ServicesDirs } from './services.js';
 import type { ResolvedTransportsOptions, TransportsOptions } from './transports/index.js';
 import type { ResolvedValidatorOptions, ValidatorOptions } from './validator.js';
+import type { ResolvedSwaggerOptionsOrDisabled, SwaggerOptionsOrDisabled } from './swagger.js';
 export interface ModuleOptions {
     transports: TransportsOptions;
     database: DataBaseOptions;
@@ -16,6 +17,7 @@ export interface ModuleOptions {
     client: ClientOptions | boolean;
     validator: ValidatorOptions;
     loadFeathersConfig: boolean;
+    swagger?: SwaggerOptionsOrDisabled;
 }
 export interface ResolvedOptions {
     templateDir: string;
@@ -27,6 +29,7 @@ export interface ResolvedOptions {
     client: ResolvedClientOptionsOrDisabled;
     validator: ResolvedValidatorOptions;
     loadFeathersConfig: boolean;
+    swagger?: ResolvedSwaggerOptionsOrDisabled;
 }
 export interface FeathersRuntimeConfig {
     auth?: ResolvedAuthOptions;

package/dist/runtime/options/index.js

@@ -7,6 +7,7 @@ import { resolveServerOptions } from "./server.js";
 import { resolveServicesDirs } from "./services.js";
 import { resolveTransportsOptions } from "./transports/index.js";
 import { resolveValidatorOptions } from "./validator.js";
+import { resolveSwaggerOptions } from "./swagger.js";
 export async function resolveOptions(options, nuxt) {
   const { rootDir, srcDir, serverDir, appDir, buildDir, ssr } = nuxt.options;
   const resolver = createResolver(import.meta.url);
@@ -17,6 +18,7 @@ export async function resolveOptions(options, nuxt) {
   const server = await resolveServerOptions(options.server, rootDir, serverDir);
   const client = await resolveClientOptions(options.client, !!database.mongo, rootDir, srcDir);
   const validator = resolveValidatorOptions(options.validator);
+  const swagger = resolveSwaggerOptions(options.swagger, transports);
   const servicesImports = await getServicesImports(servicesDirs);
   const auth = resolveAuthOptions(options.auth, !!client, servicesImports, appDir);
   const loadFeathersConfig = options.loadFeathersConfig;
@@ -29,7 +31,8 @@ export async function resolveOptions(options, nuxt) {
     client,
     validator,
     auth,
-    loadFeathersConfig
+    loadFeathersConfig,
+    swagger
   };
   console.dir(resolvedOptions, { depth: null });
   return resolvedOptions;

package/dist/runtime/options/swagger.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedTransportsOptions } from './transports/index.js';
+export interface SwaggerOptions {
+    /**
+     * Enable Swagger/OpenAPI documentation generation via feathers-swagger (legacy).
+     * When `true`, defaults are applied.
+     */
+    enabled?: boolean;
+    /** Swagger UI base path (e.g. /docs) */
+    docsPath?: string;
+    /** OpenAPI JSON path (e.g. /docs.json) */
+    docsJsonPath?: string;
+    /** OpenAPI version (2 or 3). Default: 3 */
+    openApiVersion?: 2 | 3;
+    /** OpenAPI info */
+    info?: {
+        title: string;
+        description?: string;
+        version: string;
+    };
+}
+export type SwaggerOptionsOrDisabled = SwaggerOptions | boolean;
+export interface ResolvedSwaggerOptions {
+    enabled: true;
+    docsPath: string;
+    docsJsonPath: string;
+    openApiVersion: 2 | 3;
+    info: {
+        title: string;
+        description?: string;
+        version: string;
+    };
+}
+export type ResolvedSwaggerOptionsOrDisabled = ResolvedSwaggerOptions | false;
+export declare function resolveSwaggerOptions(options: SwaggerOptionsOrDisabled | undefined, transports: ResolvedTransportsOptions): ResolvedSwaggerOptionsOrDisabled;

package/dist/runtime/options/swagger.js

@@ -0,0 +1,16 @@
+export function resolveSwaggerOptions(options, transports) {
+  if (options == null || options === false)
+    return false;
+  if (options === true)
+    options = {};
+  const enabled = options.enabled ?? true;
+  if (!enabled)
+    return false;
+  return {
+    enabled: true,
+    docsPath: options.docsPath || "/docs",
+    docsJsonPath: options.docsJsonPath || "/docs.json",
+    openApiVersion: options.openApiVersion || 3,
+    info: options.info || { title: "API Docs", version: "1.0.0" }
+  };
+}

package/dist/runtime/templates/server/plugin.js

@@ -26,6 +26,46 @@ export function getServerPluginContents(options) {
     const authService = options?.auth?.service;
     const restPath = transports?.rest?.path;
     const websocketPath = transports?.websocket?.path;
+    const swaggerEnabled = !!options.swagger;
+    const swagger = options.swagger;
+    const normalizePath = (p) => {
+      if (!p)
+        return "";
+      return p.startsWith("/") ? p : `/${p}`;
+    };
+    const trimTrailingSlash = (p) => {
+      if (!p)
+        return "";
+      return p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p;
+    };
+    const docsPath = trimTrailingSlash(normalizePath(swagger?.docsPath ?? "/docs"));
+    const docsPathSlash = `${docsPath}/`;
+    const docsJsonPath = trimTrailingSlash(normalizePath(swagger?.docsJsonPath ?? "/docs.json"));
+    const swaggerInitBlock = swaggerEnabled ? `  // Init Swagger (feathers-swagger legacy)
+  
+
+  app.configure(swagger.customMethodsHandler)
+  app.configure(swagger({
+    docsPath: '${docsPath}',
+    docsJsonPath: '/swagger.json',
+    specs: {
+      info: ${JSON.stringify(swagger?.info ?? { title: "API Docs", description: "Feathers API", version: "1.0.0" })},
+      components: {
+        securitySchemes: {
+          BearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+          },
+        },
+      },
+      security: [
+        { BearerAuth: [] },
+      ],
+    },
+    ui: swagger.swaggerUI({ docsPath: '${docsPath}' }),
+  }))
+` : "";
     return `// ! Generated by nuxt-feathers-zod - do not change manually
 import type { NitroApp } from 'nitropack'
 import type { Application } from './server.js'
@@ -36,6 +76,7 @@ ${puts([
       [exp, `import feathersExpress, { json, rest, urlencoded } from '@feathersjs/express'`],
       [sio, `import socketio from '@feathersjs/socketio'`]
     ])}
+${put(swaggerEnabled, `import swagger from 'feathers-swagger'`)}
 ${put(rest, `import { ${framework}ErrorHandler } from '@gabortorma/feathers-nitro-adapter/handlers'`)}
 ${put(auth, `import authentication from './authentication.js'`)}
 import { ${routers.join(", ")} } from '@gabortorma/feathers-nitro-adapter/routers'
@@ -52,6 +93,7 @@ export default defineNitroPlugin((nitroApp: NitroApp) => {
 ${put(options.loadFeathersConfig, `
   app.configure(configuration())
 `)}
+${put(swaggerEnabled, swaggerInitBlock)}
   // Add nitroApp to feathers app
   app.nitroApp = nitroApp;
 ${put(rest, `${put(koa, `
@@ -70,6 +112,7 @@ ${put(exp, `  // Set up Express middleware
     },
   }`)}))  
 `)}`)}
+
   // Init socket.io server for real-time functionality
   app.set('websocket', ${!!sio})${put(sio, `
   app.configure(socketio({ 
@@ -83,11 +126,13 @@ ${put(exp, `  // Set up Express middleware
   ${put(mongo, `// Init mongodb
   app.configure(mongodb)
 `)}
+
   // Init services
   ${services.map((service) => `app.configure(${service.meta.importId})`).join("\n  ")}
 
   // Init plugins
   ${plugins.map((plugin) => `app.configure(${plugin.meta.importId})`).join("\n  ")}
+
 ${put(exp, `
   // Set up Express middleware for 404s and the error handler
   app.configure(expressErrorHandler)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-feathers-zod",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "packageManager": "bun@1.3.6",
   "description": "Feathers API integration for Nuxt",
   "author": "Herve de CHAVIGNY",
@@ -21,15 +21,28 @@
     "./query": "./dist/runtime/zod/query.js",
     "./format": "./dist/runtime/zod/format.js"
   },
+  "bin": {
+    "nuxt-feathers-zod": "bin/nuxt-feathers-zod"
+  },
   "main": "./dist/module.mjs",
   "typesVersions": {
     "*": {
-      ".": ["./dist/types.d.mts"],
-      "options": ["./dist/runtime/options/index.d.mts"],
-      "ofetch-adapter": ["./dist/runtime/adapters/ofetch.d.mts"]
+      ".": [
+        "./dist/types.d.mts"
+      ],
+      "options": [
+        "./dist/runtime/options/index.d.mts"
+      ],
+      "ofetch-adapter": [
+        "./dist/runtime/adapters/ofetch.d.mts"
+      ]
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "bin",
+    "src/cli"
+  ],
   "scripts": {
     "prepack": "nuxt-module-build build",
     "dev": "nuxi dev playground",
@@ -48,7 +61,7 @@
   },
   "dependencies": {
     "@feathersjs/adapter-commons": "latest",
-    "@feathersjs/authentication": "latest",
+    "@feathersjs/authentication": "5.0.37",
     "@feathersjs/authentication-client": "latest",
     "@feathersjs/authentication-local": "latest",
     "@feathersjs/configuration": "latest",
@@ -96,16 +109,5 @@
     "vitest-mongodb": "latest",
     "vue": "latest",
     "vue-router": "latest"
-  },
-  "overrides": {
-    "@feathersjs/authentication": "5.0.37",
-    "@feathersjs/authentication-client": "5.0.37",
-    "@feathersjs/authentication-local": "5.0.37",
-    "@feathersjs/errors": "5.0.37",
-    "@feathersjs/feathers": "5.0.37",
-    "@feathersjs/koa": "5.0.37",
-    "@feathersjs/rest-client": "5.0.37",
-    "@feathersjs/schema": "5.0.37",
-    "@feathersjs/socketio-client": "5.0.37"
   }
 }

package/src/cli/index.ts

@@ -0,0 +1,619 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+import { kebabCase, pascalCase } from 'change-case'
+import consola from 'consola'
+
+type Adapter = 'mongodb' | 'memory'
+type MiddlewareTarget = 'nitro' | 'feathers'
+type IdField = 'id' | '_id'
+type CollectionName = string
+
+export type RunCliOptions = {
+  cwd: string
+}
+
+export async function runCli(argv: string[], opts: RunCliOptions) {
+  const cwd = resolve(opts.cwd)
+
+  const [cmd, subcmd, name, ...rest] = argv
+
+  if (!cmd || cmd === '-h' || cmd === '--help') {
+    printHelp()
+    process.exit(0)
+  }
+
+  // Expected:
+  // nuxt-feathers-zod add service <name> [...]
+  // nuxt-feathers-zod add middleware <name> [...]
+  if (cmd !== 'add') {
+    consola.error(`Unknown command: ${cmd}`)
+    printHelp()
+    process.exit(1)
+  }
+
+  if (subcmd !== 'service' && subcmd !== 'middleware') {
+    consola.error(`Unknown add target: ${subcmd ?? '(missing)'}`)
+    printHelp()
+    process.exit(1)
+  }
+
+  if (!name) {
+    consola.error('Missing <name>.')
+    printHelp()
+    process.exit(1)
+  }
+
+  const flags = parseFlags(rest)
+
+  if (subcmd === 'service') {
+    const adapter = (flags.adapter as Adapter | undefined) ?? 'mongodb'
+    const auth = Boolean(flags.auth)
+    const idField = (flags.idField as IdField | undefined) ?? (adapter === 'mongodb' ? '_id' : 'id')
+    const servicePath = typeof flags.path === 'string' ? String(flags.path) : undefined
+    const collectionName = typeof flags.collection === 'string' ? String(flags.collection) : undefined
+    const docs = Boolean(flags.docs)
+    const dry = Boolean(flags.dry)
+    const force = Boolean(flags.force)
+
+    const projectRoot = await findProjectRoot(cwd)
+    const servicesDir = resolve(projectRoot, flags.servicesDir ?? 'services')
+
+    await generateService({
+      projectRoot,
+      servicesDir,
+      name,
+      adapter,
+      auth,
+      idField,
+      servicePath,
+      collectionName,
+      docs,
+      dry,
+      force,
+    })
+    return
+  }
+
+  if (subcmd === 'middleware') {
+    const target = (flags.target as MiddlewareTarget | undefined) ?? 'nitro'
+    const dry = Boolean(flags.dry)
+    const force = Boolean(flags.force)
+
+    const projectRoot = await findProjectRoot(cwd)
+
+    await generateMiddleware({
+      projectRoot,
+      name,
+      target,
+      dry,
+      force,
+    })
+  }
+}
+
+function printHelp() {
+  // Keep output short; this is a CLI entrypoint.
+  // eslint-disable-next-line no-console
+  console.log(`\nnuxt-feathers-zod CLI\n\nUsage:\n  nuxt-feathers-zod add service <serviceName> [--adapter mongodb|memory] [--auth] [--idField id|_id] [--path <customPath>] [--collection <mongoCollection>] [--docs] [--servicesDir <dir>] [--dry] [--force]\n  nuxt-feathers-zod add middleware <name> [--target nitro|feathers] [--dry] [--force]\n\nExamples:\n  bunx nuxt-feathers-zod add service posts --adapter mongodb --auth\n  bunx nuxt-feathers-zod add service users --adapter mongodb --idField _id --path accounts --docs\n  bunx nuxt-feathers-zod add service haproxy-domains --path haproxy/domains --collection haproxy-domains --auth --docs\n  bunx nuxt-feathers-zod add middleware session\n  bunx nuxt-feathers-zod add middleware dummy --target feathers\n`)
+}
+
+function parseFlags(argv: string[]) {
+  const out: Record<string, string | boolean> = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a) continue
+    if (!a.startsWith('--')) continue
+    const key = a.slice(2)
+    const next = argv[i + 1]
+    if (!next || next.startsWith('--')) {
+      out[key] = true
+      continue
+    }
+    out[key] = next
+    i++
+  }
+  return out
+}
+
+async function findProjectRoot(start: string) {
+  // Walk up until we find a package.json.
+  let dir = resolve(start)
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir
+    const parent = resolve(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error(`Could not find project root from ${start}`)
+}
+
+function singularize(input: string) {
+  // Minimal heuristic (good enough for a DX helper; users can rename if needed)
+  if (input.endsWith('ies')) return `${input.slice(0, -3)}y`
+  if (input.endsWith('ses')) return input.slice(0, -2)
+  if (input.endsWith('s') && input.length > 1) return input.slice(0, -1)
+  return input
+}
+
+function normalizeServiceName(raw: string) {
+  // Allow "posts", "haproxy-domains", "traefik_stacks" etc.
+  return kebabCase(raw)
+}
+
+function normalizeServicePath(raw: string) {
+  // Feathers service paths are usually kebab-case and can include slashes.
+  // We keep user intent, but normalize leading/trailing slashes.
+  const cleaned = String(raw).trim().replace(/^\/+/, '').replace(/\/+$/, '')
+  if (!cleaned) throw new Error('Invalid --path: path cannot be empty')
+  return cleaned
+}
+
+function normalizeCollectionName(raw: string) {
+  // MongoDB collection names are strings, but in practice should not include path separators.
+  // We keep it permissive while preventing common foot-guns.
+  const cleaned = String(raw).trim()
+  if (!cleaned) throw new Error('Invalid --collection: collection name cannot be empty')
+  if (cleaned.includes('/') || cleaned.includes('\\')) {
+    throw new Error('Invalid --collection: collection name must not include \/ or \\')
+  }
+  if (cleaned.includes('\u0000')) {
+    throw new Error('Invalid --collection: collection name must not include null characters')
+  }
+  return cleaned
+}
+
+function createServiceIds(serviceNameKebab: string) {
+  const baseKebab = singularize(serviceNameKebab)
+  const basePascal = pascalCase(baseKebab)
+  const baseCamel = basePascal.charAt(0).toLowerCase() + basePascal.slice(1)
+
+  return {
+    serviceNameKebab,
+    baseKebab,
+    basePascal,
+    baseCamel,
+  }
+}
+
+type GenerateServiceOptions = {
+  projectRoot: string
+  servicesDir: string
+  name: string
+  adapter: Adapter
+  auth: boolean
+  idField: IdField
+  servicePath?: string
+  collectionName?: CollectionName
+  docs: boolean
+  dry: boolean
+  force: boolean
+}
+
+export async function generateService(opts: GenerateServiceOptions) {
+  const serviceNameKebab = normalizeServiceName(opts.name)
+  const ids = createServiceIds(serviceNameKebab)
+
+  const servicePath = normalizeServicePath(opts.servicePath ?? serviceNameKebab)
+  const collectionName = normalizeCollectionName(
+    opts.collectionName
+      ?? (servicePath.includes('/') ? serviceNameKebab : servicePath),
+  )
+
+  const dir = join(opts.servicesDir, serviceNameKebab)
+  const schemaFile = join(dir, `${serviceNameKebab}.schema.ts`)
+  const classFile = join(dir, `${serviceNameKebab}.class.ts`)
+  const sharedFile = join(dir, `${serviceNameKebab}.shared.ts`)
+  const serviceFile = join(dir, `${serviceNameKebab}.ts`)
+
+  const files: Array<{ path: string; content: string }> = [
+    { path: schemaFile, content: renderSchema(ids, opts.adapter, opts.idField) },
+    { path: classFile, content: renderClass(ids, opts.adapter, collectionName) },
+    { path: sharedFile, content: renderShared(ids, servicePath) },
+    { path: serviceFile, content: renderService(ids, opts.auth, opts.docs) },
+  ]
+
+  await ensureDir(dir, opts.dry)
+
+  for (const f of files) {
+    await writeFileSafe(f.path, f.content, { dry: opts.dry, force: opts.force })
+  }
+
+  if (opts.docs) {
+    await ensureFeathersSwaggerSupport(opts.projectRoot, { dry: opts.dry, force: opts.force })
+  }
+
+  if (!opts.dry) {
+    consola.success(`Generated service '${serviceNameKebab}' in ${relativeToCwd(dir)}`)
+  }
+}
+
+async function ensureFeathersSwaggerSupport(projectRoot: string, io: { dry: boolean; force: boolean }) {
+  // 1) Ensure TS sees `ServiceOptions.docs` (required for feathers-swagger in TS projects)
+  const typesDir = join(projectRoot, 'types')
+  const typesFile = join(typesDir, 'feathers-swagger.d.ts')
+  const typesContent = `// Auto-generated by nuxt-feathers-zod CLI (required when using feathers-swagger in TypeScript)\n\nimport type { ServiceSwaggerOptions } from 'feathers-swagger'\n\ndeclare module '@feathersjs/feathers' {\n  interface ServiceOptions {\n    docs?: ServiceSwaggerOptions\n  }\n}\n`
+
+  await ensureDir(typesDir, io.dry)
+  await writeFileSafe(typesFile, typesContent, { dry: io.dry, force: io.force })
+
+  // 2) Best-effort dependency hint (we do not auto-install dependencies)
+  try {
+    const pkgPath = join(projectRoot, 'package.json')
+    if (!existsSync(pkgPath)) return
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8')) as any
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+    if (!deps['feathers-swagger']) {
+      consola.warn(
+        `--docs was used but 'feathers-swagger' is not listed in package.json. Install it (and swagger UI deps if needed): bun add feathers-swagger swagger-ui-dist`,
+      )
+    }
+  }
+  catch {
+    // ignore
+  }
+}
+
+type GenerateMiddlewareOptions = {
+  projectRoot: string
+  name: string
+  target: MiddlewareTarget
+  dry: boolean
+  force: boolean
+}
+
+export async function generateMiddleware(opts: GenerateMiddlewareOptions) {
+  const fileBase = kebabCase(opts.name)
+
+  if (opts.target === 'nitro') {
+    const dir = join(opts.projectRoot, 'server', 'middleware')
+    const file = join(dir, `${fileBase}.ts`)
+    await ensureDir(dir, opts.dry)
+    await writeFileSafe(file, renderNitroMiddleware(fileBase), { dry: opts.dry, force: opts.force })
+    if (!opts.dry) consola.success(`Generated Nitro middleware '${fileBase}' in ${relativeToCwd(file)}`)
+    return
+  }
+
+  // feathers target: generate a server plugin under server/feathers
+  const dir = join(opts.projectRoot, 'server', 'feathers')
+  const file = join(dir, `${fileBase}.ts`)
+  await ensureDir(dir, opts.dry)
+  await writeFileSafe(file, renderFeathersPlugin(fileBase), { dry: opts.dry, force: opts.force })
+  if (!opts.dry) consola.success(`Generated Feathers server plugin '${fileBase}' in ${relativeToCwd(file)}`)
+}
+
+async function ensureDir(dir: string, dry: boolean) {
+  if (dry) return
+  await mkdir(dir, { recursive: true })
+}
+
+async function writeFileSafe(path: string, content: string, opts: { dry: boolean; force: boolean }) {
+  if (!opts.force && existsSync(path)) {
+    throw new Error(`File already exists: ${path} (use --force to overwrite)`)
+  }
+
+  if (opts.dry) {
+    consola.info(`[dry] write ${relativeToCwd(path)}`)
+    return
+  }
+
+  await writeFile(path, content, 'utf8')
+}
+
+function relativeToCwd(p: string) {
+  try {
+    return p.replace(resolve(process.cwd()) + '/', '')
+  }
+  catch {
+    return p
+  }
+}
+
+function renderSchema(ids: ReturnType<typeof createServiceIds>, adapter: Adapter, idField: IdField) {
+  const base = ids.baseCamel
+  const Base = ids.basePascal
+  const serviceClass = `${Base}Service`
+
+  const idSchemaField = idField
+  const idSchema = adapter === 'mongodb'
+    ? `
+const objectIdRegex = /^[0-9a-f]{24}$/i
+export const objectIdSchema = () => z.string().regex(objectIdRegex, 'Invalid ObjectId')
+`
+    : ''
+
+  const mainSchema = adapter === 'mongodb'
+    ? `export const ${base}Schema = z.object({
+  ${idSchemaField}: objectIdSchema(),
+  text: z.string(),
+})`
+    : `export const ${base}Schema = z.object({
+  ${idSchemaField}: z.number().int(),
+  text: z.string(),
+})`
+
+  const pickCreate = adapter === 'mongodb'
+    ? `{ text: true }`
+    : `{ text: true }`
+
+  return `// For more information about this file see https://dove.feathersjs.com/guides/cli/service.schemas.html
+
+import type { HookContext } from 'nuxt-feathers-zod/server'
+import type { ${serviceClass} } from './${ids.serviceNameKebab}.class'
+import { resolve } from '@feathersjs/schema'
+import { zodQuerySyntax } from 'nuxt-feathers-zod/query'
+import { getZodValidator } from 'nuxt-feathers-zod/validators'
+import { z } from 'zod'
+${idSchema}
+
+// Main data model schema
+${mainSchema}
+export type ${Base} = z.infer<typeof ${base}Schema>
+export const ${base}Validator = getZodValidator(${base}Schema, { kind: 'data' })
+export const ${base}Resolver = resolve<${Base}, HookContext<${serviceClass}>>({})
+
+export const ${base}ExternalResolver = resolve<${Base}, HookContext<${serviceClass}>>({})
+
+// Schema for creating new entries
+export const ${base}DataSchema = ${base}Schema.pick(${pickCreate})
+export type ${Base}Data = z.infer<typeof ${base}DataSchema>
+export const ${base}DataValidator = getZodValidator(${base}DataSchema, { kind: 'data' })
+export const ${base}DataResolver = resolve<${Base}, HookContext<${serviceClass}>>({})
+
+// Schema for updating existing entries
+export const ${base}PatchSchema = ${base}Schema.partial()
+export type ${Base}Patch = z.infer<typeof ${base}PatchSchema>
+export const ${base}PatchValidator = getZodValidator(${base}PatchSchema, { kind: 'data' })
+export const ${base}PatchResolver = resolve<${Base}, HookContext<${serviceClass}>>({})
+
+// Schema for allowed query properties
+export const ${base}QuerySchema = zodQuerySyntax(${base}Schema)
+export type ${Base}Query = z.infer<typeof ${base}QuerySchema>
+export const ${base}QueryValidator = getZodValidator(${base}QuerySchema, { kind: 'query' })
+export const ${base}QueryResolver = resolve<${Base}Query, HookContext<${serviceClass}>>({})
+`
+}
+
+function renderClass(ids: ReturnType<typeof createServiceIds>, adapter: Adapter, collectionName: string) {
+  const Base = ids.basePascal
+  const serviceName = ids.serviceNameKebab
+  const serviceClass = `${Base}Service`
+  const paramsName = `${Base}Params`
+
+  if (adapter === 'memory') {
+    return `// For more information about this file see https://dove.feathersjs.com/guides/cli/service.class.html#custom-services
+
+import type { Params } from '@feathersjs/feathers'
+import type { MemoryServiceOptions } from '@feathersjs/memory'
+import type { Application } from 'nuxt-feathers-zod/server'
+import type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query } from './${serviceName}.schema'
+import { MemoryService } from '@feathersjs/memory'
+
+export type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query }
+
+export interface ${paramsName} extends Params<${Base}Query> {}
+
+export class ${serviceClass}<ServiceParams extends Params = ${paramsName}> extends MemoryService<
+  ${Base},
+  ${Base}Data
+> {}
+
+export function getOptions(app: Application): MemoryServiceOptions<${Base}> {
+  return {
+    multi: true,
+  }
+}
+`
+  }
+
+  // mongodb
+  return `// For more information about this file see https://dove.feathersjs.com/guides/cli/service.class.html#database-services
+
+import type { Params } from '@feathersjs/feathers'
+import type { MongoDBAdapterOptions, MongoDBAdapterParams } from '@feathersjs/mongodb'
+import type { Application } from 'nuxt-feathers-zod/server'
+import type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query } from './${serviceName}.schema'
+import { MongoDBService } from '@feathersjs/mongodb'
+
+export type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query }
+
+export interface ${paramsName} extends MongoDBAdapterParams<${Base}Query> {}
+
+export class ${serviceClass}<ServiceParams extends Params = ${paramsName}> extends MongoDBService<
+  ${Base},
+  ${Base}Data,
+  ${paramsName},
+  ${Base}Patch
+> {}
+
+export function getOptions(app: Application): MongoDBAdapterOptions {
+  const mongoClient = app.get('mongodbClient')
+  return {
+    paginate: {
+      default: 10,
+      max: 100,
+    },
+    multi: true,
+    Model: mongoClient.then(db => db.collection('${collectionName}')),
+  }
+}
+`
+}
+
+function renderShared(ids: ReturnType<typeof createServiceIds>, servicePath: string) {
+  const base = ids.baseCamel
+  const Base = ids.basePascal
+  const serviceName = ids.serviceNameKebab
+  const serviceClass = `${Base}Service`
+  const methodsConst = `${base}Methods`
+  const pathConst = `${base}Path`
+  const clientFn = `${base}Client`
+  const clientServiceType = `${Base}ClientService`
+
+  return `// For more information about this file see https://dove.feathersjs.com/guides/cli/service.shared.html
+
+import type { Params } from '@feathersjs/feathers'
+import type { ClientApplication } from 'nuxt-feathers-zod/client'
+import type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query, ${serviceClass} } from './${serviceName}.class'
+
+export type { ${Base}, ${Base}Data, ${Base}Patch, ${Base}Query }
+
+export type ${clientServiceType} = Pick<${serviceClass}<Params<${Base}Query>>, (typeof ${methodsConst})[number]>
+
+export const ${pathConst} = '${servicePath}'
+
+export const ${methodsConst}: Array<keyof ${serviceClass}> = ['find', 'get', 'create', 'patch', 'remove']
+
+export function ${clientFn}(client: ClientApplication) {
+  const connection = client.get('connection')
+
+  client.use(${pathConst}, connection.service(${pathConst}), {
+    methods: ${methodsConst},
+  })
+}
+
+declare module 'nuxt-feathers-zod/client' {
+  interface ServiceTypes {
+    [${pathConst}]: ${clientServiceType}
+  }
+}
+`
+}
+
+function renderService(ids: ReturnType<typeof createServiceIds>, auth: boolean, docs: boolean) {
+  const base = ids.baseCamel
+  const Base = ids.basePascal
+  const serviceName = ids.serviceNameKebab
+  const serviceClass = `${Base}Service`
+  const authImports = auth ? "import { authenticate } from '@feathersjs/authentication'\n" : ''
+
+  const swaggerImports = ''
+
+  const swaggerSchemaImports = ''
+  const docsBlock = docs
+    ? `
+    docs: {
+      description: '${Base} service',
+      idType: 'string',
+${auth ? `      securities: ${base}Methods,
+` : ''}      definitions: {
+        ${base}: { type: 'object', properties: {} },
+        ${base}Data: { type: 'object', properties: {} },
+        ${base}Patch: { type: 'object', properties: {} },
+        ${base}Query: {
+          type: 'object',
+          properties: {
+            $limit: { type: 'number' },
+            $skip: { type: 'number' },
+            $sort: { type: 'object', additionalProperties: { type: 'number' } },
+          },
+        },
+      },
+    },
+`
+    : ''
+
+  const authAround = auth
+    ? `
+      find: [authenticate('jwt')],
+      get: [authenticate('jwt')],
+      create: [],
+      patch: [authenticate('jwt')],
+      remove: [authenticate('jwt')],
+`
+    : `
+      find: [],
+      get: [],
+      create: [],
+      patch: [],
+      remove: [],
+`
+
+  return `// For more information about this file see https://dove.feathersjs.com/guides/cli/service.html
+
+import type { Application } from 'nuxt-feathers-zod/server'
+${authImports}${swaggerImports}import { hooks as schemaHooks } from '@feathersjs/schema'
+import { getOptions, ${serviceClass} } from './${serviceName}.class'
+import {
+${swaggerSchemaImports}  ${base}DataResolver,
+  ${base}DataValidator,
+  ${base}ExternalResolver,
+  ${base}PatchResolver,
+  ${base}PatchValidator,
+  ${base}QueryResolver,
+  ${base}QueryValidator,
+  ${base}Resolver,
+} from './${serviceName}.schema'
+import { ${base}Methods, ${base}Path } from './${serviceName}.shared'
+
+export * from './${serviceName}.class'
+export * from './${serviceName}.schema'
+
+export function ${base}(app: Application) {
+  app.use(${base}Path, new ${serviceClass}(getOptions(app)), {
+    methods: ${base}Methods,
+    events: [],${docsBlock}
+  })
+
+  app.service(${base}Path).hooks({
+    around: {
+      all: [schemaHooks.resolveExternal(${base}ExternalResolver), schemaHooks.resolveResult(${base}Resolver)],
+${authAround}    },
+    before: {
+      all: [schemaHooks.validateQuery(${base}QueryValidator), schemaHooks.resolveQuery(${base}QueryResolver)],
+      find: [],
+      get: [],
+      create: [schemaHooks.validateData(${base}DataValidator), schemaHooks.resolveData(${base}DataResolver)],
+      patch: [schemaHooks.validateData(${base}PatchValidator), schemaHooks.resolveData(${base}PatchResolver)],
+      remove: [],
+    },
+    after: {
+      all: [],
+    },
+    error: {
+      all: [],
+    },
+  })
+}
+
+declare module 'nuxt-feathers-zod/server' {
+  interface ServiceTypes {
+    [${base}Path]: ${serviceClass}
+  }
+}
+`
+}
+
+function renderNitroMiddleware(name: string) {
+  const nice = name.replace(/-/g, ' ')
+  return `// Nitro middleware: ${nice}
+// Runs on every request (or conditionally based on route rules).
+
+export default defineEventHandler(async (event) => {
+  // Example: attach a request id
+  // event.context.requestId = crypto.randomUUID()
+})
+`
+}
+
+function renderFeathersPlugin(name: string) {
+  const nice = name.replace(/-/g, ' ')
+  return `// Feathers server plugin: ${nice}
+// Loaded by Nuxt Nitro server (see playground/server/feathers/*.ts for examples)
+
+import type { HookContext, NextFunction } from 'nuxt-feathers-zod/server'
+import { defineFeathersServerPlugin } from 'nuxt-feathers-zod/server'
+
+export default defineFeathersServerPlugin((app) => {
+  app.hooks({
+    setup: [
+      async (context: HookContext, next: NextFunction) => {
+        // Place initialization logic here
+        await next()
+      },
+    ],
+  })
+})
+`
+}