@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/frontend/component/cli/validate-page/types.ts

@@ -0,0 +1,58 @@
+/**
+ * cli:validate-page — types.ts
+ *
+ * Per-page deterministic validator. Runs eight blocking rules on a single
+ * generated page .tsx file. Used by the per-page audit-or-regenerate loop
+ * in ba-develop Phase 3a as the gate between scaffold-component
+ * invocations.
+ *
+ * Read-only: never writes files. The orchestrator is responsible for retries
+ * and aborts based on the report.
+ */
+import { z } from 'zod'
+
+export const ValidatePageInputSchema = z.object({
+  /** Web root, e.g. `<projectRoot>/web/<app>-web` (parent of `src/`). */
+  projectPath: z.string().min(1),
+  /**
+   * Page file to validate. Either an absolute path or a path relative to
+   * `projectPath`. Must end in `.tsx`.
+   */
+  pageFile: z.string().min(1),
+})
+
+export type ValidatePageInput = z.infer<typeof ValidatePageInputSchema>
+
+export type Severity = 'err' | 'warn'
+
+export interface Violation {
+  /** Rule id, e.g. 'imports-resolve'. Stable across releases. */
+  rule: string
+  severity: Severity
+  /** 1-based line number when the rule can pinpoint one. */
+  line?: number
+  /** Specific, actionable message including the offending value. */
+  message: string
+  /** Deterministic remediation hint — empty when fix requires judgement. */
+  suggestedFix?: string
+}
+
+export interface ValidatePageReport {
+  /** Absolute path to the page that was validated. */
+  pageFile: string
+  /** Module derived from the path, e.g. 'crm'. Null if path is non-standard. */
+  module: string | null
+  /** Entity derived from the filename, e.g. 'Contact'. Null if filename is non-standard. */
+  entity: string | null
+  /** View derived from the filename, e.g. 'list' | 'detail' | 'form' | 'dashboard' | 'create' | 'edit'. */
+  view: string | null
+  /** Ordered violations — caller renders them as-is. */
+  violations: Violation[]
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  spec?: ValidatePageInput
+}

package/templates/skills/development/frontend/component/cli/validate-page/validate.ts

@@ -0,0 +1,28 @@
+/**
+ * cli:validate-page — validate.ts
+ *
+ * Read-only Zod validation of CLI input. Disk reads happen in execute.ts.
+ */
+import {
+  ValidatePageInputSchema,
+  type ValidationResult,
+} from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ValidatePageInputSchema.safeParse(raw)
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`),
+      warnings: [],
+    }
+  }
+  if (!result.data.pageFile.endsWith('.tsx')) {
+    return {
+      valid: false,
+      errors: [`pageFile must end in .tsx (got: ${result.data.pageFile})`],
+      warnings: [],
+    }
+  }
+  return { valid: true, errors: [], warnings: [], spec: result.data }
+}

package/templates/skills/development/frontend/component/patterns/README.md

@@ -0,0 +1,42 @@
+# Composition patterns — `scaffold-component`
+
+Index of canonical pattern sheets. Each `.md` contains:
+
+- **When to use** — pick the right pattern for a screen type
+- **Anatomy** — tree showing the required wrappers + slot points
+- **Canonical example** — a full compliant TSX file you can copy-adapt
+- **Rules enforced** — which R1–R20 the pattern covers by construction
+- **Import contract** — where every name comes from
+- **Do NOT** — the recurring anti-patterns that surfaced in past runs
+
+## Rule of thumb for loading
+
+When the `scaffold-component` skill is invoked in the Frontend phase of
+`ba-develop`, **only load the pattern(s) relevant to the
+screens being generated** — not all five. Check the PRD's screen
+specifications:
+
+| Screen type (PRD) | Pattern file |
+|---|---|
+| "directory", "list", "table view" | [`list-page.md`](list-page.md) |
+| "detail", "single-entity view", "profile" | [`detail-page.md`](detail-page.md) |
+| "form", "create/edit", "wizard step" | [`form-page.md`](form-page.md) |
+| "pipeline", "kanban", "workflow board" | [`kanban-board.md`](kanban-board.md) |
+| "gallery", "catalogue", "dashboard cards" | [`entity-card.md`](entity-card.md) |
+
+## Source of truth
+
+All patterns derive from `D:/01 - projets/SmartStack.app/features/customisation-ui/`
+baseline pages + the `@atlashub/smartstack` npm package surface (see
+`node_modules/@atlashub/smartstack/dist/index.d.ts` for the exact set of
+components that SHIP with the platform).
+
+## Cross-references
+
+- **Rule catalogue** — `skills/development/frontend/ui-polish/tokens.json`
+  (20 rules) + `SKILL.md`
+- **Design tokens** — same `tokens.json` under `cssVariables` (125 CSS vars)
+- **Generator CLI** — `skills/development/frontend/component/cli/scaffold-component/`
+  emits the 3 "page" patterns (list, detail, form) automatically. kanban-board
+  and entity-card patterns are HAND-WRITTEN by the subagent when the PRD
+  asks for those screen types — that's why they need a `.md` reference.

package/templates/skills/development/frontend/component/patterns/detail-page.md

@@ -0,0 +1,133 @@
+# Pattern — `{Entity}DetailPage.tsx`
+
+## When to use
+
+The page that renders a single entity's full state (read view). URL contains
+a `:id` param. Has an "Edit" CTA that navigates to the Form page. May expose
+a sidebar slot for related data (activity timeline, relations tab, etc.).
+
+## Anatomy
+
+```
+PermissionGuard (read)
+  PageTemplate (title = entity label, icon, actions = Edit CTA)
+    Slot             — {entity}.detail.header (context={data})
+    card section     — dl grid with every field (label + value)
+    Slot             — {entity}.detail.sidebar (context={data})
+```
+
+## Canonical example (compliant)
+
+```tsx
+import { useParams, useNavigate, Navigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { Loader2, Pencil, FileText } from 'lucide-react';
+import { PermissionGuard, Slot } from '@atlashub/smartstack';
+import { PageTemplate } from '@/components/ui/PageTemplate';
+import { useContact } from '../hooks/useContact';
+
+export function ContactDetailPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { t } = useTranslation('contact');
+
+  if (!id) return <Navigate to=".." replace />;  // R9 — null-check
+
+  const { data, isLoading } = useContact(id);
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center py-12 text-[var(--text-muted)]">
+        <Loader2 className="w-5 h-5 animate-spin mr-2" />
+        {t('detail.loading')}
+      </div>
+    );
+  }
+  if (!data) {
+    return (
+      <div className="p-4 rounded-[var(--radius-card)] bg-[var(--warning-bg)] border border-[var(--warning-border)] text-[var(--warning-text)]">
+        {t('detail.notFound')}
+      </div>
+    );
+  }
+
+  const headerTitle = `${data.firstName ?? ''} ${data.lastName}`.trim();
+
+  return (
+    <PermissionGuard permission="crm.contacts.read">
+      <PageTemplate
+        title={headerTitle}
+        icon={<FileText className="w-6 h-6" />}
+        actions={
+          <PermissionGuard permission="crm.contacts.update">
+            <button
+              type="button"
+              onClick={() => navigate('./edit')}
+              className="flex items-center gap-1.5 px-3 py-2 rounded-[var(--radius-button)] bg-[var(--color-accent-500)] text-white text-sm font-medium hover:bg-[var(--color-accent-600)] transition-colors"
+            >
+              <Pencil className="w-4 h-4" />
+              {t('detail.edit')}
+            </button>
+          </PermissionGuard>
+        }
+      >
+        <Slot name="contact.detail.header" context={{ data }} />
+
+        <div className="p-6 rounded-[var(--radius-card)] border border-[var(--border-color)] bg-[var(--bg-card)]">
+          <dl className="grid grid-cols-1 md:grid-cols-2 gap-x-6 gap-y-4">
+            <div>
+              <dt className="text-xs font-semibold uppercase tracking-wider text-[var(--text-muted)] mb-1">
+                {t('detail.fields.lastName')}
+              </dt>
+              <dd className="text-sm text-[var(--text-primary)]">{data.lastName}</dd>
+            </div>
+            <div>
+              <dt className="text-xs font-semibold uppercase tracking-wider text-[var(--text-muted)] mb-1">
+                {t('detail.fields.email')}
+              </dt>
+              <dd className="text-sm text-[var(--text-primary)]">{data.email ?? '—'}</dd>
+            </div>
+            {/* one <div> per field */}
+          </dl>
+        </div>
+
+        <Slot name="contact.detail.sidebar" context={{ data }} />
+      </PageTemplate>
+    </PermissionGuard>
+  );
+}
+```
+
+## Rules this pattern enforces
+
+- **R1** — `<PageTemplate>`
+- **R3** — primary CTA Edit → `bg-[var(--color-accent-500)]`
+- **R4** — `useTranslation('entity')` + `t('detail.fields.<name>')` for every field label
+- **R5** — lucide-react icons only
+- **R6** — `<Loader2 className="animate-spin" />` for loading
+- **R9** — `useParams<{ id: string }>()` is null-checked (`if (!id) return <Navigate …>`)
+- **R10** — permission key format `{module}.{section}.{action}`
+- **R11** — two Slot extension points: `{entity}.detail.header` and `{entity}.detail.sidebar`
+- **R16** — radius tokens (`rounded-[var(--radius-card|button)]`)
+- **R19** — no palette / absolute color classes
+- **R20** — border always paired with `border-[var(--border-color)]`
+
+## Import contract
+
+| Name | From |
+|---|---|
+| `PermissionGuard`, `Slot` | `@atlashub/smartstack` |
+| `PageTemplate` | `@/components/ui/PageTemplate` |
+| Icons | `lucide-react` |
+| `useTranslation` | `react-i18next` |
+| `useParams`, `useNavigate`, `Navigate` | `react-router-dom` |
+
+## Do NOT
+
+- Skip the `if (!id) return <Navigate …>` guard — breaks R9 + crashes when route
+  lands on `/entity/` without id.
+- Render fields via hardcoded labels — every field label must be `t('detail.fields.<key>')`.
+- Put the Edit button outside `<PermissionGuard permission="*.update">`.
+- Render `data.lastName` as a raw string unprotected — always fall back via
+  `data.email ?? '—'` for nullable fields to avoid "undefined" in the UI.
+- Use `bg-white` for the card → `bg-[var(--bg-card)]`.

package/templates/skills/development/frontend/component/patterns/entity-card.md

@@ -0,0 +1,148 @@
+# Pattern — Grid of `<EntityCard>`
+
+## When to use
+
+Gallery-style lists where each row is a rich card (avatar + title + subtitle
++ stats + tags + actions) rather than a dense table. Typical use cases:
+theme presets, template catalogues, dashboards with tenant cards.
+
+If the display is a flat list with columns → use `list-page.md` + `<DataTable>`.
+If the display is a kanban with drag-drop → use `kanban-board.md`.
+
+## Anatomy
+
+```
+PermissionGuard (read)
+  PageTemplate (title, icon, actions)
+    Slot                 — {entity}.header.actions
+    filter bar           — optional, bg-[var(--bg-card)]
+    grid container       — grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4
+      EntityCard × N     — from @atlashub/smartstack
+        avatar, title, subtitle, description, stats[], badge, tags[], actions
+    Slot                 — {entity}.card.content (per-card extension)
+```
+
+## Canonical example (compliant)
+
+```tsx
+import { useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { Plus, Palette } from 'lucide-react';
+import { PermissionGuard, Slot, EntityCard } from '@atlashub/smartstack';
+import { PageTemplate } from '@/components/ui/PageTemplate';
+import { useThemes } from '../hooks/useTheme';
+
+export function ThemeGalleryPage() {
+  const { t } = useTranslation('theme');
+  const navigate = useNavigate();
+  const { data: themes = [] } = useThemes();
+
+  return (
+    <PermissionGuard permission="platform.theming.read">
+      <PageTemplate
+        title={t('list.title')}
+        subtitle={t('list.subtitle')}
+        icon={<Palette className="w-6 h-6" />}
+        actions={
+          <PermissionGuard permission="platform.theming.create">
+            <button
+              type="button"
+              onClick={() => navigate('./new')}
+              className="flex items-center gap-1.5 px-3 py-2 rounded-[var(--radius-button)] bg-[var(--color-accent-500)] text-white text-sm font-medium hover:bg-[var(--color-accent-600)] transition-colors"
+            >
+              <Plus className="w-4 h-4" />
+              {t('list.create')}
+            </button>
+          </PermissionGuard>
+        }
+      >
+        <Slot name="theme.header.actions" />
+
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4 p-4">
+          {themes.map((theme) => (
+            <EntityCard
+              key={theme.id}
+              title={theme.name}
+              subtitle={theme.mode === 'dark' ? t('list.subtitle.dark') : t('list.subtitle.light')}
+              description={theme.description ?? undefined}
+              badge={theme.isDefault ? {
+                label: t('list.badge.default'),
+                variant: 'success',
+              } : undefined}
+              stats={[
+                { label: t('list.stats.tenants'), value: theme.tenantCount },
+                { label: t('list.stats.presets'), value: theme.presetCount },
+              ]}
+              tags={theme.tags ?? []}
+              actions={[
+                {
+                  label: t('list.actions.preview'),
+                  onClick: () => navigate(`./${theme.id}/preview`),
+                },
+                {
+                  label: t('list.actions.edit'),
+                  onClick: () => navigate(`./${theme.id}/edit`),
+                  permission: 'platform.theming.update',
+                },
+              ]}
+              onClick={() => navigate(`./${theme.id}`)}
+              customFooter={<Slot name="theme.card.content" context={{ theme }} />}
+            />
+          ))}
+        </div>
+      </PageTemplate>
+    </PermissionGuard>
+  );
+}
+```
+
+## Rules this pattern enforces
+
+- **R1** — `<PageTemplate>`
+- **R3** — primary CTA accent
+- **R4** — every visible string via `t('...')`
+- **R5** — lucide-react icons
+- **R8** — NOT applicable (grid of cards is an explicit exception to "lists use DataTable")
+- **R10** — `platform.theming.<action>` permission format
+- **R11** — Slot header.actions + per-card Slot
+- **R19** — no palette / absolute colors (EntityCard internals handle their own theming)
+- **R20** — no bare borders outside of EntityCard itself
+
+## EntityCard prop contract
+
+| Prop | Type | Purpose |
+|---|---|---|
+| `avatar` | `ReactNode` | optional leading visual (icon, color swatch, image) |
+| `title` | `string` | card header, always present |
+| `subtitle` | `string \| null` | optional secondary line |
+| `description` | `string \| null` | optional paragraph body |
+| `stats` | `Array<{label,value}>` | 2-4 key metrics rendered inline |
+| `badge` | `{label, variant}` | status chip (success/warning/error/info) |
+| `tags` | `string[]` | pill list rendered at bottom |
+| `links` | `Array<{label,href}>` | external refs rendered as text links |
+| `actions` | `Array<{label,onClick,permission?}>` | CTA buttons — `permission` auto-wraps in `<PermissionGuard>` |
+| `onClick` | `() => void` | makes the whole card clickable |
+| `customHeader` | `ReactNode` | replaces the default title/subtitle block |
+| `customBody` | `ReactNode` | replaces the default description/stats block |
+| `customFooter` | `ReactNode` | injected below tags (good place for a `<Slot>`) |
+
+## Import contract
+
+| Name | From |
+|---|---|
+| `PermissionGuard`, `Slot`, `EntityCard` | `@atlashub/smartstack` |
+| `PageTemplate` | `@/components/ui/PageTemplate` |
+| Icons | `lucide-react` |
+| `useTranslation` | `react-i18next` |
+| `useNavigate` | `react-router-dom` |
+
+## Do NOT
+
+- Hand-roll a `<div className="rounded-lg bg-white shadow"><h3>…</h3>…</div>`
+  card — use `<EntityCard>`. The component handles light/dark, radius tokens,
+  hover shadows, accessibility roles.
+- Pass `badge={{ label: 'Active', variant: 'green' }}` — the variant is
+  `success | warning | error | info | accent`, not a color name.
+- Use `grid-cols-4` or `grid-cols-5` — baseline is `1 / md:2 / xl:3`.
+- Put the action buttons inside `customFooter` — use the `actions` prop so
+  EntityCard handles permissions + keyboard focus uniformly.

package/templates/skills/development/frontend/component/patterns/form-page.md

@@ -0,0 +1,191 @@
+# Pattern — `{Entity}FormPage.tsx`
+
+## When to use
+
+Create OR edit view for an entity. Single `FormPage` component handles both
+modes via `id === 'new'` convention. The form is a vertical list of labeled
+inputs wrapped in a `.card` section. Errors surface as a token-based banner
+at the top.
+
+## Anatomy
+
+```
+PermissionGuard (create or update depending on mode)
+  PageTemplate (title = createTitle | editTitle, icon = FilePen)
+    error banner       — bg-[var(--error-bg)] + AlertTriangle (R7)
+    form (onSubmit)
+      card section     — rounded-[var(--radius-card)] border bg-[var(--bg-card)]
+        Slot           — {entity}.form.fields.before (context={formData, onChange})
+        field × N      — <label> + <input className="input">
+        Slot           — {entity}.form.fields.after
+      actions row      — Cancel + Submit (Submit = accent CTA)
+```
+
+## Canonical example (compliant)
+
+```tsx
+import { useState, useEffect } from 'react';
+import type { FormEvent } from 'react';
+import { useParams, useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { Loader2, AlertTriangle, FilePen } from 'lucide-react';
+import { PermissionGuard, Slot } from '@atlashub/smartstack';
+import { PageTemplate } from '@/components/ui/PageTemplate';
+import { useContact, useCreateContact, useUpdateContact } from '../hooks/useContact';
+
+type ContactFormData = {
+  lastName: string;
+  firstName?: string;
+  email?: string;
+};
+
+const initialContactFormData: ContactFormData = {
+  lastName: '',
+  firstName: '',
+  email: '',
+};
+
+export function ContactFormPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { t } = useTranslation('contact');
+  const isEdit = !!id && id !== 'new';  // R9 — combined null-check + mode
+  const { data: existing } = useContact(isEdit ? id! : '');
+  const createMutation = useCreateContact();
+  const updateMutation = useUpdateContact();
+
+  const [formData, setFormData] = useState<ContactFormData>(initialContactFormData);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (existing) setFormData(existing as ContactFormData);
+  }, [existing]);
+
+  const onChange = <K extends keyof ContactFormData>(field: K, value: ContactFormData[K]) => {
+    setFormData((prev) => ({ ...prev, [field]: value }));
+  };
+
+  const handleSubmit = async (event: FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    try {
+      if (isEdit && id) {
+        await updateMutation.mutateAsync({ id, data: formData });
+      } else {
+        await createMutation.mutateAsync(formData);
+      }
+      navigate(-1);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  const permission = isEdit ? 'crm.contacts.update' : 'crm.contacts.create';
+  const isPending = createMutation.isPending || updateMutation.isPending;
+
+  return (
+    <PermissionGuard permission={permission}>
+      <PageTemplate
+        title={isEdit ? t('form.editTitle') : t('form.createTitle')}
+        icon={<FilePen className="w-6 h-6" />}
+      >
+        {error && (
+          <div className="p-4 rounded-[var(--radius-card)] bg-[var(--error-bg)] border border-[var(--error-border)]">
+            <div className="flex items-center gap-2 text-[var(--error-text)]">
+              <AlertTriangle className="w-5 h-5" />
+              <span>{error}</span>
+            </div>
+          </div>
+        )}
+
+        <form onSubmit={handleSubmit} className="space-y-6">
+          <div className="p-6 rounded-[var(--radius-card)] border border-[var(--border-color)] bg-[var(--bg-card)] space-y-4">
+            <Slot name="contact.form.fields.before" context={{ formData, onChange }} />
+
+            <div>
+              <label htmlFor="lastName" className="block text-sm font-medium text-[var(--text-primary)] mb-1">
+                {t('form.fields.lastName')} <span className="text-[var(--error-text)]">*</span>
+              </label>
+              <input
+                id="lastName"
+                type="text"
+                value={formData.lastName}
+                onChange={(e) => onChange('lastName', e.target.value)}
+                required
+                disabled={isPending}
+                className="input w-full disabled:opacity-50"
+              />
+            </div>
+            {/* repeat <div> + <label> + <input className="input"> per field */}
+
+            <Slot name="contact.form.fields.after" context={{ formData, onChange }} />
+          </div>
+
+          <div className="flex justify-end gap-2">
+            <button
+              type="button"
+              onClick={() => navigate(-1)}
+              disabled={isPending}
+              className="px-6 py-2 rounded-[var(--radius-button)] bg-[var(--bg-secondary)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)] disabled:opacity-50 transition-colors"
+            >
+              {t('form.cancel')}
+            </button>
+            <button
+              type="submit"
+              disabled={isPending}
+              className="flex items-center gap-2 px-6 py-2 rounded-[var(--radius-button)] bg-[var(--color-accent-500)] text-white hover:bg-[var(--color-accent-600)] disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+            >
+              {isPending && <Loader2 className="w-4 h-4 animate-spin" />}
+              {isEdit ? t('form.submitUpdate') : t('form.submitCreate')}
+            </button>
+          </div>
+        </form>
+      </PageTemplate>
+    </PermissionGuard>
+  );
+}
+```
+
+## Rules this pattern enforces
+
+- **R1** — `<PageTemplate>`
+- **R3** — submit button uses accent token; cancel uses `bg-[var(--bg-secondary)]`
+- **R4** — field labels, button text, errors all flow through `t('form.…')`
+- **R5** — lucide-react icons only
+- **R6** — Loader2 animate-spin during submit
+- **R7** — error banner uses `bg-[var(--error-bg)] border-[var(--error-border)] text-[var(--error-text)]`
+- **R9** — `!!id && id !== 'new'` combined null-check + mode detection
+- **R10** — permission key `{module}.{section}.{action}` per mode
+- **R11** — Slot extension points: `{entity}.form.fields.before/after`
+- **R13** — NOT directly applicable (no badges in form)
+- **R16** — radius tokens
+- **R19** — no palette / absolute colors
+- **R20** — every border paired with color token
+
+## The `.input` helper class
+
+Inputs use the global `.input` class (defined in baseline `base.css`) which
+bundles: radius-input token, focus ring accent-500, border-color token,
+disabled opacity, padding. DO NOT redefine these via Tailwind arbitrary
+values — `.input` is the single source of truth.
+
+## Import contract
+
+| Name | From |
+|---|---|
+| `PermissionGuard`, `Slot` | `@atlashub/smartstack` |
+| `PageTemplate` | `@/components/ui/PageTemplate` |
+| Icons (AlertTriangle, Loader2, FilePen) | `lucide-react` |
+| `useState`, `useEffect`, `FormEvent` | `react` |
+| `useParams`, `useNavigate` | `react-router-dom` |
+| `useTranslation` | `react-i18next` |
+| mutations | `../hooks/use{Entity}` (scaffolded by api-client) |
+
+## Do NOT
+
+- Use `<input />` without the `.input` class — loses focus ring + theme.
+- Render error banners with `bg-red-50 text-red-700` — use the R7 anatomy.
+- Use `disabled:bg-gray-200` — pair `disabled:opacity-50` instead (transparent, theme-safe).
+- Submit without the `isPending` disabled guard — users double-submit.
+- Skip the `Slot fields.before` / `fields.after` — they're the official
+  extension point for client customizations adding optional fields.