@atlashub/smartstack-cli 4.81.0 → 5.0.0

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

@@ -0,0 +1,114 @@
+/**
+ * cli:scaffold-routes — types.ts
+ *
+ * componentKey segment rule: each segment must be lowercase alphanumeric,
+ * may contain internal hyphens but must start with a letter. Dots are the
+ * separator between hierarchy levels and cannot appear inside a segment.
+ */
+import { z } from 'zod'
+
+const SEGMENT_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+export const RouteEntitySchema = z.object({
+  name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/, 'Entity name must be PascalCase'),
+  /**
+   * Optional explicit plural (`Categories` for `Category`, `Rues` for `Rue`).
+   * When omitted, the CLI falls back to `${name}s` — fine for regular plurals
+   * but wrong for entities whose plural ends in `ies`/`-es`/`ues`. Callers
+   * passing this through the BA pipeline use the BA-declared plural verbatim.
+   */
+  pluralName: z
+    .string()
+    .min(1)
+    .regex(/^[A-Z][A-Za-z0-9]*$/, 'pluralName must be PascalCase')
+    .optional(),
+  section: z.string().min(1).regex(SEGMENT_REGEX, 'Section must be kebab-case and start with a letter'),
+  /**
+   * Optional kebab parent for sub-resources. When set the entity is nested
+   * one extra level deep:
+   *   - componentKey   →  `{app}.{module}.{parentSection}.{section}[.{view}]`
+   *   - default page   →  `@/pages/{app}/{module}/{parentSection}/{section}`
+   *   - URL helper     →  `/{app}/{module}/{parentSection}/{section}`
+   *
+   * Mirrors how the SmartStack navigation DB stores 4-segment keys for nested
+   * resources (e.g. `gaf.referentiels.types-affaire.types-audit`). Without
+   * this field, the CLI emitted a flat 3-segment key that DynamicRouter could
+   * not resolve, leaving the page on a perpetual spinner.
+   */
+  parentSection: z
+    .string()
+    .min(1)
+    .regex(SEGMENT_REGEX, 'parentSection must be kebab-case and start with a letter')
+    .optional(),
+  views: z.array(z.enum([
+    'list', 'detail', 'create', 'edit',
+    'dashboard', 'kanban',
+    // Bug 7 fix — reconduction is the bulk-renewal pattern (AFFAIRES/Demande
+    // and other workflow-driven entities). Page lives at
+    // `${section}/reconduction`; componentKey `app.module[.parent].section.reconduction`.
+    'reconduction',
+    'app-home', 'module-home', 'section-home',
+  ])).default(['list', 'detail', 'create']),
+  /**
+   * Optional per-view file path overrides. When provided, scaffold-routes
+   * uses these for the lazy import paths instead of deriving from
+   * `@/pages/{appCode}/{module}/{section}/`. Source: `pageSpec.filePath` from the PRD.
+   * Lets the registry stay aligned with whatever directory the project
+   * actually uses (e.g. legacy `pages/budgeting/` vs canonical
+   * `pages/budgets/`) without forcing a folder rename.
+   *
+   * Keys: 'list', 'detail', 'create', 'edit'.
+   * Values: relative path from project root to the .tsx file
+   * (e.g. 'src/pages/budgeting/budgets/BudgetsListPage.tsx').
+   */
+  pageFilePaths: z.record(z.string()).optional(),
+})
+
+export const ScaffoldRoutesInputSchema = z.object({
+  module: z.string().min(1).regex(SEGMENT_REGEX, 'Module must be kebab-case and start with a letter'),
+  appCode: z.string().min(1).regex(SEGMENT_REGEX, 'appCode must be kebab-case and start with a letter'),
+  entities: z.array(RouteEntitySchema).min(1),
+  projectPath: z.string().min(1),
+})
+
+export type RouteEntity = z.infer<typeof RouteEntitySchema>
+export type ScaffoldRoutesInput = z.infer<typeof ScaffoldRoutesInputSchema>
+export interface GeneratedFile { path: string; content: string }
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }
+
+/**
+ * Validate a fully-assembled componentKey against SmartStack's DynamicRouter
+ * resolution contract. Returns null if valid, or an explanation string.
+ *
+ * Rules:
+ *  - 2 to 5 dot-separated segments:
+ *      `app.module`                                       (module-home hub)
+ *      `app.module.section`                               (section root / list view)
+ *      `app.module.section.view`                          (detail/edit/create)
+ *      `app.module.parentSection.section`                 (sub-resource list)
+ *      `app.module.parentSection.section.view`            (sub-resource detail/edit/create)
+ *  - each segment matches SEGMENT_REGEX
+ *  - final segment may be one of the IMPLICIT_SUFFIXES for view-specific
+ *    registrations (detail, edit, create, new, duplicate, settings, configure,
+ *    permissions, members, history, logs, analytics, preview, versions,
+ *    comments, attachments, audit, export, notifications, schedule, workflow,
+ *    summary, test, runs, import) — the emitted key itself is fine in any
+ *    form, but the suffix is how DynamicRouter auto-generates `/:id/edit`
+ *    etc. Mismatches produce silent spinners at runtime.
+ *
+ * The 5-segment form was added in 2026-05-27 to support nested resources
+ * whose navigation DB key carries a parent section (e.g.
+ * `gaf.referentiels.types-affaire.types-audit.detail`).
+ */
+export function validateComponentKey(key: string): string | null {
+  const parts = key.split('.')
+  if (parts.length < 2 || parts.length > 5) {
+    return `componentKey '${key}' has ${parts.length} segments — must be between 2 and 5 (app.module[.parentSection].section[.view])`
+  }
+  for (const [i, part] of parts.entries()) {
+    if (!SEGMENT_REGEX.test(part)) {
+      return `componentKey '${key}' segment ${i} ('${part}') is invalid — must be kebab-case and start with a letter`
+    }
+  }
+  return null
+}

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

@@ -0,0 +1,68 @@
+/**
+ * cli:scaffold-routes — validate.ts
+ *
+ * Structural Zod validation + non-blocking filesystem cross-check: every
+ * entity × view combination is expected to have a matching `.tsx` page under
+ * `{projectPath}/src/pages/{module}/{section}/`. Missing pages are
+ * reported as warnings so the caller (Frontend subagent) knows which pages to
+ * scaffold BEFORE writing the aggregated registry. Never blocks — the CLI may
+ * legitimately run before scaffold-component in some flows.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  ScaffoldRoutesInputSchema,
+  type ScaffoldRoutesInput,
+  type ValidationResult,
+} from './types.js'
+
+function pageNameFor(entity: string, view: string): string {
+  // List uses plural (BudgetsListPage); detail/form stay singular. Aligns
+  // with scaffold-component's emitted file names and the actual SmartStack
+  // project layout.
+  if (view === 'list') return `${entity}sListPage`
+  if (view === 'detail') return `${entity}DetailPage`
+  if (view === 'create' || view === 'edit') return `${entity}FormPage`
+  return `${entity}${view.charAt(0).toUpperCase() + view.slice(1)}Page`
+}
+
+function checkPagesExist(spec: ScaffoldRoutesInput): string[] {
+  const warnings: string[] = []
+  // Pages live at src/pages/{module}/{section}/ — no appLower prefix.
+  // This matches scaffold-component's emit path exactly, so the registry
+  // imports point at real files instead of phantom paths.
+  const pagesBase = path.join(spec.projectPath, 'src', 'pages', spec.module)
+  for (const entity of spec.entities) {
+    const sectionDir = path.join(pagesBase, entity.section)
+    for (const view of entity.views) {
+      const pageName = pageNameFor(entity.name, view)
+      const candidates = [
+        path.join(sectionDir, `${pageName}.tsx`),
+        path.join(sectionDir, `${pageName}.ts`),
+        path.join(sectionDir, pageName, 'index.tsx'),
+        path.join(sectionDir, pageName, 'index.ts'),
+      ]
+      if (!candidates.some((c) => fs.existsSync(c))) {
+        warnings.push(
+          `Page missing for ${entity.name}.${view}: expected at ${path.relative(
+            spec.projectPath,
+            candidates[0],
+          )} — run scaffold-component first, otherwise the registry will reference a phantom import (Vite fails at launch on those).`,
+        )
+      }
+    }
+  }
+  return warnings
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ScaffoldRoutesInputSchema.safeParse(raw)
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`),
+      warnings: [],
+    }
+  }
+  return { valid: true, errors: [], warnings: checkPagesExist(result.data) }
+}

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

@@ -0,0 +1,119 @@
+---
+name: frontend-structure
+description: React + Vite + Tailwind + SmartStack frontend structure (npm consumer of @atlashub/smartstack)
+group: D
+allowed-tools: [Read, Glob, Grep]
+---
+
+# Skill: Frontend SmartStack (React)
+
+## Technical Stack
+- React 19 + TypeScript 5.9
+- Vite 7
+- Tailwind CSS v4
+- SmartStack npm: `@atlashub/smartstack`
+- State/data: `@tanstack/react-query`
+- Routing: `react-router-dom` (used by `DynamicRouter` from SmartStack)
+- i18n: `react-i18next`
+
+## Project Structure
+```
+web/{app-lower}-web/
+├── src/
+│   ├── main.tsx             # SmartStackProvider + imports every *Registry
+│   ├── App.tsx              # DynamicRouter
+│   ├── index.css            # Tailwind v4
+│   ├── extensions/          # generated *Registry.ts files (PageRegistry.register)
+│   │   ├── hrmRegistry.ts
+│   │   └── catalogueRegistry.ts
+│   ├── features/
+│   │   └── {module}/{entity}/{pages,services,hooks,types}/
+│   ├── components/
+│   ├── services/
+│   ├── hooks/
+│   └── i18n/{fr,en,it,de}/{module}/{entity}.json
+├── package.json
+├── vite.config.ts
+└── tsconfig.json
+```
+
+## Key Files
+
+### `main.tsx` — entry point
+
+All registries MUST be imported BEFORE `<App/>` renders so that
+`PageRegistry.register()` calls execute before `DynamicRouter` tries to resolve
+the first route. Missing imports = blank pages with no error.
+
+```tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { SmartStackProvider } from '@atlashub/smartstack';
+import App from './App';
+import './index.css';
+
+// ⚠ MANDATORY: import every generated Registry before rendering.
+// scaffold-routes emits one file per module; list them all here.
+import './extensions/hrmRegistry';
+import './extensions/catalogueRegistry';
+// ... one line per module
+
+const config = {
+  apiUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:5142',
+  appName: '{AppCode}',
+};
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <SmartStackProvider config={config}>
+        <App />
+      </SmartStackProvider>
+    </BrowserRouter>
+  </React.StrictMode>
+);
+```
+
+### `App.tsx` — routing entry
+
+Delegates everything to `DynamicRouter` from `@atlashub/smartstack`. No manual
+`<Route>` declarations here — routes come from the menu API + PageRegistry.
+
+```tsx
+import { DynamicRouter } from '@atlashub/smartstack';
+
+export default function App() {
+  return <DynamicRouter />;
+}
+```
+
+### `index.css` — Tailwind v4 + SmartStack styles
+
+```css
+@import "tailwindcss";
+@source "node_modules/@atlashub/smartstack";
+```
+
+## Conventions
+- One component per file
+- Business hooks in `features/{module}/{entity}/hooks/`
+- API clients in `features/{module}/{entity}/services/`
+- `PermissionGuard` from `@atlashub/smartstack` to gate UI actions by permission
+- One `*Registry.ts` per module — generated by `scaffold-routes` CLI
+- i18n files per entity to avoid concurrent overwrites: `i18n/{locale}/{module}/{entity}.json`
+- `useParams<{ id: string }>()` — always `:id`, never custom param names (DynamicRouter convention)
+
+## Checklist before declaring the frontend working
+
+1. `npm run dev` → Vite outputs `Local: http://localhost:3000/`
+2. `curl http://localhost:3000/` → HTTP 200 with `<div id="root"></div>`
+3. In browser DevTools console after login: `PageRegistry.list()` returns a non-empty array (if exposed)
+4. Every module listed in the backend's `/api/navigation/menu` has a matching `*Registry.ts` import in `main.tsx`
+5. No white-screen on any route — see `debug/frontend/SKILL.md` étape 7 if any
+
+## Tests
+- Vitest + Testing Library
+- MSW for API mocks
+- `renderWithProviders(ui)` helper: wraps with `QueryClientProvider` + `MemoryRouter` + `SmartStackProvider`
+- One test file per page/hook: `tests/{module}/{entity}/{Entity}.test.tsx`

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

@@ -0,0 +1,48 @@
+---
+name: scaffold-theme
+description: Bootstrap src/index.css with Tailwind v4 + Shoelace token overrides + design tokens from the PRD theme slice (or SmartStack defaults). Idempotent overwrite.
+group: D
+phase: devFrontend
+kind: main
+section_label: 'SCAFFOLD-THEME (CSS variables + Shoelace tokens for the generated client app)'
+allowed-tools: [Read, Write, Edit, Glob, Grep]
+---
+
+# scaffold-theme — Theme bootstrap for the generated client app
+
+## Context
+
+You are scaffolding the **theme entry point** of a SmartStack-generated React + Vite + Tailwind v4 + Shoelace client app. Without this file, every component renders with browser defaults: no token-based palette, no dark-mode contract, no Shoelace `--sl-color-*` overrides — the UI looks unbranded and inconsistent across components.
+
+This skill is invoked by `ba-develop` Phase 3, sub-phase 3.0 (theme + layout), BEFORE any pages are scaffolded — so pages can reference design tokens directly via `var(--color-*)` Tailwind classes (e.g. `bg-[var(--color-accent-500)]`).
+
+## Invocation
+
+```
+npx tsx skills/development/frontend/theme/cli/scaffold-theme/index.ts \
+  --spec '{"projectPath":"<abs>","appCode":"<app>","prdSlice":<theme-slice-or-null>}'
+```
+
+`--spec` is a JSON object:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `projectPath` | string | yes | Absolute path to the web root (holds `src/`). |
+| `appCode` | string | yes | Lowercased app code (used for branding label only). |
+| `prdSlice` | object \| null | no | Optional theme tokens from the PRD. Falls back to SmartStack defaults. |
+| `force` | boolean | no | Overwrite even when content matches. Default `false` (no-op when content unchanged). |
+
+## What it produces
+
+- **`src/index.css`** — Tailwind v4 entry + Shoelace `--sl-color-*` overrides + design tokens (`--color-accent-*`, `--bg-app`, `--success-*`, `--warning-*`, `--error-*`, `--info-*`) — all rooted on `:root` and overridden under `.dark` for dark-mode contract.
+
+## Idempotency contract
+
+- **Re-run safe.** If the existing `src/index.css` has the **exact same content** as what would be generated, the CLI returns `filesCreated: []` and exits 0 (no-op).
+- **Overwrite on drift.** If the file exists but content has drifted (manual edits or stale generation), the file is overwritten unless the user marks it with `/* @customised */` at the top — that marker tells the scaffolder to preserve the file.
+- The generated file always carries a `/* AUTO-GENERATED — re-run scaffold-theme to refresh. Add @customised at top to opt out. */` header so re-runs are predictable.
+
+## When NOT to use
+
+- Customising specific tokens for a single page → put overrides in a sibling `.css` next to the page, not in `src/index.css`.
+- Adding new design tokens that aren't in the PRD theme slice → extend the PRD theme schema first, then re-run; ad-hoc additions in `src/index.css` are wiped on the next re-run.

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

@@ -0,0 +1,53 @@
+/**
+ * scaffold-theme / generate.test.ts (2026-05-27)
+ *
+ * Covers Fix #5: Shoelace imports are now conditional on the `useShoelace`
+ * flag. Default OFF so projects without `@shoelace-style/shoelace` in their
+ * package.json don't fail Vite resolution at boot.
+ */
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import type { ScaffoldThemeInput } from '../types.js'
+
+function fixture(overrides: Partial<ScaffoldThemeInput> = {}): ScaffoldThemeInput {
+  return {
+    projectPath: '/test',
+    appCode: 'TestV2',
+    force: false,
+    useShoelace: false,
+    ...overrides,
+  } as ScaffoldThemeInput
+}
+
+describe('scaffold-theme / generate — Fix #5 (Shoelace imports conditional)', () => {
+  it('omits Shoelace @import lines by default (useShoelace not set)', () => {
+    const files = generate(fixture())
+    const css = files.find(f => f.path.endsWith('index.css'))!
+    expect(css.content).not.toMatch(/@shoelace-style\/shoelace/)
+    expect(css.content).not.toMatch(/themes\/light\.css/)
+    expect(css.content).not.toMatch(/themes\/dark\.css/)
+  })
+
+  it('emits Shoelace @import lines when useShoelace: true', () => {
+    const files = generate(fixture({ useShoelace: true }))
+    const css = files.find(f => f.path.endsWith('index.css'))!
+    expect(css.content).toMatch(/@import '@shoelace-style\/shoelace\/dist\/themes\/light\.css';/)
+    expect(css.content).toMatch(/@import '@shoelace-style\/shoelace\/dist\/themes\/dark\.css' \(prefers-color-scheme: dark\);/)
+  })
+
+  it('always emits Tailwind + SmartStack theme imports regardless of useShoelace', () => {
+    for (const useShoelace of [true, false]) {
+      const css = generate(fixture({ useShoelace })).find(f => f.path.endsWith('index.css'))!
+      expect(css.content, `useShoelace=${useShoelace}`).toMatch(/@import 'tailwindcss';/)
+      expect(css.content, `useShoelace=${useShoelace}`).toMatch(/@import '@atlashub\/smartstack\/theme\.css';/)
+    }
+  })
+
+  it('emits the accent ramp from the PRD theme slice when provided', () => {
+    const files = generate(fixture({
+      prdSlice: { theme: { accent: '#ff0000' } },
+    }))
+    const css = files.find(f => f.path.endsWith('index.css'))!
+    expect(css.content).toMatch(/--color-accent-500: #ff0000;/)
+  })
+})

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

@@ -0,0 +1,129 @@
+/**
+ * scaffold-theme/generate.ts — Build the src/index.css file content from
+ * the PRD theme slice (or SmartStack defaults when absent).
+ *
+ * Pure function — no I/O. The caller writes the returned files to disk.
+ */
+import type { GeneratedFile, ScaffoldThemeInput, ThemeTokens } from './types.js';
+
+const DEFAULTS: Required<ThemeTokens> = {
+  accent: '#3b82f6',
+  darkBg: '#161618',
+  lightBg: '#ffffff',
+  radiusCard: 8,
+};
+
+const HEADER = `/* AUTO-GENERATED — re-run scaffold-theme to refresh. Add @customised at the top to opt out. */`;
+
+function shadeHex(hex: string, lightness: number): string {
+  // Quick & dirty: blend hex toward white (lightness > 0) or black (< 0).
+  // lightness in [-1, 1]. 0 = no change.
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  const t = lightness > 0 ? 255 : 0;
+  const k = Math.abs(lightness);
+  const mix = (c: number) => Math.round(c * (1 - k) + t * k);
+  const toHex = (n: number) => n.toString(16).padStart(2, '0');
+  return `#${toHex(mix(r))}${toHex(mix(g))}${toHex(mix(b))}`;
+}
+
+export function generate(spec: ScaffoldThemeInput): GeneratedFile[] {
+  const tokens: Required<ThemeTokens> = {
+    ...DEFAULTS,
+    ...(spec.prdSlice?.theme ?? {}),
+  };
+
+  // Generate accent ramp (300, 400, 500, 600, 700) from the base.
+  const a700 = shadeHex(tokens.accent, -0.3);
+  const a600 = shadeHex(tokens.accent, -0.15);
+  const a500 = tokens.accent;
+  const a400 = shadeHex(tokens.accent, 0.15);
+  const a300 = shadeHex(tokens.accent, 0.3);
+
+  // Shoelace imports are conditional (Fix #5, 2026-05-27). Projects that
+  // don't depend on `@shoelace-style/shoelace` in their package.json fail
+  // Vite resolution at boot with `Can't resolve '@shoelace-style/shoelace/…'`.
+  // The default is OFF; ba-develop / users opt in by passing useShoelace:true.
+  const shoelaceImports = spec.useShoelace
+    ? `@import '@shoelace-style/shoelace/dist/themes/light.css';
+@import '@shoelace-style/shoelace/dist/themes/dark.css' (prefers-color-scheme: dark);
+`
+    : ''
+
+  const css = `${HEADER}
+@import 'tailwindcss';
+@import '@atlashub/smartstack/theme.css';
+@source '../node_modules/@atlashub/smartstack/dist/**/*.js';
+${shoelaceImports}
+:root {
+  /* ─── Brand accent ramp (derived from --color-accent-500) ────────── */
+  --color-accent-300: ${a300};
+  --color-accent-400: ${a400};
+  --color-accent-500: ${a500};
+  --color-accent-600: ${a600};
+  --color-accent-700: ${a700};
+
+  /* ─── App backgrounds ───────────────────────────────────────────── */
+  --bg-app: ${tokens.lightBg};
+  --bg-card: #ffffff;
+  --bg-muted: #f5f5f7;
+
+  /* ─── Status palette ────────────────────────────────────────────── */
+  --success-bg: #ecfdf5;
+  --success-border: #10b981;
+  --success-text: #065f46;
+  --warning-bg: #fffbeb;
+  --warning-border: #f59e0b;
+  --warning-text: #92400e;
+  --error-bg: #fef2f2;
+  --error-border: #ef4444;
+  --error-text: #991b1b;
+  --info-bg: #eff6ff;
+  --info-border: #3b82f6;
+  --info-text: #1e40af;
+
+  /* ─── Geometry ──────────────────────────────────────────────────── */
+  --radius-card: ${tokens.radiusCard}px;
+
+  /* ─── Shoelace overrides (sl-color-primary mapped to brand accent) ── */
+  --sl-color-primary-50: ${shadeHex(a500, 0.8)};
+  --sl-color-primary-100: ${shadeHex(a500, 0.65)};
+  --sl-color-primary-200: ${shadeHex(a500, 0.5)};
+  --sl-color-primary-300: ${a300};
+  --sl-color-primary-400: ${a400};
+  --sl-color-primary-500: ${a500};
+  --sl-color-primary-600: ${a600};
+  --sl-color-primary-700: ${a700};
+  --sl-color-primary-800: ${shadeHex(a500, -0.45)};
+  --sl-color-primary-900: ${shadeHex(a500, -0.6)};
+  --sl-color-primary-950: ${shadeHex(a500, -0.75)};
+}
+
+.dark {
+  --bg-app: ${tokens.darkBg};
+  --bg-card: #1e1e22;
+  --bg-muted: #26262b;
+
+  --success-bg: #052e2b;
+  --success-border: #10b981;
+  --success-text: #34d399;
+  --warning-bg: #2a1f0a;
+  --warning-border: #f59e0b;
+  --warning-text: #fbbf24;
+  --error-bg: #2a0a0a;
+  --error-border: #ef4444;
+  --error-text: #fca5a5;
+  --info-bg: #0a1a2e;
+  --info-border: #3b82f6;
+  --info-text: #93c5fd;
+}
+
+html, body {
+  background-color: var(--bg-app);
+  color-scheme: light dark;
+}
+`;
+
+  return [{ path: 'src/index.css', content: css }];
+}

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-theme — Bootstrap src/index.css for the generated app.
+ *
+ * Idempotent: skips writes if existing file content matches. Honors a
+ * `/* @customised *\/` marker at the top of the existing file (preserves it).
+ */
+import { parseArgs } from 'node:util';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { validate } from './validate.js';
+import { generate } from './generate.js';
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js';
+
+const COMMAND = 'scaffold-theme';
+
+function main(): void {
+  const { values } = parseArgs({
+    options: {
+      spec: { 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 in --spec']));
+    process.exit(1);
+  }
+
+  const validation = validate(raw);
+  if (!validation.valid || !validation.spec) {
+    printEnvelope(failGenerate(COMMAND, validation.errors));
+    process.exit(1);
+  }
+
+  const spec = validation.spec;
+  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 filesCreated: string[] = [];
+  const filesModified: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of files) {
+    const abs = resolve(join(spec.projectPath, file.path));
+    if (existsSync(abs)) {
+      const existing = readFileSync(abs, 'utf-8');
+      if (existing.trimStart().startsWith('/* @customised')) {
+        skipped.push(file.path);
+        continue;
+      }
+      if (!spec.force && existing === file.content) {
+        // No drift — no-op.
+        continue;
+      }
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, file.content, 'utf-8');
+      filesModified.push(abs);
+    } else {
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, file.content, 'utf-8');
+      filesCreated.push(abs);
+    }
+  }
+
+  const nextSteps: string[] = [];
+  if (skipped.length > 0) {
+    nextSteps.push(`Skipped ${skipped.length} customised file(s): ${skipped.join(', ')}. Remove the @customised marker to allow overwrites.`);
+  }
+  if (filesCreated.length === 0 && filesModified.length === 0 && skipped.length === 0) {
+    nextSteps.push('Theme already up-to-date — no changes needed.');
+  }
+  if (filesCreated.length > 0) {
+    nextSteps.push(`Verify src/main.tsx imports './index.css' (Vite entry).`);
+  }
+
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { fileCount: filesCreated.length + filesModified.length, skipped: skipped.length },
+    filesCreated,
+    filesModified,
+    warnings: validation.warnings,
+    nextSteps,
+  }));
+}
+
+main();

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

@@ -0,0 +1,48 @@
+/**
+ * scaffold-theme/types.ts — Input contract + generated file shape.
+ */
+import { z } from 'zod';
+
+export const ThemeTokensSchema = z.object({
+  /** Primary accent color hex (e.g. '#3b82f6'). Optional — falls back to SmartStack default. */
+  accent: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+  /** Dark-mode app background hex. Default '#161618'. */
+  darkBg: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+  /** Light-mode app background hex. Default '#ffffff'. */
+  lightBg: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
+  /** Border radius scale in px (default 8). */
+  radiusCard: z.number().int().min(0).max(64).optional(),
+});
+
+export type ThemeTokens = z.infer<typeof ThemeTokensSchema>;
+
+export const ScaffoldThemeInputSchema = z.object({
+  projectPath: z.string().min(1),
+  appCode: z.string().min(1),
+  prdSlice: z
+    .object({
+      theme: ThemeTokensSchema.optional(),
+    })
+    .nullable()
+    .optional(),
+  force: z.boolean().default(false),
+  /**
+   * Emit the `@shoelace-style/shoelace` light/dark theme imports in
+   * `src/index.css`. Defaults to `false` so a project that doesn't ship the
+   * package in its `package.json` no longer fails Vite resolution at boot
+   * (`Can't resolve '@shoelace-style/shoelace/dist/themes/light.css'`).
+   *
+   * Set to `true` when the project lists `@shoelace-style/shoelace` as a
+   * dependency. ba-develop can flip this on by reading the target project's
+   * `package.json` before invoking the CLI.
+   */
+  useShoelace: z.boolean().default(false),
+});
+
+export type ScaffoldThemeInput = z.infer<typeof ScaffoldThemeInputSchema>;
+
+export interface GeneratedFile {
+  /** Path relative to projectPath. */
+  path: string;
+  content: string;
+}