@exxatdesignux/ui 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- [`06bd06a`](https://github.com/ExxatDesign/Exxat-DS-Workspace/commit/06bd06a6ce5ebbe7ee9aba7c16c9329b4f9bdb5f) - **Scaffolded template (`create-exxat-app`) — add `overrides` / `pnpm.overrides` for `postcss` + `ws`**
+
+  A fresh `pnpm dlx create-exxat-app my-app` (or `npx --package=@exxatdesignux/ui exxat-ui init`) was producing an app that `npm audit` reported as having **4 moderate severity vulnerabilities** on first install:
+
+  | Advisory                                                            | Vulnerable transitive | Pulled in by                                |
+  | ------------------------------------------------------------------- | --------------------- | ------------------------------------------- |
+  | GHSA-qx2v-qp2m-jg93 (XSS via unescaped `</style>` in CSS stringify) | `postcss <8.5.10`     | `next@16.2.6` (only published 16.x release) |
+  | GHSA-58qx-3vcg-4xpx (uninitialized memory disclosure)               | `ws@8.0.0 - 8.20.0`   | `pm2@^7.0.1` (only published 7.x release)   |
+
+  `npm audit fix --force` would have _downgraded_ `next` to 9.3.3 and `pm2` to 6.0.14 — both major regressions. The actual upstream fixes haven't shipped yet, so the correct mitigation is package-manager overrides that force the resolver to pick a safer version of the transitive dep without touching the parents.
+
+  Added to `packages/ui/template/package.json`:
+
+  ```json
+  "overrides": {
+    "postcss": "$postcss",
+    "ws": "^8.20.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "postcss@<8.5.10": "^8.5.14",
+      "ws@<8.20.1": "^8.20.1"
+    }
+  }
+  ```
+
+  The `"postcss": "$postcss"` reference uses npm's special syntax that aliases the override to the direct devDep version (`^8.5.14`, already safe), avoiding the `EOVERRIDE` "conflicts with direct dependency" error. pnpm doesn't support `$name`, so we use its semver-range targeting (`@<8.5.10`) which fires only on the vulnerable subset and keeps newer versions unaffected.
+
+  After the fix: fresh scaffolds report `npm audit: found 0 vulnerabilities` and install ~4s faster from dedup (951 → 947 packages).
+
+  Workspace-internal apps (`apps/web`) are unaffected — the workspace root `package.json` already carries `pnpm.overrides` for these CVEs. Only the template was leaking them to consumers because scaffolded apps don't inherit workspace overrides.
+
+  **Existing consumers (already-scaffolded apps):** apply the same `overrides` + `pnpm.overrides` blocks to their `package.json` and re-run `npm install` / `pnpm install`. The shipped `consumer-upgrade-checklist.md` will mention this on the next sync.
+
+  **New consumers:** get the fix automatically on the next `create-exxat-app` invocation once `@exxatdesignux/ui@0.5.1` is published.
+
+## 0.5.0
+
+### Minor Changes
+
+- `create-exxat-app` now drops the full Cursor + Claude agent bundle into
+  the scaffolded repo **automatically** after the dependency install.
+  Before this change, a new app shipped with only the 11 binding rules
+  that happened to live under `apps/web/.cursor/rules/`; the full curated
+  set (29 rules · 16 Cursor skills · 16 Claude skills · 6 pattern docs ·
+  4 handbook files) required a second manual `exxat-ui sync-extras` step.
+
+  What's new for a fresh `pnpm create exxat-app my-app`:
+  - After `pnpm install` succeeds, `init.mjs` invokes `sync-extras` in
+    `--quiet` mode so the scaffolded repo is one step from "open in
+    Cursor and every rule + skill is live".
+  - The bundle is namespaced (`exxat-*` files only) so re-syncing on
+    upgrade never touches a consumer's own rules, skills, AGENTS.md, or
+    product code.
+  - Opt out with `create-exxat-app my-app --no-extras` (alias
+    `--skip-extras`) — print a "run sync-extras later" hint instead.
+  - Final "Done!" message no longer treats `sync-extras` as an optional
+    follow-up; it mentions the upgrade-time refresh command instead.
+
+  Smaller polish in the same release:
+  - `--help` now documents `--no-extras`.
+  - Project-name normalization handles absolute target paths cleanly
+    (no leading-hyphen package names; no `.//absolute/path/` in the
+    success message).
+  - The `cd <target>` hint is suppressed when the user scaffolded into
+    the current directory with `.`.
+  - `sync-extras.mjs` learned `--quiet` (and the
+    `EXXAT_SYNC_EXTRAS_QUIET=1` env override) so the scaffolder can
+    call it without flooding the user with 50+ per-file log lines; the
+    final summary line still prints.
+  - README updated to describe the auto-extras flow and to clarify the
+    `sync-extras` command is now an _upgrade_ refresh, not a required
+    first step.
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -26,8 +26,23 @@ bun  create exxat-app my-app
 
 The scaffolder ships a complete Next.js 16 starter: the reference
 **Library** hub at `/library/all`, the `/columns` cell-catalog showcase,
-typed mock data, the full Cursor skill + pattern doc set under
-`cursor-rules/`, `cursor-skills/`, `patterns/`, and `handbook/`.
+typed mock data, plus the full Cursor + Claude agent bundle dropped into
+the right paths **automatically**:
+
+- `.cursor/rules/exxat-*.mdc` — 29 binding rules (Cursor reads these as
+  always-on / agent-requestable).
+- `.cursor/skills/exxat-*/` and `.claude/skills/exxat-*/` — 16 skill
+  bundles (`SKILL.md` + references); same source written to both readers.
+- `docs/exxat-ds/*.md` — 6 pattern docs (data views, command menu,
+  drawer-vs-dialog, KPI flat band, …) + the consumer upgrade checklist.
+- `docs/exxat-ds/handbook/*.md` — HANDBOOK · glossary · voice-and-tone ·
+  reference-implementations.
+- `AGENTS.md` (root) — the project's AI handbook from the reference app.
+
+When you `cd my-app` and open Cursor for the first time, every binding
+rule, skill, and pattern doc is already in place. To opt out, pass
+`--no-extras` to the scaffolder; you can run it later with
+`exxat-ui sync-extras` (see below).
 
 ## Adding to an existing Next.js app
 
@@ -55,19 +70,21 @@ Mount `KeyMetricsProvider` near the root if you want the "Ask Leo about
 these metrics" CTA wired to your AI surface (otherwise the strip just
 hides that button automatically).
 
-## Refresh Cursor skills + pattern docs in any consumer
+## Refresh Cursor / Claude agent bundle in any consumer
 
-The package ships a parallel set of binding rules, skills, and pattern
-docs so AI agents in your own repo can read the same guidance the source
-repo uses. To install or refresh them in your repo:
+`pnpm create exxat-app` drops the agent bundle for you on first scaffold.
+When you upgrade `@exxatdesignux/ui` later — or when you want to seed the
+bundle into an **existing** Next.js app that already depends on the DS —
+run:
 
 ```bash
 pnpm dlx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
 ```
 
-This copies `cursor-rules/`, `cursor-skills/`, `patterns/`, and
-`handbook/` into your repo root. The next time Cursor opens, every
-binding rule + skill is live.
+The command is **namespaced**: it only writes files starting with
+`exxat-` (rules + skills) and only inside `.cursor/`, `.claude/skills/`,
+and `docs/exxat-ds/`. Your own rules, skills, AGENTS.md, and product
+code are never touched.
 
 ## What's inside
 
@@ -121,8 +138,8 @@ natively.
   custom property the DS ships.
 
 The full doc set is mirrored under `handbook/` and `patterns/` in this
-package; `exxat-ui sync-extras` drops them into your repo so they sit
-alongside your source.
+package; `pnpm create exxat-app` drops them at `docs/exxat-ds/` on first
+scaffold, and `exxat-ui sync-extras` re-syncs them in any later upgrade.
 
 ## Compatibility
 

package/bin/init.mjs

@@ -27,9 +27,17 @@ const flags = new Set(args.filter((a) => a.startsWith("--")))
 const positional = args.filter((a) => !a.startsWith("--"))
 const targetArg = positional[0] ?? "."
 const targetDir = resolve(process.cwd(), targetArg)
-const projectName = targetArg === "." ? basename(targetDir) : targetArg
+// `displayName` is what we show in messages and use to derive package.json
+// `name`. For "." or an absolute path we just use the basename; for a
+// relative path the user typed (`my-app`, `apps/sandbox`) we keep it as-is.
+const isAbsolute = targetArg.startsWith("/") || /^[a-zA-Z]:\\/.test(targetArg)
+const displayName = targetArg === "." || isAbsolute ? basename(targetDir) : targetArg
+// `cdHint` is what we tell the user to `cd` into. If they passed an
+// absolute path, that's the literal path; otherwise the relative arg.
+const cdHint = isAbsolute ? targetDir : displayName
 const force = flags.has("--force")
 const skipInstall = flags.has("--no-install") || flags.has("--skip-install")
+const skipExtras = flags.has("--no-extras") || flags.has("--skip-extras")
 
 if (flags.has("--help") || flags.has("-h")) {
   console.log(`
@@ -47,6 +55,9 @@ Options:
                       files are NOT overwritten unless template ships the
                       same path).
   --no-install        Skip the dependency install step.
+  --no-extras         Skip auto-syncing Cursor / Claude agent skills, binding
+                      rules, and pattern docs. You can run them later with
+                      \`exxat-ui sync-extras\`.
   -h, --help          Show this message.
 
 Examples:
@@ -59,7 +70,7 @@ Examples:
 
 if (!existsSync(targetDir)) {
   mkdirSync(targetDir, { recursive: true })
-  console.log(`📁  Created ${projectName}/`)
+  console.log(`📁  Created ${displayName}/`)
 }
 
 const targetStat = statSync(targetDir)
@@ -86,7 +97,7 @@ if (blockers.length > 0 && !force) {
   process.exit(1)
 }
 
-console.log(`📦  Copying Exxat DS starter app into ${projectName}/ …`)
+console.log(`📦  Copying Exxat DS starter app into ${displayName}/ …`)
 cpSync(templateDir, targetDir, { recursive: true })
 
 // Pin DS to this CLI's published version so `latest` cache drift cannot
@@ -97,7 +108,7 @@ if (targetPkg.dependencies?.["@exxatdesignux/ui"]) {
   targetPkg.dependencies["@exxatdesignux/ui"] = `^${selfPkg.version}`
 }
 // Name the project after the target dir for nicer dev-server / process titles.
-targetPkg.name = projectName.replace(/[^a-z0-9-_]/gi, "-").toLowerCase() || "my-exxat-app"
+targetPkg.name = displayName.replace(/[^a-z0-9-_]/gi, "-").toLowerCase() || "my-exxat-app"
 writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
 console.log(`📌  Pinned @exxatdesignux/ui to ^${selfPkg.version} and named the project "${targetPkg.name}".`)
 
@@ -111,19 +122,41 @@ if (skipInstall) {
   } catch (err) {
     console.error("")
     console.error(`❌  ${pm.label} install failed. You can retry manually:`)
-    console.error(`     cd ${projectName} && ${pm.installCmd}`)
+    console.error(`     cd ${cdHint} && ${pm.installCmd}`)
     process.exit(1)
   }
 }
 
+// Drop the full curated bundle (Cursor + Claude skills, binding rules,
+// pattern docs, handbook) into the new repo so AI assistants light up on
+// first open. The bundle replaces only `exxat-*` namespaced files — the
+// consumer's own rules/skills/docs are preserved on every re-run.
+if (skipExtras) {
+  console.log(`⏭   Skipped agent skills + rules (--no-extras).`)
+} else {
+  const syncScript = resolve(__dirname, "sync-extras.mjs")
+  if (!existsSync(syncScript)) {
+    console.warn(`⚠️   Could not find sync-extras at ${syncScript} — skipping.`)
+  } else {
+    console.log(`🧠  Installing Cursor + Claude agent skills, binding rules, and pattern docs …`)
+    try {
+      execSync(`node "${syncScript}" --quiet`, { stdio: "inherit", cwd: targetDir })
+    } catch (err) {
+      console.warn(`⚠️   Agent extras step failed. You can retry manually:`)
+      console.warn(`     cd ${cdHint} && ${pm.dlxCmd} --package=@exxatdesignux/ui@${selfPkg.version} exxat-ui sync-extras`)
+    }
+  }
+}
+
 console.log("")
-console.log(`✅  Done! Your Exxat DS app is ready in ./${projectName}/`)
+console.log(`✅  Done! Your Exxat DS app is ready in ${isAbsolute ? targetDir : `./${displayName}/`}`)
 console.log("")
-console.log(`   cd ${projectName}`)
+if (targetArg !== ".") console.log(`   cd ${cdHint}`)
 console.log(`   ${pm.runCmd} dev     # start dev server`)
 console.log("")
-console.log("   Optional — refresh Cursor skills + pattern docs:")
-console.log(`     ${pm.dlxCmd} --package=@exxatdesignux/ui@${selfPkg.version} exxat-ui sync-extras`)
+console.log("   Cursor / Claude skills, rules, and pattern docs are already in place.")
+console.log("   When you upgrade @exxatdesignux/ui later, refresh them with:")
+console.log(`     ${pm.dlxCmd} --package=@exxatdesignux/ui@latest exxat-ui sync-extras`)
 console.log("")
 
 /**

package/bin/sync-extras.mjs

@@ -28,6 +28,14 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkgRoot = resolve(__dirname, "..")
 const cwd = process.cwd()
 
+// `--quiet` suppresses the per-file "[sync-extras] wrote …" lines so the
+// scaffolder (`create-exxat-app`) can call us inline without drowning the
+// user in 50+ status lines. The final summary line still prints.
+const QUIET = process.argv.includes("--quiet") || process.env.EXXAT_SYNC_EXTRAS_QUIET === "1"
+function log(...m) {
+  if (!QUIET) console.log(...m)
+}
+
 const SOURCES = {
   skills:   join(pkgRoot, "consumer-extras", "cursor-skills"),
   rules:    join(pkgRoot, "consumer-extras", "cursor-rules"),
@@ -69,7 +77,7 @@ function syncSkillsTo(label, dest) {
     if (!statSync(src).isDirectory()) continue
     if (!name.startsWith("exxat-")) continue
     replaceDir(src, join(dest, name))
-    console.log(`[sync-extras] wrote ${label}/${name}/`)
+    log(`[sync-extras] wrote ${label}/${name}/`)
     wrote++
   }
 }
@@ -91,7 +99,7 @@ function syncRules() {
     if (!statSync(src).isFile()) continue
     if (!name.startsWith("exxat-") || !name.endsWith(".mdc")) continue
     cpSync(src, join(DESTINATIONS.cursorRules, name))
-    console.log(`[sync-extras] wrote .cursor/rules/${name}`)
+    log(`[sync-extras] wrote .cursor/rules/${name}`)
     wrote++
   }
 }
@@ -111,7 +119,7 @@ function syncPatterns() {
     const src = join(SOURCES.patterns, name)
     if (!statSync(src).isFile()) continue
     cpSync(src, join(DESTINATIONS.patterns, name))
-    console.log(`[sync-extras] wrote docs/exxat-ds/${name}`)
+    log(`[sync-extras] wrote docs/exxat-ds/${name}`)
     wrote++
   }
 }
@@ -137,7 +145,7 @@ function syncHandbook() {
     const src = join(SOURCES.handbook, name)
     if (!statSync(src).isFile()) continue
     cpSync(src, join(DESTINATIONS.handbook, name))
-    console.log(`[sync-extras] wrote docs/exxat-ds/handbook/${name}`)
+    log(`[sync-extras] wrote docs/exxat-ds/handbook/${name}`)
     wrote++
   }
 }
@@ -149,4 +157,4 @@ syncPatterns()
 syncHandbook()
 
 console.log(`[sync-extras] Done. ${wrote} files / dirs written; ${skipped} optional sources missing.`)
-console.log("[sync-extras] Product routes and app content were not modified.")
+if (!QUIET) console.log("[sync-extras] Product routes and app content were not modified.")

package/dist/components/ui/banner.d.ts

@@ -4,7 +4,7 @@ import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 declare const systemBannerVariants: (props?: ({
-    variant?: "success" | "warning" | "error" | "info" | "promo" | null | undefined;
+    variant?: "error" | "success" | "warning" | "info" | "promo" | null | undefined;
     emphasis?: "prominent" | "subtle" | null | undefined;
     actionPosition?: "inline" | "bottom" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -32,7 +32,7 @@ interface SystemBannerProps extends React.HTMLAttributes<HTMLDivElement>, Varian
 }
 declare function SystemBanner({ children, title, variant, emphasis, dismissible, onDismiss, action, actionPosition, icon, decorativeOverlay, className, style, ...props }: SystemBannerProps): react_jsx_runtime.JSX.Element | null;
 declare const localBannerVariants: (props?: ({
-    variant?: "success" | "warning" | "error" | "info" | "promo" | null | undefined;
+    variant?: "error" | "success" | "warning" | "info" | "promo" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface LocalBannerProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof localBannerVariants> {
     /** Banner title (optional) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "license": "UNLICENSED",
   "author": "Exxat Design",

package/tokens/hooks-index.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.4.0",
+  "version": "0.5.1",
   "source": "packages/ui/src/globals.css",
-  "generatedAt": "2026-05-21T18:31:11.351Z",
+  "generatedAt": "2026-05-22T04:04:09.308Z",
   "tokenCount": 197,
   "themeKeys": [
     "tailwind-bridge",