@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/development/frontend/routes/cli/scaffold-routes/__tests__/generate.test.ts

@@ -0,0 +1,292 @@
+/**
+ * scaffold-routes / generate.test.ts (2026-05-27)
+ *
+ * Covers the three regressions reported alongside the GAF/REFERENTIELS
+ * post-mortem:
+ *  - Bug D: parentSection nests the componentKey (and the URL helper) so the
+ *           navigation DB's 4-segment key for sub-resources actually resolves.
+ *  - Bug E: `create` + `edit` views share the same `${E}FormPage` lazy const
+ *           — emit it exactly once so the registry compiles.
+ *  - Bug F: `module-home` view emits the 2-segment `{app}.{module}` key, not
+ *           the redundant `{app}.{module}.module-home.module-home`.
+ *
+ * Plus a couple of guard-rail tests that lock in the baseline contract so a
+ * future change can't silently regress the basic 3-segment list/detail/create
+ * key shape.
+ */
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import { validateComponentKey } from '../types.js'
+import type { ScaffoldRoutesInput } from '../types.js'
+
+function fixture(overrides: Partial<ScaffoldRoutesInput> = {}): ScaffoldRoutesInput {
+  return {
+    module: 'crm',
+    appCode: 'app',
+    entities: [
+      {
+        name: 'Contact',
+        section: 'contacts',
+        views: ['list', 'detail', 'create', 'edit'],
+      },
+    ],
+    projectPath: '/test',
+    ...overrides,
+  } as ScaffoldRoutesInput
+}
+
+describe('scaffold-routes / generate — baseline contract', () => {
+  it('emits a 3-segment componentKey for the list view', () => {
+    const files = generate(fixture())
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts', ContactsListPage)")
+  })
+
+  it('emits 4-segment keys for detail/edit/create', () => {
+    const files = generate(fixture())
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts.detail',")
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts.edit',")
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts.create',")
+  })
+
+  it('uses the BA-supplied pluralName instead of `${name}s`', () => {
+    const files = generate(fixture({
+      entities: [{
+        name: 'Rue',
+        pluralName: 'Rues',
+        section: 'rues',
+        views: ['list'],
+      }],
+    }))
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toMatch(/const RuesListPage = lazyWithRetry/)
+    expect(registry.content).not.toMatch(/const RusListPage/) // naive fallback would be wrong
+  })
+})
+
+describe('scaffold-routes / generate — Bug D (parentSection nesting)', () => {
+  it('nests sub-resource componentKeys under parentSection', () => {
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'QualificatifTypeAudit',
+        pluralName: 'QualificatifTypeAudits',
+        section: 'types-audit',
+        parentSection: 'types-affaire',
+        views: ['list', 'detail', 'create', 'edit'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    // List view: 4-segment key matches the navigation DB
+    expect(registry.content).toContain("'gaf.referentiels.types-affaire.types-audit'")
+    // Detail/edit/create: 5-segment keys
+    expect(registry.content).toContain("'gaf.referentiels.types-affaire.types-audit.detail'")
+    expect(registry.content).toContain("'gaf.referentiels.types-affaire.types-audit.edit'")
+    expect(registry.content).toContain("'gaf.referentiels.types-affaire.types-audit.create'")
+    // The flat (broken) 3-segment key must NOT appear
+    expect(registry.content).not.toContain("'gaf.referentiels.types-audit'")
+  })
+
+  it('nests sub-resource default import paths under parentSection', () => {
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'Rue',
+        pluralName: 'Rues',
+        section: 'rues',
+        parentSection: 'sites',
+        views: ['list', 'detail'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("import('@/pages/gaf/referentiels/sites/rues/RuesListPage')")
+    expect(registry.content).toContain("import('@/pages/gaf/referentiels/sites/rues/RueDetailPage')")
+  })
+
+  it('nests sub-resource URL helpers under parentSection', () => {
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'Rue',
+        pluralName: 'Rues',
+        section: 'rues',
+        parentSection: 'sites',
+        views: ['list', 'detail', 'edit', 'create'],
+      }],
+      projectPath: '/test',
+    })
+    const routes = files.find(f => f.path.includes('Routes'))!
+    expect(routes.content).toContain("list: () => '/gaf/referentiels/sites/rues'")
+    expect(routes.content).toContain("detail: (id: string) => `/gaf/referentiels/sites/rues/${id}`")
+    expect(routes.content).toContain("edit: (id: string) => `/gaf/referentiels/sites/rues/${id}/edit`")
+    expect(routes.content).toContain("create: () => '/gaf/referentiels/sites/rues/create'")
+  })
+
+  it('flat entities (no parentSection) still emit 3-segment URLs — backward compat', () => {
+    const files = generate(fixture())
+    const routes = files.find(f => f.path.includes('Routes'))!
+    expect(routes.content).toContain("list: () => '/app/crm/contacts'")
+    // No spurious empty segment in the URL literals themselves (grepping the
+    // whole file would catch the `//` in the header banner).
+    expect(routes.content).not.toMatch(/'\/[^']*\/\/[^']*'/) // empty path segment in a single-quoted URL
+    expect(routes.content).not.toMatch(/`\/[^`]*\/\/[^`]*`/) // empty path segment in a template URL
+  })
+
+  it('accepts 5-segment sub-resource keys (validateComponentKey upper limit bumped to 5)', () => {
+    expect(validateComponentKey('gaf.referentiels.types-affaire.types-audit')).toBeNull()
+    expect(validateComponentKey('gaf.referentiels.types-affaire.types-audit.detail')).toBeNull()
+    // 6 segments still rejected
+    expect(validateComponentKey('a.b.c.d.e.f')).toMatch(/must be between 2 and 5/)
+  })
+})
+
+describe('scaffold-routes / generate — Bug E (deduplicate FormPage const for create+edit)', () => {
+  it('emits exactly one `const ContactFormPage = lazyWithRetry` when both create and edit are requested', () => {
+    const files = generate(fixture())
+    const registry = files.find(f => f.path.includes('Registry'))!
+    const matches = registry.content.match(/const ContactFormPage = lazyWithRetry/g) ?? []
+    expect(matches).toHaveLength(1)
+    // …but BOTH keys still register against that single const
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts.create', ContactFormPage)")
+    expect(registry.content).toContain("PageRegistry.register('app.crm.contacts.edit', ContactFormPage)")
+  })
+
+  it('still emits a single const when only one of create/edit is present', () => {
+    const files = generate(fixture({
+      entities: [{
+        name: 'Contact',
+        section: 'contacts',
+        views: ['list', 'edit'], // edit only
+      }],
+    }))
+    const registry = files.find(f => f.path.includes('Registry'))!
+    const matches = registry.content.match(/const ContactFormPage = lazyWithRetry/g) ?? []
+    expect(matches).toHaveLength(1)
+  })
+
+  it('does not collapse distinct page names — list and detail remain separate consts', () => {
+    const files = generate(fixture())
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toMatch(/const ContactsListPage = lazyWithRetry/)
+    expect(registry.content).toMatch(/const ContactDetailPage = lazyWithRetry/)
+    expect(registry.content).toMatch(/const ContactFormPage = lazyWithRetry/)
+  })
+})
+
+describe('scaffold-routes / generate — Fix #4 (React.ComponentType<unknown> matches lazyWithRetry constraint)', () => {
+  it('emits React.ComponentType<unknown> in the module-cast (NOT bare React.ComponentType)', () => {
+    // The SmartStack `lazyWithRetry<T extends ComponentType<unknown>>` constraint
+    // rejects `ComponentType<{}>` (the implicit shape of bare
+    // `React.ComponentType`). Without the explicit generic, every registration
+    // failed TS compilation — `audit-dev-frontend` had to auto-heal every run.
+    const files = generate(fixture())
+    const registry = files.find(f => f.path.includes('Registry'))!
+    // Positive: every cast carries `<unknown>`.
+    expect(registry.content).toMatch(/default\?: React\.ComponentType<unknown>;/)
+    expect(registry.content).toMatch(/ContactsListPage\?: React\.ComponentType<unknown>/)
+    // Negative: the bare form (without `<…>`) MUST NOT leak back.
+    expect(registry.content).not.toMatch(/default\?: React\.ComponentType;/)
+  })
+})
+
+describe('scaffold-routes / generate — Bug F (module-home is the 2-segment app.module root)', () => {
+  it('generates a 2-segment key for the module-home view (no redundant suffix)', () => {
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'ReferentielsHome',
+        pluralName: 'ReferentielsHome',
+        section: 'module-home',
+        views: ['module-home'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("PageRegistry.register('gaf.referentiels', ")
+    expect(registry.content).not.toContain("'gaf.referentiels.module-home.module-home'")
+    expect(registry.content).not.toContain("'gaf.referentiels.module-home'")
+  })
+
+  it('renders a valid TypeScript identifier for hub-view page names (no hyphens)', () => {
+    // Regression: the legacy `view.charAt(0).toUpperCase() + view.slice(1)`
+    // produced `Module-homePage` — invalid identifier, breaks the build the
+    // moment a module-home entity is in the spec.
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'ReferentielsHome',
+        pluralName: 'ReferentielsHome',
+        section: 'module-home',
+        views: ['module-home'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toMatch(/const ReferentielsHomeModuleHomePage = lazyWithRetry/)
+    expect(registry.content).not.toMatch(/Module-home/)
+  })
+
+  it('section-home view registers under the section root (same key as list)', () => {
+    const files = generate({
+      module: 'referentiels',
+      appCode: 'gaf',
+      entities: [{
+        name: 'ReferentielsHome',
+        pluralName: 'ReferentielsHome',
+        section: 'home',
+        views: ['section-home'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    // section-home shares its key with the list view by design (3-segment)
+    expect(registry.content).toContain("PageRegistry.register('gaf.referentiels.home', ")
+  })
+
+  // Bug 7 — kanban + reconduction first-class views
+  it('kanban view registers with key {app}.{module}.{section}.kanban + URL helper', () => {
+    const files = generate({
+      module: 'affaires',
+      appCode: 'gaf',
+      entities: [{
+        name: 'Demande',
+        pluralName: 'Demandes',
+        section: 'demandes',
+        views: ['list', 'kanban'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("PageRegistry.register('gaf.affaires.demandes.kanban', ")
+    expect(registry.content).toMatch(/const DemandeKanbanPage = lazyWithRetry/)
+    const routesFile = files.find(f => f.path.includes('Routes'))!
+    expect(routesFile.content).toMatch(/kanban: \(\) => '\/gaf\/affaires\/demandes\/kanban'/)
+  })
+
+  it('reconduction view registers with key {app}.{module}.{section}.reconduction + URL helper', () => {
+    const files = generate({
+      module: 'affaires',
+      appCode: 'gaf',
+      entities: [{
+        name: 'Demande',
+        pluralName: 'Demandes',
+        section: 'demandes',
+        views: ['list', 'reconduction'],
+      }],
+      projectPath: '/test',
+    })
+    const registry = files.find(f => f.path.includes('Registry'))!
+    expect(registry.content).toContain("PageRegistry.register('gaf.affaires.demandes.reconduction', ")
+    expect(registry.content).toMatch(/const DemandeReconductionPage = lazyWithRetry/)
+    const routesFile = files.find(f => f.path.includes('Routes'))!
+    expect(routesFile.content).toMatch(/reconduction: \(\) => '\/gaf\/affaires\/demandes\/reconduction'/)
+  })
+})

package/templates/skills/development/frontend/routes/cli/scaffold-routes/generate.ts

@@ -0,0 +1,270 @@
+/**
+ * cli:scaffold-routes — generate.ts
+ *
+ * Emits PageRegistry registrations matching SmartStack's dynamic routing
+ * contract. The `componentKey` MUST be the dotted form derived from the route
+ * by SmartStack (`/{app}/{module}/{section}` → `{app}.{module}.{section}`)
+ * with optional sub-view suffix (`.create`, `.detail`, `.edit`) for non-list
+ * views. Anything else (kebab keys, missing app prefix, missing section
+ * segment) silently fails — DynamicRouter never resolves the page and the
+ * user sees a perpetual spinner with no error in the console.
+ *
+ * Generated code imports from `@atlashub/smartstack` (npm package), not from
+ * the SmartStack.app source tree. The page paths use the `@/pages/...` alias
+ * configured in the client's `vite.config.ts` / `tsconfig.json`.
+ *
+ * See `GET /api/navigation/menu` for the authoritative key list.
+ */
+import type { ScaffoldRoutesInput, GeneratedFile } from './types.js'
+import { validateComponentKey } from './types.js'
+
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+/** kebab → PascalCase (`module-home` → `ModuleHome`). Used to render the hub
+ *  view names as valid TypeScript identifiers in the lazyWithRetry consts —
+ *  the legacy `view.charAt(0).toUpperCase() + view.slice(1)` produced
+ *  `Module-homePage` which is a parse error. */
+function kebabToPascal(s: string): string {
+  const camel = kebabToCamel(s)
+  return camel.charAt(0).toUpperCase() + camel.slice(1)
+}
+
+export function generate(spec: ScaffoldRoutesInput): GeneratedFile[] {
+  const files: GeneratedFile[] = []
+  const registrations: string[] = []
+  const lazyBindings: string[] = []
+  // Dedup tracker (Bug E, 2026-05-27): both `create` and `edit` views map to
+  // the same `${Entity}FormPage` const, so we must emit the lazyWithRetry
+  // const exactly once per page name — even if both views appear in
+  // `entity.views`. Registrations against different keys still happen for
+  // each view, but they all reference the single shared const.
+  const emittedConsts = new Set<string>()
+  const appLower = spec.appCode.toLowerCase()
+  const invalidKeys: string[] = []
+
+  for (const entity of spec.entities) {
+    // Sub-resource nesting (Bug D, 2026-05-27): when `parentSection` is set,
+    // every key/path/URL gains an extra segment between the module and the
+    // section. This mirrors how the SmartStack navigation DB stores 4-segment
+    // keys for nested resources (`gaf.referentiels.types-affaire.types-audit`)
+    // — without the parent segment, DynamicRouter couldn't resolve the page.
+    const sectionKey = entity.parentSection
+      ? `${appLower}.${spec.module}.${entity.parentSection}.${entity.section}`
+      : `${appLower}.${spec.module}.${entity.section}`
+    const basePath = entity.parentSection
+      ? `@/pages/${appLower}/${spec.module}/${entity.parentSection}/${entity.section}`
+      : `@/pages/${appLower}/${spec.module}/${entity.section}`
+    // List pages use the plural entity name (BudgetsListPage.tsx) to match
+    // scaffold-component; detail/form stay singular. When the BA passes an
+    // explicit `pluralName` we use it verbatim (covers irregular plurals like
+    // `Categories`/`Rues`); otherwise we fall back to the naive `${name}s`.
+    const pluralName = entity.pluralName ?? `${entity.name}s`
+
+    /**
+     * Convert a project-relative file path (e.g. `src/pages/budgeting/budgets/
+     * BudgetsListPage.tsx`) to the import path expected by Vite's `@` alias
+     * (`@/pages/budgeting/budgets/BudgetsListPage`). Strips the leading `src/`
+     * + the `.tsx` suffix.
+     */
+    const toImportPath = (relPath: string): string => {
+      const normalised = relPath.replace(/\\/g, '/').replace(/\.tsx$/i, '')
+      return normalised.startsWith('src/')
+        ? `@/${normalised.slice(4)}`
+        : `@/${normalised.replace(/^\.?\//, '')}`
+    }
+
+    for (const view of entity.views) {
+      // The enum is exhaustive at the schema level; the final fallback covers
+      // future view kinds and uses kebabToPascal so hyphenated hub views
+      // (`module-home` → `ModuleHome`) emit valid TypeScript identifiers.
+      const viewStr = view as string
+      const pageName = view === 'list' ? `${pluralName}ListPage`
+        : view === 'detail' ? `${entity.name}DetailPage`
+        : view === 'create' || view === 'edit' ? `${entity.name}FormPage`
+        : `${entity.name}${kebabToPascal(viewStr)}Page`
+
+      // pageFilePaths override (from pageSpec.filePath) wins over the derived
+      // basePath. This lets the registry import from the project's actual
+      // page location (e.g. `pages/budgeting/...`) without forcing a folder
+      // rename when scaffold-component's default convention (`pages/{module}/...`)
+      // doesn't match the legacy layout.
+      const overridePath = entity.pageFilePaths?.[view]
+      const importPath = overridePath
+        ? toImportPath(overridePath)
+        : `${basePath}/${pageName}`
+      // Update pageName when the override file name differs from the default
+      // (e.g. legacy `BudgetsHomePage.tsx` instead of `BudgetsListPage.tsx`)
+      // so the registry export resolution still finds a named export.
+      const overrideBaseName = overridePath
+        ? overridePath.replace(/\\/g, '/').replace(/^.*\//, '').replace(/\.tsx$/i, '')
+        : pageName
+      const effectiveName = overridePath ? overrideBaseName : pageName
+
+      // Hub views resolve to special-shaped keys (Bug F, 2026-05-27):
+      //   `module-home`  →  `{app}.{module}`              (the module root)
+      //   `section-home` →  `{app}.{module}.{section}`    (the section root — same as `list`)
+      // Without these special cases, `module-home` produced the redundant
+      // 4-segment `{app}.{module}.module-home.module-home` (when the entity
+      // section was also called `module-home`) which DynamicRouter never matches.
+      // `app-home` is left at its default for now — surface a follow-up bug
+      // if it bites.
+      const key = view === 'module-home'
+        ? `${appLower}.${spec.module}`
+        : view === 'list' || view === 'section-home'
+          ? sectionKey
+          : `${sectionKey}.${view}`
+
+      // Fail fast: invalid componentKey is unrecoverable at runtime (silent
+      // spinner) so we refuse to emit the registry.
+      const validationError = validateComponentKey(key)
+      if (validationError) {
+        invalidKeys.push(validationError)
+        continue
+      }
+
+      // Wrap each lazyWithRetry() in `.then((m) => ({ default: m.X ?? m.default }))`
+      // so the import works whether the page is exported as `default` or as
+      // a named export matching `pageName`. Generated SmartStack pages use
+      // named exports; bare `lazyWithRetry(() => import(...))` resolves to
+      // `undefined` for those and mounts an empty Suspense fallback —
+      // invisible spinner forever. We also throw at resolution time if
+      // neither export exists, so the failure surfaces as a developer-readable
+      // error instead of a silent spinner.
+      //
+      // `lazyWithRetry` (vs bare `React.lazy`) wraps the dynamic import in an
+      // exponential-backoff retry. Transient `Failed to fetch dynamically
+      // imported module` errors (HMR rebundle window, CDN flap, stale chunk
+      // after deploy) resolve on retry instead of surfacing as a RouteErrorBoundary.
+      //
+      // Bug E (2026-05-27): we emit the const at most once per page name —
+      // both `create` and `edit` views share `${Entity}FormPage`, and TS
+      // refuses to compile a module with duplicate `const` declarations.
+      if (!emittedConsts.has(effectiveName)) {
+        emittedConsts.add(effectiveName)
+        // Explicit `<unknown>` matches the generic constraint of
+        // `lazyWithRetry<T extends ComponentType<unknown>>` in
+        // @atlashub/smartstack. The bare `React.ComponentType` defaults to
+        // `ComponentType<{}>`, which fails the constraint and Vite/TS
+        // refuses the assignment (`Argument of type '() => Promise<{ default
+        // … }>' is not assignable to parameter of type … ComponentType<unknown>`).
+        lazyBindings.push(
+          `const ${effectiveName} = lazyWithRetry(() =>
+  import('${importPath}').then((m) => {
+    const mod = m as { default?: React.ComponentType<unknown>; ${effectiveName}?: React.ComponentType<unknown> };
+    const resolved = mod.${effectiveName} ?? mod.default;
+    if (!resolved) {
+      throw new Error("Page '${effectiveName}' at ${importPath} has no default or named export matching its file name.");
+    }
+    return { default: resolved };
+  })
+);`
+        )
+      }
+      registrations.push(`PageRegistry.register('${key}', ${effectiveName});`)
+    }
+  }
+
+  if (invalidKeys.length > 0) {
+    throw new Error(
+      `scaffold-routes: refusing to emit ${invalidKeys.length} invalid componentKey(s) — fix the spec first:\n  - ${invalidKeys.join('\n  - ')}`
+    )
+  }
+
+  files.push({
+    path: `src/extensions/${spec.module}Registry.ts`,
+    content: `import React from 'react';
+import { PageRegistry, lazyWithRetry } from '@atlashub/smartstack';
+
+// ============================================================================
+// ${spec.module.toUpperCase()} MODULE — Auto-generated route registrations
+// ============================================================================
+//
+// Generated by skills/development/frontend/routes/cli/scaffold-routes.
+// Do NOT edit by hand — re-run the CLI to regenerate.
+//
+// componentKey contract: dotted form ({app}.{module}.{section}[.{view}]),
+// must equal the value returned by GET /api/navigation/menu for the matching
+// route. Mismatch = silent spinner (DynamicRouter cannot resolve the page).
+//
+// This file MUST be imported from src/main.tsx BEFORE <App/> renders so the
+// registrations run before the first route resolution. Import example:
+//   import './extensions/${spec.module}Registry';
+
+${lazyBindings.join('\n\n')}
+
+${registrations.join('\n')}
+`,
+  })
+
+  // Emit a per-module routes helper alongside the registry. Generated pages
+  // import from this file rather than hardcoding `navigate('/foo/bar/new')`,
+  // so URL paths and registry componentKeys stay in lockstep. Audit
+  // DEV-UI-013 catches any page that bypasses it (hardcoded absolute URL in
+  // navigate()).
+  //
+  // URL convention — must match the Core Navigation Seed which registers
+  // routes as /{app}/{module}/{section} (3-seg). Without the app prefix
+  // the URL helpers don't resolve to the menu entries seeded in DB and
+  // DynamicRouter falls back to misinterpreting (e.g. /budgets/budgets/budgets
+  // gets routed to /budgets/budgets/:id with id="budgets" → "introuvable"):
+  //   list   → /{app}/{module}/{section}                  (componentKey = section root)
+  //   detail → /{app}/{module}/{section}/${id}            (.detail suffix)
+  //   edit   → /{app}/{module}/{section}/${id}/edit       (.edit suffix)
+  //   create → /{app}/{module}/{section}/create           (.create suffix — NOT /new)
+  // Pages MUST navigate via these helpers — hardcoding `/new` or `./new/edit`
+  // produces a route DynamicRouter cannot resolve (silent spinner). Audit
+  // DEV-UI-013 catches the drift.
+  const sectionEntries = spec.entities
+    .map((entity) => {
+      const views = new Set(entity.views)
+      const lines: string[] = []
+      // Sub-resource URLs mirror the componentKey nesting: a sub-resource
+      // under `types-affaire` reads `/gaf/referentiels/types-affaire/types-audit`,
+      // not the flat `/gaf/referentiels/types-audit`. Without the parent
+      // segment, the Core Navigation Seed has no matching menu entry and the
+      // detail/edit pages 404.
+      const urlBase = entity.parentSection
+        ? `/${appLower}/${spec.module}/${entity.parentSection}/${entity.section}`
+        : `/${appLower}/${spec.module}/${entity.section}`
+      lines.push(`  ${kebabToCamel(entity.section)}: {`)
+      lines.push(`    list: () => '${urlBase}',`)
+      if (views.has('detail')) lines.push(`    detail: (id: string) => \`${urlBase}/\${id}\`,`)
+      if (views.has('edit')) lines.push(`    edit: (id: string) => \`${urlBase}/\${id}/edit\`,`)
+      if (views.has('create')) lines.push(`    create: () => '${urlBase}/create',`)
+      if (views.has('dashboard')) lines.push(`    dashboard: () => '${urlBase}/dashboard',`)
+      if (views.has('kanban')) lines.push(`    kanban: () => '${urlBase}/kanban',`)
+      if (views.has('reconduction')) lines.push(`    reconduction: () => '${urlBase}/reconduction',`)
+      lines.push(`  },`)
+      return lines.join('\n')
+    })
+    .join('\n')
+
+  files.push({
+    path: `src/extensions/${spec.module}Routes.ts`,
+    content: `// ============================================================================
+// ${spec.module.toUpperCase()} MODULE — Auto-generated URL helpers
+// ============================================================================
+//
+// Single source of truth for URL paths in the ${spec.module} module. Generated
+// alongside ${spec.module}Registry.ts by skills/development/frontend/routes/cli/scaffold-routes.
+// Do NOT edit by hand — re-run the CLI to regenerate.
+//
+// Generated pages MUST consume these helpers instead of hardcoding URLs in
+// navigate() calls. Audit DEV-UI-013 rejects any *Page.tsx that uses an
+// absolute string literal in navigate(...).
+//
+// Usage example:
+//   import { routes } from '@/extensions/${spec.module}Routes';
+//   navigate(routes.budgets.detail(item.id));
+//   navigate(routes.budgets.create());
+
+export const routes = {
+${sectionEntries}
+} as const;
+`,
+  })
+
+  return files
+}

package/templates/skills/development/frontend/routes/cli/scaffold-routes/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-routes — Generate PageRegistry entries
+ */
+import { parseArgs } from 'node:util'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, join } from 'node:path'
+import { validate } from './validate.js'
+import { generate } from './generate.js'
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js'
+
+const COMMAND = 'scaffold-routes'
+
+function main(): void {
+  const { values } = parseArgs({ options: { spec: { type: 'string' }, outdir: { type: 'string' }, dry_run: { type: 'boolean', default: false } }, strict: true })
+  if (!values.spec) { printEnvelope(failGenerate(COMMAND, ['--spec is required'])); process.exit(1) }
+  let raw: unknown
+  try { raw = JSON.parse(values.spec) } catch { printEnvelope(failGenerate(COMMAND, ['Invalid JSON'])); process.exit(1) }
+  const validation = validate(raw)
+  if (!validation.valid) { printEnvelope(failGenerate(COMMAND, validation.errors)); process.exit(1) }
+  const spec = raw as any
+  const files = generate(spec)
+  if (values.dry_run) {
+    printEnvelope(generateEnvelope(COMMAND, { data: { dryRun: true, files: files.map(f => f.path) }, warnings: validation.warnings }))
+    process.exit(0)
+  }
+  const outdir = values.outdir ?? spec.projectPath
+  const written: string[] = []
+  for (const file of files) { const p = resolve(join(outdir, file.path)); mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, file.content, 'utf-8'); written.push(p) }
+  const nextSteps: string[] = [
+    `Import the registry in src/main.tsx BEFORE createRoot: import './extensions/${spec.module}Registry';`,
+    'Without this import, PageRegistry.register() never runs and every route in this module renders blank.',
+  ]
+  if (validation.warnings.length > 0) nextSteps.unshift('Scaffold missing pages (see warnings) BEFORE writing the registry — phantom imports crash Vite at launch')
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { module: spec.module, fileCount: written.length },
+    filesCreated: written,
+    warnings: validation.warnings,
+    nextSteps,
+  }))
+}
+main()