jixoai-ui 0.2.0 → 0.4.0

package/README.md

@@ -16,11 +16,42 @@ The official jixoai design-language CLI. It **shares shadcn's
 ```bash
 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
 ```
 
+## 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).
 
@@ -34,7 +65,9 @@ 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; hashes cover canonical registry content
+  through `components.json` aliases (`$lib`-rooted values resolve through
+  the project's tsconfig/jsconfig `compilerOptions.paths`, the same map
+  shadcn uses); 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"]`

package/bin/jixoai-ui.mjs

@@ -29,11 +29,29 @@
  * registry sha256 differs from the locked one, re-applies hue, then runs
  * the idempotent upgrade tasks (bin/upgrade-tasks.mjs) — a converged
  * second run performs zero writes.
+ *
+ * Install integrity (consumer-feedback-fixes P0-3, 2026-09-06): "successful"
+ * means VERIFIED ON DISK — an item enters the lock only when every one of
+ * its files exists at its alias-resolved path (a non-interactive shadcn run
+ * whose overwrite prompt hits EOF cancels its write phase; the item then
+ * stays unlocked with an explicit recovery warning). After every add phase
+ * the CLI also relocates files shadcn dropped into literal `src/@lib/`,
+ * `src/@ui/` and `src/vite-plugins/` directories to their alias-resolved
+ * destinations, and item-name parsing skips `--` tokens (flags never
+ * masquerade as `@jixoai/--help`).
  */
 
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import process from "node:process";
 
@@ -56,7 +74,11 @@ Commands:
                                      lock (first upgrade then syncs to canon)
   jixoai-ui add <item...>            install registry items (delegates to
                                      \`shadcn add ${NAMESPACE}/<item>\`), then
-                                     re-applies the brand hue
+                                     re-applies the brand hue. Group
+                                     aliases: \`add effects\` installs
+                                     every ui item in the group,
+                                     \`add effects/glass\` installs one
+                                     member
   jixoai-ui upgrade                  refresh every locked item to the latest
                                      registry content, re-apply the brand
                                      hue, and run the idempotent upgrade
@@ -95,10 +117,65 @@ function ensureNamespace(config) {
   }
 }
 
+/* ── $-alias resolution (effect-attachments Lane H, 2026-09-10) ──
+ *
+ * shadcn-svelte consumers carry `$lib`-ROOTED alias values
+ * (`"ui": "$lib/ui"` — the frozen table the clean-install harness
+ * proves). A literal `$lib` directory never exists on disk, so every
+ * alias base must first resolve through the project's
+ * tsconfig/jsconfig `compilerOptions.paths` (the same map shadcn
+ * itself resolves aliases with) before it becomes a filesystem path.
+ * Before this, `add` on such consumers installed fine but the lock
+ * found ZERO files at "(no) install path" and recorded nothing —
+ * `upgrade` went dead while the files sat in place. A base that maps
+ * nowhere keeps its literal meaning; `extends`-chained configs are a
+ * known limit (the direct paths table wins). */
+const aliasResolverCache = new Map(); // cwd → (base → resolved base)
+
+function tsconfigPathsFor(cwd) {
+  for (const name of ["tsconfig.json", "jsconfig.json"]) {
+    const path = join(cwd, name);
+    if (!existsSync(path)) continue;
+    try {
+      const paths = JSON.parse(readFileSync(path, "utf8"))?.compilerOptions?.paths;
+      if (paths && typeof paths === "object") return paths;
+    } catch {
+      // an unparseable config is not fatal — the literal base stands
+    }
+  }
+  return null;
+}
+
+function aliasBaseResolver(cwd) {
+  if (aliasResolverCache.has(cwd)) return aliasResolverCache.get(cwd);
+  const paths = tsconfigPathsFor(cwd);
+  const star = (v) => String(Array.isArray(v) ? v[0] ?? "" : v ?? "").replace(/\*$/, "");
+  const resolveBase = (base) => {
+    if (!paths || !base.startsWith("$")) return base;
+    if (paths[base] !== undefined) return star(paths[base]);
+    const wildcards = Object.keys(paths)
+      .filter((k) => k.endsWith("/*"))
+      .map((k) => k.slice(0, -1)) // '$lib/*' → '$lib/'
+      .sort((a, b) => b.length - a.length); // longest prefix wins
+    for (const prefix of wildcards) {
+      if (base.startsWith(prefix)) return star(paths[`${prefix}*`]) + base.slice(prefix.length);
+    }
+    return base;
+  };
+  aliasResolverCache.set(cwd, resolveBase);
+  return resolveBase;
+}
+
+/** an alias VALUE (`"$lib/ui"` / `"src/lib/ui"`) → a cwd-relative path */
+function aliasDir(aliasValue, cwd) {
+  return resolve(cwd, aliasBaseResolver(cwd)(aliasValue));
+}
+
 function themeCssPath(config, cwd) {
   const lib = config.aliases?.lib;
   if (typeof lib !== "string") return null;
-  const candidates = [resolve(cwd, lib, "jixoai.css"), resolve(cwd, `${lib}.css`)];
+  const base = aliasBaseResolver(cwd)(lib);
+  const candidates = [resolve(cwd, base, "jixoai.css"), resolve(cwd, `${base}.css`)];
   for (const candidate of candidates) {
     if (existsSync(candidate)) return candidate;
   }
@@ -201,6 +278,147 @@ async function fetchRegistryItem(registryUrl, name) {
   return json;
 }
 
+/**
+ * Fetch + parse the registry INDEX — the same `/r/registry.json` the
+ * public site serves (`shadcn build` emits it from registry.json with
+ * `meta.group` intact, so group membership survives the pipeline).
+ * Mirrors fetchRegistryItem's URL building: the `{name}` template
+ * becomes the literal `registry`, so `https://ui.jixoai.com/r/{name}.json`
+ * resolves `https://ui.jixoai.com/r/registry.json` and local/file://
+ * mirrors land on their own index the same way.
+ */
+async function fetchRegistryIndex(registryUrl) {
+  const url = registryUrl.replace("{name}", "registry");
+  let raw;
+  try {
+    raw = await fetchText(url);
+  } catch (cause) {
+    throw new Error(`cannot fetch the registry index from ${url}: ${cause.message}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new Error(`the registry index (${url}) is not valid JSON`);
+  }
+  const items = Array.isArray(json) ? json : json.items;
+  if (!Array.isArray(items) || items.some((i) => typeof i?.name !== "string")) {
+    throw new Error(`the registry index (${url}) has no usable items array`);
+  }
+  return items;
+}
+
+/**
+ * Resolve `add` arguments to registry item names (effect-attachments
+ * Lane H, the r5 Owner request #2, 2026-09-10 — `npx jixoai-ui add
+ * effects` / `npx jixoai-ui add effects/glass`):
+ *
+ *   effects          GROUP alias — expands to EVERY registry:ui item
+ *                    whose `meta.group === 'effects'`, in REGISTRY
+ *                    ORDER (the index's item order). Groups with zero
+ *                    registry:ui members (e.g. `engines` — lib-only)
+ *                    are not add-able ids.
+ *   effects/glass    SCOPED member — resolves to `glass` after proving
+ *                    the item EXISTS and its `meta.group` is exactly
+ *                    `effects` (a violation names both groups).
+ *   glass            ITEM name — as-is, any registry type. PRECEDENCE
+ *                    LAW: an exact item name ALWAYS wins over a group
+ *                    id when the two collide (none collide today; the
+ *                    law is fixed here so a future `effects` ITEM
+ *                    simply shadows the group instead of changing the
+ *                    resolution rules).
+ *
+ * `adopt`/`upgrade` stay ITEM-NAME-ONLY on purpose: groups are an
+ * ADD-time convenience, and the lock + the upgrade loop record items,
+ * never group ids.
+ *
+ * Degradation: a registry without an index (single-item file://
+ * fixtures) keeps the standing bare-name behavior — the index is
+ * fetched ONCE per call, and a failed fetch downgrades to a warning
+ * when every arg is a plain name, while the scoped form hard-fails
+ * (it cannot be validated without the index).
+ */
+export async function resolveAddNames(registryUrl, args) {
+  let index = null;
+  let indexError = null;
+  try {
+    index = await fetchRegistryIndex(registryUrl);
+  } catch (cause) {
+    indexError = cause.message;
+  }
+  if (indexError && args.some((a) => a.includes("/"))) {
+    fail(indexError);
+  }
+  if (indexError) {
+    console.warn(
+      `jixoai-ui: ${indexError} — treating every argument as an item name (group aliases need the registry index)`,
+    );
+    return [...new Set(args)];
+  }
+  const byName = new Map(index.map((i) => [i.name, i]));
+  const groups = new Map(); // group id → registry:ui member names, index order
+  for (const item of index) {
+    if (item.type !== "registry:ui") continue;
+    const group = item.meta?.group;
+    if (typeof group !== "string") continue;
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(item.name);
+  }
+  const knownGroups = () => [...groups.keys()].join(", ");
+
+  const resolved = [];
+  const seen = new Set(); // `add effects glass` installs glass once
+  const push = (name) => {
+    if (!seen.has(name)) {
+      seen.add(name);
+      resolved.push(name);
+    }
+  };
+
+  for (const arg of args) {
+    if (!arg.includes("/")) {
+      // bare form: an exact ITEM name always wins (see the precedence law)
+      if (byName.has(arg)) {
+        push(arg);
+        continue;
+      }
+      const members = groups.get(arg);
+      if (members) {
+        console.log(`jixoai-ui: ${arg} → ${members.join(", ")}`);
+        for (const name of members) push(name);
+        continue;
+      }
+      fail(
+        `unknown item or group \`${arg}\` — known groups: ${knownGroups()}. ` +
+          `Pick an item from the registry index or a group id above`,
+      );
+    }
+    // scoped form: exactly one slash, both sides non-empty
+    const parts = arg.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      fail(`\`${arg}\` is not a valid scoped item — expected \`group/name\` (e.g. \`effects/glass\`)`);
+    }
+    const [group, name] = parts;
+    if (!byName.has(name)) {
+      const members = groups.get(group);
+      fail(
+        members
+          ? `\`${arg}\`: no registry item named \`${name}\` — group \`${group}\` has: ${members.join(", ")}`
+          : `\`${arg}\`: no registry item named \`${name}\` and \`${group}\` is not a known group — known groups: ${knownGroups()}`,
+      );
+    }
+    const realGroup = byName.get(name).meta?.group;
+    if (realGroup !== group) {
+      fail(
+        `\`${arg}\`: \`${name}\` is not in group \`${group}\` — it belongs to ` +
+          `\`${realGroup ?? "(no group)"}\`. Use \`npx jixoai-ui add ${name}\` instead`,
+      );
+    }
+    push(name);
+  }
+  return resolved;
+}
+
 function assertRegistryFiles(name, files) {
   for (const file of files) {
     if (typeof file.target !== "string" || typeof file.content !== "string") {
@@ -212,13 +430,15 @@ function assertRegistryFiles(name, files) {
 function resolveInstallPath(target, config, cwd) {
   // registry targets are alias-relative ("@ui/toc.svelte" → aliases.ui) or
   // plain project-relative paths; mirrors how shadcn places registry files.
+  // `$`-rooted alias values resolve through the project's tsconfig paths
+  // (aliasDir) — see the $-alias resolution block above.
   const match = /^@([\w.$-]+)(?:\/(.+))?$/.exec(target);
   if (match) {
     const base = config.aliases?.[match[1]];
     if (typeof base !== "string") {
       throw new Error(`cannot place \`${target}\`: components.json has no aliases.${match[1]}`);
     }
-    return resolve(cwd, join(base, match[2] ?? ""));
+    return resolve(aliasDir(base, cwd), match[2] ?? "");
   }
   return resolve(cwd, target);
 }
@@ -262,6 +482,15 @@ function writeLock(path, lock) {
  * Record freshly installed items in the lock. Shared by add/init; upgrade
  * reuses the same fetch/hash/place helpers. The install itself already
  * succeeded, so a recording failure warns instead of failing the command.
+ *
+ * Install-integrity gate (consumer-feedback-fixes P0-3, 2026-09-06):
+ * an item is locked ONLY when every one of its files exists on disk at
+ * the alias-resolved install path. A non-interactive shadcn run whose
+ * overwrite confirmation hits EOF cancels its whole write phase — the
+ * files never land, and the pre-gate CLI locked the item anyway, so
+ * `upgrade` reported it as managed while nothing was installed. A miss
+ * now keeps the item OUT of the lock and prints the missing paths with
+ * the recovery guidance.
  */
 async function recordInstalledItems(cwd, config, names) {
   const registryUrl = registryUrlFor(config);
@@ -272,8 +501,27 @@ async function recordInstalledItems(cwd, config, names) {
       const item = await fetchRegistryItem(registryUrl, name);
       assertRegistryFiles(name, item.files);
       const files = {};
+      const missing = [];
       for (const file of item.files) {
-        files[lockInstallKey(file.target, config, cwd)] = sha256(file.content);
+        const key = lockInstallKey(file.target, config, cwd);
+        if (!existsSync(resolve(cwd, key))) {
+          missing.push(key);
+          continue;
+        }
+        files[key] = sha256(file.content);
+      }
+      if (missing.length > 0) {
+        console.warn(
+          `jixoai-ui: ${name} NOT locked in ${LOCK_NAME} — ${missing.length} of ` +
+            `${item.files.length} file(s) missing at their install path(s):`,
+        );
+        for (const key of missing) console.warn(`  - ${key}`);
+        console.warn(
+          "jixoai-ui: the write phase was cancelled (shadcn's overwrite confirmation " +
+            "hit EOF under non-interactive stdin). Move the conflicting existing file(s) " +
+            "aside and re-run the add; this CLI re-applies the brand hue afterwards.",
+        );
+        continue;
       }
       lock.items[name] = { ...(lock.items[name] ?? {}), files };
       recorded++;
@@ -289,6 +537,64 @@ async function recordInstalledItems(cwd, config, names) {
   }
 }
 
+/* ── post-add relocation (consumer-feedback-fixes P0-3) ── */
+
+/**
+ * shadcn sometimes ignores the registry item's alias targets and drops
+ * files into LITERAL `src/@lib/`, `src/@ui/` and `src/vite-plugins/`
+ * directories (the alias prefix treated as a path segment). This pass
+ * walks those literal directories, moves every dropped file to its
+ * alias-resolved (or project-root) destination, reports each move, and
+ * removes the emptied literal directories. Destination collisions are
+ * reported, never clobbered.
+ */
+function relocateMisplacedFiles(cwd, config) {
+  const alias = (name) => {
+    const base = config.aliases?.[name];
+    if (typeof base !== "string") return null;
+    return aliasDir(base, cwd); // $-rooted values resolve through tsconfig paths
+  };
+  const sources = [
+    { dir: resolve(cwd, "src/@lib"), destination: alias("lib") },
+    { dir: resolve(cwd, "src/@ui"), destination: alias("ui") },
+    { dir: resolve(cwd, "src/@components"), destination: alias("components") },
+    // plain project-relative targets (e.g. vite-plugins/llms-txt.mjs)
+    // that shadcn still anchors under src/
+    { dir: resolve(cwd, "src/vite-plugins"), destination: resolve(cwd, "vite-plugins") },
+  ];
+  for (const { dir, destination } of sources) {
+    if (!destination || !existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    if (entries.length === 0) {
+      rmdirSync(dir);
+      continue;
+    }
+    const moveTree = (fromDir, toDir) => {
+      mkdirSync(toDir, { recursive: true });
+      for (const entry of readdirSync(fromDir, { withFileTypes: true })) {
+        const from = join(fromDir, entry.name);
+        const to = join(toDir, entry.name);
+        if (entry.isDirectory()) {
+          moveTree(from, to);
+          rmdirSync(from);
+        } else if (existsSync(to)) {
+          console.warn(
+            `jixoai-ui: relocation skipped — ${toPosix(relative(cwd, to))} already exists; ` +
+              `${toPosix(relative(cwd, from))} left in place`,
+          );
+        } else {
+          renameSync(from, to);
+          console.log(
+            `jixoai-ui: relocated ${toPosix(relative(cwd, from))} → ${toPosix(relative(cwd, to))}`,
+          );
+        }
+      }
+    };
+    moveTree(dir, destination);
+    if (existsSync(dir) && readdirSync(dir).length === 0) rmdirSync(dir);
+  }
+}
+
 /* ── upgrade ── */
 
 function appCssCandidates(cwd, config, lock) {
@@ -407,18 +713,19 @@ const cwd = process.cwd();
 switch (command) {
   case "init": {
     const { path, config } = readConfig(cwd);
-    const hue = hueFromArgs(rest, config.jixoai?.brandHue ?? DEFAULT_HUE);
+    const hue = hueFromArgs(rest.filter((a) => !a.startsWith("--")), config.jixoai?.brandHue ?? DEFAULT_HUE);
     ensureNamespace(config);
     config.jixoai = { ...(config.jixoai ?? {}), brandHue: hue };
     writeConfig(path, config);
     console.log(`jixoai-ui: ${NAMESPACE} namespace + jixoai config written → ${path}`);
     shadcn(["add", `${NAMESPACE}/${THEME_ITEM}`], cwd, path, config);
+    relocateMisplacedFiles(cwd, readConfig(cwd).config);
     applyHue(themeCssPath(config, cwd), hue);
     await recordInstalledItems(cwd, readConfig(cwd).config, [THEME_ITEM]);
     break;
   }
   case "hue": {
-    const hue = hueFromArgs(["--hue", rest[0]]);
+    const hue = hueFromArgs(["--hue", rest.find((a) => !a.startsWith("--"))]);
     const { path, config } = readConfig(cwd);
     config.jixoai = { ...(config.jixoai ?? {}), brandHue: hue };
     writeConfig(path, config);
@@ -426,14 +733,35 @@ switch (command) {
     break;
   }
   case "add": {
-    if (rest.length === 0) fail("add needs at least one item name (e.g. `toc`)");
+    // arg discipline (consumer-feedback-fixes P0-3): `--` tokens are
+    // flags, never item names (`add --help` used to spawn
+    // `shadcn add @jixoai/--help`)
+    if (rest.some((a) => a === "--help" || a === "-h")) {
+      console.log(USAGE);
+      break;
+    }
+    const items = rest.filter((a) => !a.startsWith("--"));
+    if (items.length === 0) {
+      fail("add needs at least one item name (e.g. `toc`, a group id like `effects`, or `effects/glass`)");
+    }
     const { path, config } = readConfig(cwd);
+    // group aliases (effect-attachments Lane H): `add effects` /
+    // `add effects/glass` resolve to ITEM names BEFORE the shadcn
+    // loop — the loop, the lock and the recording all speak RESOLVED
+    // names (so `add effects` locks glass + press-button, never an
+    // `effects` key)
+    const resolved = await resolveAddNames(registryUrlFor(config), items);
     const hue = config.jixoai?.brandHue ?? DEFAULT_HUE;
-    for (const item of rest) {
+    // one shadcn invocation PER ITEM, each carrying the @jixoai/ prefix
+    // itself (consumer-feedback-fixes P0-3 audit: the prefix must never
+    // depend on shell/shadcn multi-arg behavior — the loop re-reads the
+    // config because shadcn may rewrite it between spawns)
+    for (const item of resolved) {
       shadcn(["add", `${NAMESPACE}/${item}`], cwd, path, readConfig(cwd).config);
     }
+    relocateMisplacedFiles(cwd, readConfig(cwd).config);
     applyHue(themeCssPath(config, cwd), hue);
-    await recordInstalledItems(cwd, readConfig(cwd).config, rest);
+    await recordInstalledItems(cwd, readConfig(cwd).config, resolved);
     break;
   }
   case "adopt": {
@@ -441,7 +769,9 @@ switch (command) {
     // baselines the CURRENT disk content of the named items into the lock:
     // the first `upgrade` afterwards diffs registry canon against this
     // baseline, applies changes + hue, and the lock flips to canonical
-    // hashes — subsequent upgrades are fully idempotent.
+    // hashes — subsequent upgrades are fully idempotent. Item names only:
+    // group aliases (`effects`, `effects/glass`) are an ADD-time
+    // convenience and never expand here (see resolveAddNames).
     const names = rest.filter((a) => !a.startsWith("--"));
     if (names.length === 0) {
       fail("adopt needs item names (e.g. `adopt toc jixoai-theme`) — items whose files live at their components.json targets");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jixoai-ui",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Official jixoai design-language CLI: initializes the @jixoai shadcn registry namespace, manages the jixoai extension fields in components.json, applies the per-project brand hue, and performs locked idempotent upgrades.",
   "license": "MIT",
   "type": "module",
@@ -29,4 +29,4 @@
     "url": "https://github.com/jixoai/ui",
     "directory": "cli"
   }
-}
+}