@archetypeai/ds-cli 0.9.1 → 0.10.0

package/files/rules/state.md

@@ -1,373 +0,0 @@
----
-paths:
-  - '**/*.svelte'
-  - '**/*.svelte.js'
-  - '**/*.svelte.ts'
----
-
-# Svelte 5 State Management
-
-Svelte 5 uses runes - special `$` prefixed primitives that control reactivity.
-
-## $state - Reactive State
-
-Declare reactive state that triggers UI updates when changed:
-
-```svelte
-<script>
-  let count = $state(0);
-  let user = $state({ name: 'Alice', age: 30 });
-</script>
-
-<button onclick={() => count++}>
-  Clicked {count} times
-</button>
-```
-
-### Deep Reactivity
-
-Objects and arrays become deeply reactive proxies:
-
-```svelte
-<script>
-  let todos = $state([{ done: false, text: 'Learn Svelte 5' }]);
-
-  // This triggers updates - the array is a proxy
-  todos.push({ done: false, text: 'Build app' });
-
-  // This also triggers updates
-  todos[0].done = true;
-</script>
-```
-
-### $state.raw - Non-Proxied State
-
-For large objects you don't plan to mutate, use `$state.raw` for better performance:
-
-```svelte
-<script>
-  // Must reassign entirely, can't mutate
-  let data = $state.raw({ items: largeArray });
-
-  // This won't trigger updates
-  data.items.push(newItem);
-
-  // This will - full reassignment
-  data = { items: [...data.items, newItem] };
-</script>
-```
-
-### $state.snapshot - Get Plain Object
-
-Get a non-reactive copy of a state proxy (useful for APIs that don't expect proxies):
-
-```svelte
-<script>
-  let state = $state({ count: 0 });
-
-  function save() {
-    // Pass plain object to external API
-    const snapshot = $state.snapshot(state);
-    localStorage.setItem('state', JSON.stringify(snapshot));
-  }
-</script>
-```
-
-### Class Fields
-
-Use $state in class fields:
-
-```svelte
-<script>
-  class Counter {
-    count = $state(0);
-
-    increment() {
-      this.count++;
-    }
-  }
-
-  let counter = new Counter();
-</script>
-```
-
-## $derived - Computed Values
-
-Declare values that automatically update when dependencies change:
-
-```svelte
-<script>
-  let count = $state(0);
-  let doubled = $derived(count * 2);
-  let quadrupled = $derived(doubled * 2);
-</script>
-
-<p>{count} × 2 = {doubled}</p><p>{count} × 4 = {quadrupled}</p>
-```
-
-### $derived.by - Complex Derivations
-
-For multi-line logic, use `$derived.by`:
-
-```svelte
-<script>
-  let items = $state([1, 2, 3, 4, 5]);
-
-  let stats = $derived.by(() => {
-    const sum = items.reduce((a, b) => a + b, 0);
-    const avg = sum / items.length;
-    const max = Math.max(...items);
-    return { sum, avg, max };
-  });
-</script>
-
-<p>Sum: {stats.sum}, Avg: {stats.avg}, Max: {stats.max}</p>
-```
-
-### Overriding Derived Values (Optimistic UI)
-
-Derived values can be temporarily overridden:
-
-```svelte
-<script>
-  let { post } = $props();
-  let likes = $derived(post.likes);
-
-  async function like() {
-    likes++; // Optimistic update
-    try {
-      await api.likePost(post.id);
-    } catch {
-      likes--; // Rollback on failure
-    }
-  }
-</script>
-```
-
-## $effect - Side Effects
-
-Run code when reactive dependencies change:
-
-```svelte
-<script>
-  let count = $state(0);
-
-  $effect(() => {
-    console.log('Count changed to', count);
-    document.title = `Count: ${count}`;
-  });
-</script>
-```
-
-### Teardown / Cleanup
-
-Return a function to clean up before re-running or on destroy:
-
-```svelte
-<script>
-  let interval = $state(1000);
-
-  $effect(() => {
-    const id = setInterval(() => {
-      console.log('tick');
-    }, interval);
-
-    // Cleanup: runs before re-run and on component destroy
-    return () => clearInterval(id);
-  });
-</script>
-```
-
-### $effect.pre - Run Before DOM Updates
-
-Rarely needed - runs before DOM updates:
-
-```svelte
-<script>
-  let messages = $state([]);
-  let container;
-
-  $effect.pre(() => {
-    // Check scroll position before DOM updates
-    messages.length; // Track this dependency
-
-    if (container && shouldAutoScroll(container)) {
-      // Will scroll after DOM updates
-      tick().then(() => container.scrollTo(0, container.scrollHeight));
-    }
-  });
-</script>
-```
-
-### When NOT to Use $effect
-
-**Don't sync state - use $derived instead:**
-
-```svelte
-<script>
-  let count = $state(0);
-
-  // BAD - don't do this
-  let doubled = $state(0);
-  $effect(() => {
-    doubled = count * 2;
-  });
-
-  // GOOD - use $derived
-  let doubled = $derived(count * 2);
-</script>
-```
-
-**Don't create infinite loops:**
-
-```svelte
-<script>
-  let count = $state(0);
-
-  // BAD - infinite loop! reads and writes count
-  $effect(() => {
-    count = count + 1;
-  });
-</script>
-```
-
-**Use callbacks for linked values instead of effects:**
-
-```svelte
-<script>
-  let spent = $state(0);
-  let left = $derived(100 - spent);
-
-  // Update spent via callback, not effect
-  function updateLeft(newLeft) {
-    spent = 100 - newLeft;
-  }
-</script>
-
-<input type="range" bind:value={spent} max={100} />
-<input type="range" value={left} oninput={(e) => updateLeft(+e.target.value)} max={100} />
-```
-
-## $bindable - Two-Way Binding
-
-Enable parent components to bind to a prop:
-
-```svelte
-<!-- FancyInput.svelte -->
-<script>
-  let { value = $bindable(''), ...props } = $props();
-</script>
-
-<input bind:value {value} {...props} />
-```
-
-```svelte
-<!-- Parent.svelte -->
-<script>
-  import FancyInput from './FancyInput.svelte';
-  let name = $state('');
-</script>
-
-<FancyInput bind:value={name} /><p>Hello, {name}!</p>
-```
-
-See [components.md](./components.md) for more on `$props()` and `$bindable()`.
-
-## $inspect - Debugging (Dev Only)
-
-Log when values change (removed in production builds):
-
-```svelte
-<script>
-  let count = $state(0);
-  let user = $state({ name: 'Alice' });
-
-  // Logs whenever count or user changes
-  $inspect(count, user);
-</script>
-```
-
-### Custom Inspection
-
-```svelte
-<script>
-  let count = $state(0);
-
-  $inspect(count).with((type, value) => {
-    if (type === 'update') {
-      debugger; // Break on changes
-    }
-  });
-</script>
-```
-
-### Trace Effect Dependencies
-
-```svelte
-<script>
-  $effect(() => {
-    $inspect.trace(); // Must be first statement
-    doSomethingComplex();
-  });
-</script>
-```
-
-## Common Gotchas
-
-### Destructuring Breaks Reactivity
-
-```svelte
-<script>
-  let user = $state({ name: 'Alice', age: 30 });
-
-  // BAD - name and age are not reactive
-  let { name, age } = user;
-
-  // GOOD - access via object
-  // In template: {user.name}, {user.age}
-</script>
-```
-
-### Async Code Doesn't Track Dependencies
-
-Only synchronously-read state inside `$effect` is tracked. State read inside `setTimeout`, `await`, or callbacks is not tracked.
-
-### Exporting Reassigned State
-
-Can't directly export state that gets reassigned. Wrap in an object instead:
-
-```javascript
-// state.svelte.js
-export const counter = $state({ count: 0 });
-export function increment() {
-  counter.count++;
-}
-```
-
-### Effects Only Run in Browser
-
-`$effect` doesn't run during SSR:
-
-```svelte
-<script>
-  $effect(() => {
-    // Safe to use browser APIs here
-    window.addEventListener('resize', handleResize);
-    return () => window.removeEventListener('resize', handleResize);
-  });
-</script>
-```
-
-## Quick Reference
-
-| Rune                | Purpose           | Example                                  |
-| ------------------- | ----------------- | ---------------------------------------- |
-| `$state(value)`     | Reactive state    | `let count = $state(0)`                  |
-| `$state.raw(value)` | Non-proxied state | `let data = $state.raw(bigObject)`       |
-| `$derived(expr)`    | Computed value    | `let doubled = $derived(count * 2)`      |
-| `$derived.by(fn)`   | Complex computed  | `$derived.by(() => { ... })`             |
-| `$effect(fn)`       | Side effect       | `$effect(() => { ... })`                 |
-| `$effect.pre(fn)`   | Pre-DOM effect    | `$effect.pre(() => { ... })`             |
-| `$props()`          | Component props   | `let { foo } = $props()`                 |
-| `$bindable()`       | Two-way prop      | `let { value = $bindable() } = $props()` |
-| `$inspect(...)`     | Debug logging     | `$inspect(count)`                        |

package/files/rules/styling.md

@@ -1,142 +0,0 @@
----
-paths:
-  - '**/*.css'
-  - '**/*.svelte'
----
-
-# Styling Rules
-
-## Semantic Tokens
-
-For the complete token reference including dark mode overrides, type scale (h1–h6, p, small), and spacing definitions, read `node_modules/@archetypeai/ds-lib-tokens/theme.css`.
-
-Token naming pattern: `bg-{token}`, `text-{token}-foreground`, `border-{token}`.
-
-Core tokens: `background`, `foreground`, `primary`, `secondary`, `muted`, `card`, `accent`, `destructive`, `border`, `input`, `ring`.
-
-ATAI brand tokens: `atai-neutral`, `atai-good`, `atai-warning`, `atai-critical`.
-
-Chart series: `--chart-1` through `--chart-5` (see `@rules/charts`).
-
-## When to Use Semantic vs Standard Tailwind
-
-### Use Semantic Tokens For:
-
-```svelte
-<!-- Themed colors that should change with light/dark mode -->
-<div class="bg-background text-foreground">
-<div class="bg-card border-border">
-<button class="bg-primary text-primary-foreground">
-<span class="text-muted-foreground">
-```
-
-### Use Standard Tailwind For:
-
-```svelte
-<!-- Spacing and sizing -->
-<div class="p-4 gap-2 w-full h-screen">
-
-<!-- Layout utilities -->
-<div class="flex items-center justify-between">
-<div class="grid grid-cols-2 gap-4">
-<div class="absolute top-0 left-0">
-
-<!-- One-off custom colors -->
-<div class="bg-linear-to-r from-purple-500 to-pink-500">
-<div class="text-amber-500">  <!-- specific non-themed color -->
-
-<!-- Responsive breakpoints -->
-<div class="sm:flex md:grid lg:hidden">
-
-<!-- Animations and transitions -->
-<div class="transition-all duration-200 ease-in-out">
-```
-
-## Dark Mode
-
-Dark mode activates via `.dark` class on the root element:
-
-```html
-<html class="dark">
-  ...
-</html>
-```
-
-Semantic tokens automatically switch values in dark mode. No manual dark: prefixes needed for themed colors:
-
-```svelte
-<!-- This works in both light and dark mode automatically -->
-<div class="bg-background text-foreground border-border">
-```
-
-For custom dark mode overrides, use the `dark:` prefix:
-
-```svelte
-<div class="bg-white dark:bg-slate-900">  <!-- custom dark override -->
-```
-
-For class merging with `cn()`, see `@rules/components`.
-
-## CSS Import Order
-
-In your global CSS file:
-
-```css
-@import 'tailwindcss';
-@import 'tw-animate-css';
-@import '@archetypeai/ds-lib-tokens/fonts.css';
-@import '@archetypeai/ds-lib-tokens/theme.css';
-@source '../../node_modules/@archetypeai/ds-ui-svelte-console/dist';
-@source '../../node_modules/@archetypeai/ds-ui-svelte-labs/dist';
-```
-
-Order matters — `tailwindcss` first, then the tokens theme, then the package `@source` directives (they make Tailwind emit classes used inside the package dists).
-
-## Tailwind v4 Specifics
-
-### @theme Directive
-
-Custom theme values are defined with `@theme`:
-
-```css
-@theme {
-  --font-sans: 'PP Neue Montreal', system-ui, sans-serif;
-  --radius-md: var(--radius);
-  --spacing-md: 0.75rem;
-  --color-primary: var(--primary);
-}
-```
-
-### CSS Variables in Classes
-
-You can use CSS variables directly:
-
-```svelte
-<div style:--legend-color={seriesColor}>
-  <span class="bg-(--legend-color)"> </span>
-</div>
-```
-
-### No @apply in Components
-
-Prefer Tailwind classes directly in markup. Use @apply only in base layer CSS:
-
-```css
-/* In theme.css - OK */
-@layer base {
-  body {
-    @apply bg-background text-foreground;
-  }
-}
-```
-
-```svelte
-<!-- In components - use classes directly -->
-<div class="bg-background text-foreground">
-```
-
-## Common Patterns
-
-For focus ring, disabled state, and data-state animation CSS patterns, see `@rules/accessibility`.
-
-For icon sizing conventions, see `@rules/components`.

package/files/skills/apply-ds/SKILL.md

@@ -1,121 +0,0 @@
----
-name: apply-ds
-description: Apply DS tokens and components to an existing demo initialized with ds-cli init.
-allowed-tools: Read, Edit, Grep, Bash
----
-
-# Applying the Design System to a Demo
-
-This skill assumes `npx @archetypeai/ds-cli init` has already been run. The project has tokens, Tailwind v4, and both design system packages (`@archetypeai/ds-ui-svelte-console`, `@archetypeai/ds-ui-svelte-labs`) installed. The goal is to migrate the demo's existing UI to use DS components and semantic tokens. Read `ds-manifest.json` at the project root for the full component catalog.
-
-## Steps
-
-1. Audit for non-DS patterns
-2. Replace raw colors with semantic tokens
-3. Replace native elements with DS components
-4. Apply layout patterns
-5. Set up linting and formatting
-6. Verify
-
-## Step 1: Audit for Non-DS Patterns
-
-Run the `scripts/audit.sh` script located in this skill's directory from the project root. The script scans all `.svelte` files and reports:
-
-- **Raw Tailwind colors** — utilities like `bg-gray-100`, `text-blue-500`, `border-red-300` that should be semantic tokens
-- **Native HTML elements** — `<button>`, `<input>`, `<table>`, `<select>`, `<textarea>`, `<dialog>`, `<hr>` that have DS component equivalents
-- **Hardcoded colors** — inline `color:`, `background:`, `background-color:`, `border-color:` style values
-- **Class concatenation** — string templates or `+` concatenation on class attributes instead of `cn()`
-
-Review the output to prioritize what to migrate.
-
-## Step 2: Replace Raw Colors with Semantic Tokens
-
-Replace raw Tailwind color utilities with semantic equivalents throughout `.svelte` files:
-
-| Raw Tailwind | Semantic Token |
-| --- | --- |
-| `bg-white` | `bg-background` |
-| `bg-black` | `bg-foreground` |
-| `text-black` | `text-foreground` |
-| `text-white` | `text-background` |
-| `bg-gray-50`, `bg-gray-100` | `bg-muted` |
-| `text-gray-500`, `text-gray-600` | `text-muted-foreground` |
-| `bg-gray-200`, `bg-gray-300` | `bg-accent` |
-| `border-gray-200`, `border-gray-300` | `border-border` |
-| `bg-slate-900`, `bg-gray-900` | `bg-primary` |
-| `text-slate-900`, `text-gray-900` | `text-primary` |
-| `bg-red-*` | `bg-destructive` |
-| `text-red-*` | `text-destructive` |
-| `bg-green-*` | `bg-atai-good` |
-| `text-green-*` | `text-atai-good` |
-| `bg-yellow-*` | `bg-atai-warning` |
-| `text-yellow-*` | `text-atai-warning` |
-| `bg-blue-*` | `bg-atai-neutral` |
-| `text-blue-*` | `text-atai-neutral` |
-
-Use judgement — not every raw color maps 1:1. Context matters:
-
-- A `bg-gray-100` card background → `bg-card` or `bg-muted`
-- A `bg-gray-100` hover state → `bg-accent`
-- A `text-gray-400` placeholder → `text-muted-foreground`
-- A `border-gray-200` divider → `border-border`
-
-Leave non-color utilities (`p-4`, `flex`, `rounded-lg`, etc.) unchanged.
-
-## Step 3: Replace Native Elements with DS Components
-
-Swap native HTML elements for their DS component equivalents. Add imports as needed.
-
-| Native Element | DS Component | Import From |
-| --- | --- | --- |
-| `<button>` | `<Button>` | `@archetypeai/ds-ui-svelte-console/primitives/button` |
-| `<input>` | `<Input>` | `@archetypeai/ds-ui-svelte-console/primitives/input` |
-| `<textarea>` | `<Textarea>` | `@archetypeai/ds-ui-svelte-console/primitives/textarea` |
-| `<select>` | `<Select.Root>` + `<Select.Trigger>` + `<Select.Content>` + `<Select.Item>` | `@archetypeai/ds-ui-svelte-console/primitives/select` |
-| `<table>` | `<Table.Root>` + `<Table.Header>` + `<Table.Row>` + `<Table.Head>` + `<Table.Body>` + `<Table.Cell>` | `@archetypeai/ds-ui-svelte-console/primitives/table` |
-| `<dialog>` | `<Dialog.Root>` + `<Dialog.Content>` + `<Dialog.Header>` + `<Dialog.Title>` | `@archetypeai/ds-ui-svelte-console/primitives/dialog` |
-| `<hr>` | `<Separator>` | `@archetypeai/ds-ui-svelte-console/primitives/separator` |
-| `<label>` | `<Label>` | `@archetypeai/ds-ui-svelte-console/primitives/label` |
-| `<a>` (styled as button) | `<Button variant="link">` or `<Button>` with `href` | `@archetypeai/ds-ui-svelte-console/primitives/button` |
-
-For each replacement:
-
-1. Add the import to the `<script>` block
-2. Replace the element and map attributes (`class` → `class`, `onclick` → `onclick`, etc.)
-3. Use `cn()` from `$lib/utils.js` for merging classes — never raw concatenation
-4. Map native variants: e.g. a small styled button → `<Button size="sm">`, a ghost-styled button → `<Button variant="ghost">`
-
-## Step 4: Apply Layout Patterns
-
-Identify structural opportunities to use DS composition patterns:
-
-- **Cards** — wrap content sections in `<Card.Root>` / `<Card.Header>` / `<Card.Content>` instead of raw `<div>` with border/shadow classes
-- **Separators** — replace `<hr>` or border-bottom hacks with `<Separator>`
-- **Badges** — replace styled `<span>` status indicators with `<Badge>`
-- **Spinners** — replace loading placeholders with `<Spinner>`
-- **Empty states** — replace ad-hoc "no data" markup with `<EmptyState>`
-- **Tooltips** — replace `title` attributes with `<Tooltip.Root>` / `<Tooltip.Trigger>` / `<Tooltip.Content>`
-
-Import console components from `@archetypeai/ds-ui-svelte-console/primitives/<name>` and labs components (menubar, charts, slider, switch, ...) from `@archetypeai/ds-ui-svelte-labs/primitives/<name>` — see `ds-manifest.json` for the catalog.
-
-## Step 5: Lint and Format
-
-Run linting and formatting to clean up the migrated code:
-
-```bash
-npm run lint:fix && npm run format
-```
-
-See `@rules/linting.md` for details.
-
-## Step 6: Verify
-
-Confirm the design system is properly applied:
-
-- [ ] No raw Tailwind color utilities in `.svelte` files (re-run the audit script)
-- [ ] Native elements replaced with DS components where appropriate
-- [ ] Component imports resolve to the design system packages (`@archetypeai/ds-ui-svelte-console`, `@archetypeai/ds-ui-svelte-labs`) — or `$lib/components/ui/` only for deliberately modified registry source
-- [ ] `cn()` used for class merging — no string concatenation
-- [ ] Linting passes: `npm run lint && npm run format:check`
-- [ ] App builds without errors: `npm run build`
-- [ ] App runs correctly: `npm run dev`