@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/development/frontend/component/patterns/kanban-board.md

@@ -0,0 +1,195 @@
+# Pattern — Kanban Board
+
+## When to use
+
+Pipeline / workflow visualization where entities move through a fixed set of
+STAGES (qualification → proposal → negotiation → won / lost). Drag-and-drop
+moves items between columns; columns named `won` / `lost` / `abandoned` are
+TERMINAL (no drop). A parallel `ListView` route is expected for users who
+prefer a table.
+
+## Anatomy
+
+```
+PageTemplate (title, actions = [switch to list, + new, filter bar])
+  Slot             — {entity}.header.actions
+  filter bar       — bg-[var(--bg-card)] with border-b border-[var(--border-color)]
+  columns flex     — one <div> per stage
+    stage header   — label + count (bg-[var(--bg-hover)])
+    card list      — draggable cards, bg-[var(--bg-card)]
+```
+
+## Canonical example (compliant)
+
+```tsx
+import { useState, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate } from 'react-router-dom';
+import { PermissionGuard, Slot } from '@atlashub/smartstack';
+import { PageTemplate } from '@/components/ui/PageTemplate';
+import { opportunitiesApi } from '@/services/api/prospectionApi';
+import type {
+  OpportunityListDto,
+  OpportunityStatus,
+  OpportunityFilters,
+  OpportunityStageDto,
+} from '@/types/prospection';
+
+const COLUMNS: OpportunityStatus[] = [
+  'qualification', 'proposition', 'negociation', 'gagnee', 'perdue', 'abandonnee',
+];
+const TERMINAL: ReadonlySet<OpportunityStatus> = new Set(['gagnee', 'perdue', 'abandonnee']);
+
+export function PipelinePage() {
+  const { t } = useTranslation('prospection');
+  const navigate = useNavigate();
+  const [items, setItems] = useState<OpportunityListDto[]>([]);
+  const [stages, setStages] = useState<OpportunityStageDto[]>([]);
+  const [draggedId, setDraggedId] = useState<string | null>(null);
+
+  useEffect(() => {
+    void opportunitiesApi.getStages().then(setStages);
+    void opportunitiesApi.getAll().then(setItems);
+  }, []);
+
+  const handleDrop = async (target: OpportunityStatus) => {
+    if (!draggedId) return;
+    const opp = items.find((o) => o.id === draggedId);
+    if (!opp || opp.status === target) return;
+    const stage = stages.find((s) => s.name === target);
+    if (!stage) return;
+    await opportunitiesApi.moveStage(draggedId, { toStageId: stage.id });
+    setItems((prev) => prev.map((o) => o.id === draggedId ? { ...o, status: target, stageName: stage.name } : o));
+    setDraggedId(null);
+  };
+
+  const byStatus = (s: OpportunityStatus) => items.filter((o) => o.status === s);
+
+  return (
+    <PermissionGuard permission="crm.prospection.read">
+      <PageTemplate
+        title={t('pipeline.title')}
+        actions={
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              onClick={() => navigate('/crm/prospection/pipeline/list')}
+              className="rounded-[var(--radius-button)] border border-[var(--border-color)] px-3 py-1.5 text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)]"
+            >
+              {t('pipeline.viewList')}
+            </button>
+            <PermissionGuard permission="crm.prospection.create">
+              <button
+                type="button"
+                onClick={() => navigate('/crm/prospection/pipeline/new')}
+                className="rounded-[var(--radius-button)] bg-[var(--color-accent-500)] px-4 py-2 text-sm font-medium text-white hover:bg-[var(--color-accent-600)] transition-colors"
+              >
+                + {t('pipeline.newOpportunity')}
+              </button>
+            </PermissionGuard>
+          </div>
+        }
+      >
+        <Slot name="opportunity.header.actions" />
+
+        <div className="flex flex-1 overflow-auto gap-3 p-4">
+          {COLUMNS.map((status) => {
+            const colItems = byStatus(status);
+            const isTerminal = TERMINAL.has(status);
+            return (
+              <div
+                key={status}
+                className="flex flex-col w-56 shrink-0 rounded-[var(--radius-card)] border border-[var(--border-color)] bg-[var(--bg-hover)]"
+                onDragOver={(e) => { if (!isTerminal) e.preventDefault(); }}
+                onDrop={() => { void handleDrop(status); }}
+              >
+                <div className="border-b border-[var(--border-color)] px-3 py-2">
+                  <p className="text-sm font-semibold text-[var(--text-primary)]">
+                    {t(`pipeline.status.${status}`)}
+                  </p>
+                  <p className="text-xs text-[var(--text-secondary)]">{colItems.length}</p>
+                </div>
+
+                <div className="flex-1 overflow-auto p-2 space-y-2">
+                  {colItems.length === 0 ? (
+                    <p className="py-4 text-center text-xs text-[var(--text-secondary)]">
+                      {t('common.noResults')}
+                    </p>
+                  ) : (
+                    colItems.map((opp) => (
+                      <button
+                        key={opp.id}
+                        type="button"
+                        draggable={!isTerminal}
+                        onDragStart={() => setDraggedId(opp.id)}
+                        onDragEnd={() => setDraggedId(null)}
+                        onClick={() => navigate(`/crm/prospection/pipeline/${opp.id}`)}
+                        className="w-full text-left rounded-[var(--radius-badge)] border border-[var(--border-color)] bg-[var(--bg-card)] p-3 shadow-sm cursor-pointer hover:shadow-md transition-shadow"
+                      >
+                        <div className="flex items-start justify-between gap-2">
+                          <p className="text-sm font-medium text-[var(--text-primary)] truncate flex-1">
+                            {opp.title}
+                          </p>
+                          {opp.isAtRisk && (
+                            <span className="shrink-0 rounded-[var(--radius-badge)] bg-[var(--error-bg)] px-1.5 py-0.5 text-xs text-[var(--error-text)]">
+                              {t('pipeline.atRisk')}
+                            </span>
+                          )}
+                        </div>
+                        <p className="mt-1 text-xs text-[var(--text-secondary)]">
+                          {opp.estimatedAmount.toLocaleString()} {opp.currency}
+                        </p>
+                      </button>
+                    ))
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </PageTemplate>
+    </PermissionGuard>
+  );
+}
+```
+
+## Rules this pattern enforces
+
+- **R1** — `<PageTemplate>`
+- **R3** — primary CTA accent (new opportunity button)
+- **R4** — `useTranslation('entity')` + `t('pipeline.status.<status>')`
+- **R8** — NOT applicable (kanban is NOT a list — raw `<table>` exception)
+- **R10** — permission format
+- **R11** — Slot `{entity}.header.actions`
+- **R16** — radius tokens on columns + cards
+- **R17** — cards use `<button>` not `<div onClick>` — keyboard accessibility
+- **R19** — `bg-[var(--bg-hover)]` for column, `bg-[var(--bg-card)]` for card (NO `bg-white`)
+- **R20** — every border paired with `border-[var(--border-color)]`
+
+## Terminal-column contract
+
+Columns representing final states (`won` / `lost` / `abandoned`) have a
+distinct drop behaviour: `onDragOver` must NOT call `preventDefault` — this
+rejects drops from the browser. Cards inside terminal columns have
+`draggable={false}`. The pattern above uses a `TERMINAL` set for clarity.
+
+## Import contract
+
+| Name | From |
+|---|---|
+| `PermissionGuard`, `Slot` | `@atlashub/smartstack` |
+| `PageTemplate` | `@/components/ui/PageTemplate` |
+| `useTranslation` | `react-i18next` |
+| `useNavigate` | `react-router-dom` |
+
+## Do NOT
+
+- Use `<div onClick>` for the cards — use `<button type="button">` (R17).
+- `bg-white` for the card → `bg-[var(--bg-card)]`.
+- `border` alone on column/card → always paired with `border-[var(--border-color)]`.
+- Emoji ⚠ for the at-risk badge — use an i18n string or lucide icon.
+- Allow drag-to-terminal without a confirmation step if the PRD says moves
+  to terminal states require justification (rule-dependent — check the
+  business rules slice before scaffolding).
+- Render a separate `<h1>` inside PageTemplate's children — title is already
+  emitted by `<PageTemplate title={…}>`.

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

@@ -0,0 +1,175 @@
+# Pattern — `{Entity}ListPage.tsx`
+
+## When to use
+
+Any page that renders a flat list of entities: contacts, leads, tickets, orders,
+products. Columns are known and finite (≤10). Search + pagination are expected.
+
+For grid-of-cards (gallery), use `entity-card.md`. For pipeline stages,
+use `kanban-board.md`.
+
+## Anatomy
+
+```
+PermissionGuard (read)
+  PageTemplate (title, icon, actions)
+    Slot             — {entity}.header.actions
+    error banner     — token-based (R7)
+    Slot             — {entity}.table.columns.before
+    isLoading ?      — Loader2 animate-spin
+      DataTable<T>   — from @atlashub/smartstack
+    Slot             — {entity}.table.columns.after
+```
+
+## Canonical example (compliant)
+
+```tsx
+import type { ReactNode } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { Loader2, Plus, Pencil, Trash2, List } from 'lucide-react';
+import { PermissionGuard, Slot, DataTable } from '@atlashub/smartstack';
+import { PageTemplate } from '@/components/ui/PageTemplate';
+import { useContacts, useDeleteContact } from '../hooks/useContact';
+import type { Contact } from '../types';
+
+type DataTableColumn<T> = {
+  key: string;
+  label: string;
+  sortable?: boolean;
+  align?: 'left' | 'center' | 'right';
+  render?: (item: T) => ReactNode;
+};
+
+export function ContactListPage() {
+  const { t } = useTranslation('contact');
+  const navigate = useNavigate();
+  const { data, isLoading, error } = useContacts();
+  const deleteMutation = useDeleteContact();
+
+  const columns: DataTableColumn<Contact>[] = [
+    { key: 'lastName', label: t('list.columns.lastName'), sortable: true },
+    { key: 'email', label: t('list.columns.email'), sortable: true },
+    {
+      key: '__actions',
+      label: t('list.actions'),
+      align: 'right',
+      render: (item) => (
+        <div className="flex items-center justify-end gap-1">
+          <PermissionGuard permission="crm.contacts.update">
+            <button
+              type="button"
+              onClick={(e) => { e.stopPropagation(); navigate(`./${item.id}/edit`); }}
+              className="p-1.5 rounded-[var(--radius-badge)] hover:bg-[var(--bg-hover)] text-[var(--text-muted)] hover:text-[var(--text-primary)]"
+              title={t('list.edit')}
+            >
+              <Pencil className="w-4 h-4" />
+            </button>
+          </PermissionGuard>
+          <PermissionGuard permission="crm.contacts.delete">
+            <button
+              type="button"
+              onClick={(e) => { e.stopPropagation(); void deleteMutation.mutateAsync(item.id); }}
+              className="p-1.5 rounded-[var(--radius-badge)] hover:bg-[var(--error-bg)] text-[var(--text-muted)] hover:text-[var(--error-text)]"
+              title={t('list.delete')}
+            >
+              <Trash2 className="w-4 h-4" />
+            </button>
+          </PermissionGuard>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <PermissionGuard permission="crm.contacts.read">
+      <PageTemplate
+        title={t('list.title')}
+        subtitle={t('list.subtitle')}
+        icon={<List className="w-6 h-6" />}
+        actions={
+          <PermissionGuard permission="crm.contacts.create">
+            <button
+              type="button"
+              onClick={() => navigate('./new/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"
+            >
+              <Plus className="w-4 h-4" />
+              {t('list.create')}
+            </button>
+          </PermissionGuard>
+        }
+      >
+        <Slot name="contact.header.actions" />
+
+        {error && (
+          <div className="mb-4 p-3 rounded-[var(--radius-card)] bg-[var(--error-bg)] border border-[var(--error-border)] text-sm text-[var(--error-text)]">
+            {t('list.error')}: {String(error)}
+          </div>
+        )}
+
+        <Slot name="contact.table.columns.before" />
+
+        {isLoading ? (
+          <div className="flex items-center justify-center py-12 text-[var(--text-muted)]">
+            <Loader2 className="w-5 h-5 animate-spin mr-2" />
+            {t('list.loading')}
+          </div>
+        ) : (
+          <DataTable<Contact>
+            data={data?.items ?? []}
+            columns={columns}
+            searchable
+            searchPlaceholder={t('list.search')}
+            pagination={{ pageSize: 20, showSizeSelector: true }}
+            getRowKey={(item) => item.id}
+            emptyMessage={t('list.empty')}
+            onRowClick={(item) => navigate(`./${item.id}`)}
+          />
+        )}
+
+        <Slot name="contact.table.columns.after" />
+      </PageTemplate>
+    </PermissionGuard>
+  );
+}
+```
+
+## Rules this pattern enforces
+
+- **R1** — `<PageTemplate>` wrap
+- **R3** — primary CTA uses `bg-[var(--color-accent-500)] text-white hover:bg-[var(--color-accent-600)]`
+- **R4** — every user-facing string flows through `useTranslation('entity')` + `t('key')`
+- **R5** — icons only from `lucide-react`
+- **R6** — loading state = `<Loader2 className="animate-spin" />`
+- **R8** — `<DataTable>` (npm `@atlashub/smartstack`), NOT raw `<table>`
+- **R10** — permission keys `{module}.{section}.{action}` (no appCode prefix)
+- **R11** — Slot injection points: `{entity}.header.actions`, `{entity}.table.columns.before/after`
+- **R13** — status badges use `bg-[var(--<status>-bg)]` anatomy
+- **R16** — radius tokens (`rounded-[var(--radius-button|card|badge)]`)
+- **R19** — no palette (`bg-gray-*`, `text-blue-*`) nor absolute (`bg-white`, `bg-black`) colors
+- **R20** — borders always paired with `border-[var(--border-color)]`
+
+## Import contract
+
+| Name | From | Notes |
+|---|---|---|
+| `PermissionGuard`, `Slot`, `DataTable` | `@atlashub/smartstack` | npm package |
+| `PageTemplate` | `@/components/ui/PageTemplate` | local baseline file |
+| Icons (Loader2, Plus, Pencil, Trash2, List) | `lucide-react` | no other icon lib |
+| `useTranslation` | `react-i18next` | |
+| `useNavigate` | `react-router-dom` | |
+
+**DataTableColumn type is NOT re-exported from `@atlashub/smartstack`** — declare
+the minimal local type alias as shown (lines 12-18 of the canonical example).
+
+## Do NOT
+
+- Raw `<table>` / `<thead>` / `<tbody>` — use `<DataTable>`
+- `bg-white` → `bg-[var(--bg-card)]`
+- `bg-gray-50` → `bg-[var(--bg-hover)]` or `bg-[var(--bg-secondary)]`
+- `border` alone → `border border-[var(--border-color)]`
+- `text-blue-700` → `text-[var(--info-text)]`
+- `className="bg-[#6366f1]"` → use the accent token
+- Hardcoded user-facing strings — always `t('key')`
+- `<div onClick>` for buttons — use `<button type="button">`

package/templates/skills/development/frontend/extension-config/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: frontend-extension-config
+description: >
+  Generates ExtensionConfig (@atlashub/smartstack) with slot definitions that
+  mirror the <Slot name="..."> calls emitted by frontend/component.
+phase: development/frontend
+cli: cli/scaffold-extension-config
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Extension Config — Slots + Columns + Form Fields
+
+Generates the `ExtensionConfig` that publishes the module's extension points
+(slots, table columns, form fields) to SmartStack's extension system.
+
+`ExtensionConfig` type comes from `@atlashub/smartstack` (npm).
+
+## Slot catalog contract
+
+The slot catalog emitted here MUST match exactly the `<Slot name="...">` calls
+emitted by `frontend/component/scaffold-component`. Renaming in one place
+without the other breaks composition silently (fills will never render).
+
+Per entity, six slots are registered:
+
+| Slot name | Rendered by `{Entity}ListPage`/`DetailPage`/`FormPage` | Context shape |
+|-----------|--------------------------------------------------------|---------------|
+| `{module}.{entityLower}.list.before` | ListPage, above the table | `{}` |
+| `{module}.{entityLower}.list.after` | ListPage, below the table | `{}` |
+| `{module}.{entityLower}.detail.before` | DetailPage, top | `{ data: {Entity} }` |
+| `{module}.{entityLower}.detail.after` | DetailPage, bottom | `{ data: {Entity} }` |
+| `{module}.{entityLower}.form.fields.before` | FormPage, before scaffolded fields | `{ formData, onChange }` |
+| `{module}.{entityLower}.form.fields.after` | FormPage, after scaffolded fields | `{ formData, onChange }` |
+
+## Output pattern
+
+```ts
+import type { ExtensionConfig } from '@atlashub/smartstack';
+
+/**
+ * Extension configuration for the hrm module.
+ *
+ * Slot catalog (each <Slot name="..."> call must match exactly):
+ *   - 'hrm.employee.list.before': Rendered above the Employee list table.
+ *       context: {}
+ *   - 'hrm.employee.detail.before': Rendered at the top of the Employee detail page.
+ *       context: { data: Employee }
+ *   - ...
+ *
+ * Add Fill components in your app entrypoint to inject content into any slot:
+ *   <Fill slot="hrm.employee.list.before">{yourJsx}</Fill>
+ */
+export const hrmConfig: ExtensionConfig = {
+  slots: {
+    'hrm.employee.list.before': null,
+    'hrm.employee.list.after': null,
+    'hrm.employee.detail.before': null,
+    'hrm.employee.detail.after': null,
+    'hrm.employee.form.fields.before': null,
+    'hrm.employee.form.fields.after': null,
+    // ... one group per entity
+  },
+  tableColumns: {},
+  formFields: {},
+  hooks: {},
+};
+```
+
+The `tableColumns` and `formFields` are left empty for the client to populate
+with domain-specific column extensions and custom `ext.*` form fields. `hooks`
+is reserved for future behavioural extension points.
+
+## ⚠ BLOCKING — Key Rules
+
+1. **Module name**: kebab-case, starts with a letter (regex `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`).
+2. **Entity names**: PascalCase (regex `/^[A-Z][A-Za-z0-9]*$/`).
+3. **Slot naming**: must match the pattern `{module}.{entityLower}.{view}.{position}` (five parts for form fields). The component generator emits exactly this shape — any deviation breaks the contract.
+
+## Invocation
+
+```bash
+npx tsx skills/development/frontend/extension-config/cli/scaffold-extension-config/index.ts \
+  --spec '{"module":"hrm","appCode":"myapp","entities":["Employee","Contract"],"projectPath":"/path"}'
+```
+
+## Output
+
+- `src/extensions/{module}Extensions.ts` — one file per module listing all entities' slots.
+
+## Client usage
+
+Register the config with the SmartStack extension system (usually in `main.tsx`
+after the registry imports):
+
+```ts
+import { registerExtensionConfig } from '@atlashub/smartstack';
+import { hrmConfig } from './extensions/hrmExtensions';
+
+registerExtensionConfig('hrm', hrmConfig);
+```
+
+Then fills can be provided anywhere in the app:
+
+```tsx
+<Fill slot="hrm.employee.list.before">
+  <MyCustomBanner />
+</Fill>
+```

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

@@ -0,0 +1,64 @@
+/**
+ * cli:scaffold-extension-config — generate.ts
+ *
+ * Emits an ExtensionConfig for a module, listing every slot that the scaffolded
+ * components publish via `<Slot name="..." />`. Clients (or other extensions)
+ * fill these slots with `<Fill slot="..." />`.
+ *
+ * ExtensionConfig type comes from `@atlashub/smartstack` (npm).
+ *
+ * The slot catalog below mirrors the exact `<Slot name="...">` calls emitted by
+ * `frontend/component` generator. Renaming slots in one place without the other
+ * breaks composition silently.
+ */
+import type { ScaffoldExtensionConfigInput, GeneratedFile } from './types.js'
+
+interface SlotDescriptor {
+  name: string
+  description: string
+  contextShape: string
+}
+
+function buildSlots(module: string, entity: string): SlotDescriptor[] {
+  const eLower = entity.charAt(0).toLowerCase() + entity.slice(1)
+  const base = `${module}.${eLower}`
+  return [
+    { name: `${base}.list.before`, description: `Rendered above the ${entity} list table.`, contextShape: `{}` },
+    { name: `${base}.list.after`, description: `Rendered below the ${entity} list table.`, contextShape: `{}` },
+    { name: `${base}.detail.before`, description: `Rendered at the top of the ${entity} detail page.`, contextShape: `{ data: ${entity} }` },
+    { name: `${base}.detail.after`, description: `Rendered at the bottom of the ${entity} detail page.`, contextShape: `{ data: ${entity} }` },
+    { name: `${base}.form.fields.before`, description: `Injects form fields before the scaffolded ones.`, contextShape: `{ formData: ${entity}FormData, onChange: (field, value) => void }` },
+    { name: `${base}.form.fields.after`, description: `Injects form fields after the scaffolded ones.`, contextShape: `{ formData: ${entity}FormData, onChange: (field, value) => void }` },
+  ]
+}
+
+export function generate(spec: ScaffoldExtensionConfigInput): GeneratedFile[] {
+  const allSlots = spec.entities.flatMap(e => buildSlots(spec.module, e))
+  const jsDocLines = allSlots
+    .map(s => ` *   - '${s.name}': ${s.description}\n *       context: ${s.contextShape}`)
+    .join('\n')
+  const slotEntries = allSlots.map(s => `    '${s.name}': null,`).join('\n')
+
+  const content = `import type { ExtensionConfig } from '@atlashub/smartstack';
+
+/**
+ * Extension configuration for the ${spec.module} module.
+ *
+ * Slot catalog (each <Slot name="..."> call below must match exactly):
+${jsDocLines}
+ *
+ * Add Fill components in your app entrypoint to inject content into any slot:
+ *   <Fill slot="${allSlots[0]?.name ?? 'example'}">{yourJsx}</Fill>
+ */
+export const ${spec.module}Config: ExtensionConfig = {
+  slots: {
+${slotEntries}
+  },
+  tableColumns: {},
+  formFields: {},
+  hooks: {},
+};
+`
+
+  return [{ path: `src/extensions/${spec.module}Extensions.ts`, content }]
+}

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-extension-config — Generate ExtensionConfig
+ */
+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-extension-config'
+
+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: ['Import config in app entry point'],
+  }))
+}
+
+main()

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

@@ -0,0 +1,27 @@
+/**
+ * cli:scaffold-extension-config — types.ts
+ *
+ * Slot name format: `{module}.{entity}.{view}.{position}` where each segment is
+ * kebab-case. Deviating from this pattern breaks runtime slot resolution.
+ */
+import { z } from 'zod'
+
+const SEGMENT_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+export const ScaffoldExtensionConfigInputSchema = z.object({
+  module: z.string().min(1).regex(SEGMENT_REGEX, 'module must be kebab-case'),
+  appCode: z.string().min(1).regex(SEGMENT_REGEX, 'appCode must be kebab-case'),
+  entities: z.array(z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/, 'entities must be PascalCase')).min(1),
+  projectPath: z.string().min(1),
+})
+
+export type ScaffoldExtensionConfigInput = z.infer<typeof ScaffoldExtensionConfigInputSchema>
+export interface GeneratedFile {
+  path: string
+  content: string
+}
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}

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

@@ -0,0 +1,16 @@
+/**
+ * cli:scaffold-extension-config — validate.ts
+ */
+import { ScaffoldExtensionConfigInputSchema, type ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ScaffoldExtensionConfigInputSchema.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: [],
+  }
+}