basalt-ui 1.23.0 → 1.24.0

package/dist/cli/index.js

@@ -89,7 +89,7 @@ function readBasaltConfig(cwd) {
     return {};
   }
 }
-const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/;
+const SCANNABLE_EXT = /\.(?:tsx?|jsx|astro|vue|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
   let entries;
   try {
@@ -170,6 +170,18 @@ function descendantProjects(cwd, depth = 2) {
   }
   return out;
 }
+function ascendantProject(cwd) {
+  const repoRoot = findRepoRoot(cwd);
+  if (repoRoot === cwd) return null;
+  let current = dirname(cwd);
+  for (; ; ) {
+    if (hasBasaltProject(current)) return current;
+    if (current === repoRoot) return null;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
 function resolveProjectDir(cwd) {
   const override = process.env["BASALT_CWD"];
   if (override !== void 0 && override.length > 0) {
@@ -183,6 +195,8 @@ function resolveProjectDir(cwd) {
     return { dir: candidates[0], relocatedFrom: cwd, ambiguous: null };
   }
   if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates };
+  const above = ascendantProject(cwd);
+  if (above !== null) return { dir: above, relocatedFrom: cwd, ambiguous: null };
   return { dir: cwd, relocatedFrom: null, ambiguous: null };
 }
 function declaredProfile(cfg, flags) {
@@ -617,9 +631,13 @@ function readFrameworkVersion(pkgRoot) {
     return "0.0.0";
   }
 }
+function basaltBinCommand(install, cwd) {
+  if (install.dir === null) return "bunx basalt-ui";
+  const binDir = resolve(install.dir, "..", ".bin");
+  return `${relativePosix(cwd, binDir).replace(/^\.\//, "")}/basalt-ui`;
+}
 function buildTemplateVars(pkgRoot, cwd, cfg) {
   const install = findBasaltInstall(cwd);
-  const binDir = install.dir === null ? null : resolve(install.dir, "..", ".bin");
   return {
     APP_NAME: readPackageName(cwd),
     BASALT_VERSION: readFrameworkVersion(pkgRoot),
@@ -628,7 +646,7 @@ function buildTemplateVars(pkgRoot, cwd, cfg) {
     ROOTS_GLOBS: resolveRoots(cfg).map(toRootGlob).join(" "),
     OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, "configs/oxlint.json"),
     LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, "configs/lefthook.yml"),
-    BASALT_BIN: binDir === null ? "bunx basalt-ui" : `${relativePosix(cwd, binDir).replace(/^\.\//, "")}/basalt-ui`
+    BASALT_BIN: basaltBinCommand(install, cwd)
   };
 }
 function fillTemplate(tpl, vars) {
@@ -1268,7 +1286,7 @@ Theme guard hook: add to .claude/settings.json \u2192 hooks.PreToolUse to catch
     "PreToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",
-        "hooks": [{ "type": "command", "command": "bunx basalt-ui guard-hook" }]
+        "hooks": [{ "type": "command", "command": "${ctx.vars.BASALT_BIN} guard-hook" }]
       }
     ]
   }`
@@ -1299,6 +1317,9 @@ function readOxlintPresetPlugins(pkgRoot) {
     return [];
   }
 }
+function parentInstallAdvice(cwd, parent, verb) {
+  return `This repo's install is at ${relativePosix(cwd, parent)} (${parent}) \u2014 run ${verb} there, or set BASALT_CWD to it.`;
+}
 function findManifestAbove(dir) {
   let current = resolve(dir, "..");
   for (; ; ) {
@@ -1337,7 +1358,7 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     const elsewhere = findManifestAbove(cwd);
     const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length;
     console.error(
-      `\u2716 basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} \u2014 refusing to scaffold. \`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s decision, and continuing here would write ${wouldWrite} managed file(s) into this directory.` + (elsewhere === null ? " No manifest exists at any ancestor either \u2014 run `basalt-ui init` here if this package really is meant to be a consumer." : ` This repo's install is at ${relativePosix(cwd, elsewhere)} (${elsewhere}) \u2014 run sync there, or set BASALT_CWD to it.`)
+      `\u2716 basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} \u2014 refusing to scaffold. \`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s decision, and continuing here would write ${wouldWrite} managed file(s) into this directory.` + (elsewhere === null ? " No manifest exists at any ancestor either \u2014 run `basalt-ui init` here if this package really is meant to be a consumer." : ` ${parentInstallAdvice(cwd, elsewhere, "sync")}`)
     );
     return 1;
   }
@@ -1706,6 +1727,7 @@ basalt-ui doctor \u2014 ${cwd}
   }
   const manifestAbs = resolve(cwd, MANIFEST_PATH);
   const manifestExists = existsSync(manifestAbs);
+  const parentInstall = manifestExists ? null : findManifestAbove(cwd);
   const profile = inferredProfile(cwd, cfg, flags);
   if (profile === "tokens-only") {
     lines.push(
@@ -1721,6 +1743,10 @@ basalt-ui doctor \u2014 ${cwd}
     pass(`${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile`);
   } else if (manifestExists) {
     pass(`${MANIFEST_PATH} exists`);
+  } else if (parentInstall !== null) {
+    fail(
+      `${MANIFEST_PATH} missing here, but this is not an unscaffolded consumer. ${parentInstallAdvice(cwd, parentInstall, "doctor")} \`basalt-ui init\` is NOT the fix: it would scaffold a SECOND consumer beside the real one.`
+    );
   } else {
     fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
   }
@@ -1816,7 +1842,7 @@ basalt-ui doctor \u2014 ${cwd}
     const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
     if (oxlintrcRaw === null) {
       fail(
-        ".oxlintrc.json missing \u2014 the shipped oxlint preset (the basalt/* design rules) is not active. Run `basalt-ui init` to seed it."
+        ".oxlintrc.json missing \u2014 the shipped oxlint preset (the basalt/* design rules) is not active. " + (parentInstall === null ? "Run `basalt-ui init` to seed it." : `${parentInstallAdvice(cwd, parentInstall, "doctor")} The preset is seeded once, at the install \u2014 not per package.`)
       );
     } else {
       const parsed = parseJsonc(oxlintrcRaw);
@@ -1864,30 +1890,52 @@ basalt-ui doctor \u2014 ${cwd}
     );
   } else if (lefthookGate.kind === "absent") {
     warn(
-      `${lefthookGate.file}: \`lefthook dump\` resolves the merged config and NO pre-commit command runs check-theme \u2014 the theme guard is not gating commits. Either add "extends: [${lefthookCorrect}]", or add your own command running \`bunx basalt-ui check-theme\` (with \`root:\` if it must run in a subdirectory).`
+      `${lefthookGate.file}: \`lefthook dump\` resolves the merged config and NO pre-commit command runs check-theme \u2014 the theme guard is not gating commits. Either add "extends: [${lefthookCorrect}]", or add your own command running \`${basaltBinCommand(install, cwd)} check-theme\` (with \`root:\` if it must run in a subdirectory).`
     );
   } else {
     warn(
-      `${lefthookGate.file} names no basalt gate and \`lefthook dump\` could not be run here, so this check cannot tell a missing gate from one wired through an \`include:\` or a remote config it never read \u2014 treat it as advisory. If the guard really is unwired, add "extends: [${lefthookCorrect}]" or your own command running \`bunx basalt-ui check-theme\`.`
+      `${lefthookGate.file} names no basalt gate and \`lefthook dump\` could not be run here, so this check cannot tell a missing gate from one wired through an \`include:\` or a remote config it never read \u2014 treat it as advisory. If the guard really is unwired, add "extends: [${lefthookCorrect}]" or your own command running \`${basaltBinCommand(install, cwd)} check-theme\`.`
     );
   }
-  const publicDir = resolve(cwd, "public");
-  if (profile === "framework" && existsSync(publicDir)) {
-    const iconFiles = [
-      "favicon.ico",
-      "favicon.svg",
-      "favicon-96x96.png",
-      "apple-touch-icon.png",
-      "web-app-manifest-192x192.png",
-      "web-app-manifest-512x512.png"
-    ];
-    const missingIcons = iconFiles.filter((f) => !existsSync(resolve(publicDir, f)));
-    if (missingIcons.length > 0) {
-      warn(
-        `public/ is missing basaltAppPlugin icon file(s): ${missingIcons.join(", ")} \u2014 generate them (e.g. via realfavicongenerator.net) and place them at the public/ root.`
+  if (profile === "framework") {
+    const appDir = findAppPluginDir(cwd, cfg);
+    const iconsIn = appDir ?? cwd;
+    const icons = readAppIconsOption(iconsIn);
+    const here = appDir === null || appDir === cwd ? "" : `${relativePosix(cwd, appDir)}/`;
+    const publicDir = resolve(iconsIn, "public");
+    if (appDir === null && !existsSync(publicDir)) {
+      pass("app icons: no `basaltAppPlugin(` under this project and no public/ \u2014 nothing to check");
+    } else if (icons.kind === "none") {
+      pass("basaltAppPlugin is configured with no icons \u2014 nothing to check");
+    } else if (!existsSync(publicDir)) {
+      skip(
+        `app icons \u2014 ${here === "" ? "this package" : here.replace(/\/$/, "")} configures basaltAppPlugin, but there is no \`public/\` beside its vite config, so the files it references cannot be located. Use Vite's public-dir convention, or set \`icons: false\` if this app ships none.`
+      );
+    } else if (icons.kind === "explicit") {
+      const missing = icons.sources.filter(
+        (src) => !existsSync(resolve(publicDir, src.replace(/^\//, "")))
       );
+      if (missing.length > 0) {
+        warn(
+          `basaltAppPlugin declares icon(s) that are not in ${here}public/: ${missing.join(", ")} \u2014 the manifest and the head links will point at a 404. Place them, or drop them from the \`icons\` array.`
+        );
+      } else {
+        pass(
+          `${here}public/ has all ${icons.sources.length} icon file(s) basaltAppPlugin's \`icons\` option names`
+        );
+      }
     } else {
-      pass("public/ has all of basaltAppPlugin's default icon files");
+      const dir = icons.kind === "default" ? icons.dir : null;
+      const iconRoot = dir === null ? publicDir : resolve(publicDir, dir.replace(/^\//, ""));
+      const shown = dir === null ? `${here}public/` : `${here}public/${dir.replace(/^\//, "")}`;
+      const missingIcons = DEFAULT_APP_ICON_FILES.filter((f) => !existsSync(resolve(iconRoot, f)));
+      if (missingIcons.length > 0) {
+        warn(
+          `${shown} is missing basaltAppPlugin icon file(s): ${missingIcons.join(", ")} \u2014 generate them (e.g. via realfavicongenerator.net) and place them at the ${shown} root, or name the icons this app really has via the plugin's \`icons\` array.`
+        );
+      } else {
+        pass(`${shown} has all of basaltAppPlugin's default icon files`);
+      }
     }
   }
   const workspaceWalk = collectWorkspacePackages(cwd);
@@ -2008,6 +2056,93 @@ basalt-ui v${pkgVersion} \u2014 published surface
   console.log("");
   return 0;
 }
+const DEFAULT_APP_ICON_FILES = [
+  "favicon.ico",
+  "favicon.svg",
+  "favicon-96x96.png",
+  "apple-touch-icon.png",
+  "web-app-manifest-192x192.png",
+  "web-app-manifest-512x512.png"
+];
+const VITE_CONFIG_FILES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.cts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.cjs"
+];
+function findAppPluginDir(cwd, cfg) {
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = [];
+  const add = (dir) => {
+    if (seen.has(dir)) return;
+    seen.add(dir);
+    candidates.push(dir);
+  };
+  add(cwd);
+  for (const root of resolveRoots(cfg)) {
+    let current = resolve(cwd, root);
+    while (current !== cwd && !relative(cwd, current).startsWith("..")) {
+      add(current);
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  for (const dir of candidates) {
+    const configPath = VITE_CONFIG_FILES.map((f) => resolve(dir, f)).find((f) => existsSync(f));
+    if (configPath === void 0) continue;
+    if (readIfExists(configPath)?.includes("basaltAppPlugin(") === true) return dir;
+  }
+  return null;
+}
+function balancedSpan(text, open) {
+  const pairs = { "(": ")", "{": "}", "[": "]" };
+  const closer = pairs[text[open]];
+  if (closer === void 0) return null;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === text[open]) depth++;
+    else if (ch === closer) {
+      depth--;
+      if (depth === 0) return text.slice(open, i + 1);
+    }
+  }
+  return null;
+}
+function readAppIconsOption(cwd) {
+  const configPath = VITE_CONFIG_FILES.map((f) => resolve(cwd, f)).find((f) => existsSync(f));
+  if (configPath === void 0) return { kind: "unknown" };
+  const text = readIfExists(configPath);
+  if (text === null) return { kind: "unknown" };
+  const call = text.indexOf("basaltAppPlugin(");
+  if (call === -1) return { kind: "unknown" };
+  const args = balancedSpan(text, call + "basaltAppPlugin".length);
+  if (args === null) return { kind: "unknown" };
+  const key = args.search(/\bicons\s*:/);
+  if (key === -1) return { kind: "default", dir: null };
+  const valueStart = args.indexOf(":", key) + 1;
+  const rest = args.slice(valueStart).trimStart();
+  if (rest.startsWith("false")) return { kind: "none" };
+  const offset = args.length - rest.length;
+  if (rest.startsWith("[")) {
+    const list = balancedSpan(args, offset);
+    if (list === null) return { kind: "unknown" };
+    const sources = [...list.matchAll(/\bsrc\s*:\s*['"`]([^'"`]+)['"`]/g)].map(
+      (m) => m[1]
+    );
+    return sources.length === 0 ? { kind: "none" } : { kind: "explicit", sources };
+  }
+  if (rest.startsWith("{")) {
+    const obj = balancedSpan(args, offset);
+    if (obj === null) return { kind: "unknown" };
+    const dir = /\bdir\s*:\s*['"`]([^'"`]+)['"`]/.exec(obj);
+    return { kind: "default", dir: dir === null ? null : dir[1] };
+  }
+  return { kind: "unknown" };
+}
 function flagValue(flags, name) {
   const i = flags.indexOf(name);
   if (i === -1) return void 0;
@@ -2021,6 +2156,36 @@ function generatedHeader(version, command, flags) {
 /* basalt-ui ${version} \u2014 \`basalt-ui ${invocation}\` */
 `;
 }
+const PROVENANCE_VERSION = /^(\/\* basalt-ui )(\d+\.\d+\.\d+\S*)( — `basalt-ui (?:tokens:css|fonts:css)[^`]*` \*\/)$/;
+function provenanceVersion(css) {
+  const match = PROVENANCE_VERSION.exec(css.split("\n")[1] ?? "");
+  return match === null ? null : match[2];
+}
+function withoutProvenanceVersion(css) {
+  const lines = css.split("\n");
+  const line = lines[1];
+  if (line === void 0) return css;
+  const match = PROVENANCE_VERSION.exec(line);
+  if (match === null) return css;
+  lines[1] = `${match[1]}<version>${match[3]}`;
+  return lines.join("\n");
+}
+function versionTriple(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function describeVersionSkew(onDisk, current) {
+  const a = versionTriple(onDisk);
+  const b = versionTriple(current);
+  if (a === null || b === null) return "a different";
+  for (let i = 0; i < 3; i++) {
+    const left = a[i];
+    const right = b[i];
+    if (left < right) return "an older";
+    if (left > right) return "a newer";
+  }
+  return "a different";
+}
 function normalizeColorFunctions(css) {
   return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
     const parts = args.split(",").map((part) => normalizeCssNumber(part.trim()));
@@ -2055,12 +2220,27 @@ function emitGeneratedCss(content, flags, cwd, command) {
       );
       return 1;
     }
-    if (onDisk === content) {
-      console.log(`\u2713 ${command} --check: ${shown} is up to date.`);
+    if (withoutProvenanceVersion(onDisk) === withoutProvenanceVersion(content)) {
+      const diskVersion = provenanceVersion(onDisk);
+      const currentVersion = provenanceVersion(content);
+      const skew = diskVersion !== null && currentVersion !== null && diskVersion !== currentVersion ? ` (Its provenance line names basalt-ui ${diskVersion}, ${describeVersionSkew(diskVersion, currentVersion)} release than the ${currentVersion} that just ran \u2014 only that version token is excluded from the comparison. Re-run without --check whenever you want it refreshed.)` : "";
+      console.log(`\u2713 ${command} --check: ${shown} is up to date.${skew}`);
       return 0;
     }
+    const diskLines = onDisk.split("\n");
+    const wantLines = content.split("\n");
+    const provenanceOnly = diskLines.length === wantLines.length && diskLines.every((line, i) => i === 1 || line === wantLines[i]) && diskLines[1] !== wantLines[1];
+    if (provenanceOnly) {
+      console.error(
+        `\u2716 ${command} --check: ${shown}'s \`@generated\` provenance line does not match the command that produced this content \u2014 the token values agree, line 2 does not.
+  on disk: ${diskLines[1]}
+  emitted: ${wantLines[1]}
+Line 1 tells the reader to regenerate with line 2, so line 2 is gated: run the emitted invocation without --check and commit the result, or change the flags this check runs with to the ones the file was really built from. Only the version token is exempt.`
+      );
+      return 1;
+    }
     console.error(
-      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${onDisk.split("\n").length} lines, emitted ${content.split("\n").length}) \u2014 re-run the same command without --check and commit the result.`
+      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${diskLines.length} lines, emitted ${wantLines.length}) \u2014 re-run the same command without --check and commit the result. Only the \`@generated\` provenance line's VERSION token is excluded from this comparison, so a release alone never trips it \u2014 but its flags do.`
     );
     return 1;
   }
@@ -2241,13 +2421,71 @@ async function guardHook(cwd = process.cwd()) {
   }
   return 0;
 }
-const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] |\n                  sync [--force] [--check] [--tokens-only|--framework] |\n                  check-theme [--audit-allows] | check-coverage | info [--json] |\n                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\ncheck-theme [--tokens-only|--framework] [--audit-allows]\n  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n  `basalt.exemptRules` entry, with what each one still suppresses \u2014 proved by re-running the\n  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\nsync [--force] [--check] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n\ncheck-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\nrelocate to the single package below the cwd carrying a basalt config when invoked from a repo\nroot that has none \u2014 several carrying one is ambiguous and exits 1 in ALL THREE.\n--tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.";
+const COMMAND_FLAGS = {
+  init: ["--with-router", "--with-query", "--merge-lint"],
+  sync: ["--force", "--check", "--tokens-only", "--framework"],
+  "check-theme": ["--audit-allows", "--tokens-only", "--framework"],
+  "check-coverage": [],
+  info: ["--json"],
+  doctor: ["--tokens-only", "--framework"],
+  "guard-hook": [],
+  "tokens:css": [
+    "--out",
+    "--check",
+    "--selector-attribute",
+    "--selector-class",
+    "--light-class",
+    "--dark-value",
+    "--light-value",
+    "--default-scheme",
+    "--media-fallback",
+    "--only",
+    "--no-legacy-aliases"
+  ],
+  "fonts:css": ["--out", "--check"]
+};
+const VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--out",
+  "--selector-attribute",
+  "--selector-class",
+  "--light-class",
+  "--dark-value",
+  "--light-value",
+  "--default-scheme",
+  "--only"
+]);
+function unknownFlag(cmd, flags) {
+  const allowed = COMMAND_FLAGS[cmd];
+  if (allowed === void 0) return null;
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (!flag.startsWith("-")) continue;
+    if (!allowed.includes(flag)) return flag;
+    if (VALUE_FLAGS.has(flag)) i++;
+  }
+  return null;
+}
+const USAGE = "Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n                  sync [--force] [--check] [--tokens-only|--framework] |\n                  check-theme [--audit-allows] | check-coverage | info [--json] |\n                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\ncheck-theme [--tokens-only|--framework] [--audit-allows]\n  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n  `basalt.exemptRules` entry, with what each one still suppresses \u2014 proved by re-running the\n  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\nsync [--force] [--check] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n\ncheck-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\nrelocate to the single package below the cwd carrying a basalt config when invoked from a repo\nroot that has none \u2014 several carrying one is ambiguous and exits 1 in ALL THREE.\n--tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.\n--version / -v prints the resolved package version and exits 0 \u2014 the one command that proves\nWHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\nunrecognized flag exits 1 and names what it did not understand; neither is ever ignored.";
 function run(argv, cwd = process.cwd()) {
   const [cmd, ...flags] = argv;
   if (cmd === "help" || cmd === "--help" || cmd === "-h" || flags.includes("--help") || flags.includes("-h")) {
     console.log(USAGE);
     return 0;
   }
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    console.log(readFrameworkVersion(packageRoot()));
+    return 0;
+  }
+  if (cmd !== void 0) {
+    const bad = unknownFlag(cmd, flags);
+    if (bad !== null) {
+      console.error(
+        `basalt-ui ${cmd}: unrecognized flag '${bad}'. Accepted: ${(COMMAND_FLAGS[cmd] ?? []).join(" ") || "(none)"} --help
+`
+      );
+      return 1;
+    }
+  }
   switch (cmd) {
     case "init":
       return init(cwd, {
@@ -2275,6 +2513,10 @@ function run(argv, cwd = process.cwd()) {
     case "fonts:css":
       return fontsCss(flags, cwd);
     default:
+      console.error(
+        cmd === void 0 ? "basalt-ui: no command given.\n" : `basalt-ui: unknown command '${cmd}'.
+`
+      );
       console.error(USAGE);
       return 1;
   }

package/dist/dashboard/empty-state.d.ts

@@ -4,8 +4,12 @@ export type EmptyStateProps = {
     icon?: ReactNode;
     /** Head-font title (18px, weight 550, ink). */
     title: string;
-    /** Muted 15px description, capped at ~360px so it reads as a short explanation. */
-    description: string;
+    /**
+     * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
+     * compact panel ("No data yet") should not have to invent a second sentence, and five argo
+     * features wrapped this component solely to avoid doing so.
+     */
+    description?: string;
     /** Optional call-to-action rendered below the description. */
     action?: ReactNode;
     /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */

package/dist/dashboard/empty-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAgB,GACjB,EAAE,eAAe,+BA0BjB"}
+{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAgB,GACjB,EAAE,eAAe,+BA4BjB"}

package/dist/dashboard/empty-state.js

@@ -32,7 +32,7 @@ function EmptyState({
             children: title
           }
         ),
-        /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }, children: description }),
+        description !== void 0 && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }, children: description }),
         action
       ]
     }

package/dist/dashboard/index.d.ts

@@ -2,4 +2,5 @@ export { DeltaBadge, type DeltaBadgeProps } from './delta-badge.js';
 export { StatCard, type StatCardProps, type StatCardTone } from './stat-card.js';
 export { EmptyState, type EmptyStateProps } from './empty-state.js';
 export { SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './settings-section.js';
+export { QueryState, type QueryStateProps, type QueryStateLike, type QueryStateVariant, type QueryEmptyCopy, LoadingState, type LoadingStateProps, ErrorState, type ErrorStateProps, } from './query-state.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/dashboard/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA"}

package/dist/dashboard/index.js

@@ -6,10 +6,18 @@ import {
   SettingsRow,
   DangerZone
 } from "./settings-section.js";
+import {
+  QueryState,
+  LoadingState,
+  ErrorState
+} from "./query-state.js";
 export {
   DangerZone,
   DeltaBadge,
   EmptyState,
+  ErrorState,
+  LoadingState,
+  QueryState,
   SettingsRow,
   SettingsSection,
   StatCard

package/dist/dashboard/query-state.d.ts

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+/** `'page'` = a full route body (generous padding). `'section'` = a card/panel region (compact). */
+export type QueryStateVariant = 'page' | 'section';
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
+ * hand-rolled result must be passable without a cast (3 of image-share's 10 call sites are), and
+ * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
+ * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
+ * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is
+ * that the compiler stops policing the shape — which is why {@link QueryState} asserts it at
+ * runtime.
+ */
+export type QueryStateLike<TData> = {
+    data: TData | undefined;
+    isError: boolean;
+    error: unknown;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    refetch: () => unknown;
+};
+/** Copy for the empty branch. Rendered through `EmptyState`, so it looks like every other one. */
+export type QueryEmptyCopy = {
+    title: string;
+    /** Optional — a one-word empty panel should not have to invent a sentence. */
+    description?: string;
+    /** Optional glyph slot, rendered faint. */
+    icon?: ReactNode;
+    /** Call-to-action below the copy (e.g. "Reset filters"). */
+    action?: ReactNode;
+};
+export type LoadingStateProps = {
+    variant?: QueryStateVariant;
+    /** Accessible name for the spinner. Say what is loading. */
+    label?: string;
+};
+/** A spinner on its own — `variant="page"` centres it in a generous block, `'section'` is bare. */
+export declare function LoadingState({ variant, label, }: LoadingStateProps): ReactNode;
+export type ErrorStateProps = {
+    /** Whatever was thrown — the raw Eden/fetch envelope is fine, it gets decoded. */
+    error: unknown;
+    /** Alert heading. Say what failed, e.g. `Could not load images`. */
+    title?: string;
+    /** Shown only when the server body carries no readable message. */
+    fallback?: string;
+    onRetry?: () => void;
+    /** Disables/spins the retry button while a refetch is in flight. */
+    retrying?: boolean;
+    variant?: QueryStateVariant;
+    /** Extra controls beside Retry (e.g. a "Back to shares" link). */
+    action?: ReactNode;
+};
+/**
+ * The error branch: the REAL server message (via `toErrorMessage`) plus a retry. Usable on its own,
+ * outside a query — an auth gate or a boundary fallback renders it directly.
+ */
+export declare function ErrorState({ error, title, fallback, onRetry, retrying, variant, action, }: ErrorStateProps): ReactNode;
+export type QueryStateProps<TData> = {
+    query: QueryStateLike<TData>;
+    /** A render function gets `data` narrowed to non-undefined; a plain node also works. */
+    children: ReactNode | ((data: TData) => ReactNode);
+    /** Omit to render nothing when the result is empty. */
+    empty?: QueryEmptyCopy;
+    /** Override the default `[]` / `{ data: [] }` emptiness test — `() => false` disables it. */
+    isEmpty?: (data: TData) => boolean;
+    /** Alert heading on the error branch — say what failed. */
+    errorTitle?: string;
+    /** Shown only when the server body carries no readable message. */
+    errorFallback?: string;
+    /** Extra controls beside Retry on the error branch. */
+    errorAction?: ReactNode;
+    variant?: QueryStateVariant;
+    /** Replace the default spinner (e.g. with a skeleton grid). */
+    loading?: ReactNode;
+};
+/**
+ * Renders loading / error-with-retry / empty / children for a query result, in that order.
+ * Branch precedence is the whole point, and it is deliberate:
+ *
+ *  - error AND no cached data → the full error state (the page cannot render)
+ *  - error WITH cached data   → children, plus a compact "showing cached data" banner on top
+ *    (a background refetch failing must not blank a page that already works)
+ *  - no data, fetch idle      → empty (this is an `enabled: false` query, not a pending one)
+ *  - no data, fetching        → `loading` (or the default spinner)
+ *
+ * @example
+ * <QueryState
+ *   query={q}
+ *   errorTitle="Could not load images"
+ *   empty={{ title: 'No images match', description: 'Widen the capture dates.' }}
+ * >
+ *   {(data) => <ImageGrid images={data.rows} />}
+ * </QueryState>
+ */
+export declare function QueryState<TData>({ query, children, empty, isEmpty, errorTitle, errorFallback, errorAction, variant, loading, }: QueryStateProps<TData>): ReactNode;
+//# sourceMappingURL=query-state.d.ts.map

package/dist/dashboard/query-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/query-state.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,oGAAoG;AACpG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAA;AAElD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAID,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,EAC3B,OAAgB,EAChB,KAAiB,GAClB,EAAE,iBAAiB,GAAG,SAAS,CAI/B;AAID,MAAM,MAAM,eAAe,GAAG;IAC5B,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAA8B,EAC9B,QAAgC,EAChC,OAAO,EACP,QAAgB,EAChB,OAAgB,EAChB,MAAM,GACP,EAAE,eAAe,GAAG,SAAS,CAoB7B;AAyCD,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IACnC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IAClD,uDAAuD;IACvD,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,EAChC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,OAAO,EACP,UAA6B,EAC7B,aAAqC,EACrC,WAAW,EACX,OAAgB,EAChB,OAAO,GACR,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,SAAS,CAiDpC"}