jixoai-ui 0.1.2 → 0.2.0

package/README.md

@@ -16,9 +16,50 @@ 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 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
 ```
 
 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; 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:
+
+```bash
+npx jixoai-ui upgrade && npm run build && npm test
+```

package/bin/jixoai-ui.mjs

@@ -3,7 +3,7 @@
  * jixoai-ui — the official jixoai design-language CLI (bin/jixoai-ui.mjs).
  *
  * Orthogonal intents (2026-08-20): components.json extension management;
- * brand-hue application; registry add delegation.
+ * brand-hue application; registry add delegation; locked idempotent upgrades.
  *
  * Config contract (Owner decision, 2026-08-20): the CLI SHARES shadcn's
  * components.json and extends it with a non-conflicting `jixoai` object:
@@ -16,18 +16,34 @@
  *
  * The registry URL points at the official Pages-hosted registry; hue lives
  * in ONE config field and is written into the installed jixoai.css
- * (--brand-hue) on every init/add/hue run.
+ * (--brand-hue) on every init/add/hue/upgrade run.
+ *
+ * Install manifest (Owner decision, 2026-08-20): successful init/add runs
+ * record every installed item in `jixoai-ui.lock` (next to components.json):
+ *
+ *   { "items": { "toc": { "files": { "src/lib/ui/toc.svelte": "<sha256>" } } } }
+ *
+ * Keys are install paths resolved through components.json aliases; hashes
+ * cover CANONICAL registry content (pre-hue, pre-task). `upgrade` fetches
+ * each locked item from registries["@jixoai"], writes only files whose
+ * 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.
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import process from "node:process";
 
+import { upgradeTasks } from "./upgrade-tasks.mjs";
+
 const REGISTRY_URL = "https://ui.jixoai.com/r/{name}.json";
 const NAMESPACE = "@jixoai";
 const THEME_ITEM = "jixoai-theme";
 const DEFAULT_HUE = 0;
+const LOCK_NAME = "jixoai-ui.lock";
 
 const USAGE = `jixoai-ui — the jixoai design language CLI
 
@@ -36,9 +52,15 @@ Commands:
                                      jixoai config block, install the theme,
                                      and apply the brand hue
   jixoai-ui hue <degrees>            set the project brand hue (config + css)
+  jixoai-ui adopt <item...>          baseline hand-installed items into the
+                                     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
+  jixoai-ui upgrade                  refresh every locked item to the latest
+                                     registry content, re-apply the brand
+                                     hue, and run the idempotent upgrade
+                                     tasks (repeat runs perform zero writes)
   jixoai-ui config                   print the resolved jixoai config
 
 The CLI extends shadcn's components.json — run \`npx shadcn init\` first in
@@ -128,6 +150,257 @@ function hueFromArgs(args, fallback = DEFAULT_HUE) {
   return Math.round(value);
 }
 
+/* ── install manifest (jixoai-ui.lock) + shared install/upgrade core ── */
+
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function toPosix(path) {
+  return path.split("\\").join("/");
+}
+
+function registryUrlFor(config) {
+  const url = config.registries?.[NAMESPACE] ?? REGISTRY_URL;
+  if (!url.includes("{name}")) {
+    fail(`the ${NAMESPACE} registry url must contain a {name} template (got \`${url}\`)`);
+  }
+  return url;
+}
+
+async function fetchText(url) {
+  // file:// registries are read from disk (local/offline development);
+  // everything else goes through global fetch.
+  if (url.startsWith("file:")) {
+    return readFileSync(new URL(url), "utf8");
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return response.text();
+}
+
+async function fetchRegistryItem(registryUrl, name) {
+  const url = registryUrl.replace("{name}", name);
+  let raw;
+  try {
+    raw = await fetchText(url);
+  } catch (cause) {
+    throw new Error(`cannot fetch registry item \`${name}\` from ${url}: ${cause.message}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new Error(`registry item \`${name}\` (${url}) is not valid JSON`);
+  }
+  if (!Array.isArray(json.files)) {
+    throw new Error(`registry item \`${name}\` (${url}) has no files array`);
+  }
+  return json;
+}
+
+function assertRegistryFiles(name, files) {
+  for (const file of files) {
+    if (typeof file.target !== "string" || typeof file.content !== "string") {
+      throw new Error(`registry item \`${name}\` has a file without string target/content`);
+    }
+  }
+}
+
+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.
+  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(cwd, target);
+}
+
+function lockInstallKey(target, config, cwd) {
+  return toPosix(relative(cwd, resolveInstallPath(target, config, cwd)));
+}
+
+function readLock(cwd, { required }) {
+  const path = join(cwd, LOCK_NAME);
+  if (!existsSync(path)) {
+    if (required) {
+      fail(
+        `${LOCK_NAME} not found — nothing to upgrade. Install components first: \`npx jixoai-ui add <item>\``,
+      );
+    }
+    return { path, lock: { items: {} }, existed: false };
+  }
+  let lock;
+  try {
+    lock = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    fail(`${LOCK_NAME} is not valid JSON: ${cause.message}`);
+  }
+  if (
+    typeof lock !== "object" || lock === null ||
+    typeof lock.items !== "object" || lock.items === null
+  ) {
+    fail(
+      `${LOCK_NAME} must contain an \`items\` map ({ items: { [name]: { files: { [path]: sha256 } } } })`,
+    );
+  }
+  return { path, lock, existed: true };
+}
+
+function writeLock(path, lock) {
+  writeFileSync(path, JSON.stringify(lock, null, 2) + "\n");
+}
+
+/**
+ * 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.
+ */
+async function recordInstalledItems(cwd, config, names) {
+  const registryUrl = registryUrlFor(config);
+  const { path, lock, existed } = readLock(cwd, { required: false });
+  let recorded = 0;
+  for (const name of names) {
+    try {
+      const item = await fetchRegistryItem(registryUrl, name);
+      assertRegistryFiles(name, item.files);
+      const files = {};
+      for (const file of item.files) {
+        files[lockInstallKey(file.target, config, cwd)] = sha256(file.content);
+      }
+      lock.items[name] = { ...(lock.items[name] ?? {}), files };
+      recorded++;
+      console.log(`jixoai-ui: locked ${name} (${Object.keys(files).length} file(s)) → ${path}`);
+    } catch (cause) {
+      console.warn(
+        `jixoai-ui: ${cause.message} — ${name} not recorded in ${LOCK_NAME}; \`upgrade\` will skip it`,
+      );
+    }
+  }
+  if (recorded > 0 || existed) {
+    writeLock(path, lock);
+  }
+}
+
+/* ── upgrade ── */
+
+function appCssCandidates(cwd, config, lock) {
+  // site-scope files upgrade tasks may inspect: the app-level css pointed
+  // at by components.json (tailwind.css) plus conventional locations,
+  // minus anything already covered by the lock.
+  const locked = new Set();
+  for (const item of Object.values(lock.items)) {
+    for (const key of Object.keys(item.files ?? {})) locked.add(key);
+  }
+  const candidates = new Set();
+  const tailwindCss = config.tailwind?.css;
+  if (typeof tailwindCss === "string" && tailwindCss) candidates.add(toPosix(tailwindCss));
+  for (const fallback of ["src/app.css", "app.css", "src/app.postcss", "src/styles/globals.css"]) {
+    candidates.add(fallback);
+  }
+  return [...candidates].filter((key) => !locked.has(key) && existsSync(resolve(cwd, key)));
+}
+
+function taskContext(cwd, item, key) {
+  const filePath = resolve(cwd, key);
+  return {
+    cwd,
+    item, // registry item name, or null for site-scope entries
+    path: key,
+    filePath,
+    get content() {
+      return readFileSync(filePath, "utf8");
+    },
+    read: () => readFileSync(filePath, "utf8"),
+    write: (next) => writeFileSync(filePath, next),
+    log: (message) => console.log(`jixoai-ui: ${message}`),
+    warn: (message) => console.warn(`jixoai-ui: ${message}`),
+  };
+}
+
+function runUpgradeTasks(cwd, config, lock) {
+  const contexts = [];
+  for (const [name, item] of Object.entries(lock.items)) {
+    for (const key of Object.keys(item.files ?? {})) {
+      if (existsSync(resolve(cwd, key))) contexts.push(taskContext(cwd, name, key));
+    }
+  }
+  for (const key of appCssCandidates(cwd, config, lock)) {
+    contexts.push(taskContext(cwd, null, key));
+  }
+  let ran = 0;
+  let skipped = 0;
+  for (const task of upgradeTasks) {
+    let taskRan = false;
+    for (const ctx of contexts) {
+      if (task.item && task.item !== ctx.item) continue;
+      if (!task.applies(ctx.read(), ctx)) continue;
+      task.run(ctx);
+      taskRan = true;
+    }
+    if (taskRan) ran++;
+    else skipped++;
+  }
+  return { ran, skipped };
+}
+
+async function runUpgrade(cwd, config) {
+  const registryUrl = registryUrlFor(config);
+  const { path: lockPath, lock } = readLock(cwd, { required: true });
+  const names = Object.keys(lock.items);
+  if (names.length === 0) {
+    fail(`${LOCK_NAME} records no items — install one first: \`npx jixoai-ui add <item>\``);
+  }
+
+  let updated = 0;
+  let unchanged = 0;
+  for (const name of names) {
+    let item;
+    try {
+      item = await fetchRegistryItem(registryUrl, name);
+    } catch (cause) {
+      fail(`upgrade aborted while fetching \`${name}\`: ${cause.message}`);
+    }
+    assertRegistryFiles(name, item.files);
+    const previous = lock.items[name]?.files ?? {};
+    const files = {};
+    for (const file of item.files) {
+      const key = lockInstallKey(file.target, config, cwd);
+      const hash = sha256(file.content);
+      files[key] = hash;
+      if (previous[key] === hash && existsSync(resolve(cwd, key))) {
+        unchanged++; // registry content identical to the locked install
+        continue;
+      }
+      const filePath = resolve(cwd, key);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, file.content);
+      updated++;
+      console.log(`jixoai-ui: updated ${name} → ${key}`);
+    }
+    lock.items[name] = { files };
+    writeLock(lockPath, lock); // persist per item so an abort keeps progress
+  }
+
+  applyHue(themeCssPath(config, cwd), config.jixoai?.brandHue ?? DEFAULT_HUE);
+
+  const tasks = runUpgradeTasks(cwd, config, lock);
+
+  writeLock(lockPath, lock);
+  console.log(
+    `jixoai-ui: upgrade complete — updated ${updated}, unchanged ${unchanged}, ` +
+      `tasks ran ${tasks.ran}, skipped ${tasks.skipped}`,
+  );
+  console.log(`jixoai-ui: ${LOCK_NAME} updated → ${lockPath}`);
+}
+
 const [command, ...rest] = process.argv.slice(2);
 const cwd = process.cwd();
 
@@ -141,6 +414,7 @@ switch (command) {
     console.log(`jixoai-ui: ${NAMESPACE} namespace + jixoai config written → ${path}`);
     shadcn(["add", `${NAMESPACE}/${THEME_ITEM}`], cwd, path, config);
     applyHue(themeCssPath(config, cwd), hue);
+    await recordInstalledItems(cwd, readConfig(cwd).config, [THEME_ITEM]);
     break;
   }
   case "hue": {
@@ -159,6 +433,51 @@ switch (command) {
       shadcn(["add", `${NAMESPACE}/${item}`], cwd, path, readConfig(cwd).config);
     }
     applyHue(themeCssPath(config, cwd), hue);
+    await recordInstalledItems(cwd, readConfig(cwd).config, rest);
+    break;
+  }
+  case "adopt": {
+    // Hand-installed sites (same-source copies) have no lock yet. adopt
+    // 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.
+    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");
+    }
+    const { config } = readConfig(cwd);
+    const { path, lock } = readLock(cwd, { required: false });
+    let recorded = 0;
+    for (const name of names) {
+      const item = await fetchRegistryItem(registryUrlFor(config), name);
+      assertRegistryFiles(name, item.files);
+      const files = {};
+      const missing = [];
+      for (const file of item.files) {
+        const abs = resolveInstallPath(file.target, config, cwd);
+        if (!existsSync(abs)) { missing.push(file.target); continue; }
+        files[lockInstallKey(file.target, config, cwd)] = sha256(readFileSync(abs, "utf8"));
+      }
+      if (missing.length === item.files.length) {
+        console.warn(`jixoai-ui: no files of ${name} found at their targets — skipped`);
+        continue;
+      }
+      if (missing.length > 0) {
+        console.warn(`jixoai-ui: ${name} partially present (missing ${missing.join(", ")}) — locked the rest; partial files will restore on next upgrade`);
+      }
+      lock.items[name] = { files };
+      recorded++;
+      console.log(`jixoai-ui: adopted ${name} (${Object.keys(files).length} file(s)) → ${path}`);
+    }
+    if (recorded === 0) fail("nothing adopted");
+    writeLock(path, lock);
+    console.log("jixoai-ui: baseline recorded — run `jixoai-ui upgrade` to sync to registry canon");
+    break;
+  }
+  case "upgrade": {
+    const { config } = readConfig(cwd);
+    await runUpgrade(cwd, config);
     break;
   }
   case "config": {

package/bin/upgrade-tasks.mjs

@@ -0,0 +1,69 @@
+/**
+ * jixoai-ui upgrade tasks (bin/upgrade-tasks.mjs).
+ *
+ * Contract (Owner decision, 2026-08-20): every task is IDEMPOTENT —
+ * `applies(content, ctx)` returns true only while the legacy pattern still
+ * exists, and `run(ctx)` rewrites exactly that pattern. Re-running
+ * `jixoai-ui upgrade` therefore converges to zero writes.
+ *
+ * Task shape: { name, item?, applies(content, ctx) → boolean, run(ctx) }.
+ * `item` (optional) scopes the task to one registry item; without it the
+ * task sees every locked file plus the site-scope candidates (app-level
+ * css). `ctx` exposes { cwd, item, path, filePath, content (getter),
+ * read(), write(next), log(msg), warn(msg) }.
+ */
+export const upgradeTasks = [
+  {
+    name: "legacy-import-paths",
+    // pre-0.2.0 toc installs imported the engine/css via bare @lib or
+    // relative specifiers; the components now use SvelteKit $lib aliases.
+    applies(content) {
+      return content.includes("@lib/toc-engine") || content.includes("../lib/toc.css");
+    },
+    run(ctx) {
+      const next = ctx
+        .read()
+        .replaceAll("@lib/toc-engine", "$lib/toc-engine")
+        .replaceAll("../lib/toc.css", "$lib/toc.css");
+      ctx.write(next);
+      ctx.log(`task legacy-import-paths: rewrote toc imports to $lib aliases → ${ctx.path}`);
+    },
+  },
+  {
+    name: "spine-axis",
+    item: "toc",
+    // the desktop Rule Tracker spine sits ON the node axis (left: 0), not
+    // 2px off it. Anchored to declaration position (^ + indentation only)
+    // so prose comments ("spine sits left: 2px …") and other declarations
+    // (border-left: 2px) are never touched.
+    applies(content, ctx) {
+      return ctx.path.endsWith(".css") && /^[ \t]*left:[ \t]*2px/m.test(content);
+    },
+    run(ctx) {
+      const next = ctx.read().replace(
+        /^([ \t]*)left:[ \t]*2px/gm,
+        (_match, indent) => `${indent}left: 0px`,
+      );
+      ctx.write(next);
+      ctx.log(`task spine-axis: moved the spine onto the node axis (left: 2px → 0px) → ${ctx.path}`);
+    },
+  },
+  {
+    name: "scroll-margin-cleanup",
+    // DIAGNOSTIC ONLY — never edits files. scroll-margin-top on the
+    // anchors and scroll-padding-top on the scroll container STACK (see
+    // the "named line law" in toc.css), so a site carrying both doubles
+    // its anchor landings past the toc line. Which of the two owns the
+    // offset is an app-level layout decision jixoai-ui must not make for
+    // you, so this task only warns — and because it fixes nothing, it
+    // re-reports on every run until the owner removes the redundancy.
+    applies(content) {
+      return content.includes("scroll-margin-top") && content.includes("scroll-padding-top");
+    },
+    run(ctx) {
+      ctx.warn(
+        `${ctx.path} declares both scroll-margin-top and scroll-padding-top — the offsets stack and anchor jumps land past the toc line. Keep scroll-padding-top on the scroll container (the jixoai toc consumes --jx-toc-line that way) and remove the target-side scroll-margin-top. jixoai-ui never edits app-level css automatically.`,
+      );
+    },
+  },
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jixoai-ui",
-  "version": "0.1.2",
-  "description": "Official jixoai design-language CLI: initializes the @jixoai shadcn registry namespace, manages the jixoai extension fields in components.json, and applies the per-project brand hue.",
+  "version": "0.2.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",
   "bin": {