start-vibing-stacks 2.0.3 → 2.1.0

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '2.0.3';
+const VERSION = '2.1.0';
 const gradient = (text) => {
     const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
     return text.split('').map((c, i) => colors[i % colors.length](c)).join('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/frontend/react/skills/react-standards/SKILL.md

@@ -49,27 +49,139 @@ export default function Dashboard() {
 
 **Rule:** Never leave raw `console.log`. Always use controlled debug pattern.
 
-## TailwindCSS Class Organization
+## TailwindCSS Class Organization (CONST Pattern)
+
+**MANDATORY:** Define all CSS classes as constants at the TOP of the file, before the component.
+
+### Why
+
+1. **No re-renders** — string constants have stable references (no new object per render)
+2. **Single source of truth** — change style once, updates everywhere
+3. **Clean JSX** — readable templates, no class soup
+4. **Prevents React state warnings** — no inline objects/strings changing reference
+5. **Easy theming** — swap tokens in one place
+
+### Pattern
 
 ```tsx
-// ✅ Classes as CONST — clean JSX
-const STYLES = {
-    container: 'flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm',
-    title: 'text-2xl font-bold text-gray-900',
-    button: 'px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition',
-    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6',
-};
+// ═══════════════════════════════════════════
+// 1. TRANSLATIONS (before hooks)
+// ═══════════════════════════════════════════
+const LABELS = {
+    title: __('dashboard.title'),
+    save: __('common.save'),
+} as const;
 
+// ═══════════════════════════════════════════
+// 2. STYLES (semantic tokens, not raw colors)
+// ═══════════════════════════════════════════
+const STYLES = {
+    // Layout
+    page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
+    section: 'space-y-6',
+    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4',
+
+    // Cards
+    card: 'bg-card border border-card-line rounded-xl p-6 hover:shadow-md transition-shadow',
+    cardHeader: 'flex items-center justify-between border-b border-card-divider pb-4 mb-4',
+    cardTitle: 'text-lg font-semibold text-foreground',
+    cardDescription: 'text-sm text-muted-foreground mt-1',
+
+    // Table
+    table: 'w-full text-sm',
+    tableHeader: 'text-left text-muted-foreground font-medium border-b border-border',
+    tableRow: 'border-b border-border hover:bg-muted/50 transition-colors',
+    tableCell: 'px-4 py-3 text-foreground',
+
+    // Buttons
+    btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover font-medium disabled:opacity-50 disabled:cursor-not-allowed transition-colors',
+    btnSecondary: 'px-4 py-2 bg-layer border border-layer-line text-layer-foreground rounded-lg hover:bg-layer-hover font-medium transition-colors',
+    btnDestructive: 'px-4 py-2 bg-destructive text-destructive-foreground rounded-lg hover:bg-destructive-hover font-medium transition-colors',
+    btnGhost: 'px-4 py-2 text-muted-foreground hover:bg-muted rounded-lg transition-colors',
+
+    // Forms
+    input: 'w-full h-10 px-3 rounded-md border border-border bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent transition-colors',
+    label: 'block text-sm font-medium text-foreground mb-1',
+    fieldError: 'mt-1 text-sm text-destructive',
+
+    // Status badges
+    badgeSuccess: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400',
+    badgeWarning: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400',
+    badgeDanger: 'inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400',
+
+    // Typography
+    heading: 'text-2xl font-bold text-foreground',
+    subheading: 'text-lg font-semibold text-foreground',
+    body: 'text-sm text-foreground',
+    muted: 'text-sm text-muted-foreground',
+} as const;
+
+// ═══════════════════════════════════════════
+// 3. COMPONENT
+// ═══════════════════════════════════════════
 export default function Dashboard() {
+    const [data, setData] = useState(null);
+
     return (
-        <div className={STYLES.container}>
-            <h1 className={STYLES.title}>{LABELS.title}</h1>
+        <div className={STYLES.page}>
+            <h1 className={STYLES.heading}>{LABELS.title}</h1>
+            <div className={STYLES.grid}>
+                <div className={STYLES.card}>
+                    <h2 className={STYLES.cardTitle}>Stats</h2>
+                    <p className={STYLES.cardDescription}>Overview</p>
+                </div>
+            </div>
         </div>
     );
 }
+```
+
+### Composing Styles
 
-// ❌ Inline class soup
-<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm"> // ❌
+```tsx
+// ✅ Combine with template literal when conditional
+<tr className={`${STYLES.tableRow} ${isSelected ? 'bg-primary/5' : ''}`}>
+
+// ✅ clsx/cn for complex conditions
+import { cn } from '@/lib/utils';
+<button className={cn(STYLES.btnPrimary, isFullWidth && 'w-full', className)}>
+```
+
+### Rules
+
+1. **CONST at top** — before hooks, before component
+2. **`as const`** — TypeScript ensures immutability
+3. **Semantic tokens** — `bg-card` not `bg-white`, `text-foreground` not `text-gray-900`
+4. **No inline class strings > 3 utilities** — extract to STYLES
+5. **Shared styles** — create a `styles.ts` file for cross-component constants
+
+```tsx
+// resources/js/styles.ts — shared across components
+export const SHARED_STYLES = {
+    page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
+    btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover ...',
+    input: 'w-full h-10 px-3 rounded-md border border-border bg-background ...',
+} as const;
+```
+
+### ❌ FORBIDDEN
+
+```tsx
+// ❌ Inline class soup — unreadable, unstable reference
+<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm">
+
+// ❌ Raw colors instead of tokens
+const STYLES = { card: 'bg-white text-gray-900' };  // ❌ Breaks dark mode
+
+// ❌ Dynamic class construction (breaks Tailwind purge)
+const color = 'blue';
+<div className={`bg-${color}-500`}>  // ❌ Purged!
+
+// ❌ Styles inside component (new object every render)
+export default function Bad() {
+    const styles = { card: 'bg-card p-4' };  // ❌ Inside = new ref every render
+    return <div className={styles.card} />;
+}
 ```
 
 ## SVG Icons

package/stacks/php/skills/laravel-inertia-i18n/SKILL.md

@@ -0,0 +1,294 @@
+# Laravel + Inertia i18n — Centralized Translations
+
+**ALWAYS invoke when adding translations, creating new pages, or working with multilingual content.**
+
+## Architecture
+
+```
+Laravel Backend                    Inertia Share              React Frontend
+┌─────────────────┐               ┌──────────────┐           ┌──────────────────┐
+│ lang/en/*.php    │──→ config ──→│ InertiaShare  │──→ props →│ __('key')        │
+│ lang/pt/*.php    │   mapping    │ translations  │           │ via usePage()    │
+│ lang/en.json     │              │ + cache       │           │                  │
+└─────────────────┘               └──────────────┘           └──────────────────┘
+
+Key decisions:
+- Translations live in Laravel (single source of truth)
+- Only NEEDED translations sent per page (not all)
+- Cached forever (invalidate on deploy)
+- Frontend reads via usePage().props.translations
+```
+
+## Backend: Translation Files
+
+### File Structure
+
+```
+lang/
+├── en/
+│   ├── messages.php        # Global (loaded on all pages)
+│   ├── validation.php      # Laravel validation messages
+│   ├── auth.php            # Auth pages
+│   └── admin/
+│       ├── dashboard.php   # Admin dashboard specific
+│       └── ai-models.php   # AI models page specific
+├── pt/
+│   ├── messages.php
+│   ├── validation.php
+│   └── admin/
+│       ├── dashboard.php
+│       └── ai-models.php
+├── en.json                 # JSON format (optional, merged)
+└── pt.json
+```
+
+### Translation File Example
+
+```php
+// lang/en/messages.php
+return [
+    'common' => [
+        'buttons' => [
+            'save' => 'Save',
+            'cancel' => 'Cancel',
+            'close' => 'Close',
+            'saving' => 'Saving...',
+            'add_ai_model' => 'Add AI Model',
+        ],
+    ],
+    'errors' => [
+        'error' => 'Error',
+        'api_save_failed_generic' => 'Failed to save. Please try again.',
+        'validation_failed_check_fields' => 'Validation failed. Please check the fields.',
+        'invalid_json' => 'Invalid JSON format.',
+    ],
+    'admin' => [
+        'ai' => [
+            'ai-models' => [
+                'new_model_button' => 'New AI Model',
+                'add_modal_description' => 'Fill in the details to add a new AI model.',
+                'fields' => [
+                    'name' => 'Name',
+                    'slug' => 'Slug',
+                    'system_prompt' => 'System Prompt',
+                    'temperature' => 'Temperature',
+                    // ...
+                ],
+            ],
+        ],
+    ],
+];
+```
+
+## Backend: Page-to-Translation Mapping
+
+### Config File
+
+```php
+// config/translations_inertia.php
+return [
+    // Global: loaded on EVERY page
+    'global' => [
+        'messages',      // lang/{locale}/messages.php
+    ],
+
+    // Per-page: loaded only when visiting that route
+    'pages' => [
+        'admin/dashboard' => ['admin/dashboard'],
+        'admin/ai-models' => ['admin/ai-models'],
+        'auth/login' => ['auth'],
+        'auth/register' => ['auth'],
+    ],
+];
+```
+
+**Rule:** Only send translations the page actually needs — not the entire `lang/` folder.
+
+## Backend: InertiaShare Middleware
+
+```php
+// app/Support/InertiaShare.php
+class InertiaShare
+{
+    public static function getProps(Request $request): array
+    {
+        $locale = App::getLocale();
+
+        return [
+            'auth' => [
+                'user' => $request->user()?->only('id', 'name', 'email', 'role', 'timezone', 'avatar_url'),
+            ],
+            'locale' => $locale,
+            'translations' => static::getTranslations($locale, $request->route()->uri),
+            'flash' => [
+                'success' => session('success'),
+                'error' => session('error'),
+            ],
+        ];
+    }
+
+    protected static function getTranslations(string $locale, string $pageUri): array
+    {
+        $cacheKey = "translations_{$locale}_{$pageUri}";
+
+        return Cache::rememberForever($cacheKey, function () use ($locale, $pageUri) {
+            $globalFiles = config('translations_inertia.global', []);
+            $pageFiles = config("translations_inertia.pages.{$pageUri}", []);
+            $files = array_unique(array_merge($globalFiles, $pageFiles));
+
+            $translations = [];
+            $langPath = lang_path($locale);
+
+            foreach ($files as $file) {
+                $filePath = "{$langPath}/{$file}.php";
+                if (File::exists($filePath)) {
+                    $translations[$file] = require $filePath;
+                }
+            }
+
+            // Merge JSON translations (lang/{locale}.json)
+            $jsonPath = lang_path("{$locale}.json");
+            if (File::exists($jsonPath)) {
+                $json = json_decode(File::get($jsonPath), true);
+                if (is_array($json)) {
+                    $translations = array_merge($translations, $json);
+                }
+            }
+
+            return $translations;
+        });
+    }
+}
+```
+
+### Register in Middleware
+
+```php
+// app/Http/Middleware/HandleInertiaRequests.php
+use App\Support\InertiaShare;
+
+public function share(Request $request): array
+{
+    return array_merge(parent::share($request), InertiaShare::getProps($request));
+}
+```
+
+## Frontend: translate.js Utility
+
+```js
+// resources/js/Utils/translate.js
+import { usePage } from '@inertiajs/react';
+
+/**
+ * Get translated string by dot-notation key.
+ * @param {string} key - e.g. 'messages.common.buttons.save'
+ * @param {object} replacements - e.g. { name: 'John' } for ':name'
+ * @returns {string} Translated string or key as fallback
+ */
+export default function __(key, replacements = {}) {
+    const { translations } = usePage().props;
+
+    let translation = key.split('.').reduce(
+        (obj, part) => (obj && obj[part] !== undefined ? obj[part] : null),
+        translations
+    );
+
+    // Fallback: return key if not found
+    if (translation === null || translation === undefined) {
+        return key;
+    }
+
+    // Replace :placeholders
+    if (typeof translation === 'string' && Object.keys(replacements).length > 0) {
+        Object.keys(replacements).forEach((placeholder) => {
+            translation = translation.replace(
+                new RegExp(`:${placeholder}`, 'g'),
+                replacements[placeholder]
+            );
+        });
+    }
+
+    return translation;
+}
+```
+
+## Frontend: Component Pattern (CONST)
+
+```tsx
+import __ from '@/Utils/translate';
+
+// ═══════════════════════════════════════════
+// 1. TRANSLATIONS — before hooks, outside component
+// ═══════════════════════════════════════════
+const LABELS = {
+    title: __('messages.admin.ai.ai-models.new_model_button'),
+    description: __('messages.admin.ai.ai-models.add_modal_description'),
+    nameField: __('messages.admin.ai.ai-models.fields.name'),
+    slugField: __('messages.admin.ai.ai-models.fields.slug'),
+    save: __('messages.common.buttons.save'),
+    saving: __('messages.common.buttons.saving'),
+    cancel: __('messages.common.buttons.cancel'),
+    errorTitle: __('messages.errors.error'),
+    validationFailed: __('messages.errors.validation_failed_check_fields'),
+} as const;
+
+// ═══════════════════════════════════════════
+// 2. CSS STYLES — semantic tokens
+// ═══════════════════════════════════════════
+const STYLES = {
+    modal: 'relative w-full max-w-[558px] rounded-3xl bg-card p-6 lg:p-10',
+    title: 'mb-6 text-xl font-semibold text-foreground',
+    description: 'mb-7 text-sm leading-6 text-muted-foreground',
+    form: 'space-y-4',
+    gridTwo: 'grid grid-cols-2 gap-4',
+    actions: 'mt-8 flex w-full flex-col sm:flex-row items-center justify-between gap-3',
+    fieldError: 'text-sm text-destructive mt-1',
+    btnFull: 'w-full',
+} as const;
+
+// ═══════════════════════════════════════════
+// 3. COMPONENT
+// ═══════════════════════════════════════════
+export default function AiModelsAddModal({ isOpen, onClose, onAdded }) {
+    // hooks, state, handlers...
+
+    return (
+        <Modal isOpen={isOpen} onClose={onClose} className={STYLES.modal}>
+            <h4 className={STYLES.title}>{LABELS.title}</h4>
+            <p className={STYLES.description}>{LABELS.description}</p>
+            {/* form fields using LABELS and STYLES */}
+        </Modal>
+    );
+}
+```
+
+## Adding New Translations
+
+### Checklist
+
+1. Add string to `lang/en/{file}.php` **and** `lang/pt/{file}.php`
+2. If new file: add to `config/translations_inertia.php` (global or page-specific)
+3. Clear cache: `php artisan cache:clear`
+4. In React component: add to `LABELS` const using `__('key')`
+5. **NEVER** call `__()` inside JSX directly — always via LABELS const
+
+### Cache Invalidation
+
+```bash
+# After adding/changing translations:
+php artisan cache:clear
+
+# For Octane (in-memory):
+php artisan octane:reload
+```
+
+## FORBIDDEN
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| `__()` inside JSX return | `LABELS.title` via const |
+| Send ALL translations to every page | Map per-page in config |
+| Hardcode strings in components | Use translation keys |
+| Skip Portuguese translation | Always add both `en` + `pt` |
+| `Cache::forget()` for translations | `cache:clear` on deploy |
+| Translation keys in camelCase | Use dot.notation `messages.admin.title` |