@atlashub/smartstack-cli 1.37.0 → 2.1.0

package/templates/skills/ui-components/patterns/data-table.md

@@ -0,0 +1,39 @@
+# DataTable Pattern
+
+## COMPONENT: DataTable
+
+```tsx
+import { DataTable } from '@/components/ui/DataTable';
+
+<DataTable
+  data={users}
+  columns={[
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'role', label: 'Role', render: (user) => <Badge>{user.role}</Badge> }
+  ]}
+  pagination={{ pageSize: 10 }}
+  searchable
+  onRowClick={(user) => navigate(`/users/${user.id}`)}
+/>
+```
+
+## COMPONENT: Tooltip
+
+```tsx
+import { Tooltip } from '@/components/ui/Tooltip';
+
+// Variants: default, error, warning, success, info
+// Positions: top, bottom, left, right
+
+<Tooltip content="Permission required" variant="error">
+  <button disabled>Protected action</button>
+</Tooltip>
+```
+
+### Disabled Button with Explanation Pattern
+```tsx
+const canExecute = hasPermission('module.action.execute');
+<Tooltip content={!canExecute ? t('errors.noPermission') : undefined} variant="error" disabled={canExecute}>
+  <button disabled={!canExecute}>Action</button>
+</Tooltip>
+```

package/templates/skills/ui-components/patterns/entity-card.md

@@ -0,0 +1,77 @@
+# EntityCard Pattern (MANDATORY)
+
+**ALWAYS use `EntityCard` for entity cards. NEVER use custom cards with divs.**
+
+```typescript
+import { EntityCard, ProviderCard, TemplateCard } from '@/components/ui/EntityCard';
+```
+
+## EntityCard Usage
+```tsx
+<EntityCard
+  avatar={{ letter: 'O', color: '#10a37f' }}
+  title="OpenAI" subtitle="openai"
+  description="OpenAI GPT models"
+  stats="15 model(s)"
+  badge={{ icon: Shield, tooltip: 'Admin API supported' }}
+  links={[{ icon: ExternalLink, label: 'Website', href: 'https://...' }]}
+  actions={[{ label: 'Config', onClick: () => {}, variant: 'primary' }]}
+/>
+```
+
+## ProviderCard Usage (AI Providers)
+```tsx
+<ProviderCard name="OpenAI" code="openai" description="..." modelCount={15} color="#10a37f"
+  websiteUrl="..." docsUrl="..." apiKeyUrl="..." hasAdminKey />
+```
+
+## TemplateCard Usage (Templates)
+```tsx
+<TemplateCard name="Welcome" code="welcome" category="Transactional" isActive isSystem
+  icon={Mail} translationsCount={3} onClick={() => {}} onEdit={() => {}} onDelete={() => {}} />
+```
+
+## EntityCard Props
+| Prop | Type |
+|------|------|
+| `avatar` | `{ letter, color, imageUrl? }` |
+| `title`, `subtitle`, `description` | `string` |
+| `stats` | `string` |
+| `badge` | `{ icon?, tooltip?, color? }` |
+| `links` | `Array<{ icon, label, href?, onClick? }>` |
+| `actions` | `Array<{ label, href?, onClick?, variant, icon?, disabled? }>` |
+
+## Action Variants (EntityCard)
+| Variant | Style |
+|---------|-------|
+| `primary` | `bg-[var(--color-accent-600)] text-white` |
+| `secondary` | `bg-[var(--bg-secondary)] text-[var(--text-secondary)]` |
+| `ghost` | `text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]` (NO border!) |
+
+## Custom Cards (Status, Dashboard)
+
+Button alignment pattern at bottom (mandatory for custom cards):
+
+```tsx
+// WARNING: h-full flex flex-col + flex-1 + mt-auto
+<div className="h-full flex flex-col rounded-[var(--radius-card)] border ...">
+  {/* Header */}
+  <div className="px-4 py-3 bg-gradient-to-r from-[var(--color-accent-500)]/10 ...">
+    {/* ... */}
+  </div>
+  {/* Content with flex-1 */}
+  <div className="flex-1 flex flex-col p-4">
+    {/* Variable content */}
+    {/* WARNING: mt-auto for button at bottom */}
+    <button className="mt-auto w-full ...">Action</button>
+  </div>
+</div>
+```
+
+## When to Use EntityCard vs Custom
+
+| EntityCard for | Custom for |
+|----------------|------------|
+| Homogeneous entity lists | Dashboard stats cards |
+| Catalogs | Cards with complex interactive states |
+| Clickable grids | Cards with integrated forms |

package/templates/skills/ui-components/patterns/grid-layout.md

@@ -0,0 +1,91 @@
+# Grid Layout Patterns
+
+## Responsive Grid
+
+```tsx
+// Standard
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
+  {items.map(item => <EntityCard key={item.id} {...mapToCardProps(item)} />)}
+</div>
+
+// With empty state
+{items.length === 0 ? (
+  <div className="text-center py-12"><p>No items</p></div>
+) : (
+  <div className="grid ...">...</div>
+)}
+```
+
+## Detail Page Template
+
+### Structure
+```tsx
+<div className="container mx-auto px-4 py-6 max-w-7xl space-y-6">
+  {/* Header */}
+  <div className="flex items-center gap-4">
+    <button onClick={() => navigate(-1)} className="p-2 rounded-[var(--radius-button)] hover:bg-[var(--bg-hover)]">
+      <ArrowLeft className="w-5 h-5 text-[var(--text-secondary)]" />
+    </button>
+    <div className="flex-1">
+      <h1 className="text-xl sm:text-2xl font-bold text-[var(--text-primary)]">{title}</h1>
+      <p className="text-sm text-[var(--text-secondary)]">{subtitle}</p>
+    </div>
+    <div className="flex items-center gap-2">
+      {/* Status badges */}
+    </div>
+  </div>
+
+  {/* Pill Tabs */}
+  <div className="flex gap-1 p-1 bg-[var(--bg-secondary)] rounded-[var(--radius-card)] border border-[var(--border-color)]">
+    {tabs.map(tab => (
+      <button
+        key={tab.id}
+        className={`px-4 py-2 rounded-[var(--radius-button)] font-medium ${
+          activeTab === tab.id
+            ? 'bg-[var(--color-accent-600)] text-white'
+            : 'text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]'
+        }`}
+      >
+        {tab.label}
+      </button>
+    ))}
+  </div>
+
+  {/* Tab Content */}
+  <div className="min-h-[400px]">{/* ... */}</div>
+</div>
+```
+
+### Info Card Pattern
+```tsx
+<div className="p-4 rounded-[var(--radius-card)] bg-[var(--bg-primary)] border border-[var(--border-color)]">
+  <div className="flex items-center justify-between mb-4">
+    <h3 className="text-lg font-semibold text-[var(--text-primary)] flex items-center gap-2">
+      <Icon className="w-5 h-5" />
+      {title}
+    </h3>
+    <button className="flex items-center gap-1 px-3 py-1.5 rounded-[var(--radius-button)] bg-[var(--bg-secondary)] text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]">
+      <Edit3 className="w-4 h-4" />
+      {t('common:edit')}
+    </button>
+  </div>
+  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+    <div className="p-3 rounded-lg bg-[var(--bg-secondary)]">
+      <p className="text-xs text-[var(--text-tertiary)] uppercase tracking-wider mb-1">{label}</p>
+      <p className="text-sm text-[var(--text-primary)] font-medium">{value}</p>
+    </div>
+  </div>
+</div>
+```
+
+### Error Display Pattern
+```tsx
+{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>
+)}
+```

package/templates/skills/ui-components/patterns/kanban.md

@@ -0,0 +1,43 @@
+# Kanban Board Pattern
+
+## Structure
+
+```tsx
+<div className="flex gap-4 overflow-x-auto pb-4">
+  {columns.map(column => (
+    <div key={column.id} className="flex-shrink-0 w-72">
+      {/* Column Header */}
+      <div className="flex items-center justify-between mb-3 px-2">
+        <h3 className="font-medium text-[var(--text-primary)]">{column.title}</h3>
+        <span className="text-xs text-[var(--text-tertiary)] bg-[var(--bg-secondary)] px-2 py-0.5 rounded-full">
+          {column.items.length}
+        </span>
+      </div>
+
+      {/* Column Cards */}
+      <div className="space-y-2">
+        {column.items.map(item => (
+          <div
+            key={item.id}
+            className="p-3 rounded-[var(--radius-card)] bg-[var(--bg-primary)] border border-[var(--border-color)] hover:border-[var(--color-accent-500)] cursor-pointer"
+          >
+            <p className="text-sm font-medium text-[var(--text-primary)]">{item.title}</p>
+            <p className="text-xs text-[var(--text-secondary)] mt-1">{item.description}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+## Column Status Mapping
+
+Use CSS variables for column header colors:
+
+| Column Status | Header Accent |
+|--------------|---------------|
+| To Do / Pending | `var(--info-dot)` |
+| In Progress | `var(--color-accent-500)` |
+| Review | `var(--warning-dot)` |
+| Done | `var(--success-dot)` |

package/templates/skills/ui-components/style-guide.md

@@ -0,0 +1,86 @@
+# Style Guide
+
+## CRITICAL: CSS VARIABLES (NEVER HARDCODE COLORS)
+
+**NEVER use hardcoded Tailwind colors.** ALWAYS use CSS variables for theme compliance.
+
+### Status Colors
+| Status | Background | Text | Border | Dot (solid) |
+|--------|------------|------|--------|-------------|
+| **Info** (Pending, Business) | `--info-bg` | `--info-text` | `--info-border` | `--info-dot` |
+| **Success** (Active) | `--success-bg` | `--success-text` | `--success-border` | `--success-dot` |
+| **Warning** (Suspended, Owner) | `--warning-bg` | `--warning-text` | `--warning-border` | `--warning-dot` |
+| **Error** (Danger, Archive) | `--error-bg` | `--error-text` | `--error-border` | `--error-dot` |
+| **Accent** (Personal, Primary) | `--accent-bg` | `--accent-text` | `--accent-border` | `--color-accent-500` |
+
+### Badge Pattern
+```tsx
+// CORRECT - Uses CSS variables
+<span className="px-2 py-0.5 text-xs rounded-[var(--radius-badge)] bg-[var(--info-bg)] text-[var(--info-text)]">
+  Info Badge
+</span>
+
+// WRONG - Hardcoded Tailwind colors
+<span className="bg-blue-500/10 text-blue-500">Info Badge</span>
+```
+
+### Status Config Pattern
+```tsx
+// CORRECT
+const STATUS_CONFIG = {
+  Pending: { bgColor: 'bg-[var(--info-bg)]', color: 'text-[var(--info-text)]', borderColor: 'border-[var(--info-border)]' },
+  Active: { bgColor: 'bg-[var(--success-bg)]', color: 'text-[var(--success-text)]', borderColor: 'border-[var(--success-border)]' },
+  Suspended: { bgColor: 'bg-[var(--warning-bg)]', color: 'text-[var(--warning-text)]', borderColor: 'border-[var(--warning-border)]' },
+  Archived: { bgColor: 'bg-[var(--bg-tertiary)]', color: 'text-[var(--text-tertiary)]', borderColor: 'border-[var(--border-color)]' }
+};
+
+// WRONG - dark: variants are obsolete
+const STATUS_CONFIG = {
+  Active: { bgColor: 'bg-emerald-50 dark:bg-emerald-900/20', ... }
+};
+```
+
+## BUTTON VARIANTS
+
+### Action Buttons (Status changes)
+```tsx
+// Success action (Activate)
+<button className="px-4 py-2 rounded-[var(--radius-button)] bg-[var(--success-dot)] text-white hover:opacity-90">
+  Activate
+</button>
+
+// Warning action (Suspend)
+<button className="px-4 py-2 rounded-[var(--radius-button)] bg-[var(--warning-dot)] text-white hover:opacity-90">
+  Suspend
+</button>
+
+// Danger action (Archive/Delete)
+<button className="px-4 py-2 rounded-[var(--radius-button)] bg-[var(--error-dot)] text-white hover:opacity-90">
+  Archive
+</button>
+
+// Primary action
+<button className="px-4 py-2 rounded-[var(--radius-button)] bg-[var(--color-accent-600)] text-white hover:bg-[var(--color-accent-700)]">
+  Save
+</button>
+
+// Ghost action (NO BORDER!)
+<button className="px-4 py-2 rounded-[var(--radius-button)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:bg-[var(--bg-hover)]">
+  Refresh
+</button>
+
+// Secondary action
+<button className="px-4 py-2 rounded-[var(--radius-button)] bg-[var(--bg-secondary)] text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]">
+  Cancel
+</button>
+```
+
+### Button Rules
+| Variant | Background | Text | Border | Hover |
+|---------|------------|------|--------|-------|
+| **Primary** | `--color-accent-600` | `white` | none | `--color-accent-700` |
+| **Success** | `--success-dot` | `white` | none | `opacity-90` |
+| **Warning** | `--warning-dot` | `white` | none | `opacity-90` |
+| **Danger** | `--error-dot` | `white` | none | `opacity-90` |
+| **Secondary** | `--bg-secondary` | `--text-secondary` | none | `--bg-hover` |
+| **Ghost** | transparent | `--text-secondary` | **NONE** | `--bg-hover` |

package/templates/skills/utils/SKILL.md

@@ -2,6 +2,7 @@
 name: utils
 description: Utility skills for SmartStack CLI development
 argument-hint: "<subcommand> [options]"
+model: haiku
 ---
 
 <objective>

package/templates/skills/validate/SKILL.md

@@ -3,6 +3,7 @@ name: validate
 description: Validate SmartStack conventions using MCP
 argument-hint: "[scope]"
 model: sonnet
+allowed-tools: Read, Grep, Glob, ToolSearch
 ---
 
 <objective>

package/templates/skills/workflow/SKILL.md

@@ -156,6 +156,33 @@ workflowsApi.execute(workflowId, variables)
 □ Tests: trigger, emails, variables
 ```
 
+## RELATION WITH DOMAIN EVENTS
+
+Workflow triggers (`TriggerAsync`) are the **primary mechanism** for cross-process automation (emails, webhooks, multi-step flows).
+
+**Domain Events** (MediatR `INotificationHandler<T>`) are a complementary pattern for **in-process** side effects (audit logging, cache invalidation, read-model updates).
+
+**Recommended pattern:** Domain Event handler bridges to Workflow triggers:
+```csharp
+// OrderCreatedEventHandler calls TriggerAsync for cross-process actions
+public async Task Handle(OrderCreatedEvent notification, CancellationToken ct)
+{
+    await _workflowService.TriggerAsync("order.created",
+        new Dictionary<string, object>{ ["orderId"] = notification.OrderId }, ct: ct);
+}
+```
+
+**When to use which:**
+| Scenario | Mechanism |
+|----------|-----------|
+| Send email after entity creation | Workflow Trigger |
+| Invalidate cache after entity update | Domain Event |
+| Log audit trail | Domain Event |
+| Multi-step business process with delays | Workflow Trigger |
+| Notify multiple services of same change | Domain Event → Workflow Trigger |
+
+See `review-code/references/smartstack-conventions.md` (Domain Events section) for the full implementation pattern.
+
 ## ABSOLUTE RULES
 
 | DO | DON'T |