@decantr/cli 1.0.0-beta.8 → 1.1.0

package/dist/upgrade-KRFCKUMR.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import {
+  RegistryClient
+} from "./chunk-K6MIDPQH.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.1.0",
   "description": "Decantr CLI — search the registry, validate essence files, and access design intelligence from the terminal",
   "license": "MIT",
   "repository": {
@@ -16,18 +16,19 @@
   "main": "dist/index.js",
   "files": [
     "dist",
-    "src/templates"
+    "src/templates",
+    "src/bundled"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@decantr/essence-spec": "1.0.0-beta.3",
-    "@decantr/registry": "1.0.0-beta.3"
-  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@decantr/essence-spec": "workspace:*",
+    "@decantr/registry": "workspace:*"
   }
-}
+}

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>
+
+# Search for patterns
+npx @decantr/cli search <query>
+```
+
+### With MCP Tools (If Available)
 
-If you have access to Decantr MCP tools:
+> 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
+
+This project uses **@decantr/css** for layout atoms and the generated CSS files for theme tokens and recipe decorators.
+
+### Setup
+
+```javascript
+// 1. Import the atoms runtime
+import { css } from '@decantr/css';
+
+// 2. Import generated CSS files (created by decantr init)
+import './styles/tokens.css';      // Theme tokens (--d-primary, --d-surface, etc.)
+import './styles/decorators.css';  // Recipe decorators ({{THEME_RECIPE}}-card, etc.)
+```
+
+### 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
+
+### Using Atoms
+
+The `css()` function processes atom strings and injects CSS at runtime:
+
+```jsx
+// Layout atoms
+<div className={css('_flex _col _gap4 _p4')}>
+  <h1 className={css('_heading1')}>Title</h1>
+  <p className={css('_textsm _fgmuted')}>Description</p>
+</div>
+
+// Responsive prefixes (mobile-first)
+<div className={css('_gc1 _sm:gc2 _lg:gc4')}>
+  {/* 1 col -> 2 cols at 640px -> 4 cols at 1024px */}
+</div>
+
+// Pseudo-class prefixes
+<button className={css('_bgprimary _h:bgprimary/80')}>
+  Hover me
+</button>
+```
+
+### Common Atoms
+
+| Category | Atoms | Description |
+|----------|-------|-------------|
+| Display | `_flex`, `_grid`, `_block`, `_none` | Display types |
+| Flexbox | `_col`, `_row`, `_wrap`, `_flex1` | Flex direction/behavior |
+| Alignment | `_aic`, `_jcc`, `_jcsb` | Align/justify content |
+| Spacing | `_gap{n}`, `_p{n}`, `_m{n}`, `_px{n}` | Gap, padding, margin |
+| Sizing | `_wfull`, `_hfull`, `_w{n}`, `_h{n}` | Width, height |
+| Typography | `_textsm`, `_textlg`, `_heading1`-`_heading6` | Font sizes |
+| Colors | `_bgprimary`, `_bgsurface`, `_fgmuted` | Background, foreground |
+
+### CSS Architecture
+
+The CSS is organized into two parts:
+
+1. **Atoms (@decantr/css)** - Layout utilities injected at runtime into `@layer d.atoms`
+2. **Generated CSS files** - Theme tokens and recipe decorators created during scaffold
+
+```
+src/styles/
+  tokens.css      # :root { --d-primary: #...; --d-surface: #...; }
+  decorators.css  # .{{THEME_RECIPE}}-card { ... }
+```
+
+### Variable Naming Convention
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `--d-` | Core Decantr tokens | `--d-primary`, `--d-bg` |
+| `--d-gap-{n}` | Spacing tokens | `--d-gap-4`, `--d-gap-8` |
+| `--d-radius` | Border radius | `--d-radius`, `--d-radius-lg` |
+
+### 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.
 

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Decantr AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.