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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vite-plugin-feathersjs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# create-feathers-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Générez des applications FeathersJS v5 avec Vue 3, Pinia, Vite, Quasar 2 ou Tailwind CSS + daisyUI.
+
+Le CLI est indépendant du runtime [`@vevedh/vite-plugin-feathersjs`](https://www.npmjs.com/package/@vevedh/vite-plugin-feathersjs) (version 0.2.6). La version candidate `0.1.0-rc.4` **n'est pas encore publiée**. Elle ajoute la PWA optionnelle au rendu SPA.
+
+## Usage
+
+```powershell
+# Préversion disponible sur npm : 0.1.0-rc.1
+npm exec --yes --package=@vevedh/create-feathers-app@0.1.0-rc.1 -- create-feathers-app portail --ui daisyui --render spa
+
+# R17-r3 candidat, depuis les sources mises en stage :
+node .release/create-feathers-app/bin/create-feathers-app.mjs portail-ssr --ui quasar2 --render ssr
+```
+
+| Interface | SPA | SSR | SSG |
+| --- | --- | --- | --- |
+| Quasar 2 | Générable | Générable, validation Windows en cours | Bloqué |
+| daisyUI 5 | Générable | Générable | Générable |
+
+## PWA optionnelle (SPA uniquement)
+
+Le paramètre `--pwa on` ajoute `vite-plugin-pwa` v2 en dépendance de développement, une icône SVG locale de démonstration et un manifeste Web App. Le service worker, désactivé en développement, est généré au build et conserve uniquement des ressources statiques, jamais les réponses `/api` ou les échanges Socket.IO. Par défaut, `--pwa off` ne change pas les templates existants.
+
+```powershell
+node .release/create-feathers-app/bin/create-feathers-app.mjs portail-spa --ui quasar2 --render spa --pwa on --dry-run
+```
+
+SSR/SSG avec PWA est refusé tant que leur cycle de vie n'est pas certifié. Pour une installation sur les navigateurs ciblés, remplacer l'icône SVG de démonstration par des icônes PNG 192 et 512 pixels, puis contrôler HTTPS, les mises à jour et le mode hors-ligne.
+
+## Ajouter un service Feathers
+
+```powershell
+cd portail
+node ../chemin/vers/create-feathers-app/bin/create-feathers-app.mjs service add tickets --schema zod --db main
+```
+
+Le générateur ajoute le module `api/services/tickets` et son inscription dans le registre Feathers. Les schémas disponibles sont `typebox`, `json` et `zod`. Le service mémoire est destiné au laboratoire local, avec CRUD REST et validation des données.
+
+## Profils d'identité et de bases
+
+La création de projet accepte `--auth none|jwt|oauth2|oidc|keycloak`, `--schema typebox|json|zod` et `--db main:memory,audit:mongodb` avec alias nommés. **Les authentifications externes et les connexions persistantes sont des profils de configuration, pas des intégrations opérationnelles.** L'API échoue volontairement au démarrage jusqu'au raccordement et à la certification du fournisseur ou du SGBD.
+
+Les projets sans authentification sont exclusivement des démonstrations locales. Ils ne doivent jamais être exposés tels quels sur Internet. Aucun secret, mot de passe ou jeton n'est inclus dans les templates.
+
+## Windows
+
+```powershell
+corepack pnpm install
+corepack pnpm run typecheck
+corepack pnpm run build
+corepack pnpm run dev:all
+```
+
+SPA et daisyUI SSR/SSG utilisent `http://127.0.0.1:5173`. Quasar SSR utilise `http://127.0.0.1:8080` via un proxy local ; le SSR brut écoute sur 9100.
+
+La documentation publique VitePress figure dans `docs/cli` du dépôt et sera déployée sur GitHub Pages après activation du workflow de publication.
+
+## API Feathers intégrée à Vite en développement (RC4)
+
+Pour les applications SPA, `--dev-api vite` est désormais la valeur par défaut.
+Le plugin public `@vevedh/vite-plugin-feathersjs@0.2.6` est chargé depuis
+`vite.config.ts` et monte les services sur `/api` pendant `vite dev`.
+Il n'y a pas de second serveur REST ni de proxy REST à démarrer.
+
+L'option `--dev-api separate` conserve l'ancien comportement à deux processus.
+Pour SSR/SSG, le mode séparé reste obligatoire. Avec `--transport both`,
+Socket.IO reste sur le port privé `127.0.0.1:3031`, accessible depuis la SPA
+via le proxy WebSocket Vite. La configuration de Feathers échoue au chargement
+si les profils d'identité ou bases externes ne sont pas opérationnels.
+
+```powershell
+node .release/create-feathers-app/bin/create-feathers-app.mjs mon-spa --ui quasar2 --render spa --dev-api vite --transport both
+```
+
+**Production** : le plugin Vite s'exécute uniquement en développement.
+Le serveur `api/server.mjs` autonome reste disponible et obligatoire pour
+le déploiement ; `vite preview` n'héberge pas l'API.
+Le runtime `0.2.6` n'a pas été modifié.

package/bin/create-feathers-app.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { dirname,resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readFile } from 'node:fs/promises'
+import { createGenerator } from '../lib/scaffold.mjs'
+import { runServiceCommand } from '../lib/services.mjs'
+const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'..')
+const {version}=JSON.parse(await readFile(resolve(packageRoot,'package.json'),'utf8'))
+const args=process.argv.slice(2)
+if(args.includes('--help')||args.includes('-h')||!args.length){
+  console.log(`create-feathers-app ${version}
+
+Usage: create-feathers-app <name> [options]
+  --name <name>       Project name (alternative to positional name)
+  --dir <directory>   Safe folder name (within current directory)
+  --ui <quasar2|daisyui>  Default daisyui
+  --render <spa|ssr|ssg>  Default spa
+  --adapter <koa|express>  Default koa
+  --transport <rest|both>  Default rest (both only for SPA)
+  --pwa <on|off>      Optional offline SPA shell (default off, no API caching)
+  --dev-api <vite|separate>    SPA default vite; SSR/SSG always separate
+  --dry-run           Preview files without writing
+  --json              Machine-readable output
+  --schema <typebox|json|zod>     Service schema preset (default typebox)
+  --auth <none|jwt|oauth2|oidc|keycloak>  Identity configuration blueprint
+  --db <alias:adapter[,alias:adapter]>    Named connections (default main:memory)
+  --version           Print CLI version
+
+Service: create-feathers-app service add <name> [--project <path>] [--schema typebox|json|zod] [--db <alias>] [--auth none|jwt] [--dry-run]
+
+Available: Quasar 2 SPA/SSR; daisyUI SPA, SSR, SSG.
+Quasar SSR uses the R16-certified architecture; R17-generated SSR requires its own Windows E2E certification. Quasar SSG not supported.`)
+}else if(args.includes('--version')||args.includes('-v'))console.log(version)
+else if(args[0]==='service') {
+  try { await runServiceCommand(args.slice(1),process.cwd()) } catch(error){console.error(`FAIL: ${error.message}`);process.exitCode=1}
+}
+else {
+  const {parse,generate}=createGenerator({outputRoot:process.cwd(),templatesRoot:resolve(packageRoot,'templates'),reportRoot:process.cwd()})
+  try {
+    const options=parse(args)
+    const result=await generate(options)
+    console.log(options.json?JSON.stringify(result,null,2):`${options.dryRun?'DRY RUN':'CREATED'}: ${result.destination} (${result.files.length} files)`)
+  } catch(error){console.error(`FAIL: ${error.message}`);process.exitCode=1}
+}

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) }
+}

package/lib/planner/plan.mjs

@@ -0,0 +1,107 @@
+import { normalizePlanOptions } from './options.mjs'
+
+const DATABASE_PACKAGES = {
+  memory: ['@feathersjs/memory'],
+  mongodb: ['@feathersjs/mongodb', 'mongodb'],
+  postgresql: ['@feathersjs/knex', 'knex', 'pg'],
+  mariadb: ['@feathersjs/knex', 'knex', 'mysql2'],
+  mysql: ['@feathersjs/knex', 'knex', 'mysql2'],
+  sqlite: ['@feathersjs/knex', 'knex'],
+}
+const PROVIDERS = {
+  jwt: ['@feathersjs/authentication'],
+  local: ['@feathersjs/authentication-local'],
+  oauth: ['@feathersjs/authentication-oauth'],
+  oidc: [],
+  ldap: [],
+}
+/** Deterministic, read-only plan. This is a capability contract, NOT a scaffold.
+ * Store no connection URLs or authentication secrets in this plan.
+ */
+export function buildProjectPlan(rawOptions) {
+  const options = normalizePlanOptions(rawOptions)
+  const packages = new Set(['vite', 'vue', 'pinia', '@feathersjs/feathers', '@feathersjs/koa', '@vevedh/vite-plugin-feathersjs'])
+  const tasks = []
+  const warnings = []
+  if (options.ui === 'quasar2') {
+    if (options.engine === 'vite') {
+      for (const pkg of ['quasar', '@quasar/extras', '@quasar/vite-plugin@^1', 'sass-embedded']) packages.add(pkg)
+      tasks.push('Vite 7 requires @quasar/vite-plugin 1.x, which supports SPA only; certify Quasar 2 component compatibility.')
+    }
+    else {
+      for (const pkg of ['quasar', '@quasar/extras', '@quasar/app-vite']) packages.add(pkg)
+      tasks.push('Use Quasar CLI with Vite rather than @quasar/vite-plugin. Scaffold independently and certify integration with Feathers v5, services, Pinia, HMR and deployment.')
+      if (options.render === 'ssg') warnings.push('Quasar CLI Vite SSG is in beta: APIs and deployment requirements may change.')
+      warnings.push('Quasar CLI SSR/SSG + vite-plugin-feathersjs integration is NOT yet implemented or certified in this project.')
+    }
+  }
+  else {
+    for (const pkg of ['tailwindcss', '@tailwindcss/vite', 'daisyui']) packages.add(pkg)
+    if (options.ui === 'daisyui-kit') warnings.push('daisyUI kit is an external UI-template/preset selection; its license and assets are NOT bundled or installed by the planner.')
+    tasks.push('Use the Tailwind 4 Vite plugin and daisyUI CSS; avoid duplicate global UnoCSS/Tailwind resets.')
+    if (options.render === 'ssr') {
+      packages.add('@vue/server-renderer')
+      tasks.push('Build a Vite/Vue SSR server entry, isolated per-request Vue/Pinia state, HTML template and hydration, and certify dev and production SSR.')
+    }
+    if (options.render === 'ssg') {
+      packages.add('vite-ssg')
+      tasks.push('Prerender only public/static routes; verify generated HTML and client hydration, and use a separate Feathers API for dynamic data.')
+    }
+  }
+  if (options.render === 'ssr') {
+    warnings.push('SSR must isolate Pinia and authentication state per request; never serialize tokens, secrets or other users’ data into HTML.')
+    tasks.push('Define a production SSR server lifecycle, security headers, cache policy and explicit separation from Feathers REST/Socket.IO endpoints.')
+  }
+  if (options.render === 'ssg') {
+    warnings.push('SSG must not bake user-specific, authenticated or private content into static HTML; dynamic services require a running Feathers API.')
+  }
+  if (options.pwa === 'on') {
+    if (options.engine === 'vite') packages.add('vite-plugin-pwa')
+    tasks.push(options.engine === 'quasar-cli-vite' ? 'Configure Quasar CLI PWA takeover / offline mode for the selected SSR/SSG build, and certify separately.' : 'Configure manifest, icons, service worker lifecycle and offline caching; test update/recovery and HTTPS deployment.')
+  }
+  if (options.schema === 'typebox') {
+    packages.add('@feathersjs/typebox')
+    packages.add('@feathersjs/schema')
+  }
+  else if (options.schema === 'json') {
+    packages.add('@feathersjs/schema')
+    tasks.push('Generate plain JSON Schema and typed Ajv validators/resolvers; compile schema once, do not bypass query validation.')
+  }
+  else {
+    packages.add('zod')
+    warnings.push('Zod requires a Feathers v5 validation/resolver integration. The native TypeBox/Ajv generator cannot be reused unchanged.')
+    tasks.push('Implement and test dedicated Zod validation hooks for data, patch and query before enabling generated services.')
+  }
+  for (const strategy of options.auth.filter(item => item !== 'none')) {
+    for (const pkg of PROVIDERS[strategy]) packages.add(pkg)
+    if (strategy === 'oidc' || strategy === 'ldap') warnings.push(`${strategy.toUpperCase()} requires a separately implemented/audited authentication strategy and identity-provider configuration.`)
+  }
+  if (!options.auth.includes('none')) {
+    packages.add('@feathersjs/authentication-client')
+    tasks.push('Register AuthenticationService and per-service authenticate/authorize hooks; require RBAC for protected services.')
+  }
+  if (options.auth.includes('oauth')) tasks.push('Choose OAuth providers explicitly and configure redirect allowlists, callback HTTPS URLs, account linking and secret storage.')
+  for (const db of options.databases) for (const pkg of DATABASE_PACKAGES[db.adapter]) packages.add(pkg)
+  if (options.databases.some(db => db.adapter === 'sqlite')) warnings.push('Choose and certify a compatible SQLite driver for the target Node/Knex versions before implementation.')
+  if (options.databases.some(db => db.adapter === 'memory')) warnings.push('Memory adapter is for development/test: not durable production storage.')
+  if (options.databases.length > 1) tasks.push('Create separate named clients and bind each service to exactly one connection; cross-database transactions are not automatic.')
+  const connections = options.databases.map(({ alias, adapter }) => ({ alias, adapter, envKey: `FEATHERS_DB_${alias.replaceAll('-', '_').toUpperCase()}_URL`, isPrimary: alias === options.primary }))
+  const rendering = {
+    mode: options.render,
+    engine: options.engine,
+    deployment: options.render === 'ssr' ? 'node-ssr-runtime-required' : options.render === 'ssg' ? 'static-pages-plus-separate-feathers-api' : 'static-spa-plus-feathers-api',
+    hydrationRequired: options.render !== 'spa',
+    integrationStatus: 'not-generated-or-certified',
+  }
+  return {
+    version: 2, status: 'planning-only', writesFiles: false,
+    project: options.name,
+    stack: { vite: options.engine === 'vite' ? '7' : 'managed-by-quasar-cli', vue: '3', feathers: '5', pinia: true, ui: options.ui, render: options.render, renderEngine: options.engine, pwa: options.pwa === 'on', schema: options.schema, transport: options.transport },
+    rendering,
+    authentication: { strategies: options.auth, customIntegrationRequired: options.auth.filter(item => ['oidc', 'ldap'].includes(item)) },
+    database: { primary: options.primary, connections },
+    proposedPackages: [...packages].sort(),
+    implementationTasks: tasks,
+    warnings,
+  }
+}