@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-api-client — Generate TypeScript API clients + React Query hooks
+ */
+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-api-client'
+
+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) } }))
+    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) }
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { module: spec.module, fileCount: written.length },
+    filesCreated: written,
+    nextSteps: ['Run npm run build to verify'],
+  }))
+}
+main()

package/templates/skills/development/frontend/api-client/cli/scaffold-api-client/types.ts

@@ -0,0 +1,251 @@
+/**
+ * cli:scaffold-api-client — types.ts
+ */
+import { z } from 'zod'
+
+export const ApiFieldSchema = z.object({ name: z.string(), type: z.string(), required: z.boolean().default(true) })
+
+/**
+ * Per-page mode (Step 5 of the per-page vertical-slice refactor): every
+ * non-CRUD action declared in the BA's `BaScreen.Config.actions[]` adds:
+ *  - one method on `{entity}Service` (calls api.post(...))
+ *  - one React hook (useState/useEffect) wrapping the service call
+ *
+ * `action.code` is the **business identifier** (kebab-case) used for
+ * TypeScript member naming:
+ *  - service member name  =  toCamelCase(code)   → `toggleActif`
+ *  - hook name            =  `use` + toPascalCase(code) + Entity → `useToggleActifEmploye`
+ *
+ * `action.endpoint` (optional) is the **URL segment** matching the controller
+ * route attribute. When omitted, `code` is used as the URL segment
+ * (backward-compatible for controllers whose business and route names align).
+ * Use `endpoint` when the controller route diverges from the business
+ * identifier — e.g.:
+ *  - `code: 'toggle-actif'`  →  `endpoint: 'activate'`
+ *  - `code: 'sync-from-pce'` →  `endpoint: 'sync-from-proconcept'`
+ *  - `code: 'map-to-pce'`    →  `endpoint: 'map-proconcept'`
+ *
+ * The single source of truth across the pipeline lives in
+ * `lib/page-spec-actions.ts` (`PageCustomActionSchema`). See that file for the
+ * full contract; this schema is the per-CLI projection used by api-client
+ * generation only. ba-develop's Phase 3a spec-builder reads each controller's
+ * `[Http*("…")]` attributes to populate `endpoint` here.
+ *
+ * Hook name follows the canonical pattern : kebab → PascalCase + entity name.
+ *  - `archive` row              → `useArchiveBudget()` calls POST /api/.../{id}/archive
+ *  - `bulk-archive`             → `useBulkArchiveBudget()` calls POST /api/.../bulk/archive
+ *  - `export` header            → `useExportBudget()` calls POST /api/.../export
+ *  - `sync-from-proconcept`     → `useSyncFromProconceptBudget()` calls POST /api/.../sync-from-proconcept
+ *  - `toggle-actif` + endpoint:'activate'
+ *                               → `useToggleActifBudget()` calls POST /api/.../{id}/activate
+ *
+ * @see lib/page-spec-actions.ts (canonical PageCustomActionSchema)
+ */
+export const ApiCustomActionSchema = z.object({
+  code: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'code must be kebab-case'),
+  /** Distinguishes API-bound actions from pure client-side navigations.
+   *  `api`      → emits the service member + the React hook (the default).
+   *  `navigate` → emits NOTHING in scaffold-api-client (no service member,
+   *               no hook). The button is rendered by scaffold-component with
+   *               an inline `navigate(targetRoute)` call. Without this filter,
+   *               every "open detail" or "go to dashboard" button in the BA
+   *               pagespecs produced a phantom `POST /{id}/open` endpoint that
+   *               does not exist on any controller — 6 entities × 1 button =
+   *               6 systematic 404s in the REFERENTIELS post-mortem.
+   *  Mirrors the canonical `kind` field of `lib/page-spec-actions.ts`. */
+  kind: z.enum(['api', 'navigate']).default('api'),
+  /** URL segment used in the service call. When omitted, falls back to `code`.
+   *  Use when the controller route differs from the business identifier:
+   *    code: 'toggle-actif'  →  endpoint: 'activate'
+   *    code: 'sync-from-pce' →  endpoint: 'sync-from-proconcept'
+   *  Accepts single segments (`activate`) or slash-separated paths
+   *  (`dashboard/consolidated`) — every segment must be kebab-case. */
+  endpoint: z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/, 'endpoint must be kebab-case path segment(s)')
+    .optional(),
+  scope: z.enum(['row', 'bulk', 'header']).default('row'),
+  /** TypeScript payload type emitted in the hook signature (e.g.
+   *  `ApproveRequest`). When null, the mutation takes no body — just an id
+   *  for row-scope, or no args for header-scope. */
+  payloadType: z.string().nullable().optional(),
+  /** Optional shape for the `payloadType` interface. When provided, the
+   *  scaffolder emits `export interface ${payloadType} { ${field}: ${tsType}; ... }`
+   *  in `types/index.ts`. When omitted, a permissive placeholder
+   *  `interface ${payloadType} { [key: string]: unknown }` is emitted with a
+   *  TODO comment — this keeps TypeScript happy (no TS2304 « cannot find name »)
+   *  while signalling that BA work is needed to firm up the shape. Builtin
+   *  types (`string`, `string[]`, etc.) and DTOs already generated for the
+   *  entity (`${E}ListDto`, …) are never re-emitted. */
+  payloadShape: z.record(z.string(), z.string()).optional(),
+  /** TypeScript response type for the service method. `void` for 204
+   *  (no body) endpoints. */
+  responseType: z.string().min(1).default('void'),
+  /** Optional shape for the `responseType` interface. Same semantics as
+   *  `payloadShape` above. Skipped when `responseType` is `void`. */
+  responseShape: z.record(z.string(), z.string()).optional(),
+  /** HTTP method for the service call. Defaults to `post` for mutations.
+   *  Set to `get` for read-only actions like `export` whose backend
+   *  controller uses `[HttpGet]`. */
+  httpMethod: z.enum(['get', 'post', 'put', 'patch', 'delete']).default('post'),
+})
+
+/**
+ * One column from a pagespec — used in screen-driven mode (Wave F1) to shape
+ * the TypeScript `${E}ListDto` / `${E}DetailDto` interfaces from the BA contract
+ * (`pagespecs/<Entity>.<view>.md` → `columns[]`).
+ *
+ * - `key`        is the property name on the C# DTO (PascalCase on the wire,
+ *                JSON-serialised camelCase by ASP.NET → matches `key` as-is
+ *                when the BA author writes camelCase).
+ * - `formatHint` mirrors `scaffold-screen-controller`'s `dotnetTypeFor` so the
+ *                TypeScript field type matches the C# one byte-for-byte:
+ *                  currency/decimal/number → number
+ *                  integer/count           → number
+ *                  date/datetime           → string (ISO-8601)
+ *                  bool/boolean            → boolean
+ *                  guid/uuid               → string
+ *                  (default)               → string
+ *
+ * The same shape is used in the backend CLI's `PageSpecColumn` (see
+ * `templates/skills/development/backend/screen-controller/cli/scaffold-screen-controller/types.ts`).
+ * Drift between the two is caught by the integration test in
+ * `__tests__/screen-strata-contract.test.ts` (added in Wave F4).
+ */
+export const ApiScreenColumnSchema = z.object({
+  key: z.string().min(1),
+  formatHint: z.string().optional(),
+})
+
+export const ApiEntitySchema = z.object({
+  name: z.string().min(1),
+  pluralName: z.string().optional(),
+  section: z.string().min(1),
+  /**
+   * Sub-resource URL template (2026-05-27).
+   *
+   * When set, the entity is nested under a parent: every service method takes
+   * `parentId: string` as its first parameter and the API path is computed
+   * by substituting `{parentId}` in this template. Use for sub-resources whose
+   * controller route includes a parent ID, e.g.:
+   *   - Rue under Site:          '/api/gaf/referentiels/sites/{parentId}/rues'
+   *   - Qualificatif under Type: '/api/gaf/referentiels/types-affaire/{parentId}/qualificatifs/audit'
+   *
+   * When omitted, the standard flat URL applies (derived from `appCode` /
+   * `module` / `section` per the `routeMode`). Required substring: `{parentId}`.
+   *
+   * Constraint: incompatible with `useScreens: true` / `routeMode: 'screens'`
+   * (the screen stratum has no nested URL convention). The CLI surfaces an
+   * error if both are set.
+   */
+  parentPath: z
+    .string()
+    .min(1)
+    .regex(/^\/.*\{parentId\}.*$/, "parentPath must be an absolute URL containing the literal '{parentId}' placeholder")
+    .optional(),
+  /**
+   * Parameter name for the parent ID in emitted service / hook signatures.
+   * Defaults to `parentId`. Set to a domain-specific name (e.g. `siteId`,
+   * `typeAffaireId`) so generated code reads naturally to humans:
+   *   useRue(siteId: string, id: string)  vs  useRue(parentId: string, id: string)
+   */
+  parentIdParam: z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-zA-Z0-9]*$/, 'parentIdParam must be a camelCase identifier')
+    .default('parentId'),
+  fields: z.array(ApiFieldSchema).default([]),
+  customActions: z.array(ApiCustomActionSchema).default([]),
+  /**
+   * When true, the scaffolder also emits a typed wrapper for the entity's
+   * dashboard endpoints :
+   *   getConsolidated() → GET /api/{module}/{plural-kebab}/dashboard/consolidated
+   *   getAlerts()       → GET /api/{module}/{plural-kebab}/dashboard/alerts
+   * Plus a `useDashboard{Entity}` React Query hook bundling both calls
+   * (KPIs in `data.consolidated`, alerts in `data.alerts`).
+   * The companion `{Entity}DashboardPage.tsx` (scaffold-component view
+   * 'dashboard') consumes this hook — never raw axios.
+   */
+  hasDashboard: z.boolean().default(false),
+  /**
+   * Column contract for shaping the TypeScript DTOs (Wave F1, 2026-05-27;
+   * extended Wave F5, 2026-05-27).
+   *
+   * When provided, the `${E}ListDto` and `${E}DetailDto` interfaces are
+   * shaped from these pagespec columns — matching the C# DTO returned by the
+   * controller — in ALL route modes (direct, integration, screens). The
+   * historical `useScreens`-only gate has been removed: drift between the
+   * frontend TS interface and the backend C# DTO is a bug class we want
+   * eliminated regardless of stratum.
+   *
+   * The emitted shape:
+   *   { Id, <each list column>,   CreatedAt }                 (list)
+   *   { Id, <each detail column>, CreatedAt, UpdatedAt }      (detail)
+   *
+   * `/ba-develop` Phase 3a populates this by parsing every
+   * `<MODULE>/pagespecs/<Entity>.<view>.md` for the entity and collecting the
+   * `columns[]` JSON block.
+   *
+   * When absent — only when the spec carries no pagespec column data — the
+   * CLI falls back to `entity.fields.slice(0,5)` (legacy heuristic) so older
+   * pipelines that haven't wired pagespec extraction yet still emit a
+   * well-formed interface.
+   *
+   * The field name retains the historical `screenColumns` for backward
+   * compatibility with existing /ba-develop spec builders; the columns
+   * themselves are not screen-mode specific.
+   */
+  screenColumns: z.object({
+    list: z.array(ApiScreenColumnSchema).optional(),
+    detail: z.array(ApiScreenColumnSchema).optional(),
+  }).optional(),
+})
+
+export const ScaffoldApiClientInputSchema = z.object({
+  module: z.string().min(1),
+  appCode: z.string().min(1),
+  entities: z.array(ApiEntitySchema).min(1),
+  projectPath: z.string().min(1),
+  /**
+   * Route mode — selects which URL convention the api-client emits.
+   *
+   *   'direct' (default) — `/api/{appCode}/{module}/{section}`.
+   *     The standard SmartStack controller route emitted by Phase 2a.
+   *     Path is computed from the spec's `appCode`, `module`, and each
+   *     entity's `section`. REST CRUD methods.
+   *
+   *   'integration' — `/api/v1/integration/{plural-kebab}`.
+   *     Legacy machine-to-machine stratum. Use when the backend
+   *     controller was generated by `scaffold-controller`.
+   *
+   *   'screens' — `/api/screens/{plural-kebab}/{view}`.
+   *     Screen-driven stratum. Set when Phase 2b's screen controllers
+   *     exist. `delete` and `getLookup` fall back to integration.
+   *
+   * Backward compat: `useScreens: true` is equivalent to
+   * `routeMode: 'screens'`.
+   */
+  routeMode: z.enum(['direct', 'integration', 'screens']).default('direct'),
+  useScreens: z.boolean().default(false),
+  /**
+   * HTTP client source. Default 'smartstack' uses `api` from
+   * `@atlashub/smartstack` (pre-configured with auth, tenant, retry;
+   * returns unwrapped data, not AxiosResponse).
+   * 'axios' generates a local axios instance with manual configuration —
+   * for projects that don't use the SmartStack npm package.
+   */
+  httpClient: z.enum(['smartstack', 'axios']).default('smartstack'),
+  /**
+   * Relative path from projectPath to the web project root.
+   * Defaults to `web/${appCode}-web`.
+   */
+  webRoot: z.string().optional(),
+}).strict()
+
+export type ApiCustomAction = z.infer<typeof ApiCustomActionSchema>
+export type ApiScreenColumn = z.infer<typeof ApiScreenColumnSchema>
+export type ApiEntity = z.infer<typeof ApiEntitySchema>
+export type ScaffoldApiClientInput = z.infer<typeof ScaffoldApiClientInputSchema>
+export interface GeneratedFile { path: string; content: string }
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }

package/templates/skills/development/frontend/api-client/cli/scaffold-api-client/validate.ts

@@ -0,0 +1,10 @@
+/**
+ * cli:scaffold-api-client — validate.ts
+ */
+import { ScaffoldApiClientInputSchema, type ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ScaffoldApiClientInputSchema.safeParse(raw)
+  if (result.success) return { valid: true, errors: [], warnings: [] }
+  return { valid: false, errors: result.error.issues.map(i => `[${i.path.join('.')}] ${i.message}`), warnings: [] }
+}

package/templates/skills/development/frontend/auth/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: frontend-auth
+description: Scaffold the per-project useAuth hook + PermissionGuard component
+group: development.frontend
+cli: scaffold-frontend-auth
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Frontend auth scaffold
+
+Generates the canonical authentication primitives every SmartStack-generated
+React app needs to gate UI by permission :
+
+- `src/business/auth/useAuth.ts` — Zustand-backed hook that loads
+  `/api/auth/me` once at mount, exposes `{ user, permissions, isAuthenticated,
+  hasPermission(path) }`. The `hasPermission` is a strict
+  `permissions.includes(path)` match — the path shape is whatever the DB
+  seed emits, so the same string flows BA → PRD → DB → JSX literal →
+  hasPermission lookup with no transformation in the pipeline.
+
+- `src/components/auth/PermissionGuard.tsx` — wraps children, renders
+  `null` when the auth store is still loading or when `hasPermission(path)
+  === false`. Optional `fallback?: ReactNode` for a placeholder.
+
+## Why a dedicated CLI
+
+The pages emitted by `scaffold-component` reference `<PermissionGuard
+permission="...">` everywhere. Without this companion scaffold the
+component does not exist (Phase 3a fails to build) or worse, it exists
+as an unimplemented stub that always returns its children — letting any
+authenticated user click every action regardless of role. A dedicated
+CLI guarantees the hook + the guard are wired together, ship in a
+known location, and stay overwritable on regeneration via the
+`@customised` marker convention.
+
+## Inputs
+
+`{ projectPath, appCode }` — the same minimal contract as
+`scaffold-layout`. The hook is project-agnostic ; `appCode` is only
+used to derive the web folder name (`web/{appCode}-web/`).
+
+## Outputs
+
+| File | Idempotency |
+|------|-------------|
+| `web/{appCode}-web/src/business/auth/useAuth.ts` | Honours `// @customised` marker |
+| `web/{appCode}-web/src/components/auth/PermissionGuard.tsx` | Honours `// @customised` marker |
+| `web/{appCode}-web/src/business/auth/auth-store.ts` | Honours `// @customised` marker |
+
+## When the runtime mounts
+
+The `useAuth` hook fires `api.get('/api/auth/me')` once on the first
+render of any consumer. The response shape it expects :
+
+```json
+{
+  "user": { "id": "...", "email": "...", "displayName": "..." },
+  "permissions": [
+    "restauration.carte.dishes.read",
+    "restauration.carte.dishes.create",
+    "restauration.carte.dishes.allergens.read"
+  ]
+}
+```
+
+The backend endpoint must return `permissions` as an array of full path
+strings matching whatever `*PermissionsSeedDataProvider.cs` seeded — 4
+or 5 segments, lower-kebab case throughout.
+
+## Anti-patterns
+
+- ❌ Adding business logic to PermissionGuard. It does ONE thing: hide
+  children when the user lacks the permission.
+- ❌ Resolving permissions client-side via heuristics (e.g. inferring
+  create from edit). The permission strings are the contract.
+- ❌ Caching beyond the session. If the user's role changes, they must
+  re-login to see the new gates.

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

@@ -0,0 +1,306 @@
+/**
+ * scaffold-frontend-auth/generate.ts — Emits the canonical auth primitives.
+ *
+ * Three files, all under the project's `web/{appCode}-web/src/` tree :
+ *   - `business/auth/auth-store.ts` — Zustand store (user, permissions,
+ *     loading, lastFetchedAt).
+ *   - `business/auth/useAuth.ts` — hook that bootstraps the store on first
+ *     consumer mount + exposes `hasPermission(path)`.
+ *   - `components/auth/PermissionGuard.tsx` — wraps children, returns null
+ *     when the auth store is loading or the permission is missing.
+ *
+ * The hook expects the backend to expose `GET /api/auth/me` returning :
+ *   { user: { id, email, displayName }, permissions: string[] }
+ * Permissions are full canonical paths (e.g.
+ * `restauration.carte.dishes.create` or
+ * `restauration.carte.dishes.allergens.create`) and `hasPermission` does
+ * a strict `permissions.includes(path)` match — no transformation.
+ */
+import type { GeneratedFile, ScaffoldFrontendAuthInput } from './types.js';
+
+const HEADER = '/* generated by scaffold-frontend-auth — overwrite-safe ; add the line `// @customised` at the top to lock against regeneration */\n';
+
+export function generate(spec: ScaffoldFrontendAuthInput): GeneratedFile[] {
+  const webRoot = `web/${spec.appCode}-web/src`;
+  return [
+    { path: `${webRoot}/business/auth/auth-store.ts`, content: authStore() },
+    { path: `${webRoot}/business/auth/useAuth.ts`, content: useAuthHook() },
+    { path: `${webRoot}/components/auth/PermissionGuard.tsx`, content: permissionGuard() },
+  ];
+}
+
+function authStore(): string {
+  return `${HEADER}import { create } from 'zustand';
+
+/**
+ * Mirror of the backend \`UserInfo\` record returned by \`GET /api/auth/me\`
+ * (see \`SmartStack.Application/Auth/DTOs/AuthDtos.cs:UserInfo\`). Fields
+ * are kept flat to match the wire format verbatim — no remapping in the
+ * fetch layer, so the entire payload is debuggable from a single
+ * \`console.log(useAuthStore.getState().user)\`.
+ */
+export interface AuthUser {
+  id: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  roles: string[];
+  /** Array of full permission paths returned verbatim by the backend.
+   *  Canonical shape: \`{app}.{module}.{section}[.{resource}].{action}\`
+   *  (4 or 5 segments). \`useAuth().hasPermission()\` strips the leading
+   *  appCode segment when comparing with the page-side path (which is
+   *  3 segments for section-scoped, 4 for resource-scoped — see useAuth.ts).
+   *  Mirrored at the store top level so hasPermission() does not need to
+   *  dereference user. */
+  permissions: string[];
+  tenants: TenantSummary[];
+}
+
+export interface TenantSummary {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+export interface AuthState {
+  user: AuthUser | null;
+  /** Full permission paths granted to the current user.
+   *  Format: \`{app}.{module}.{section}[.{resource}].{action}\` (4 or 5 segments).
+   *  Mirrors \`user.permissions\` for fast lookup without dereferencing user. */
+  permissions: string[];
+  /** True between the first api.get call and its first response (success or error). */
+  loading: boolean;
+  /** Wall-clock of the last successful /api/auth/me response. 0 when never fetched. */
+  lastFetchedAt: number;
+  /** Last error message, when the bootstrap call failed. */
+  error: string | null;
+  setLoading: (v: boolean) => void;
+  setSession: (u: AuthUser | null, perms: string[]) => void;
+  setError: (e: string | null) => void;
+  reset: () => void;
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  permissions: [],
+  loading: false,
+  lastFetchedAt: 0,
+  error: null,
+  setLoading: (loading) => set({ loading }),
+  setSession: (user, permissions) => set({
+    user,
+    permissions,
+    loading: false,
+    lastFetchedAt: Date.now(),
+    error: null,
+  }),
+  setError: (error) => set({ error, loading: false }),
+  reset: () => set({
+    user: null,
+    permissions: [],
+    loading: false,
+    lastFetchedAt: 0,
+    error: null,
+  }),
+}));
+`;
+}
+
+function useAuthHook(): string {
+  return `${HEADER}import { useEffect } from 'react';
+import { api } from '@atlashub/smartstack';
+import { useAuthStore, type AuthUser } from './auth-store';
+
+let bootstrapPromise: Promise<void> | null = null;
+
+/**
+ * Bootstraps the auth store from \`GET /api/auth/me\`. Called by
+ * useAuth() on first mount of any consumer. Subsequent calls are
+ * no-ops while the first fetch is still in flight (single-flight via
+ * bootstrapPromise).
+ *
+ * The backend returns \`UserInfo\` flat :
+ *   { id, email, firstName, lastName, roles, permissions, tenants }
+ * (see \`SmartStack.Application/Auth/DTOs/AuthDtos.cs\`). We store the
+ * whole object as \`user\` and mirror \`permissions\` at the store top
+ * level for fast hasPermission() lookups.
+ */
+async function bootstrap(): Promise<void> {
+  if (bootstrapPromise) return bootstrapPromise;
+  const store = useAuthStore.getState();
+  if (store.lastFetchedAt > 0) return; // already loaded once this session
+  store.setLoading(true);
+  bootstrapPromise = (async () => {
+    try {
+      const resp = await api.get<AuthUser>('/api/auth/me');
+      const permissions = Array.isArray(resp?.permissions) ? resp.permissions : [];
+      useAuthStore.getState().setSession(resp ?? null, permissions);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      useAuthStore.getState().setError(msg);
+    } finally {
+      bootstrapPromise = null;
+    }
+  })();
+  return bootstrapPromise;
+}
+
+export interface UseAuthReturn {
+  user: AuthUser | null;
+  permissions: string[];
+  isAuthenticated: boolean;
+  loading: boolean;
+  error: string | null;
+  /**
+   * True when the user holds the permission. Four match modes, tried in
+   * order (first hit wins) :
+   *
+   * 1. **Super-admin wildcard** — \`permissions\` contains \`"*"\`. Always true.
+   *    Mirrors SmartStack's \`WILDCARD_PERMISSION\` convention exported from
+   *    \`@atlashub/smartstack/utils/permissions\`.
+   * 2. **Fast strict match** — caller passed a fully-qualified path that
+   *    matches a store entry verbatim (4-/5-seg with appCode).
+   * 3. **Subtree wildcard** — a store entry like \`testv2.budgets.*\` or
+   *    \`budgets.*\` covers any path under that prefix (canonical or stripped
+   *    form, so the wildcard also matches the page-side 3-/4-seg input).
+   * 4. **Strip-leading-segment match** — the BA convention emits page-side
+   *    paths without the appCode segment (3-seg section / 4-seg resource).
+   *    Strip the leading segment of each store entry and compare strictly.
+   *
+   * Page-side path shape (input to this function):
+   *   - section-scoped : 3 segments \`{module}.{section}.{action}\`
+   *   - resource-scoped : 4 segments \`{module}.{section}.{resource}.{action}\`
+   *
+   * Store-side shape (DB / \`permission.Path\` / \`/api/auth/me\` payload):
+   *   - super-admin : \`["*"]\`
+   *   - subtree wildcard : \`["testv2.budgets.*"]\`
+   *   - section-scoped : \`["{app}.{module}.{section}.{action}"]\`
+   *   - resource-scoped : \`["{app}.{module}.{section}.{resource}.{action}"]\`
+   *
+   * Case-sensitive across all passes.
+   */
+  hasPermission: (path: string) => boolean;
+  /**
+   * Force a re-fetch of /api/auth/me. Useful after a role change in the
+   * admin UI ; otherwise the bootstrap-once default is enough.
+   */
+  refresh: () => Promise<void>;
+}
+
+export function useAuth(): UseAuthReturn {
+  useEffect(() => {
+    void bootstrap();
+  }, []);
+  const user = useAuthStore((s) => s.user);
+  const permissions = useAuthStore((s) => s.permissions);
+  const loading = useAuthStore((s) => s.loading);
+  const error = useAuthStore((s) => s.error);
+
+  const hasPermission = (path: string): boolean => {
+    if (!path) return false;
+    // 1. Super-admin shortcut. SmartStack convention : \`*\` = all permissions
+    //    (\`@atlashub/smartstack/utils/permissions\` exports the same constant
+    //    as WILDCARD_PERMISSION). Without this branch, a platform admin
+    //    seeded with [\`"*"\`] sees every PermissionGuard return null and the
+    //    UI renders blank — repro on run fbe07a0c.
+    if (permissions.includes('*')) return true;
+    // 2. Fast strict match : caller already passed a fully-qualified
+    //    4-/5-seg path that matches a store entry verbatim.
+    if (permissions.includes(path)) return true;
+    // 3. & 4. Per-entry inspection — covers subtree wildcards
+    //    (\`testv2.budgets.*\`) and the BA convention (page emits 3-seg
+    //    section / 4-seg resource without the appCode prefix, store carries
+    //    the canonical 4-/5-seg form). The \`indexOf('.')\` guards against
+    //    single-segment store entries (defensive — should not occur with
+    //    seeded data).
+    return permissions.some((entry) => {
+      // 3. Subtree wildcard. Match against both the canonical prefix
+      //    (\`testv2.budgets.\`) and the page-side stripped prefix
+      //    (\`budgets.\`) so the same store entry covers both shapes of
+      //    input.
+      if (entry.endsWith('.*')) {
+        const prefix = entry.slice(0, -1); // keeps the trailing dot
+        if (path.startsWith(prefix)) return true;
+        const dot = prefix.indexOf('.');
+        if (dot >= 0) {
+          const strippedPrefix = prefix.slice(dot + 1);
+          if (strippedPrefix && path.startsWith(strippedPrefix)) return true;
+        }
+        return false;
+      }
+      // 4. Strip leading appCode segment, compare strictly with input.
+      const dot = entry.indexOf('.');
+      if (dot < 0) return false;
+      return entry.slice(dot + 1) === path;
+    });
+  };
+
+  const refresh = async (): Promise<void> => {
+    useAuthStore.getState().reset();
+    bootstrapPromise = null;
+    await bootstrap();
+  };
+
+  return {
+    user,
+    permissions,
+    isAuthenticated: !!user,
+    loading,
+    error,
+    hasPermission,
+    refresh,
+  };
+}
+`;
+}
+
+function permissionGuard(): string {
+  return `${HEADER}import type { ReactNode } from 'react';
+import { useAuth } from '@/business/auth/useAuth';
+
+interface PermissionGuardProps {
+  /**
+   * Permission path the user must hold to see the children. **Page-side**
+   * shape (no appCode prefix) :
+   *   - section-scoped  : 3 segments \`{module}.{section}.{action}\`
+   *   - resource-scoped : 4 segments \`{module}.{section}.{resource}.{action}\`
+   *
+   * The leading appCode segment is added by the auth store entries (which
+   * carry the canonical \`permission.Path\` from the DB) and stripped at
+   * \`hasPermission()\` time. Pages stay app-agnostic ; the store stays
+   * canonical.
+   */
+  permission: string;
+  children: ReactNode;
+  /**
+   * Optional placeholder rendered when the user lacks the permission.
+   * Default: nothing (the gated block disappears entirely).
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Hides children when :
+ *   - the auth bootstrap is still loading (no flash of forbidden UI),
+ *   - the user is not authenticated,
+ *   - or hasPermission(permission) returns false.
+ *
+ * This component does ONE thing on purpose. Business logic that
+ * conditionally enables actions per row / per column / per state lives
+ * in the consuming component, not here.
+ */
+export function PermissionGuard({
+  permission,
+  children,
+  fallback = null,
+}: PermissionGuardProps): ReactNode {
+  const { loading, isAuthenticated, hasPermission } = useAuth();
+  if (loading) return null;
+  if (!isAuthenticated) return fallback;
+  if (!hasPermission(permission)) return fallback;
+  return children;
+}
+
+export default PermissionGuard;
+`;
+}