@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/lib/page-spec-actions.ts

@@ -0,0 +1,350 @@
+/**
+ * lib/page-spec-actions.ts — Canonical Zod schema for custom page actions.
+ *
+ * SINGLE SOURCE OF TRUTH for the contract `screen.md` → `pagespec.actions[]` →
+ * scaffold-controller / scaffold-business / scaffold-api-client / scaffold-component.
+ *
+ * The CLI deterministic generators already accept their own ad-hoc shapes
+ * (`ControllerCustomActionSchema`, `BusinessCustomActionSchema`,
+ * `ApiCustomActionSchema`, `PageActionMinSchema`). This module unifies the
+ * upstream contract: ba-create-prd writes a `PageCustomAction[]` into every
+ * pagespec, ba-develop derives each generator's input from it, and the dev
+ * audits cross-check the generated code against the same schema.
+ *
+ * The fundamental invariant:
+ *   pageSpec.action.endpoint  ===  [HttpVerb("<endpoint>")] route attribute
+ *                             ===  apiClient.<verb>('/api/.../<endpoint>')
+ *
+ * The same string is propagated VERBATIM in both directions. Frontend and
+ * backend can never drift on a name, because there is only one name.
+ *
+ * @see business-analyse/create-prd/SKILL.md  (propagates screen.md → pagespec)
+ * @see ba-develop/SKILL.md                      (derives the generator inputs)
+ * @see development/backend/controller/cli/scaffold-controller/types.ts (downstream consumer)
+ * @see development/frontend/component/cli/scaffold-component/types.ts  (downstream consumer)
+ * @see development/audit-dev-api/SKILL.md       (DEV-API-010/011 — pageSpec ↔ controller)
+ * @see development/audit-dev-frontend/SKILL.md  (DEV-UI-019/020/021 — pageSpec ↔ service.ts)
+ */
+import { z } from 'zod'
+import { toKebabCase, toCamelCase, toPascalCase } from './string-utils.js'
+
+/**
+ * Action codes emitted by the canonical CRUD paths of every scaffolder.
+ * Filters here are applied BEFORE iterating customActions so we never emit
+ * a duplicate POST for an action already handled by the standard generator.
+ *
+ * Examples:
+ * - `create` (header) → `POST /` from scaffold-controller's actions[] enum
+ * - `edit` (row)      → navigate(routes.<entity>.edit(item.id)) from scaffold-component
+ * - `delete` (row)    → `DELETE /{id:guid}` from scaffold-controller
+ */
+export const STANDARD_CRUD_CODES = new Set<string>([
+  'create', 'read', 'list', 'detail',
+  'edit', 'update', 'delete',
+])
+
+/**
+ * Compute the default URL segment for an action code.
+ * The pageSpec author can override by setting `endpoint` explicitly — useful
+ * when the business code (e.g. `syncFromPce`) maps to a legacy backend route
+ * (e.g. `sync-from-proconcept`).
+ *
+ *   defaultEndpoint('syncFromPce')   === 'sync-from-pce'
+ *   defaultEndpoint('archive')       === 'archive'
+ *   defaultEndpoint('analyzeImpact') === 'analyze-impact'
+ */
+export function defaultEndpoint(code: string): string {
+  return toKebabCase(code)
+}
+
+/**
+ * Derive the C# controller method name from a pageSpec endpoint.
+ * Scaffold-controller appends `Async`, so this helper returns the bare PascalCase
+ * — the suffix is the generator's responsibility.
+ *
+ *   controllerMethodNameFromEndpoint('sync-from-proconcept') === 'SyncFromProconcept'
+ *   controllerMethodNameFromEndpoint('archive')              === 'Archive'
+ */
+export function controllerMethodNameFromEndpoint(endpoint: string): string {
+  return toPascalCase(endpoint)
+}
+
+/**
+ * Derive the TypeScript service-method name from a pageSpec endpoint.
+ * Used by scaffold-api-client when emitting `<entity>Service.ts` members.
+ *
+ *   serviceMethodNameFromEndpoint('sync-from-proconcept') === 'syncFromProconcept'
+ *   serviceMethodNameFromEndpoint('archive')              === 'archive'
+ */
+export function serviceMethodNameFromEndpoint(endpoint: string): string {
+  return toCamelCase(endpoint)
+}
+
+/**
+ * Optional state-machine metadata. Populated by ba-create-prd from any
+ * linked business rule of type `workflow` whose flow lists a status
+ * transition. Consumed by scaffold-business to emit the guard
+ * (`if (entity.Status not in fromStatus) throw …`) and the assignment
+ * (`entity.Status = toStatus`).
+ */
+export const WorkflowTransitionSchema = z.object({
+  /** Allowed source statuses (raw values from the Status enum/lookup). */
+  fromStatus: z.array(z.string().min(1)).min(1),
+  /** Target status (raw value). */
+  toStatus: z.string().min(1),
+  /** Names of parameters the use case requires on the request body. */
+  flowParameters: z.array(z.string().min(1)).default([]),
+})
+
+export type WorkflowTransition = z.infer<typeof WorkflowTransitionSchema>
+
+/**
+ * One custom page action — the full vertical-slice contract.
+ *
+ * `kind: "api"` actions generate a backend endpoint + a service method + a
+ * React Query hook + a button. `kind: "navigate"` actions generate ONLY a
+ * button that calls `navigate(targetRoute)` — no API call, no hook, no axios
+ * (this is the fix for the legacy pattern `POST /{id}/open` → 405).
+ */
+export const PageCustomActionSchema = z.object({
+  /**
+   * Business identifier in camelCase. Drives the human-facing label key and
+   * the React Query hook name (`use<PascalCase(code)>${Entity}`). MAY differ
+   * from `endpoint` when the BA wants a clean UI label but the backend uses
+   * a legacy route name (e.g. code='syncFromPce', endpoint='sync-from-proconcept').
+   *
+   * Accepted: camelCase or single-word lowercase. We allow letters & digits but
+   * not dashes to keep TypeScript identifiers valid.
+   */
+  code: z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-zA-Z0-9]*$/, 'code must be camelCase or a single lowercase word'),
+
+  /**
+   * Distinguishes API-bound actions from pure navigations.
+   * - `api`      → emits backend endpoint + service method + React Query hook + button
+   * - `navigate` → emits ONLY a button that calls `navigate(targetRoute)`
+   *
+   * Default `api` for legacy pagespecs that omit the field.
+   */
+  kind: z.enum(['api', 'navigate']).default('api'),
+
+  /** Where the button renders. */
+  scope: z.enum(['row', 'bulk', 'header']),
+
+  /**
+   * URL segment, verbatim. Used identically on both sides:
+   *   - backend  →  [HttpVerb("<endpoint>")]
+   *   - frontend →  apiClient.<verb>('/api/.../<endpoint>')
+   *
+   * Optional in the schema — when missing for `kind:api`, ba-create-prd
+   * fills it with `defaultEndpoint(code)`. The audits enforce presence after
+   * normalisation.
+   */
+  endpoint: z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-z0-9-]*$/, 'endpoint must be kebab-case')
+    .optional(),
+
+  /** HTTP verb. Defaults POST (state mutations). GET for compute / read-only
+   *  endpoints (analyze-impact). */
+  httpMethod: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('POST'),
+
+  /**
+   * C# DTO type names. null when there is no body / no response payload
+   * (state-mutation endpoints like archive that return 204).
+   */
+  payloadDto: z.string().nullable().optional(),
+  responseDto: z.string().nullable().default(null),
+
+  /**
+   * TypeScript counterparts. When omitted, scaffold-api-client falls back to
+   * `payloadDto` / `responseDto` (they are usually identical PascalCase names
+   * shared with the backend via codegen).
+   */
+  payloadType: z.string().nullable().optional(),
+  responseType: z.string().nullable().default(null),
+
+  /**
+   * For `kind:navigate`: the screen the button leads to. ba-create-prd
+   * resolves it into a concrete `targetRoute` string by looking it up in the
+   * screen registry. One of `targetScreen` or `targetRoute` MUST be set.
+   */
+  targetScreen: z
+    .string()
+    .regex(/^SCR-[A-Z0-9_-]+$/, 'targetScreen must be SCR-...')
+    .optional(),
+
+  /**
+   * For `kind:navigate`: the resolved route helper expression, e.g.
+   * `routes.referentiels.typesAffaire.detail(item.id)`. scaffold-component
+   * inlines this verbatim inside `onClick={() => navigate(<targetRoute>)}`.
+   */
+  targetRoute: z.string().min(1).optional(),
+
+  /** i18n key for the button label. */
+  labelKey: z.string().min(1),
+
+  /**
+   * Three-segment permission constant (`<module>.<section>.<action>`).
+   * Drives the PermissionGuard wrapping in scaffold-component AND the
+   * permissionAction segment passed to scaffold-controller / scaffold-business.
+   */
+  permission: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/,
+      'permission must be `<module>.<section>.<action>` kebab-case',
+    ),
+
+  /** Visual variant. Defaults `secondary` for custom actions, `primary` for the
+   *  first header action (create), `danger` for destructive (delete). */
+  variant: z.enum(['primary', 'secondary', 'danger']).optional(),
+
+  /** UC-... back-reference (mandatory for kind:api so the stub carries a
+   *  TODO[UC-…] anchor that audit-dev-api can verify). */
+  ucReference: z
+    .string()
+    .regex(/^UC-[A-Z0-9_-]+$/, 'ucReference must be UC-...')
+    .optional(),
+
+  /** BR-... guards to enforce before performing the action. */
+  guardRules: z.array(z.string().regex(/^BR-[A-Z0-9_-]+$/)).default([]),
+
+  /** Optional state-machine transition. Populated by ba-create-prd from a
+   *  linked workflow rule, consumed by scaffold-business. */
+  workflowTransition: WorkflowTransitionSchema.optional(),
+
+  /** Module names this action depends on (entities not yet in prd.entities.md).
+   *  scaffold-business emits a `// BLOCKED[CROSS-MODULE: …]` TODO so audit-dev
+   *  can flag the dependency. */
+  crossModuleDeps: z.array(z.string().min(1)).default([]),
+}).superRefine((action, ctx) => {
+  if (action.kind === 'navigate') {
+    if (!action.targetRoute && !action.targetScreen) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['targetRoute'],
+        message: 'navigate action requires targetRoute or targetScreen',
+      })
+    }
+    if (action.endpoint) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['endpoint'],
+        message: 'navigate action must NOT carry endpoint — use targetRoute/targetScreen',
+      })
+    }
+    if (action.payloadDto || action.payloadType) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['payloadDto'],
+        message: 'navigate action must NOT carry payloadDto/payloadType',
+      })
+    }
+    if (action.workflowTransition) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['workflowTransition'],
+        message: 'navigate action must NOT carry workflowTransition',
+      })
+    }
+  } else {
+    // kind === 'api'
+    if (action.targetScreen || action.targetRoute) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['kind'],
+        message: 'api action must NOT carry targetScreen/targetRoute — set kind:navigate instead',
+      })
+    }
+  }
+})
+
+export type PageCustomAction = z.infer<typeof PageCustomActionSchema>
+
+/**
+ * Normalise a `PageCustomAction` after validation: fill missing defaults so
+ * downstream consumers (ba-develop, audits) can rely on a stable shape.
+ *
+ * - `kind:api` without `endpoint` → `defaultEndpoint(code)`
+ * - `kind:api` without `payloadType`/`responseType` → mirror the C# DTO names
+ */
+export function normalizePageCustomAction(action: PageCustomAction): PageCustomAction {
+  if (action.kind === 'navigate') return action
+  const endpoint = action.endpoint ?? defaultEndpoint(action.code)
+  return {
+    ...action,
+    endpoint,
+    payloadType: action.payloadType ?? action.payloadDto ?? null,
+    responseType: action.responseType ?? action.responseDto ?? null,
+  }
+}
+
+/**
+ * Extract the permission's last segment, which maps to scaffold-controller's
+ * `permissionAction` field (it joins it with the module/section to build
+ * `<Mod>Permissions.<Section>.<PermissionAction>`).
+ *
+ *   lastPermissionSegment('referentiels.types-affaire.execute') === 'execute'
+ */
+export function lastPermissionSegment(permission: string): string {
+  const parts = permission.split('.')
+  return parts[parts.length - 1] ?? ''
+}
+
+/**
+ * Build the expected URL path matched against axios calls in audit-dev-frontend
+ * and against `[HttpVerb("…")]` attributes in audit-dev-api.
+ *
+ *   expectedUrlPath('header', 'sync-from-pce')      → '/sync-from-pce'
+ *   expectedUrlPath('row', 'archive')               → '/{id}/archive'
+ *   expectedUrlPath('bulk', 'export')               → '/bulk/export'
+ *
+ * The returned path is RELATIVE to the controller mount point
+ * (`/api/<module>/<plural-kebab>`). Audits concatenate the prefix when
+ * comparing against full URLs.
+ */
+export function expectedUrlPath(
+  scope: PageCustomAction['scope'],
+  endpoint: string,
+): string {
+  switch (scope) {
+    case 'row':
+      return `/{id}/${endpoint}`
+    case 'bulk':
+      return `/bulk/${endpoint}`
+    case 'header':
+      return `/${endpoint}`
+  }
+}
+
+/**
+ * Same as `expectedUrlPath` but uses the C# route-attribute syntax with the
+ * `{id:guid}` constraint that scaffold-controller emits. Audit-dev-api uses
+ * this form when checking `[HttpVerb("…")]` strings.
+ */
+export function expectedControllerRoute(
+  scope: PageCustomAction['scope'],
+  endpoint: string,
+): string {
+  switch (scope) {
+    case 'row':
+      return `{id:guid}/${endpoint}`
+    case 'bulk':
+      return `bulk/${endpoint}`
+    case 'header':
+      return endpoint
+  }
+}
+
+/**
+ * Filter a list of pagespec actions down to the custom (non-CRUD) ones —
+ * used by every downstream consumer that derives a specific scaffolder input.
+ */
+export function customActionsOnly<T extends { code: string }>(actions: T[]): T[] {
+  return actions.filter(a => !STANDARD_CRUD_CODES.has(a.code))
+}

package/templates/skills/lib/skill-slug.ts

@@ -0,0 +1,121 @@
+/**
+ * lib/skill-slug.ts — Single source of truth for mapping an authoring path
+ * under `templates/skills/` to the slug it is deployed under in
+ * `~/.claude/skills/` (and therefore the slash-command name it answers to).
+ *
+ * Consumed by:
+ *   - `src/lib/installer.ts` at install time (decides what to copy where)
+ *   - `scripts/generate-docs/lib/skill-parser.ts` at doc-build time (decides
+ *     what slug to print on each skill card)
+ *
+ * Keeping a single implementation prevents the two paths from drifting.
+ */
+
+const BA_GROUP = 'business-analyse/';
+
+/**
+ * Claude Code only registers a skill when its directory is a DIRECT child of
+ * the skills root (the folder name is the slash-command token; nested folders
+ * are not invocable and there is no namespacing for plain skills). The BA
+ * skills are authored grouped under `business-analyse/<name>/` for repo
+ * organisation, so at deploy time we FLATTEN + PREFIX them to `ba-<name>/` —
+ * each phase then becomes an individual, grouped command
+ * (`/ba-create-menu`, `/ba-create-actors`, …).
+ *
+ * Returns the remapped relative path, or `null` for files that must NOT be
+ * deployed as commands (the `_workflow/` companions and the `CLAUDE.md` index
+ * — these stay repo-only; each skill inlines what it needs).
+ *
+ * @param file Relative path under `templates/skills/`, e.g.
+ *             `business-analyse/create-menu/SKILL.md`. Slashes are normalised.
+ */
+export function remapSkillPath(file: string): string | null {
+  const norm = file.replace(/\\/g, '/');
+  if (!norm.startsWith(BA_GROUP)) {
+    return file; // top-level skills (incl. ba-develop) deploy as-is
+  }
+  const rest = norm.slice(BA_GROUP.length); // 'create-menu/SKILL.md' | 'CLAUDE.md' | '_workflow/ba-files.md'
+  const slash = rest.indexOf('/');
+  if (slash === -1) {
+    return null; // bare file directly under business-analyse/ (e.g. CLAUDE.md index) — not deployed
+  }
+  const name = rest.slice(0, slash);
+  if (name.startsWith('_')) {
+    return null; // internal companions (_workflow, _fallback-summary, …) — repo-only
+  }
+  return `ba-${rest}`; // business-analyse/create-menu/SKILL.md → ba-create-menu/SKILL.md
+}
+
+/**
+ * Convenience: extract just the deployed slug (top-level folder name) from
+ * an authoring path. Returns `null` for repo-only files.
+ *
+ * Examples:
+ *   skillSlugFromAuthoringPath('business-analyse/create-menu/SKILL.md')
+ *     => 'ba-create-menu'
+ *   skillSlugFromAuthoringPath('efcore/SKILL.md')
+ *     => 'efcore'
+ *   skillSlugFromAuthoringPath('development/backend/controller/SKILL.md')
+ *     => 'development'                  // first segment
+ *   skillSlugFromAuthoringPath('business-analyse/_workflow/ba-files.md')
+ *     => null
+ *
+ * NOTE: For nested-but-deployed skills (e.g. `development/backend/controller/`),
+ * the installer does NOT flatten — Claude only registers `development/` as the
+ * slash command. The doc generator therefore uses the SKILL.md `name:`
+ * frontmatter as the canonical slug, not this path-derived value, for any
+ * skill that lives more than one folder deep.
+ */
+export function skillSlugFromAuthoringPath(file: string): string | null {
+  const remapped = remapSkillPath(file);
+  if (remapped === null) return null;
+  const norm = remapped.replace(/\\/g, '/');
+  const slash = norm.indexOf('/');
+  return slash === -1 ? norm.replace(/\.md$/, '') : norm.slice(0, slash);
+}
+
+/**
+ * Returns the "phase" bucket for a skill, used by the doc generator to group
+ * skill cards on `commands.html`, `business-analyse.html`, etc. Inferred from
+ * folder structure unless overridden by the SKILL.md `phase:` frontmatter.
+ *
+ * Examples:
+ *   phaseFromAuthoringPath('efcore/SKILL.md')                              => 'infrastructure'
+ *   phaseFromAuthoringPath('gitflow/SKILL.md')                             => 'infrastructure'
+ *   phaseFromAuthoringPath('business-analyse/audit-actors/SKILL.md')      => 'business-analyse'
+ *   phaseFromAuthoringPath('development/backend/controller/SKILL.md')     => 'development/backend'
+ *   phaseFromAuthoringPath('development/frontend/theme/SKILL.md')         => 'development/frontend'
+ *   phaseFromAuthoringPath('validation/conventions/SKILL.md')             => 'validation'
+ *   phaseFromAuthoringPath('init/SKILL.md')                                => 'lifecycle'
+ */
+const LIFECYCLE_SLUGS = new Set([
+  'init', 'upgrade', 'review', 'check-version', 'cli-app-sync', 'dev-start',
+  'documentation', 'quick-search', 'smoke-generation', 'ui-components',
+  'utils', 'validate-feature', 'conventions',
+]);
+const INFRASTRUCTURE_SLUGS = new Set([
+  'efcore', 'gitflow', 'external', 'lib',
+  'ba-develop', 'ba-develop-plan',
+]);
+
+export function phaseFromAuthoringPath(file: string): string {
+  const norm = file.replace(/\\/g, '/');
+  const segments = norm.split('/');
+  const first = segments[0];
+
+  if (first === 'business-analyse') return 'business-analyse';
+  if (first === 'development') {
+    // development/backend/<x>/SKILL.md  => 'development/backend'
+    // development/frontend/<x>/SKILL.md => 'development/frontend'
+    // development/audit-dev-<x>/SKILL.md => 'development/audit'
+    // development/{debug,run,testing,smoke-test,audit}/<...>/SKILL.md => keep
+    const second = segments[1];
+    if (!second) return 'development';
+    if (second.startsWith('audit-dev-')) return 'development/audit';
+    return `development/${second}`;
+  }
+  if (first === 'validation') return 'validation';
+  if (LIFECYCLE_SLUGS.has(first)) return 'lifecycle';
+  if (INFRASTRUCTURE_SLUGS.has(first)) return 'infrastructure';
+  return 'other';
+}

package/templates/skills/lib/string-utils.ts

@@ -0,0 +1,140 @@
+/**
+ * lib/string-utils.ts — String transformations for dev CLIs.
+ * Ported from SmartStack.cli/src/mcp/lib/string-utils.ts.
+ *
+ * Centralizes case conversions and naming helpers used by scaffolders,
+ * validators and analyzers that reason about SmartStack naming conventions.
+ */
+
+/**
+ * Convert PascalCase/camelCase to kebab-case. Handles consecutive uppercase letters.
+ *   "HumanResources" → "human-resources"
+ *   "APIClient" → "api-client"
+ *   "HRDepartment" → "hr-department"
+ */
+export function toKebabCase(segment: string): string {
+  return segment
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+}
+
+/**
+ * Convert kebab-case (or already camelCase) to camelCase.
+ *   "human-resources" → "humanResources"
+ *   "employees" → "employees"
+ */
+export function toCamelCase(segment: string): string {
+  return segment.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Convert any case to PascalCase.
+ *   "human-resources" → "HumanResources"
+ *   "humanResources"  → "HumanResources"
+ */
+export function toPascalCase(segment: string): string {
+  const camel = toCamelCase(segment);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+/** Capitalize the first letter. */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Simple English singularization. Handles common plural forms.
+ *   "employees" → "employee"
+ *   "companies" → "company"
+ *   "processes" → "process"
+ *   "addresses" → "address"
+ *   "status" → "status"
+ */
+export function singularize(word: string): string {
+  if (word.endsWith('ies')) return word.slice(0, -3) + 'y';
+  if (word.endsWith('sses')) return word.slice(0, -2);
+  if (
+    word.endsWith('shes') ||
+    word.endsWith('ches') ||
+    word.endsWith('xes') ||
+    word.endsWith('zes')
+  ) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith('ses')) return word.slice(0, -1);
+  if (word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1);
+  return word;
+}
+
+/**
+ * Very rough English pluralization (inverse of singularize).
+ *   "employee" → "employees"
+ *   "company"  → "companies"
+ *   "address"  → "addresses"
+ */
+export function pluralize(word: string): string {
+  if (word.endsWith('y') && !/[aeiou]y$/.test(word)) return word.slice(0, -1) + 'ies';
+  if (word.endsWith('s') || word.endsWith('x') || word.endsWith('z')) return word + 'es';
+  if (word.endsWith('sh') || word.endsWith('ch')) return word + 'es';
+  return word + 's';
+}
+
+/**
+ * Convert a NavRoute dot-path to a URL path with kebab-case segments.
+ *   "humanResources.employees" → "human-resources/employees"
+ */
+export function navRouteToUrlPath(navRoute: string): string {
+  return navRoute.split('.').map(toKebabCase).join('/');
+}
+
+const FRENCH_DETERMINERS = new Set([
+  'le', 'la', 'les', 'l',
+  'un', 'une', 'des',
+  'de', 'du', 'd',
+  'a', 'au', 'aux',
+  'et', 'ou',
+]);
+
+/**
+ * Slugify a human-readable role label into a functional kebab-case code.
+ * Used by Phase 0 Core Foundation Seed to derive Role.code from actor.label,
+ * avoiding propagation of BA analysis codes (e.g. "BA-002-AC-008") that have
+ * no business meaning at the domain level.
+ *
+ *   "Gestionnaire de budget"      → "gestionnaire-budget"
+ *   "Contrôleur de gestion"        → "controleur-gestion"
+ *   "L'agent des comptes clients" → "agent-comptes-clients"
+ *
+ * Pipeline: NFD-strip accents (Unicode combining marks U+0300..U+036F) →
+ * lowercase → tokenise on non-alphanumeric →
+ * drop French determiners → join with '-'. If every token is a determiner
+ * (pathological case like label="Le"), keep the original tokens so we never
+ * return an empty string for a non-empty input.
+ */
+export function slugifyRoleCode(label: string): string {
+  if (!label || !label.trim()) return '';
+  const ascii = label.normalize('NFD').replace(/[̀-ͯ]/g, '');
+  const tokens = ascii.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (tokens.length === 0) return '';
+  const meaningful = tokens.filter((t) => !FRENCH_DETERMINERS.has(t));
+  const finalTokens = meaningful.length > 0 ? meaningful : tokens;
+  return finalTokens.join('-');
+}
+
+/**
+ * Disambiguate a list of slugs by appending `-2`, `-3`, ... to duplicates so
+ * that every output is unique. Order is preserved — the first occurrence keeps
+ * its plain slug, subsequent collisions get numeric suffixes.
+ *
+ *   ["manager", "manager", "controleur", "manager"]
+ *     → ["manager", "manager-2", "controleur", "manager-3"]
+ */
+export function disambiguateRoleCodes(slugs: string[]): string[] {
+  const seen = new Map<string, number>();
+  return slugs.map((s) => {
+    const count = (seen.get(s) ?? 0) + 1;
+    seen.set(s, count);
+    return count === 1 ? s : `${s}-${count}`;
+  });
+}