@decantr/cli 1.0.0-beta.8 → 1.0.0

package/dist/upgrade-FWICWIQW.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import {
+  RegistryClient
+} from "./chunk-PWTUBGGJ.js";
+import "./chunk-PDX44BCA.js";
+
+// src/commands/upgrade.ts
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+var GREEN = "\x1B[32m";
+var YELLOW = "\x1B[33m";
+var RESET = "\x1B[0m";
+var DIM = "\x1B[2m";
+async function cmdUpgrade(projectRoot = process.cwd()) {
+  const essencePath = join(projectRoot, "decantr.essence.json");
+  if (!existsSync(essencePath)) {
+    console.error("No decantr.essence.json found. Run `decantr init` first.");
+    process.exitCode = 1;
+    return;
+  }
+  const essence = JSON.parse(readFileSync(essencePath, "utf-8"));
+  const client = new RegistryClient({
+    cacheDir: join(projectRoot, ".decantr", "cache")
+  });
+  console.log("Checking for updates...\n");
+  const upgrades = [];
+  if (essence.theme?.style) {
+    const theme = await client.fetchTheme(essence.theme.style);
+    if (theme && theme.data.version) {
+      const current = essence.theme.version || "0.0.0";
+      if (theme.data.version !== current) {
+        upgrades.push({
+          type: "theme",
+          id: essence.theme.style,
+          currentVersion: current,
+          latestVersion: theme.data.version
+        });
+      }
+    }
+  }
+  if (essence.blueprint) {
+    const blueprint = await client.fetchBlueprint(essence.blueprint);
+    if (blueprint && blueprint.data.version) {
+      const current = essence.blueprintVersion || "0.0.0";
+      if (blueprint.data.version !== current) {
+        upgrades.push({
+          type: "blueprint",
+          id: essence.blueprint,
+          currentVersion: current,
+          latestVersion: blueprint.data.version
+        });
+      }
+    }
+  }
+  if (upgrades.length === 0) {
+    console.log(`${GREEN}Everything is up to date.${RESET}`);
+    return;
+  }
+  console.log("Available upgrades:\n");
+  for (const u of upgrades) {
+    console.log(`  ${u.type}/${u.id}: ${DIM}${u.currentVersion}${RESET} -> ${GREEN}${u.latestVersion}${RESET}`);
+  }
+  console.log(`
+${YELLOW}Run with --apply to apply upgrades.${RESET}`);
+}
+export {
+  cmdUpgrade
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Decantr CLI — search the registry, validate essence files, and access design intelligence from the terminal",
   "license": "MIT",
   "repository": {
@@ -16,7 +16,8 @@
   "main": "dist/index.js",
   "files": [
     "dist",
-    "src/templates"
+    "src/templates",
+    "src/bundled"
   ],
   "publishConfig": {
     "access": "public"

package/src/bundled/blueprints/default.json

@@ -0,0 +1,24 @@
+{
+  "id": "default",
+  "$schema": "https://decantr.ai/schemas/blueprint.v1.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Decantr Default",
+  "description": "Minimal starter blueprint for offline scaffolding. Visit decantr.ai/registry for more options.",
+  "tags": ["starter", "minimal", "offline"],
+  "compose": ["starter"],
+  "theme": {
+    "style": "default",
+    "mode": "system",
+    "recipe": null,
+    "shape": "rounded"
+  },
+  "personality": ["clean", "minimal"],
+  "features": [],
+  "routes": {
+    "/": {
+      "shell": "default",
+      "page": "home"
+    }
+  }
+}

package/src/bundled/patterns/content-section.json

@@ -0,0 +1,27 @@
+{
+  "id": "content-section",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Content Section",
+  "description": "Generic content section with heading and body.",
+  "components": [],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Centered content with max-width",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap4 _py8 _px6 _mxauto _maxw[800px]"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap4 _py8 _px6 _mxauto _maxw[800px]",
+    "slots": {
+      "heading": "Section heading",
+      "body": "Section content"
+    }
+  }
+}

package/src/bundled/patterns/footer.json

@@ -0,0 +1,27 @@
+{
+  "id": "footer",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Footer",
+  "description": "Page footer with links and copyright.",
+  "components": ["Link"],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Simple footer with links and copyright",
+      "layout": {
+        "layout": "row",
+        "atoms": "_flex _aic _jcsb _px6 _py4 _borderT _fgmuted"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "row",
+    "atoms": "_flex _aic _jcsb _px6 _py4 _borderT _fgmuted",
+    "slots": {
+      "links": "Footer links",
+      "copyright": "Copyright notice"
+    }
+  }
+}

package/src/bundled/patterns/form-basic.json

@@ -0,0 +1,27 @@
+{
+  "id": "form-basic",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Basic Form",
+  "description": "Simple form with inputs and submit button.",
+  "components": ["Input", "Button", "Label"],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Vertical form with stacked fields",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _gap4"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _gap4",
+    "slots": {
+      "fields": "Form input fields",
+      "actions": "Submit/cancel buttons"
+    }
+  }
+}

package/src/bundled/patterns/hero.json

@@ -0,0 +1,28 @@
+{
+  "id": "hero",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Hero",
+  "description": "Landing page hero section with headline, subheadline, and CTA.",
+  "components": ["Button"],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Centered hero with headline and CTA",
+      "layout": {
+        "layout": "stack",
+        "atoms": "_flex _col _aic _tc _py12 _gap6"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "stack",
+    "atoms": "_flex _col _aic _tc _py12 _gap6",
+    "slots": {
+      "headline": "Main headline text",
+      "subheadline": "Supporting description",
+      "cta": "Call-to-action button(s)"
+    }
+  }
+}

package/src/bundled/patterns/nav-header.json

@@ -0,0 +1,28 @@
+{
+  "id": "nav-header",
+  "$schema": "https://decantr.ai/schemas/pattern.v2.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Navigation Header",
+  "description": "Top navigation bar with logo, links, and actions.",
+  "components": ["Button", "Link"],
+  "default_preset": "standard",
+  "presets": {
+    "standard": {
+      "description": "Horizontal nav with logo left, links center, actions right",
+      "layout": {
+        "layout": "row",
+        "atoms": "_flex _aic _jcsb _px6 _py3 _borderB"
+      }
+    }
+  },
+  "default_layout": {
+    "layout": "row",
+    "atoms": "_flex _aic _jcsb _px6 _py3 _borderB",
+    "slots": {
+      "logo": "Brand logo or name",
+      "links": "Navigation links",
+      "actions": "Action buttons (login, signup)"
+    }
+  }
+}

package/src/bundled/shells/default.json

@@ -0,0 +1,20 @@
+{
+  "id": "default",
+  "$schema": "https://decantr.ai/schemas/shell.v1.json",
+  "version": "1.0.0",
+  "name": "Default Shell",
+  "description": "Simple top-nav + main content layout.",
+  "layout": "stack",
+  "atoms": "_flex _col _minh[100vh]",
+  "config": {
+    "regions": ["header", "body"],
+    "header": {
+      "height": "auto",
+      "sticky": true
+    },
+    "body": {
+      "scroll": true,
+      "flex": 1
+    }
+  }
+}

package/src/bundled/themes/default.json

@@ -0,0 +1,48 @@
+{
+  "id": "default",
+  "$schema": "https://decantr.ai/schemas/theme.v1.json",
+  "version": "1.0.0",
+  "decantr_compat": ">=1.0.0",
+  "name": "Decantr Default",
+  "description": "Neutral theme that works in light and dark modes. Clean and professional.",
+  "tags": ["neutral", "light", "dark", "minimal"],
+  "personality": "clean + minimal + professional",
+  "seed": {
+    "primary": "#3B82F6",
+    "secondary": "#6B7280",
+    "accent": "#8B5CF6",
+    "background": "#FFFFFF"
+  },
+  "palette": {
+    "background": {
+      "light": "#FFFFFF",
+      "dark": "#18181B"
+    },
+    "surface": {
+      "light": "#F9FAFB",
+      "dark": "#27272A"
+    },
+    "surface-raised": {
+      "light": "#F3F4F6",
+      "dark": "#3F3F46"
+    },
+    "border": {
+      "light": "#E5E7EB",
+      "dark": "#52525B"
+    },
+    "text": {
+      "light": "#111827",
+      "dark": "#FAFAFA"
+    },
+    "text-muted": {
+      "light": "#6B7280",
+      "dark": "#A1A1AA"
+    },
+    "primary": {
+      "light": "#3B82F6",
+      "dark": "#60A5FA"
+    }
+  },
+  "modes": ["light", "dark", "system"],
+  "shapes": ["rounded", "sharp", "pill"]
+}

package/src/templates/DECANTR.md.template

@@ -98,6 +98,20 @@ When a user request would violate guard rules:
 }
 ```
 
+### Theme Quick Reference
+
+{{THEME_QUICK_REFERENCE}}
+
+**To fetch complete theme and recipe specs:**
+```bash
+npx @decantr/cli get theme {{THEME_STYLE}}
+npx @decantr/cli get recipe {{THEME_RECIPE}}
+```
+
+{{ACCESSIBILITY_SECTION}}
+
+{{SEO_SECTION}}
+
 ### Pages
 
 {{PAGES_TABLE}}
@@ -112,16 +126,32 @@ When a user request would violate guard rules:
 
 **Always check these before generating UI code:**
 
-### With MCP Tools (Recommended)
+### Quick Commands
+
+```bash
+# Get full theme spec (colors, palette, modes)
+npx @decantr/cli get theme {{THEME_STYLE}}
+
+# Get recipe decorators and effects
+npx @decantr/cli get recipe {{THEME_RECIPE}}
+
+# Get pattern structure and presets
+npx @decantr/cli get pattern <pattern-name>
 
-If you have access to Decantr MCP tools:
+# Search for patterns
+npx @decantr/cli search <query>
+```
+
+### With MCP Tools (If Available)
+
+> Note: MCP tools require the `@decantr/mcp-server` to be configured. If these tools are not available, use the CLI commands above.
 
 1. `decantr_read_essence` — Load the current essence
 2. `decantr_check_drift` — Verify your planned changes won't violate rules
 3. `decantr_resolve_pattern` — Get pattern details before implementing
 4. `decantr_suggest_patterns` — Find appropriate patterns for new sections
 
-### Without MCP Tools
+### Without MCP Tools or CLI
 
 1. Read `decantr.essence.json` in the project root
 2. Verify the page you're editing exists in `structure[]`
@@ -159,7 +189,7 @@ After generating code, verify:
 Run validation to check for violations:
 
 ```bash
-decantr validate
+npx @decantr/cli validate
 ```
 
 Or use the MCP tool:
@@ -205,6 +235,115 @@ Use the same component variants throughout a pattern. If buttons are `primary` s
 
 ---
 
+## CSS Implementation
+
+### HTML Setup
+
+Your `index.html` MUST have theme and mode attributes:
+
+```html
+<!DOCTYPE html>
+<html lang="en" data-theme="{{THEME_STYLE}}" data-mode="{{THEME_MODE}}">
+  <head>
+    <meta name="color-scheme" content="{{THEME_MODE}}">
+    ...
+  </head>
+</html>
+```
+
+**Why this matters:**
+- `data-theme` enables theme switching via JS without reloading CSS
+- `data-mode` enables light/dark toggle
+- `color-scheme` tells the browser to style native controls (scrollbars, inputs) correctly
+
+### CSS Layer Structure
+
+Use `@layer` for proper cascade control:
+
+```css
+@layer decantr.reset, decantr.tokens, decantr.decorators, decantr.patterns, decantr.utilities, app;
+
+@layer decantr.reset {
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; }
+}
+
+@layer decantr.tokens {
+  /* Base spacing (theme-agnostic) */
+  :root {
+    --gap1: 4px;
+    --gap2: 8px;
+    --gap3: 12px;
+    --gap4: 16px;
+    --gap6: 24px;
+    --gap8: 32px;
+    --gap12: 48px;
+  }
+
+  /* Theme-specific tokens */
+  html[data-theme="{{THEME_STYLE}}"] {
+    color-scheme: {{THEME_MODE}};
+
+    /* Seed colors from theme */
+    --d-primary: /* from theme.seed.primary */;
+    --d-secondary: /* from theme.seed.secondary */;
+    --d-accent: /* from theme.seed.accent */;
+    --d-bg: /* from theme.seed.background */;
+
+    /* Surface stack */
+    --d-surface: rgba(255, 255, 255, 0.03);
+    --d-surface-raised: rgba(255, 255, 255, 0.06);
+    --d-border: rgba(255, 255, 255, 0.1);
+
+    /* Text hierarchy */
+    --d-text: #FFFFFF;
+    --d-text-secondary: rgba(255, 255, 255, 0.7);
+    --d-text-muted: rgba(255, 255, 255, 0.4);
+  }
+}
+
+@layer decantr.decorators {
+  /* Recipe-specific classes from {{THEME_RECIPE}} */
+}
+
+@layer decantr.patterns {
+  .pattern-hero { }
+  .pattern-kpi-grid { }
+}
+
+@layer app {
+  /* Your application overrides */
+}
+```
+
+### Variable Naming Convention
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `--d-` | Core Decantr tokens | `--d-primary`, `--d-bg` |
+| `--{recipe}-` | Recipe-specific | `--lum-orb-opacity` |
+| `--gap{N}` | Spacing tokens | `--gap4`, `--gap8` |
+
+### Theme Switching (JavaScript)
+
+```javascript
+// Switch theme
+document.documentElement.dataset.theme = 'newTheme';
+
+// Switch mode
+document.documentElement.dataset.mode = 'light';
+document.querySelector('meta[name="color-scheme"]').content = 'light';
+```
+
+### Get Full Theme/Recipe Specs
+
+```bash
+npx @decantr/cli get theme {{THEME_STYLE}}   # See seed colors, palette
+npx @decantr/cli get recipe {{THEME_RECIPE}} # See decorators, effects
+```
+
+---
+
 ## Spatial Guidelines
 
 ### Personality to Density Mapping
@@ -341,7 +480,7 @@ These files contain tier-specific rules and checklists.
 **"I don't know which pattern to use"**
 1. Use `decantr_suggest_patterns` with a description
 2. Or check the patterns in `.decantr/cache/patterns/`
-3. Or search the registry with `decantr search <query>`
+3. Or search the registry with `npx @decantr/cli search <query>`
 
 ---
 
@@ -366,7 +505,7 @@ When the user wants to change the design spec:
 
 1. Read the current `decantr.essence.json`
 2. Make the requested changes
-3. Validate with `decantr validate`
+3. Validate with `npx @decantr/cli validate`
 4. Write the updated file
 5. Regenerate `DECANTR.md` if structure changed significantly
 

package/src/templates/task-add-page.md.template

@@ -40,7 +40,7 @@ Before generating code for a new page, add it to the essence:
 Run validation to ensure the essence is valid:
 
 ```bash
-decantr validate
+npx @decantr/cli validate
 ```
 
 ### 3. Then Generate
@@ -54,7 +54,7 @@ Before adding a page:
 - [ ] The page ID is added to `structure[]` in essence
 - [ ] The page has a `shell` defined
 - [ ] The page has a `layout[]` with pattern IDs
-- [ ] Validation passes (`decantr validate`)
+- [ ] Validation passes (`npx @decantr/cli validate`)
 
 During code generation:
 
@@ -65,7 +65,7 @@ During code generation:
 
 After generation:
 
-- [ ] Run `decantr validate`
+- [ ] Run `npx @decantr/cli validate`
 - [ ] Verify the page matches the theme
 - [ ] Check that the recipe styles are applied
 

package/src/templates/task-modify.md.template

@@ -102,8 +102,8 @@ During modification:
 
 After modification:
 
-- [ ] Run `decantr validate`
-- [ ] Run `decantr audit` to check drift
+- [ ] Run `npx @decantr/cli validate`
+- [ ] Run `npx @decantr/cli audit` to check drift
 - [ ] Verify no warnings or errors
 
 ## Spacing Enforcement

package/src/templates/task-scaffold.md.template

@@ -41,7 +41,7 @@ During scaffolding:
 
 After scaffolding:
 
-- [ ] Run `decantr validate` to check the essence
+- [ ] Run `npx @decantr/cli validate` to check the essence
 - [ ] Verify each page renders correctly
 - [ ] Check theme consistency across pages
 
@@ -56,7 +56,7 @@ After scaffolding is complete:
 1. Run the development server
 2. Verify all pages load
 3. Check theme consistency
-4. Run `decantr validate`
+4. Run `npx @decantr/cli validate`
 
 Once verified, subsequent changes will use **{{GUARD_MODE}}** enforcement mode.