@vevedh/create-feathers-app 0.0.0-stage → 0.1.0-rc.10

package/lib/compose.mjs

@@ -0,0 +1,252 @@
+/** Opt-in, loopback-only Docker Compose profiles for Vite-first SPA applications.
+ * Authentication and database capability guards from scaffold.mjs stay active.
+ */
+const composeModes = new Set(['dev', 'prod', 'both'])
+
+function requireExact(files, path, before, after) {
+  const source = files.get(path)
+  if (typeof source !== 'string' || source.split(before).length !== 2) {
+    throw new Error(`Unexpected ${path} template; refusing Docker generation`)
+  }
+  files.set(path, source.replace(before, after))
+}
+
+function composeReadme(options) {
+  const dev = options.compose === 'dev' || options.compose === 'both'
+  const prod = options.compose === 'prod' || options.compose === 'both'
+  return `# Docker Compose — ${options.name}
+
+Ces fichiers déploient le squelette Vite-first, **pas une application déjà sécurisée pour Internet**.
+Le service de démonstration \`notes\` est en mémoire et sans authentification. Les ports HTTP sont publiés sur \`127.0.0.1\` uniquement.
+Aucun port de base de données n'est exposé. Le générateur **n'active pas** les profils JWT, OAuth ou bases externes : leurs garde-fous existants continuent de refuser le démarrage tant que leur intégration n'est pas certifiée.
+
+## Prérequis
+
+- Docker Desktop avec Docker Compose v2.
+- Node.js compatible et Corepack/pnpm pour produire \`pnpm-lock.yaml\`.
+- Vérifier les dépendances, leurs licences et vulnérabilités avant tout déploiement.
+
+${dev ? `## Développement
+
+\`docker compose -f compose.dev.yaml up --build\`
+
+Ouvrir http://127.0.0.1:5173. Le serveur Vite monte Feathers via le plugin Vite, sans lancer un deuxième processus d'API. Aucun autre port n'est publié.
+
+Arrêt : \`docker compose -f compose.dev.yaml down\` (le volume de dépendances est conservé).
+
+` : ''}${prod ? `## Image de déploiement (prototype isolé)
+
+Créer et réviser le lockfile à la racine du projet :
+
+\`corepack pnpm install --lockfile-only\`
+
+\`docker compose -f compose.prod.yaml up --build -d\`
+
+Ouvrir http://127.0.0.1:8080. Nginx sert la SPA et relaie \`/api/\` à Feathers et ${options.transport === 'both' ? '\`/socket.io/\` au serveur temps réel.' : 'aucun Socket.IO (REST uniquement).'} Le backend n'a pas de port publié sur l'hôte.
+
+Arrêt : \`docker compose -f compose.prod.yaml down\`.
+
+**Avant une réelle mise en production :** remplacer le service notes non protégé, activer JWT/RBAC et une persistance durable, vérifier les migrations, isoler les secrets, mettre en place le reverse proxy HTTPS et la politique d'origines, vérifier les journaux et sauvegardes et exécuter les E2E REST/Socket.IO de la cible. Ne pas changer l'interface hôte de \`127.0.0.1\` vers \`0.0.0.0\` sans ces contrôles.
+
+` : ''}## Particularités
+
+- Choix générés : ${options.ui} SPA, ${options.adapter}, ${options.transport}, PWA ${options.pwa}.
+- Le serveur API autonome peut écouter sur toutes les interfaces **du conteneur** uniquement via \`FEATHERS_BIND_HOST=0.0.0.0\` ; le réseau \`backend\` est interne et non publié.
+- Le mode PWA, lorsqu'il est sélectionné, ne doit jamais mettre \`/api/\` ou \`/socket.io/\` en cache.
+- Les images de production sont construites depuis un lockfile audité ; ne jamais copier de \`.env\` réel dans les images.
+- Les ports peuvent être personnalisés uniquement côté loopback via \`P4_DEV_PORT\` et \`P4_HTTP_PORT\`.
+`
+}
+
+function devCompose(options) {
+  return `name: ${options.name}-dev
+services:
+  app:
+    image: node:24-bookworm-slim
+    working_dir: /workspace
+    command: ["sh", "-c", "corepack pnpm install --no-frozen-lockfile && corepack pnpm exec vite --host 0.0.0.0 --port 5173 --strictPort"]
+    environment:
+      NODE_ENV: development
+      VITE_FEATHERS_REALTIME: "${options.transport === 'both' ? '1' : '0'}"
+      P4_DEV_PORT: "\${P4_DEV_PORT:-5173}"
+    volumes:
+      - .:/workspace
+      - dependencies:/workspace/node_modules
+    ports:
+      - "127.0.0.1:\${P4_DEV_PORT:-5173}:5173"
+    security_opt:
+      - no-new-privileges:true
+volumes:
+  dependencies:
+`
+}
+
+function prodCompose(options) {
+  return `name: ${options.name}-prod
+services:
+  api:
+    build:
+      context: .
+      dockerfile: infra/compose/Dockerfile.api
+    environment:
+      NODE_ENV: production
+      FEATHERS_BIND_HOST: "0.0.0.0"
+      FEATHERS_ADAPTER: "${options.adapter}"
+      FEATHERS_SOCKETIO: "${options.transport === 'both' ? '1' : '0'}"
+      FEATHERS_API_PORT: "3030"
+      FEATHERS_PUBLIC_ORIGIN: "http://127.0.0.1:\${P4_HTTP_PORT:-8080}"
+      FEATHERS_PREVIEW_ORIGIN: "http://127.0.0.1:\${P4_HTTP_PORT:-8080}"
+    expose:
+      - "3030"
+    networks:
+      - backend
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    tmpfs:
+      - /tmp
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3030/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 10s
+      timeout: 5s
+      retries: 8
+      start_period: 20s
+  web:
+    build:
+      context: .
+      dockerfile: infra/compose/Dockerfile.web
+    depends_on:
+      api:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:\${P4_HTTP_PORT:-8080}:8080"
+    networks:
+      - frontend
+      - backend
+    security_opt:
+      - no-new-privileges:true
+networks:
+  frontend:
+  backend:
+    internal: true
+`
+}
+
+const apiDockerfile = `FROM node:24-bookworm-slim
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml ./
+RUN corepack pnpm install --frozen-lockfile --prod
+COPY api ./api
+USER node
+EXPOSE 3030
+CMD ["node", "api/server.mjs"]
+`
+
+const webDockerfile = `FROM node:24-bookworm-slim AS builder
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml ./
+RUN corepack pnpm install --frozen-lockfile
+COPY . .
+RUN corepack pnpm run build
+
+FROM nginx:stable-alpine
+COPY infra/compose/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder /app/dist /usr/share/nginx/html
+EXPOSE 8080
+`
+
+function nginx(options) {
+  return `server {
+  listen 8080;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+  autoindex off;
+  server_tokens off;
+  add_header X-Content-Type-Options nosniff always;
+  add_header Referrer-Policy no-referrer always;
+  add_header X-Frame-Options DENY always;
+  location = /api { return 404; }
+  location /api/ {
+    proxy_pass http://api:3030/api/;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_read_timeout 30s;
+  }
+${options.transport === 'both' ? `  location /socket.io/ {
+    proxy_pass http://api:3030;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_read_timeout 65s;
+  }
+` : `  location /socket.io/ { return 404; }
+`}  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}
+`
+}
+
+const dockerIgnore = `node_modules
+.git
+.agents
+.ai
+.codex
+.cursor
+.claude
+.gemini
+.windsurf
+.mcp.json
+.env
+.env.*
+!.env.example
+database.env
+*.zip
+*.log
+coverage
+dist
+.vite
+.quasar
+docs-private
+test-results
+playwright-report
+`
+
+export function enableCompose(files, options) {
+  if (!composeModes.has(options.compose) || options.render !== 'spa') {
+    throw new Error('Compose generation supports only SPA and compose dev|prod|both')
+  }
+  const dev = options.compose === 'dev' || options.compose === 'both'
+  const prod = options.compose === 'prod' || options.compose === 'both'
+  if (dev && options.devApi !== 'vite') {
+    throw new Error('Compose development requires --dev-api vite for a single Feathers/Vite listener')
+  }
+  const created = new Map([['COMPOSE.md', composeReadme(options)]])
+  if (dev) created.set('compose.dev.yaml', devCompose(options))
+  if (prod) {
+    created.set('compose.prod.yaml', prodCompose(options))
+    created.set('infra/compose/Dockerfile.api', apiDockerfile)
+    created.set('infra/compose/Dockerfile.web', webDockerfile)
+    created.set('infra/compose/nginx.conf', nginx(options))
+    // The only Docker interface bound to all container addresses is the private API listener.
+    requireExact(files, 'api/server.mjs', "const realtime = process.env.FEATHERS_SOCKETIO === '1'", "const bindHost = process.env.FEATHERS_BIND_HOST === '0.0.0.0' ? '0.0.0.0' : '127.0.0.1'\nconst realtime = process.env.FEATHERS_SOCKETIO === '1'")
+    requireExact(files, 'api/server.mjs', "const wsPort = Number(process.env.FEATHERS_SOCKET_PORT || 3031)\n", '')
+    requireExact(files, 'api/server.mjs', ' || !Number.isInteger(wsPort) || wsPort === port', '')
+    requireExact(files, 'api/server.mjs', "socketio: realtime ? { port: wsPort, origins: [...new Set([origin, previewOrigin])], host: '127.0.0.1' } : false,", "socketio: realtime ? { mode: 'external', origins: [...new Set([origin, previewOrigin])] } : false,")
+    requireExact(files, 'api/server.mjs', 'await runtime.start()\nconst httpServer = createServer', 'const httpServer = createServer')
+    requireExact(files, 'api/server.mjs', "httpServer.listen(port, '127.0.0.1', resolve)", 'httpServer.listen(port, bindHost, resolve)')
+    requireExact(files, 'api/server.mjs', '  httpServer.listen(port, bindHost, resolve)\n})', '  httpServer.listen(port, bindHost, resolve)\n})\nif (realtime) await runtime.start(httpServer)\nelse await runtime.start()')
+    requireExact(files, 'api/server.mjs', '  await new Promise(resolve => httpServer.close(resolve))\n  await runtime.close()', '  await runtime.close()\n  if (httpServer.listening) await new Promise(resolve => httpServer.close(resolve))')
+  }
+  created.set('.dockerignore', dockerIgnore)
+  for (const [key, content] of created) {
+    if (files.has(key)) throw new Error(`Compose file conflicts with a template: ${key}`)
+    files.set(key, content)
+  }
+}

package/lib/persistence-lab/create-secret.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { randomBytes } from 'node:crypto'
+import { mkdir, open, lstat } from 'node:fs/promises'
+import { resolve, join } from 'node:path'
+const dir = resolve('secrets')
+const file = join(dir, 'db_password')
+try {
+  if (process.argv.length !== 2) throw Error('ARGUMENTS_REFUSED')
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  if ((await lstat(dir)).isSymbolicLink()) throw Error('SECRET_PATH_REFUSED')
+  const handle = await open(file, 'wx', 0o600)
+  try { await handle.writeFile(randomBytes(36).toString('base64url') + '\n') } finally { await handle.close() }
+  console.log('P5_SECRET=CREATED | PATH=secrets/db_password | CONTENT=REDACTED')
+} catch {
+  console.error('P5_SECRET=REFUSED | EXISTING_FILE_OR_UNSAFE_PATH')
+  process.exitCode = 2
+}

package/lib/persistence-lab/notes-service.mjs

@@ -0,0 +1,68 @@
+import { randomInt } from 'node:crypto'
+import { BadRequest, NotFound } from '@feathersjs/errors'
+
+// Laboratory-only, unauthenticated Feathers service using a real database adapter.
+// Never expose it beyond the local reverse proxy; P5-R6-B will add JWT/RBAC.
+function idOf(value) {
+  const n = typeof value === 'string' && /^[1-9][0-9]{0,9}$/.test(value) ? Number(value) : value
+  if (!Number.isSafeInteger(n) || n < 1 || n > 2147483647) throw new BadRequest('Invalid note ID')
+  return n
+}
+function titleOf(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).join(',') !== 'title') {
+    throw new BadRequest('Invalid note data')
+  }
+  const title = value.title
+  if (typeof title !== 'string' || title.trim().length < 1 || title.length > 120 || /[\u0000-\u001f\u007f]/.test(title)) {
+    throw new BadRequest('Invalid note title')
+  }
+  return title.trim()
+}
+function noQuery(params) {
+  const query = params?.query
+  if (query !== undefined && (query === null || typeof query !== 'object' || Array.isArray(query) || Object.keys(query).length !== 0)) {
+    throw new BadRequest('Query operators are not allowed in this laboratory service')
+  }
+}
+function present(value) {
+  if (!value || typeof value !== 'object') throw new Error('DB_RECORD_INVALID')
+  const id = idOf(value.id)
+  if (typeof value.title !== 'string') throw new Error('DB_RECORD_INVALID')
+  return { id, title: value.title }
+}
+export class PersistentNotesService {
+  constructor(databaseAdapter) {
+    if (!databaseAdapter || ['find','get','create','patch','remove'].some(name => typeof databaseAdapter[name] !== 'function')) {
+      throw new Error('DB_ADAPTER_REQUIRED')
+    }
+    this.adapter = databaseAdapter
+    for (const method of ['find','get','create','patch','remove']) this[method] = this[method].bind(this)
+  }
+  async find(params) {
+    noQuery(params)
+    const rows = await this.adapter.find({ query: { $limit: 100 }, paginate: false })
+    if (!Array.isArray(rows)) throw new Error('DB_LIST_INVALID')
+    return rows.map(present)
+  }
+  async get(id, params) {
+    noQuery(params)
+    try { return present(await this.adapter.get(idOf(id))) }
+    catch (error) { if (error?.code === 404) throw new NotFound('Note not found'); throw error }
+  }
+  async create(data, params) {
+    noQuery(params)
+    // Numeric IDs retain compatibility with the published Vue/Pinia Note interface.
+    // No in-memory counter; id uniqueness is enforced by the DB primary key/index.
+    return present(await this.adapter.create({ id: randomInt(1, 2147483647), title: titleOf(data) }))
+  }
+  async patch(id, data, params) {
+    noQuery(params)
+    try { return present(await this.adapter.patch(idOf(id), { title: titleOf(data) })) }
+    catch (error) { if (error?.code === 404) throw new NotFound('Note not found'); throw error }
+  }
+  async remove(id, params) {
+    noQuery(params)
+    try { return present(await this.adapter.remove(idOf(id))) }
+    catch (error) { if (error?.code === 404) throw new NotFound('Note not found'); throw error }
+  }
+}

package/lib/persistence-lab/open.mjs

@@ -0,0 +1,30 @@
+import { readFile, lstat } from 'node:fs/promises'
+import { openNamedDatabaseProviders } from './database-providers.generated.mjs'
+import { databaseDeclarations } from '../config/database-connections.generated.mjs'
+import { checkNotesStorage } from './storage.mjs'
+
+// Docker secrets are read only at runtime, not copied into images or exposed via VITE_*.
+export async function openNotesDatabase() {
+  if (process.env.NODE_ENV !== 'production' || process.env.P5_PERSISTENCE_MODE !== 'notes-lab') {
+    throw new Error('PERSISTENCE_PROFILE_NOT_ENABLED')
+  }
+  if (databaseDeclarations.length !== 1) throw new Error('DB_SINGLE_PROVIDER_REQUIRED')
+  const declaration = databaseDeclarations[0]
+  const secretFile = process.env.P5_DATABASE_PASSWORD_FILE
+  if (secretFile !== '/run/secrets/p5_database_password') throw new Error('DB_SECRET_MISSING')
+  const stat = await lstat(secretFile)
+  if (!stat.isFile() || stat.size < 16 || stat.size > 256) throw new Error('DB_SECRET_INVALID')
+  const password = (await readFile(secretFile, 'utf8')).replace(/\r?\n$/, '')
+  if (password.length < 16 || password.length > 256 || /[\u0000-\u001f\u007f]/.test(password)) throw new Error('DB_SECRET_INVALID')
+  const providers = await openNamedDatabaseProviders({
+    ...process.env,
+    [`${declaration.envPrefix}_PASSWORD`]: password,
+  })
+  try {
+    const adapter = await checkNotesStorage(providers.get(declaration.alias))
+    return { adapter, close: () => providers.close() }
+  } catch {
+    await providers.close()
+    throw new Error('DB_SCHEMA_NOT_READY')
+  }
+}

package/lib/persistence-lab/prepare.mjs

@@ -0,0 +1,27 @@
+import { openNamedDatabaseProviders } from '../api/runtime/database-providers.generated.mjs'
+import { databaseDeclarations } from '../api/config/database-connections.generated.mjs'
+import { prepareNotesStorage } from '../api/runtime/storage.mjs'
+import { readFile, lstat } from 'node:fs/promises'
+
+if (process.env.NODE_ENV !== 'production' || process.env.P5_PERSISTENCE_MODE !== 'notes-lab' || databaseDeclarations.length !== 1) {
+  console.error('P5_DB_INIT=REFUSED'); process.exitCode = 2
+} else {
+  let providers
+  try {
+    const declaration = databaseDeclarations[0]
+    const file = process.env.P5_DATABASE_PASSWORD_FILE
+    if (file !== '/run/secrets/p5_database_password') throw new Error('DB_SECRET_MISSING')
+    const stat = await lstat(file)
+    if (!stat.isFile() || stat.size < 16 || stat.size > 256) throw new Error('DB_SECRET_INVALID')
+    const password = (await readFile(file, 'utf8')).replace(/\r?\n$/, '')
+    if (password.length < 16 || password.length > 256 || /[\u0000-\u001f\u007f]/.test(password)) throw new Error('DB_SECRET_INVALID')
+    providers = await openNamedDatabaseProviders({ ...process.env, [`${declaration.envPrefix}_PASSWORD`]: password })
+    await prepareNotesStorage(providers.get(declaration.alias))
+    console.log('P5_DB_INIT=PASS | NOTES_SCHEMA=READY | NO_SEED=YES')
+  } catch {
+    console.error('P5_DB_INIT=FAIL | NO_SCHEMA_DOWNGRADE')
+    process.exitCode = 2
+  } finally {
+    try { await providers?.close() } catch { process.exitCode = 2 }
+  }
+}

package/lib/persistence-lab/storage.mjs

@@ -0,0 +1,27 @@
+// Explicit additive schema provisioning; never drop a table, document, index or volume.
+const table = 'app_notes'
+export async function prepareNotesStorage(provider) {
+  if (!provider || !['postgresql','mariadb','mongodb'].includes(provider.adapter)) throw new Error('DB_UNSUPPORTED')
+  if (provider.adapter === 'mongodb') {
+    try { await provider.db.createCollection(table) }
+    catch (error) { if (error?.code !== 48) throw error }
+    await provider.db.collection(table).createIndex({ id: 1 }, { unique: true })
+  } else {
+    if (!await provider.db.schema.hasTable(table)) {
+      await provider.db.schema.createTable(table, t => {
+        t.integer('id').primary()
+        t.string('title', 120).notNullable()
+      })
+    }
+    for (const column of ['id', 'title']) {
+      if (!await provider.db.schema.hasColumn(table, column)) throw new Error('DB_SCHEMA_MIGRATION_REQUIRED')
+    }
+  }
+}
+export async function checkNotesStorage(provider) {
+  if (!provider || !['postgresql','mariadb','mongodb'].includes(provider.adapter)) throw new Error('DB_UNSUPPORTED')
+  if (provider.adapter === 'mongodb') {
+    if (!await provider.db.listCollections({ name: table }).hasNext()) throw new Error('DB_SCHEMA_NOT_READY')
+  } else if (!await provider.db.schema.hasTable(table)) throw new Error('DB_SCHEMA_NOT_READY')
+  return provider.service(table)
+}

package/lib/persistence-lab.mjs

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises'
+import { enableUniversalLab } from './universal/lab.mjs'
+import { enableJwtSessionLab } from './auth-lab.mjs'
+
+const adapters = Object.freeze({
+  postgresql: { image: 'postgres:16-alpine', port: 5432, volume: '/var/lib/postgresql/data',
+    environment: `      POSTGRES_USER: featherslab\n      POSTGRES_DB: feathers_lab\n      POSTGRES_PASSWORD_FILE: /run/secrets/p5_database_password\n`,
+    health: `      test: ["CMD-SHELL", "pg_isready -U featherslab -d feathers_lab"]\n` },
+  mariadb: { image: 'mariadb:11.4', port: 3306, volume: '/var/lib/mysql',
+    environment: `      MARIADB_USER: featherslab\n      MARIADB_DATABASE: feathers_lab\n      MARIADB_PASSWORD_FILE: /run/secrets/p5_database_password\n      MARIADB_RANDOM_ROOT_PASSWORD: "1"\n`,
+    health: `      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]\n` },
+  mongodb: { image: 'mongo:7', port: 27017, volume: '/data/db',
+    environment: `      MONGO_INITDB_ROOT_USERNAME: featherslab\n      MONGO_INITDB_ROOT_PASSWORD_FILE: /run/secrets/p5_database_password\n`,
+    health: `      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand({ping:1}).ok"]\n` },
+})
+function change(files, path, before, after) {
+  const old = files.get(path)
+  if (typeof old !== 'string' || old.split(before).length !== 2) {
+    throw new Error(`Persistence template drift: ${path}`)
+  }
+  files.set(path, old.replace(before, after))
+}
+const source = async name => readFile(new URL(`./persistence-lab/${name}`, import.meta.url), 'utf8')
+
+/** Opt-in, single-provider, unauthenticated *local laboratory* only.
+ * No implicit weakening of the existing auth/DB capability guard.
+ */
+export async function enablePersistentLab(files, options) {
+  if (options.persistence !== 'lab' || options.compose !== 'prod' || options.render !== 'spa' || !['none','jwt'].includes(options.auth) || options.databases.length !== 1) {
+    throw new Error('Persistence lab requires SPA --compose prod --auth none and exactly one DB')
+  }
+  const declaration = options.databases[0]
+  if (declaration.adapter === 'universal') return enableUniversalLab(files, options, enablePersistentLab)
+  const settings = adapters[declaration.adapter]
+  if (!settings) throw new Error('Persistence lab supports postgresql|mariadb|mongodb only')
+  const envPrefix = `P5_DB_${declaration.alias.replaceAll('-', '_').toUpperCase()}`
+  const env = `      P5_PERSISTENCE_MODE: notes-lab\n      P5_DATABASE_PASSWORD_FILE: /run/secrets/p5_database_password\n      ${envPrefix}_HOST: db\n      ${envPrefix}_PORT: "${settings.port}"\n      ${envPrefix}_USER: featherslab\n      ${envPrefix}_NAME: feathers_lab\n`
+  const deps = '    depends_on:\n      migrate:\n        condition: service_completed_successfully\n    secrets:\n      - p5_database_password\n'
+  change(files, 'compose.prod.yaml', '      FEATHERS_API_PORT: "3030"\n', `      FEATHERS_API_PORT: "3030"\n${env}`)
+  change(files, 'compose.prod.yaml', '    expose:\n      - "3030"\n', `    expose:\n      - "3030"\n${deps}`)
+  const job = `  migrate:\n    build:\n      context: .\n      dockerfile: infra/compose/Dockerfile.api\n    command: ["node", "scripts/prepare-notes.mjs"]\n    environment:\n      NODE_ENV: production\n${env}    depends_on:\n      db:\n        condition: service_healthy\n    secrets:\n      - p5_database_password\n    networks:\n      - backend\n    security_opt:\n      - no-new-privileges:true\n    read_only: true\n    tmpfs:\n      - /tmp\n  db:\n    image: ${settings.image}\n    environment:\n${settings.environment}    secrets:\n      - p5_database_password\n    networks:\n      - backend\n    volumes:\n      - persistence_data:${settings.volume}\n    healthcheck:\n${settings.health}      interval: 10s\n      timeout: 5s\n      retries: 12\n      start_period: 25s\n`
+  change(files, 'compose.prod.yaml', '  web:\n    build:\n', `${job}  web:\n    build:\n`)
+  const prod = files.get('compose.prod.yaml')
+  if (!prod.endsWith('    internal: true\n')) throw new Error('Compose network declaration changed')
+  files.set('compose.prod.yaml', `${prod}volumes:\n  persistence_data:\nsecrets:\n  p5_database_password:\n    file: ./secrets/db_password\n`)
+  change(files, 'infra/compose/Dockerfile.api', 'COPY api ./api\n', 'COPY api ./api\nCOPY scripts/prepare-notes.mjs ./scripts/prepare-notes.mjs\n')
+  change(files, '.dockerignore', 'docs-private\n', 'docs-private\nsecrets\n')
+  const ignores = files.get('.gitignore')
+  if (!ignores || !ignores.includes('docs-private/')) throw new Error('Missing safe .gitignore')
+  files.set('.gitignore', `${ignores.trimEnd()}\nsecrets/\n`)
+  files.set('api/config/database-connections.generated.mjs', `export const databaseDeclarations = Object.freeze(${JSON.stringify([{ alias: declaration.alias, adapter: declaration.adapter, envPrefix }])})\n`)
+  files.set('api/runtime/database-providers.generated.mjs', await readFile(new URL('./secure-runtime/providers.mjs', import.meta.url), 'utf8'))
+  for (const [name,path] of [
+    ['notes-service.mjs', 'api/runtime/notes-service.mjs'],
+    ['storage.mjs', 'api/runtime/storage.mjs'],
+    ['open.mjs', 'api/runtime/open.mjs'],
+    ['prepare.mjs', 'scripts/prepare-notes.mjs'],
+    ['create-secret.mjs', 'scripts/create-lab-secret.mjs'],
+  ]) files.set(path, await source(name))
+
+  const cap = `// Opt-in laboratory contract: never start a database-backed demo on Vite dev or in a public host.\n` +
+    `export function assertCapabilities() {\n` +
+    `  if (process.env.NODE_ENV !== 'production' || process.env.P5_PERSISTENCE_MODE !== 'notes-lab') {\n` +
+    `    throw new Error('External persistence requires the private Docker Production lab profile')\n` +
+    `  }\n` +
+    `}\n`
+  if (!files.get('api/config/capabilities.mjs')?.includes('Database adapters not provisioned:')) {
+    throw new Error('Existing capability guard drift')
+  }
+  files.set('api/config/capabilities.mjs', cap)
+  change(files, 'vite.config.ts', 'assertCapabilities()\nexport default defineConfig({',
+    "if (process.env.NODE_ENV !== 'production') assertCapabilities()\nexport default defineConfig({")
+  change(files, 'api/services/notes/notes.service.mjs', "app.use('notes', new NotesService(),", "const persistenceService = app.get('p5PersistentNotes')\n  if (!persistenceService) throw new Error('DB_NOT_BOUND')\n  app.use('notes', persistenceService,")
+
+  let server = files.get('api/server.mjs')
+  if (typeof server !== 'string' || !server.includes('assertCapabilities()') || !server.includes('const runtime = await createFeathersRuntime(')) {
+    throw new Error('Production server template drift')
+  }
+  // Invariant: provider opens and schema is checked before registering services or opening HTTP.
+  server = `import { openNotesDatabase } from './runtime/open.mjs'\nimport { PersistentNotesService } from './runtime/notes-service.mjs'\n${server}`
+  const start = 'const runtime = await createFeathersRuntime(modules.map(String), file => import(file), {'
+  if (server.split(start).length !== 2) throw new Error('Runtime bootstrap changed')
+  server = server.replace(start,
+    `const persistence = await openNotesDatabase()\nlet persistenceReady = false\ntry {\n${start}\n  configure: app => app.set('p5PersistentNotes', new PersistentNotesService(persistence.adapter)),`)
+  const closeOld = '  await runtime.close()'
+  if (server.split(closeOld).length !== 2) throw new Error('Runtime close changed')
+  server = server.replace(closeOld, `${closeOld}\n  await persistence.close()`)
+  server += `\npersistenceReady = true\n} finally {\n  if (!persistenceReady) await persistence.close()\n}\n`
+  files.set('api/server.mjs', server)
+  const readme = [
+    '# Persistance Feathers — laboratoire Docker Production',
+    '',
+    '**Profil sans authentification : utilisation locale uniquement.** Nginx est exposé sur 127.0.0.1.',
+    `Base sélectionnée : ${declaration.adapter} (alias ${declaration.alias}).`,
+    '',
+    '## Premier démarrage',
+    '',
+    'Dans le dossier du projet généré :',
+    '```powershell',
+    'node scripts/create-lab-secret.mjs',
+    'corepack pnpm install --lockfile-only',
+    'docker compose -f compose.prod.yaml up --build -d',
+    '```',
+    '',
+    'Ouvrir http://127.0.0.1:8080, ajouter une note puis redémarrer seulement l’API :',
+    '```powershell',
+    'docker compose -f compose.prod.yaml restart api',
+    'docker compose -f compose.prod.yaml ps',
+    '```',
+    '',
+    'Les notes sont stockées dans le volume `persistence_data`. `docker compose down` le conserve.',
+    '**Ne jamais lancer `down -v` pour ce test : cela supprime le volume !**',
+    'Le job `migrate` crée la structure au besoin, sans supprimer de données.',
+    'Le mot de passe est fourni par un secret Docker `secrets/db_password`, exclu de Git et des images.',
+    '',
+    '## Limites et sécurité',
+    '',
+    '- Démonstration sans JWT/RBAC : ne pas exposer au réseau public.',
+    '- Une seule connexion, un service notes et Compose Production uniquement.',
+    '- Développement Vite avec DB externe bloqué ; aucun repli vers la mémoire.',
+    '- Le service add reste volontairement bloqué pour les DB externes.',
+    '- Socket.IO annonce des événements, pas un journal persistant.',
+    '- Les images Docker de DB doivent être figées à un digest et revues avant production réelle.',
+    '',
+  ].join('\n')
+  files.set('PERSISTENCE.md', readme)
+  const manifest = JSON.parse(files.get('package.json'))
+  // Pin operational DB drivers for reproducible lockfiles; do not modify other profiles.
+  if (declaration.adapter === 'postgresql') { manifest.dependencies.knex = '3.3.0'; manifest.dependencies.pg = '8.23.1' }
+  if (declaration.adapter === 'mariadb') { manifest.dependencies.knex = '3.3.0'; manifest.dependencies.mysql2 = '3.24.6' }
+  if (declaration.adapter === 'mongodb') manifest.dependencies.mongodb = '6.19.0'
+  manifest.scripts['db:secret:lab'] = 'node scripts/create-lab-secret.mjs'
+  files.set('package.json', JSON.stringify(manifest, null, 2) + '\n')
+  if (options.auth === 'jwt') await enableJwtSessionLab(files, options)
+}

package/lib/planner/options.mjs

@@ -0,0 +1,74 @@
+/** Candidate options for a future scaffolding CLI. No files or runtime services
+ * are generated by this read-only planner. Keep mappings reviewable and explicit.
+ */
+export const UI_PRESETS = Object.freeze(['quasar2', 'daisyui', 'daisyui-kit'])
+export const SCHEMA_PRESETS = Object.freeze(['typebox', 'json', 'zod'])
+export const AUTH_PRESETS = Object.freeze(['none', 'jwt', 'local', 'oauth', 'oidc', 'ldap'])
+export const DATABASE_PRESETS = Object.freeze(['memory', 'mongodb', 'postgresql', 'mariadb', 'mysql', 'sqlite'])
+export const RENDER_PRESETS = Object.freeze(['spa', 'ssr', 'ssg'])
+export const RENDER_ENGINES = Object.freeze(['auto', 'vite', 'quasar-cli-vite'])
+export const TRANSPORT_PRESETS = Object.freeze(['rest', 'socketio', 'both'])
+export const NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+const AVAILABLE_OPTIONS = new Set(['--name', '--ui', '--render', '--pwa', '--schema', '--auth', '--db', '--primary', '--transport', '--engine', '--dry-run', '--json', '--help'])
+
+function requiredChoice(value, choices, name) {
+  if (!choices.includes(value)) throw new Error(`Invalid ${name}: expected ${choices.join('|')}`)
+  return value
+}
+function parseUniqueCsv(value, name) {
+  if (typeof value !== 'string' || !value || value.length > 512) throw new Error(`Invalid ${name}`)
+  const parts = value.split(',')
+  if (!parts.length || parts.some(part => !part || part !== part.trim()) || new Set(parts).size !== parts.length) throw new Error(`Invalid or duplicate ${name}`)
+  return parts
+}
+export function parsePlanArguments(args) {
+  if (args.includes('--help') || args.includes('-h')) return { help: true }
+  const options = { name: 'my-feathers-app', ui: 'daisyui', render: 'spa', pwa: 'off', schema: 'typebox', auth: 'none', db: 'main:memory', primary: 'main', transport: 'rest', engine: 'auto', dryRun: true, json: false }
+  const seen = new Set()
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index]
+    if (!AVAILABLE_OPTIONS.has(flag) || flag === '--help' || seen.has(flag)) throw new Error(`Unknown or duplicate option: ${flag}`)
+    seen.add(flag)
+    if (flag === '--dry-run' || flag === '--json') options[flag === '--dry-run' ? 'dryRun' : 'json'] = true
+    else {
+      const value = args[++index]
+      if (!value || value.startsWith('--')) throw new Error(`Missing value for ${flag}`)
+      options[flag.slice(2)] = value
+    }
+  }
+  return options
+}
+export function normalizePlanOptions(input) {
+  const name = input.name ?? 'my-feathers-app'
+  if (typeof name !== 'string' || name.length > 48 || !NAME_PATTERN.test(name)) throw new Error('Invalid --name: lowercase kebab-case, maximum 48 characters')
+  const ui = requiredChoice(input.ui ?? 'daisyui', UI_PRESETS, '--ui')
+  const render = requiredChoice(input.render ?? 'spa', RENDER_PRESETS, '--render')
+  const pwa = requiredChoice(input.pwa ?? 'off', ['on', 'off'], '--pwa')
+  const schema = requiredChoice(input.schema ?? 'typebox', SCHEMA_PRESETS, '--schema')
+  const transport = requiredChoice(input.transport ?? 'rest', TRANSPORT_PRESETS, '--transport')
+  const requestedEngine = requiredChoice(input.engine ?? 'auto', RENDER_ENGINES, '--engine')
+  // Quasar Vite plugin works in SPA; Quasar CLI with Vite is a separate toolchain
+  // required for SSR/SSG. Neither integrates this Feathers plugin automatically.
+  const engine = requestedEngine === 'auto'
+    ? (ui === 'quasar2' && render !== 'spa' ? 'quasar-cli-vite' : 'vite')
+    : requestedEngine
+  if (ui !== 'quasar2' && engine === 'quasar-cli-vite') throw new Error('Quasar CLI is only compatible with --ui quasar2')
+  if (ui === 'quasar2' && render !== 'spa' && engine === 'vite') throw new Error('Quasar standalone Vite plugin supports SPA only; select --engine quasar-cli-vite for SSR/SSG')
+  const auth = parseUniqueCsv(input.auth ?? 'none', '--auth')
+  for (const strategy of auth) requiredChoice(strategy, AUTH_PRESETS, '--auth')
+  if (auth.includes('none') && auth.length > 1) throw new Error('Cannot combine --auth none with authentication strategies')
+  // AuthenticationService issues JWTs for the standard local and OAuth flows.
+  if (auth.some(strategy => ['local', 'oauth'].includes(strategy)) && !auth.includes('jwt')) auth.unshift('jwt')
+  const databases = parseUniqueCsv(input.db ?? 'main:memory', '--db').map(spec => {
+    const match = /^([a-z][a-z0-9-]{0,31}):([a-z]+)$/.exec(spec)
+    if (!match) throw new Error('Invalid --db: use alias:adapter[,alias:adapter]')
+    const [, alias, adapter] = match
+    requiredChoice(adapter, DATABASE_PRESETS, '--db adapter')
+    return { alias, adapter }
+  })
+  if (new Set(databases.map(db => db.alias)).size !== databases.length) throw new Error('Duplicate database connection alias')
+  const primary = input.primary ?? 'main'
+  if (!databases.some(db => db.alias === primary)) throw new Error('--primary must match a --db alias')
+  return { name, ui, render, engine, pwa, schema, transport, auth, databases, primary, dryRun: true, json: Boolean(input.json) }
+}