jixoai-ui CLI

The official jixoai design-language CLI. It shares shadcn's components.json and extends it with a non-conflicting jixoai block:

{
  // ...shadcn fields stay untouched (style, aliases, registries, ...)...
  "registries": { "@jixoai": "https://ui.jixoai.com/r/{name}.json" },
  "jixoai": { "brandHue": 160 }
  // `--css <path>` adds "cssPath": "<path>" here — see Flags below
}

Usage

npx jixoai-ui init --hue 160   # namespace + config + theme + hue, one shot
npx jixoai-ui add toc          # = shadcn add @jixoai/toc, hue re-applied
npx jixoai-ui add effects      # group alias: every ui item in the group
npx jixoai-ui add effects/glass  # one member (membership validated)
npx jixoai-ui add llms-txt     # AI export: llms.txt / llms-full.txt / page .md
npx jixoai-ui upgrade          # refresh locked items + run upgrade tasks
npx jixoai-ui hue 165          # retheme by changing one number
npx jixoai-ui config           # print the resolved jixoai config

Flags

• --css <path> (init/hue/add/upgrade) — where jixoai.css lives, overriding the whole aliases.lib hunt. For consumers whose $lib alias maps nowhere (hue fails with the exact reason), one --css fixes every later run: the path is remembered as jixoai.cssPath inside the jixoai block. --css=<path> works too.
• --registry <dir|url> (init/add/adopt/upgrade) — override registries["@jixoai"] for one run, no config edit. A local directory of <name>.json payloads (a checkout's built public/r/, or any mirror's output) is read straight off disk; a url template must contain {name} (file:// or an http(s) mirror on localhost). The spawned shadcn fetches the same override (http(s) only — shadcn cannot read file://), and your configured url is restored afterwards. When the registry is unreachable, every fetch error carries the way out: retry, --registry mirror, and npx jixoai-ui@latest (a stale npx cache may be serving an outdated CLI).
• --overwrite (init/add) — forwarded to shadcn. Under non-interactive stdin (CI, agent shells) it is implied: shadcn's overwrite confirmation cannot be answered at EOF and would cancel the whole write phase. An install whose files never landed fails with exit code 1 — nothing enters jixoai-ui.lock unverified.

Group aliases

add accepts three argument forms (effect-attachments Lane H):

• Item name — npx jixoai-ui add glass: as-is, any registry type. An exact item name always wins when an item and a group id collide.
• Group id — npx jixoai-ui add effects: expands to EVERY registry:ui item whose meta.group is effects, in registry order, and prints the expansion (jixoai-ui: effects → press-button, glass). The expansion is what installs AND what enters jixoai-ui.lock — the lock records item names, never group ids.
• Scoped member — npx jixoai-ui add effects/glass: resolves to glass after validating the group actually owns the item; a wrong group (add effects/toc) exits non-zero naming the item's real group and the requested one.

Groups are an ADD-time convenience: adopt and upgrade stay item-name-only. Membership comes from /r/registry.json (the registry index) — a custom registry URL without an index keeps the standing bare-name behavior for plain adds and refuses the scoped form.

llms-txt installs vite-plugins/llms-txt.mjs — the build-time llms.txt/llms-full.txt/per-page-.md generator (llmstxt.org proposal v2). Wire it ONE way: llmsTxt() in vite plugins for plain-build sites, or generateLlmsTxt(distDir, config) as the last step of an orchestrated build. Full law + config schema: skills/jixoai-website/references/llms-txt.md.

Requires components.json (run npx shadcn init first in fresh projects — this CLI extends shadcn's config, it never replaces it).

upgrade

npx jixoai-ui upgrade pulls the latest version of every installed component and runs the idempotent upgrade tasks. Running it again changes nothing — a converged second run performs zero writes, so it is safe in CI and in any shell loop.

• Lock: init/add record every installed item in jixoai-ui.lock (next to components.json) as { items: { [name]: { files: { [path]: sha256 } } } }. Paths are resolved through components.json aliases ($lib-rooted values resolve through the project's tsconfig/jsconfig compilerOptions.paths, the same map shadcn uses — wildcard-only tables and extends chains included); hashes cover canonical registry content (pre-hue, pre-task). A missing or empty lock fails with exit code 1 and tells you to add first.
• Refresh: every locked item is fetched from registries["@jixoai"] with {name} replaced (file:// URLs work for local registries). A file is written only when its registry sha256 differs from the locked one; identical content is skipped and counted as unchanged. Network, HTTP, and JSON failures abort with an explicit error and exit code 1.
• Hue: after the writes the brand hue is re-applied to jixoai.css.
• Tasks: bin/upgrade-tasks.mjs exports the task array [{ name, item?, applies(content, ctx), run(ctx) }]. A task fires only while its legacy pattern still exists (applies), so re-running always converges:
  • legacy-import-paths — @lib/toc-engine → $lib/toc-engine and ../lib/toc.css → $lib/toc.css (only where the old specifier exists).
  • spine-axis (item toc) — left: 2px → left: 0px in the toc css.
  • scroll-margin-cleanup — diagnostic only: warns when the app-level css declares both scroll-margin-top and scroll-padding-top (the offsets stack; which one owns the offset is an app decision jixoai-ui never makes for you). It never edits files, so it re-reports on every run until the redundancy is removed.
• Summary: updated N / unchanged M / tasks ran X, skipped Y, then the lock hashes are updated.

CI usage — always upgrade, build, and test against the freshest components:

npx jixoai-ui upgrade && npm run build && npm test