nxds-cli 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,1928 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command, CommanderError, Option } from "commander";
+import path11 from "path";
+
+// ../catalog/scripts/catalog-schema.ts
+import path from "path";
+import { valid, validRange } from "semver";
+import { z } from "zod";
+function relativePath(value) {
+  const normalized = path.posix.normalize(value.replaceAll("\\", "/")).replace(/\/+$/, "");
+  if ([...normalized].some((char) => char < " " || char === "\x7F") || path.posix.isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized) || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    return null;
+  }
+  return normalized;
+}
+var relativePathSchema = z.string().refine(
+  (value) => relativePath(value) === value,
+  "must be a relative path that stays inside its folder"
+);
+var versionSchema = z.string().refine((value) => valid(value) === value, "must be a release version");
+var rangeSchema = z.string().refine(
+  (value) => /^[ -~]+$/.test(value) && value === value.trim() && validRange(value) !== null,
+  "must be a semver range"
+);
+var npmNameSchema = z.string().regex(
+  /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/,
+  "must be an npm package name"
+);
+var frameworkSchema = z.enum(["react", "vue"]);
+function isFramework(value) {
+  return frameworkSchema.safeParse(value).success;
+}
+function variantsSchema(variant) {
+  return z.object({
+    react: variant.optional(),
+    vue: variant.optional()
+  });
+}
+var catalogFileSchema = z.object({
+  /** Relative to the project's nxds folder. */
+  path: relativePathSchema,
+  content: z.string()
+});
+var setupStepSchema = z.enum([
+  "add-css-import",
+  "add-head-script",
+  "wrap-root-with-provider"
+]);
+var npmPackagesSchema = z.record(npmNameSchema, rangeSchema);
+function variantWith(packages) {
+  return z.object({
+    /** Other items this one needs, installed first. */
+    items: z.array(z.string()),
+    packages,
+    files: z.array(catalogFileSchema),
+    /** Files in `files` the nxds CSS entry imports. */
+    css: z.array(relativePathSchema),
+    steps: z.array(setupStepSchema)
+  }).refine(
+    ({ css, files }) => css.every((entry) => files.some((file) => file.path === entry)),
+    { path: ["css"], message: "must name files in `files`" }
+  );
+}
+var variantSchema = variantWith(z.object({ npm: npmPackagesSchema }));
+var setupVariantSchema = variantWith(
+  z.object({
+    npm: npmPackagesSchema,
+    /** The Tailwind range `init` installs, with the app's build plugin, when the app has no Tailwind. */
+    tailwind: rangeSchema
+  })
+);
+var itemInfo = {
+  name: z.string(),
+  title: z.string(),
+  description: z.string(),
+  docs: z.string()
+};
+var setupItemSchema = z.object({
+  ...itemInfo,
+  kind: z.literal("setup"),
+  variants: variantsSchema(setupVariantSchema)
+});
+var catalogItemSchema = z.discriminatedUnion("kind", [
+  setupItemSchema,
+  z.object({
+    ...itemInfo,
+    kind: z.enum(["component", "block"]),
+    variants: variantsSchema(variantSchema)
+  })
+]);
+var CATALOG_SCHEMA = 1;
+var catalogSchema = z.object({
+  schema: z.literal(CATALOG_SCHEMA),
+  /** The `@nxds/react` version this catalog was built from. */
+  version: versionSchema,
+  /** The frameworks the CLI installs. The docs copy also carries variants for others; a release catalog drops them. Names this version doesn't know are dropped too. */
+  frameworks: z.array(z.string()).transform((frameworks) => frameworks.filter(isFramework)),
+  items: z.array(catalogItemSchema)
+});
+function lines(issues, prefix) {
+  return issues.flatMap((issue) => {
+    const at = [...prefix, ...issue.path];
+    if (issue.code === "invalid_key") return lines(issue.issues, at);
+    return [
+      `${at.length > 0 ? at.map(String).join(".") : "(root)"}: ${issue.message}`
+    ];
+  });
+}
+function issueLines(error) {
+  return lines(error.issues, []);
+}
+
+// src/catalog.ts
+import { existsSync } from "fs";
+import path2 from "path";
+import { EnvHttpProxyAgent, fetch } from "undici";
+
+// src/cli-command.ts
+var CLI_COMMAND = "npx nxds-cli@latest";
+
+// src/errors.ts
+import { readFileSync } from "fs";
+var EXIT_CODES = {
+  ok: 0,
+  /** A network or registry failure, an invalid file, or a bug in nxds. */
+  error: 1,
+  /** A bad flag, unknown command or item, or a missing argument. */
+  usage: 2,
+  /** The command ran, and left something for the person to do: conflicts, kept files, manual steps or failed checks. */
+  attention: 3
+};
+var CliError = class extends Error {
+  exitCode = EXIT_CODES.error;
+};
+var UsageError = class extends CliError {
+  exitCode = EXIT_CODES.usage;
+};
+function readJson(file) {
+  const text = readFileSync(file, "utf8");
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new CliError(
+      `${file} is not valid JSON (${error.message}). Fix it, then run the command again.`
+    );
+  }
+}
+
+// src/catalog.ts
+var SETUP = "setup";
+var DEFAULT_REGISTRY = "https://nxds.dev/r";
+var FETCH_TIMEOUT_MS = 3e4;
+var dispatcher = new EnvHttpProxyAgent();
+function isUrl(registry) {
+  return /^https?:\/\//.test(registry);
+}
+function resolveRegistry(option) {
+  if (!option) return DEFAULT_REGISTRY;
+  return isUrl(option) ? option.replace(/\/+$/, "") : path2.resolve(option);
+}
+function timeoutError(url, error) {
+  if (!(error instanceof Error) || error.name !== "TimeoutError") return null;
+  return new CliError(
+    `${url} did not answer within ${FETCH_TIMEOUT_MS / 1e3}s. Check your connection, then run the command again.`
+  );
+}
+async function fetchJson(url) {
+  let response;
+  try {
+    response = await fetch(url, {
+      dispatcher,
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    const timeout = timeoutError(url, error);
+    if (timeout) throw timeout;
+    const { message, cause } = error;
+    const reason = cause instanceof Error ? cause.message : message;
+    throw new CliError(
+      `Could not reach ${url} (${reason}). Check your connection, or set HTTPS_PROXY if you are behind a proxy, then run the command again.`
+    );
+  }
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new CliError(
+      `${url} answered ${response.status}. Run the command again later.`
+    );
+  }
+  try {
+    return await response.json();
+  } catch (error) {
+    throw timeoutError(url, error) ?? new CliError(
+      `${url} is not valid JSON (${error.message}). Run the command again later.`
+    );
+  }
+}
+function registryLocation(registry, file) {
+  return isUrl(registry) ? `${registry}/${file}` : path2.join(registry, file);
+}
+async function readRegistryFile(registry, file) {
+  const location = registryLocation(registry, file);
+  if (isUrl(registry)) return fetchJson(location);
+  return existsSync(location) ? readJson(location) : null;
+}
+function isNewerSchema(value) {
+  return typeof value === "object" && value !== null && "schema" in value && typeof value.schema === "number" && value.schema > CATALOG_SCHEMA;
+}
+async function fetchRelease(registry, version) {
+  const file = `${version}.json`;
+  const value = await readRegistryFile(registry, file);
+  if (value === null) return null;
+  if (isNewerSchema(value)) {
+    const release = version === "latest" ? "The latest nxds release" : `nxds ${version}`;
+    throw new CliError(
+      `${release} needs a newer nxds-cli than ${"0.2.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
+    );
+  }
+  const invalid = (problems) => new CliError(
+    `${registryLocation(registry, file)} is not a valid nxds release:
+${problems.map((line) => `  ${line}`).join("\n")}
+Check \`--registry\`, or run the command again later.`
+  );
+  const parsed = catalogSchema.safeParse(value);
+  if (!parsed.success) throw invalid(issueLines(parsed.error));
+  if (version !== "latest" && parsed.data.version !== version) {
+    throw invalid([`version: it holds nxds ${parsed.data.version}`]);
+  }
+  return parsed.data;
+}
+async function loadRelease(registry, version) {
+  const catalog = await fetchRelease(registry, version);
+  if (catalog) return catalog;
+  throw new CliError(
+    version === "latest" ? `${registry} has no nxds release.` : `${registry} has no nxds ${version}, the release this app is on. Run \`${CLI_COMMAND} update\` to move to the latest release.`
+  );
+}
+function findItem(catalog, name) {
+  const item = catalog.items.find((candidate) => candidate.name === name);
+  if (item) return item;
+  throw new UsageError(
+    `nxds ${catalog.version} has no item named "${name}". Run \`${CLI_COMMAND} search ${name}\` to find the right name, or \`${CLI_COMMAND} update\` if it's newer.`
+  );
+}
+function variantOf(item, framework) {
+  const variant = item.variants[framework];
+  if (variant) return variant;
+  throw new CliError(`${item.title} is not available for ${framework} yet.`);
+}
+function setupVariant(catalog, framework) {
+  const setup = catalog.items.find((item) => item.name === SETUP);
+  if (setup?.kind !== "setup") {
+    throw new Error(`nxds ${catalog.version} has no "${SETUP}" setup item.`);
+  }
+  return variantOf(setup, framework);
+}
+function resolveItems(catalog, framework, names) {
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  function visit(name) {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const item = findItem(catalog, name);
+    variantOf(item, framework).items.forEach(visit);
+    ordered.push(item);
+  }
+  names.forEach(visit);
+  return ordered;
+}
+function releaseFiles(catalog, framework) {
+  return new Map(
+    catalog.items.flatMap(
+      (item) => (item.variants[framework]?.files ?? []).map(
+        (file) => [file.path, file.content]
+      )
+    )
+  );
+}
+function splitInstalled(catalog, installed) {
+  const names = new Set(catalog.items.map((item) => item.name));
+  return {
+    known: installed.filter((name) => names.has(name)),
+    removed: installed.filter((name) => !names.has(name))
+  };
+}
+
+// src/config.ts
+import { existsSync as existsSync2, writeFileSync } from "fs";
+import path3 from "path";
+import { z as z2 } from "zod";
+var CONFIG_FILE = "nxds.json";
+var configSchema = z2.looseObject({
+  /** The CLI installs React only. */
+  framework: z2.literal("react"),
+  /** The nxds release every installed file comes from. */
+  version: versionSchema,
+  /** The nxds folder, relative to the project root. */
+  dir: relativePathSchema,
+  /** The nxds CSS entry, relative to the project root. */
+  css: relativePathSchema,
+  /** Installed items, in install order. */
+  items: z2.array(z2.string())
+});
+function configPath(root) {
+  return path3.join(root, CONFIG_FILE);
+}
+function readConfig(root) {
+  const file = configPath(root);
+  if (!existsSync2(file)) return null;
+  const parsed = configSchema.safeParse(readJson(file));
+  if (parsed.success) return parsed.data;
+  throw new CliError(
+    `${CONFIG_FILE} is not valid:
+${issueLines(parsed.error).map((line) => `  ${line}`).join(
+      "\n"
+    )}
+Fix it, or delete ${CONFIG_FILE} and run \`${CLI_COMMAND} init\` again.`
+  );
+}
+function requireConfig(root) {
+  const config = readConfig(root);
+  if (config) return config;
+  throw new CliError(
+    `nxds is not set up here. Run \`${CLI_COMMAND} init\` first.`
+  );
+}
+function writeConfig(root, config) {
+  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}
+`);
+}
+
+// src/project.ts
+import { existsSync as existsSync4 } from "fs";
+import path5 from "path";
+import { major, minVersion as minVersion2, validRange as validRange3 } from "semver";
+
+// src/packages.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import path4 from "path";
+import { minVersion, satisfies, validRange as validRange2 } from "semver";
+var ADD_COMMAND = {
+  npm: ["install"],
+  pnpm: ["add"],
+  yarn: ["add"],
+  bun: ["add"]
+};
+function declaresRange(project, name, range) {
+  const declared = project.dependencies[name];
+  if (declared === void 0) return false;
+  if (validRange2(declared) === null) return true;
+  const lowest = minVersion(declared);
+  return lowest !== null && satisfies(lowest, range);
+}
+function packagesToInstall(project, packages) {
+  return Object.entries(packages).filter(([name, range]) => !declaresRange(project, name, range)).map(([name, range]) => `${name}@${range}`);
+}
+function installedVersion(project, name) {
+  let dir = project.root;
+  for (; ; ) {
+    const manifest = path4.join(dir, "node_modules", name, "package.json");
+    if (existsSync3(manifest)) {
+      return readJson(manifest).version ?? null;
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function installPackages(project, specs, { dev }) {
+  if (specs.length === 0) return;
+  const args = [
+    ...ADD_COMMAND[project.packageManager],
+    ...dev ? ["-D"] : [],
+    ...specs
+  ];
+  const options = {
+    cwd: project.root,
+    stdio: ["ignore", 2, 2]
+  };
+  const run = process.platform === "win32" ? spawnSync(
+    [project.packageManager, ...args.map((arg) => `"${arg}"`)].join(" "),
+    { ...options, shell: true }
+  ) : spawnSync(project.packageManager, args, options);
+  if (run.status !== 0) {
+    throw new CliError(
+      `\`${project.packageManager} ${args.join(" ")}\` failed. Fix the error above, then run the same nxds command again.`
+    );
+  }
+  for (const spec of specs) {
+    const name = spec.slice(0, spec.lastIndexOf("@"));
+    project.dependencies[name] = spec.slice(name.length + 1);
+  }
+}
+
+// src/project.ts
+var LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"]
+];
+var APP_DIRS = ["app", "src/app"];
+var VITE_ENTRIES = ["src/main.tsx", "src/main.jsx"];
+var VITE_CONFIGS = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.js"
+];
+function firstExisting(root, candidates) {
+  return candidates.find((file) => existsSync4(path5.join(root, file)));
+}
+function detectSetup(root, dependencies) {
+  if ("next" in dependencies && firstExisting(
+    root,
+    APP_DIRS.map((dir) => `${dir}/layout.tsx`)
+  )) {
+    return "next-app";
+  }
+  if ("vite" in dependencies && "react" in dependencies && firstExisting(root, VITE_ENTRIES)) {
+    return "vite-react";
+  }
+  return null;
+}
+function readProject(root) {
+  const manifestPath = path5.join(root, "package.json");
+  if (!existsSync4(manifestPath)) {
+    throw new CliError(
+      `No package.json in ${root}. Run \`${CLI_COMMAND}\` from your app's root folder, or pass --cwd.`
+    );
+  }
+  const manifest = readJson(manifestPath);
+  const dependencies = {
+    ...manifest.devDependencies,
+    ...manifest.dependencies
+  };
+  return {
+    root,
+    setup: detectSetup(root, dependencies),
+    packageManager: LOCKFILES.find(([file]) => existsSync4(path5.join(root, file)))?.[1] ?? "npm",
+    usesSrc: existsSync4(path5.join(root, "src")),
+    typescript: existsSync4(path5.join(root, "tsconfig.json")),
+    dependencies
+  };
+}
+function findFile(project, candidates) {
+  return firstExisting(project.root, candidates);
+}
+function majorVersion(project, name) {
+  const declared = project.dependencies[name];
+  if (declared === void 0) return null;
+  if (validRange3(declared) !== null) return minVersion2(declared)?.major ?? null;
+  const installed = installedVersion(project, name);
+  return installed === null ? null : major(installed);
+}
+
+// src/commands/browse.ts
+function appRelease(cwd, registry) {
+  return loadRelease(registry, readConfig(cwd)?.version ?? "latest");
+}
+function summary(item) {
+  return {
+    name: item.name,
+    kind: item.kind,
+    title: item.title,
+    description: item.description
+  };
+}
+function firstSentence(text) {
+  return text.split(/(?<=\.)\s/)[0]?.replaceAll("`", "") ?? text;
+}
+function summaryLines(items) {
+  const width = Math.max(...items.map((item) => item.name.length));
+  return items.map(
+    (item) => `${item.name.padEnd(width)}  ${firstSentence(item.description)}`
+  );
+}
+async function list(cwd, registry, kind) {
+  const items = (await appRelease(cwd, registry)).items.filter(
+    (item) => item.name !== SETUP && (kind === void 0 || item.kind === kind)
+  );
+  return { data: items.map(summary), lines: summaryLines(items), ok: true };
+}
+async function search(cwd, registry, query) {
+  const needle = query.toLowerCase();
+  const rank = (item) => {
+    if (item.name.includes(needle)) return 0;
+    if (item.title.toLowerCase().includes(needle)) return 1;
+    if (item.description.toLowerCase().includes(needle)) return 2;
+    return void 0;
+  };
+  const items = (await appRelease(cwd, registry)).items.filter((item) => item.name !== SETUP).flatMap((item) => {
+    const score = rank(item);
+    return score === void 0 ? [] : [{ item, score }];
+  }).sort((a, b) => a.score - b.score).map(({ item }) => item);
+  return {
+    data: items.map(summary),
+    lines: items.length > 0 ? summaryLines(items) : [`Nothing matches "${query}".`],
+    ok: true
+  };
+}
+function projectFramework(cwd, catalog) {
+  const configured = readConfig(cwd)?.framework;
+  if (configured) return configured;
+  const [only, ...others] = catalog.frameworks;
+  if (only && others.length === 0) return only;
+  throw new CliError(
+    `This release has several frameworks. Run \`${CLI_COMMAND} init\` first, so nxds knows which one your app uses.`
+  );
+}
+async function view(cwd, registry, name) {
+  const catalog = await appRelease(cwd, registry);
+  const item = findItem(catalog, name);
+  const variant = variantOf(item, projectFramework(cwd, catalog));
+  const packages = Object.entries(variant.packages.npm).map(
+    ([pkg, range]) => `${pkg}@${range}`
+  );
+  const needs = variant.items.filter((other) => other !== SETUP);
+  return {
+    data: {
+      ...summary(item),
+      docs: item.docs,
+      items: variant.items,
+      packages,
+      files: variant.files.map((file) => file.path)
+    },
+    lines: [
+      `${item.title} (${item.kind})`,
+      item.description,
+      `Docs: ${item.docs}`,
+      ...needs.length > 0 ? [`Also installs: ${needs.join(", ")}`] : [],
+      ...packages.length > 0 ? [`Packages: ${packages.join(" ")}`] : [],
+      "Files:",
+      ...variant.files.map((file) => `  ${file.path}`)
+    ],
+    ok: true
+  };
+}
+function info(cwd) {
+  const project = readProject(cwd);
+  const config = readConfig(cwd);
+  const setupLabel = {
+    "next-app": "Next.js App Router",
+    "vite-react": "Vite + React"
+  };
+  return {
+    data: {
+      setup: project.setup,
+      packageManager: project.packageManager,
+      typescript: project.typescript,
+      tailwind: project.dependencies.tailwindcss ?? null,
+      initialized: config !== null,
+      version: config?.version ?? null,
+      dir: config?.dir ?? null,
+      css: config?.css ?? null,
+      items: config?.items ?? []
+    },
+    lines: [
+      `App: ${project.setup ? setupLabel[project.setup] : "not supported by init (see https://nxds.dev/getting-started/install)"}`,
+      `Package manager: ${project.packageManager}`,
+      `TypeScript: ${project.typescript ? "yes" : "no"}`,
+      `Tailwind: ${project.dependencies.tailwindcss ?? "not installed"}`,
+      config ? `nxds: ${config.version} in ${config.dir}, CSS entry ${config.css}` : `nxds: not set up. Run \`${CLI_COMMAND} init\`.`,
+      ...config && config.items.length > 0 ? [
+        `Installed: ${config.items.filter((item) => item !== SETUP).join(", ") || "setup only"}`
+      ] : []
+    ],
+    ok: true
+  };
+}
+
+// src/commands/check.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync7, readFileSync as readFileSync4 } from "fs";
+import path8 from "path";
+import { satisfies as satisfies2 } from "semver";
+
+// src/files.ts
+import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import path6 from "path";
+import { merge } from "node-diff3";
+function baseOf(previous, file) {
+  if (!previous) return void 0;
+  return previous.get(file) ?? "";
+}
+function withLf(content) {
+  return `${content.replace(/\r\n?/g, "\n").replace(/\n+$/, "")}
+`;
+}
+function normalize(content) {
+  const lines2 = withLf(content).split("\n").map((line) => line.trimEnd());
+  return `${lines2.join("\n").trimEnd()}
+`;
+}
+function sameContent(a, b) {
+  return b !== void 0 && normalize(a) === normalize(b);
+}
+var OURS_LABEL = "your file";
+var CONFLICT_START = `<<<<<<< ${OURS_LABEL}`;
+function hasConflictMarkers(content) {
+  return content.split(/\r?\n/).includes(CONFLICT_START);
+}
+function conflictedFiles(root, config, files) {
+  return [...files].filter((file) => {
+    const target = path6.join(root, config.dir, file);
+    return existsSync5(target) && hasConflictMarkers(readFileSync2(target, "utf8"));
+  });
+}
+function fileState(root, config, file, previous) {
+  const target = path6.join(root, config.dir, file.path);
+  if (!existsSync5(target)) return "missing";
+  const onDisk = readFileSync2(target, "utf8");
+  if (hasConflictMarkers(onDisk)) return "conflicted";
+  if (sameContent(onDisk, file.content)) return "current";
+  return sameContent(onDisk, previous?.get(file.path)) ? "outdated" : "changed";
+}
+function mergeFile(ours, base, theirs, version) {
+  const lines2 = (content) => withLf(content).split("\n");
+  const { conflict, result } = merge(lines2(ours), lines2(base), lines2(theirs), {
+    label: { a: OURS_LABEL, b: `nxds ${version}` }
+  });
+  return { content: result.join("\n"), conflict };
+}
+function writeFiles(root, config, files, previous, { overwrite, dryRun, version }) {
+  const result = {
+    written: [],
+    unchanged: [],
+    merged: [],
+    conflicted: [],
+    unresolved: [],
+    skipped: []
+  };
+  const write = (file, content) => {
+    if (dryRun) return;
+    const target = path6.join(root, config.dir, file);
+    mkdirSync(path6.dirname(target), { recursive: true });
+    writeFileSync2(target, content);
+  };
+  for (const file of files) {
+    const state = fileState(root, config, file, previous);
+    if (state === "current") {
+      result.unchanged.push(file.path);
+      continue;
+    }
+    if (overwrite || state === "missing" || state === "outdated") {
+      result.written.push(file.path);
+      write(file.path, file.content);
+      continue;
+    }
+    if (state === "conflicted") {
+      result.unresolved.push(file.path);
+      continue;
+    }
+    const base = baseOf(previous, file.path);
+    if (base === void 0) {
+      result.skipped.push(file.path);
+      continue;
+    }
+    const target = path6.join(root, config.dir, file.path);
+    const ours = readFileSync2(target, "utf8");
+    const merged = mergeFile(ours, base, file.content, version);
+    if (sameContent(ours, merged.content)) {
+      result.unchanged.push(file.path);
+      continue;
+    }
+    result[merged.conflict ? "conflicted" : "merged"].push(file.path);
+    write(file.path, merged.content);
+  }
+  return result;
+}
+function relativeImport(fromFile, toFile) {
+  const relative = path6.relative(path6.dirname(fromFile), toFile).split(path6.sep).join("/");
+  return relative.startsWith(".") ? relative : `./${relative}`;
+}
+
+// src/setup/react.ts
+import {
+  isArrayExpression,
+  isCallExpression,
+  isExportDefaultDeclaration,
+  isIdentifier,
+  isJSXElement as isJSXElement2,
+  isMemberExpression,
+  isObjectExpression,
+  isObjectProperty,
+  isSpreadElement
+} from "@babel/types";
+import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
+import path7 from "path";
+
+// src/setup/source-edit.ts
+import { parse } from "@babel/parser";
+import {
+  isImportDeclaration,
+  isJSXAttribute,
+  isJSXElement,
+  isJSXIdentifier,
+  traverseFast
+} from "@babel/types";
+function parseModule(source, file) {
+  try {
+    return parse(source, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"]
+    }).program;
+  } catch (error) {
+    throw new CliError(
+      `Could not parse ${file}: ${error.message}. Fix the syntax error, then run the command again.`
+    );
+  }
+}
+function startOf(node) {
+  return node.start;
+}
+function endOf(node) {
+  return node.end;
+}
+function findNode(root, matches) {
+  let found;
+  traverseFast(root, (node) => {
+    if (!matches(node)) return void 0;
+    found = node;
+    return traverseFast.stop;
+  });
+  return found;
+}
+function jsxName(element) {
+  const { name } = element.openingElement;
+  return isJSXIdentifier(name) ? name.name : void 0;
+}
+function findJsx(root, name) {
+  return findNode(
+    root,
+    (node) => isJSXElement(node) && jsxName(node) === name
+  );
+}
+function applyInsertions(source, insertions) {
+  return [...insertions].sort((a, b) => b.at - a.at).reduce(
+    (text, { at, text: inserted }) => text.slice(0, at) + inserted + text.slice(at),
+    source
+  );
+}
+function importInsertion(source, program2, lines2) {
+  const imports = program2.body.filter((node) => isImportDeclaration(node));
+  const first = imports[0];
+  const quote = first && source[startOf(first.source)];
+  const semicolons = !first || source[endOf(first) - 1] === ";";
+  const text = lines2.map((line) => quote === '"' ? line.replaceAll("'", '"') : line).map((line) => semicolons ? line : line.replace(/;$/, "")).join("\n");
+  const lastImport = imports.at(-1);
+  if (lastImport) return { at: endOf(lastImport), text: `
+${text}` };
+  const lastDirective = program2.directives.at(-1);
+  if (lastDirective) return { at: endOf(lastDirective), text: `
+
+${text}` };
+  return { at: 0, text: `${text}
+
+` };
+}
+function lineIndent(source, offset) {
+  const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
+  return /^[ \t]*/.exec(source.slice(lineStart))?.[0] ?? "";
+}
+function beforeWhitespace(source, offset) {
+  let at = offset;
+  while (at > 0 && /\s/.test(source.charAt(at - 1))) at -= 1;
+  return at;
+}
+function openingTagEnd(element) {
+  return endOf(element.openingElement);
+}
+function hasAttribute(element, name) {
+  return element.openingElement.attributes.some(
+    (attribute) => isJSXAttribute(attribute) && isJSXIdentifier(attribute.name) && attribute.name.name === name
+  );
+}
+function attributeInsertion(element, name) {
+  const opening = element.openingElement;
+  const tagEnd = endOf(opening) - (opening.selfClosing ? 2 : 1);
+  return { at: tagEnd, text: ` ${name}` };
+}
+
+// src/setup/react.ts
+var STORAGE_KEY = "nxds-appearance";
+var PROVIDER = "components/appearance/provider";
+var TAILWIND_PLUGIN = {
+  "next-app": "@tailwindcss/postcss",
+  "vite-react": "@tailwindcss/vite"
+};
+function tailwindPackages(setup, range) {
+  return { tailwindcss: range, [TAILWIND_PLUGIN[setup]]: range };
+}
+function appDir(project) {
+  const dir = APP_DIRS.find(
+    (candidate) => existsSync6(path7.join(project.root, candidate, "layout.tsx"))
+  );
+  if (!dir)
+    throw new CliError("No app/layout.tsx or src/app/layout.tsx found.");
+  return dir;
+}
+function entryDir(project) {
+  return project.setup === "next-app" ? appDir(project) : "src";
+}
+function defaultDir(project) {
+  return project.usesSrc ? "src/components/nxds" : "components/nxds";
+}
+function cssEntryPath(project) {
+  return `${entryDir(project)}/nxds.css`;
+}
+function read(project, file) {
+  return readFileSync3(path7.join(project.root, file), "utf8");
+}
+function cssEntry(config, withPreflight) {
+  const tokens = relativeImport(config.css, `${config.dir}/tailwind/nxds.css`);
+  return [
+    ...withPreflight ? [
+      "@layer theme, base, components, utilities;",
+      "@import 'tailwindcss/preflight.css' layer(base);"
+    ] : [],
+    `@import '${tokens}';`,
+    "@import 'tw-animate-css';",
+    ""
+  ].join("\n");
+}
+function cssImportLine(config, file) {
+  return `@import '${relativeImport(config.css, `${config.dir}/${file}`)}';`;
+}
+var APPEARANCE_STATE = `import {
+  DEFAULT_NXDS_APPEARANCE,
+  type NxdsAppearanceState,
+} from '@nxds/core';
+
+export const defaultAppearance = {
+  ...DEFAULT_NXDS_APPEARANCE,
+} satisfies NxdsAppearanceState;
+`;
+function providerImport(fromFile, config, file = "") {
+  return relativeImport(fromFile, `${config.dir}/${PROVIDER}${file}`);
+}
+function editedFile(file, content) {
+  return { path: file, content, created: false };
+}
+var NO_CHANGES = { changes: [], manual: [] };
+var PROVIDER_PROPS = `storageKey="${STORAGE_KEY}" defaultState={defaultAppearance}`;
+var SCRIPT_ELEMENT = `<NxdsAppearanceScript ${PROVIDER_PROPS} />`;
+function wireNextLayout(project, config, steps) {
+  const layout = `${appDir(project)}/layout.tsx`;
+  const source = read(project, layout);
+  if (/NxdsAppearance(Provider|Script)/.test(source)) return NO_CHANGES;
+  const program2 = parseModule(source, layout);
+  const html = findJsx(program2, "html");
+  const body = html && findJsx(html, "body");
+  const head = html && findJsx(html, "head");
+  if (!html || !body?.closingElement || head && !head.closingElement) {
+    return {
+      changes: [],
+      manual: [
+        {
+          file: layout,
+          step: `Add ${SCRIPT_ELEMENT} inside <head>, and wrap the content of <body> in <NxdsAppearanceProvider ${PROVIDER_PROPS}>.`
+        }
+      ]
+    };
+  }
+  const step = "  ";
+  const imports = [];
+  const insertions = [];
+  if (steps.has("add-css-import")) imports.push("import './nxds.css';");
+  if (steps.has("wrap-root-with-provider")) {
+    const bodyIndent = lineIndent(source, startOf(body));
+    imports.push(
+      `import { NxdsAppearanceProvider } from '${providerImport(layout, config)}';`
+    );
+    insertions.push(
+      {
+        at: openingTagEnd(body),
+        text: `
+${bodyIndent}${step}<NxdsAppearanceProvider ${PROVIDER_PROPS}>`
+      },
+      {
+        at: beforeWhitespace(source, startOf(body.closingElement)),
+        text: `
+${bodyIndent}${step}</NxdsAppearanceProvider>`
+      }
+    );
+  }
+  if (steps.has("add-head-script")) {
+    const htmlIndent = lineIndent(source, startOf(html));
+    imports.push(
+      `import { NxdsAppearanceScript } from '${providerImport(layout, config, "/server")}';`
+    );
+    insertions.push(
+      head ? {
+        at: openingTagEnd(head),
+        text: `
+${lineIndent(source, startOf(head))}${step}${SCRIPT_ELEMENT}`
+      } : {
+        at: openingTagEnd(html),
+        text: `
+${htmlIndent}${step}<head>
+${htmlIndent}${step}${step}${SCRIPT_ELEMENT}
+${htmlIndent}${step}</head>`
+      }
+    );
+    if (!hasAttribute(html, "suppressHydrationWarning")) {
+      insertions.push(attributeInsertion(html, "suppressHydrationWarning"));
+    }
+  }
+  if (insertions.length > 0) {
+    imports.push("import { defaultAppearance } from './appearance-state';");
+  }
+  if (imports.length === 0) return NO_CHANGES;
+  insertions.push(importInsertion(source, program2, imports));
+  return {
+    changes: [editedFile(layout, applyInsertions(source, insertions))],
+    manual: []
+  };
+}
+function renderedElement(program2) {
+  const call = findNode(
+    program2,
+    (node) => isCallExpression(node) && isMemberExpression(node.callee) && isIdentifier(node.callee.property, { name: "render" }) && isJSXElement2(node.arguments[0])
+  );
+  return call?.arguments[0];
+}
+function wireViteEntry(project, config, steps) {
+  const entry = findFile(project, VITE_ENTRIES);
+  if (!entry) throw new CliError("No src/main.tsx found.");
+  const source = read(project, entry);
+  if (source.includes("NxdsAppearanceProvider")) return NO_CHANGES;
+  const program2 = parseModule(source, entry);
+  const imports = [];
+  const insertions = [];
+  if (steps.has("add-css-import")) imports.push("import './nxds.css';");
+  if (steps.has("wrap-root-with-provider")) {
+    const app = renderedElement(program2);
+    if (!app) {
+      return {
+        changes: [],
+        manual: [
+          {
+            file: entry,
+            step: `Wrap the element you render in <NxdsAppearanceProvider ${PROVIDER_PROPS}>.`
+          }
+        ]
+      };
+    }
+    const indent = lineIndent(source, startOf(app));
+    imports.push(
+      `import { NxdsAppearanceProvider } from '${providerImport(entry, config)}';`,
+      "import { defaultAppearance } from './appearance-state';"
+    );
+    insertions.push(
+      {
+        at: startOf(app),
+        text: `<NxdsAppearanceProvider ${PROVIDER_PROPS}>
+${indent}`
+      },
+      { at: endOf(app), text: `
+${indent}</NxdsAppearanceProvider>` }
+    );
+  }
+  if (imports.length === 0) return NO_CHANGES;
+  insertions.push(importInsertion(source, program2, imports));
+  return {
+    changes: [editedFile(entry, applyInsertions(source, insertions))],
+    manual: []
+  };
+}
+var VITE_PLUGIN = `import {
+  createNxdsAppearanceBootstrapScript,
+  createNxdsAppearanceSnapshotFromState,
+} from '@nxds/core';
+import type { Plugin } from 'vite';
+
+import { defaultAppearance } from './src/appearance-state';
+
+/** Adds the nxds theme script to index.html, so the page doesn't flash the wrong theme. */
+export function nxdsAppearance(): Plugin {
+  const script = createNxdsAppearanceBootstrapScript({
+    storageKey: '${STORAGE_KEY}',
+    defaultSnapshot: createNxdsAppearanceSnapshotFromState(defaultAppearance),
+  });
+  return {
+    name: 'nxds-appearance',
+    transformIndexHtml: (html) =>
+      html.replace('</head>', \`<script>\${script}</script></head>\`),
+  };
+}
+`;
+function configObject(program2) {
+  const declaration = program2.body.find(
+    (node) => isExportDefaultDeclaration(node)
+  )?.declaration;
+  if (isObjectExpression(declaration)) return declaration;
+  if (!isCallExpression(declaration)) return void 0;
+  const [argument] = declaration.arguments;
+  return isObjectExpression(argument) ? argument : void 0;
+}
+function hasProperty(object, name) {
+  return object.properties.some(
+    (property) => !isSpreadElement(property) && isIdentifier(property.key, { name })
+  );
+}
+function pluginsArray(object) {
+  const property = object.properties.find(
+    (candidate) => isObjectProperty(candidate) && isIdentifier(candidate.key, { name: "plugins" })
+  );
+  return isObjectProperty(property) && isArrayExpression(property.value) ? property.value : void 0;
+}
+var TAILWIND_VITE_PLUGIN = {
+  call: "tailwindcss()",
+  importLine: "import tailwindcss from '@tailwindcss/vite';"
+};
+var NXDS_VITE_PLUGIN = {
+  call: "nxdsAppearance()",
+  importLine: "import { nxdsAppearance } from './nxds.vite';"
+};
+var VITE_ALIAS = "{ '@': '/src' }";
+function wireViteConfig(project, addTailwind, steps) {
+  const configFile = findFile(project, VITE_CONFIGS) ?? "vite.config.ts";
+  const addScript = steps.has("add-head-script") && !existsSync6(path7.join(project.root, "nxds.vite.ts"));
+  const changes = addScript ? [{ path: "nxds.vite.ts", content: VITE_PLUGIN, created: true }] : [];
+  const source = existsSync6(path7.join(project.root, configFile)) ? read(project, configFile) : "";
+  const program2 = source ? parseModule(source, configFile) : void 0;
+  const object = program2 && configObject(program2);
+  const plugins = object && pluginsArray(object);
+  const newPlugins = [
+    ...addTailwind ? [TAILWIND_VITE_PLUGIN] : [],
+    ...steps.has("add-head-script") && !source.includes("nxdsAppearance") ? [NXDS_VITE_PLUGIN] : []
+  ];
+  const needsAlias = !/['"]@['"]/.test(source);
+  const manual = [];
+  const insertions = [];
+  const imports = [];
+  if (newPlugins.length > 0 && plugins) {
+    const calls = newPlugins.map((plugin) => plugin.call).join(", ");
+    const last = plugins.elements.at(-1);
+    insertions.push(
+      last ? { at: endOf(last), text: `, ${calls}` } : { at: startOf(plugins) + 1, text: calls }
+    );
+    imports.push(...newPlugins.map((plugin) => plugin.importLine));
+  } else if (newPlugins.length > 0) {
+    manual.push({
+      file: configFile,
+      step: `Add ${newPlugins.map((plugin) => `${plugin.call} (${plugin.importLine})`).join(" and ")} to the plugins array.`
+    });
+  }
+  if (needsAlias && object && !hasProperty(object, "resolve")) {
+    const last = object.properties.at(-1);
+    const alias = `resolve: {
+    alias: ${VITE_ALIAS},
+  }`;
+    insertions.push(
+      last ? { at: endOf(last), text: `,
+  ${alias}` } : { at: startOf(object) + 1, text: `
+  ${alias},
+` }
+    );
+  } else if (needsAlias) {
+    manual.push({
+      file: configFile,
+      step: `Add resolve.alias ${VITE_ALIAS}, so imports like @/components/nxds/... resolve.`
+    });
+  }
+  if (program2 && insertions.length > 0) {
+    insertions.push(importInsertion(source, program2, imports));
+    changes.push(editedFile(configFile, applyInsertions(source, insertions)));
+  }
+  return { changes, manual };
+}
+var ALIAS_PATTERN = /"@\/\*"/;
+var PATHS_PATTERN = /"paths"\s*:/;
+var COMPILER_OPTIONS = /"compilerOptions"\s*:\s*\{/;
+function wireTsconfigAlias(project) {
+  const file = findFile(project, ["tsconfig.app.json", "tsconfig.json"]);
+  if (!file) throw new CliError("No tsconfig.json found.");
+  const source = read(project, file);
+  if (ALIAS_PATTERN.test(source)) return NO_CHANGES;
+  const target = project.usesSrc ? "./src/*" : "./*";
+  const match = COMPILER_OPTIONS.exec(source);
+  if (!match || PATHS_PATTERN.test(source)) {
+    return {
+      changes: [],
+      manual: [
+        {
+          file,
+          step: `Add "@/*": ["${target}"] to compilerOptions.paths.`
+        }
+      ]
+    };
+  }
+  const at = match.index + match[0].length;
+  return {
+    changes: [
+      editedFile(
+        file,
+        applyInsertions(source, [
+          { at, text: `
+    "paths": { "@/*": ["${target}"] },` }
+        ])
+      )
+    ],
+    manual: []
+  };
+}
+var ESLINT_CONFIGS = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.ts"
+];
+function exportedConfigs(program2) {
+  const declaration = program2.body.find(
+    (node) => isExportDefaultDeclaration(node)
+  )?.declaration;
+  if (isArrayExpression(declaration)) return declaration.elements;
+  if (!isCallExpression(declaration)) return [];
+  const [first] = declaration.arguments;
+  return isArrayExpression(first) ? first.elements : declaration.arguments;
+}
+function wireViteEslint(project, config) {
+  const file = findFile(project, ESLINT_CONFIGS);
+  if (!file) return NO_CHANGES;
+  const source = read(project, file);
+  if (!source.includes("react-refresh") || source.includes(config.dir)) {
+    return NO_CHANGES;
+  }
+  const rule = `{
+    files: ['${config.dir}/**/*.{ts,tsx}'],
+    rules: { 'react-refresh/only-export-components': 'off' },
+  }`;
+  const last = exportedConfigs(parseModule(source, file)).at(-1);
+  if (!last) {
+    return {
+      changes: [],
+      manual: [
+        {
+          file,
+          step: `Add ${rule.replace(/\s+/g, " ")} to the exported config.`
+        }
+      ]
+    };
+  }
+  return {
+    changes: [
+      editedFile(
+        file,
+        applyInsertions(source, [{ at: endOf(last), text: `,
+  ${rule}` }])
+      )
+    ],
+    manual: []
+  };
+}
+var POSTCSS_CONFIG = `export default {
+  plugins: { '@tailwindcss/postcss': {} },
+};
+`;
+var POSTCSS_CONFIGS = [
+  "postcss.config.mjs",
+  "postcss.config.js",
+  "postcss.config.cjs"
+];
+function wireNextTailwind(project) {
+  const existing = findFile(project, POSTCSS_CONFIGS);
+  if (!existing) {
+    return {
+      changes: [
+        { path: "postcss.config.mjs", content: POSTCSS_CONFIG, created: true }
+      ],
+      manual: []
+    };
+  }
+  return {
+    changes: [],
+    manual: [
+      {
+        file: existing,
+        step: "Add '@tailwindcss/postcss': {} to the plugins."
+      }
+    ]
+  };
+}
+function createdUnlessExists(project, file, content) {
+  if (existsSync6(path7.join(project.root, file))) return NO_CHANGES;
+  return { changes: [{ path: file, content, created: true }], manual: [] };
+}
+function planWiring(project, config, addTailwind, setupSteps) {
+  const steps = new Set(setupSteps);
+  const plans = [wireTsconfigAlias(project)];
+  if (steps.has("add-css-import")) {
+    plans.push(
+      createdUnlessExists(project, config.css, cssEntry(config, addTailwind))
+    );
+  }
+  if (steps.has("add-head-script") || steps.has("wrap-root-with-provider")) {
+    plans.push(
+      createdUnlessExists(
+        project,
+        `${entryDir(project)}/appearance-state.ts`,
+        APPEARANCE_STATE
+      )
+    );
+  }
+  if (project.setup === "next-app") {
+    plans.push(wireNextLayout(project, config, steps));
+    if (addTailwind) plans.push(wireNextTailwind(project));
+  } else {
+    plans.push(wireViteEntry(project, config, steps));
+    plans.push(wireViteConfig(project, addTailwind, steps));
+    plans.push(wireViteEslint(project, config));
+  }
+  return {
+    changes: plans.flatMap((plan) => plan.changes),
+    manual: plans.flatMap((plan) => plan.manual)
+  };
+}
+
+// src/commands/check.ts
+async function diff(cwd, registry, names) {
+  const config = requireConfig(cwd);
+  const latest = await loadRelease(registry, "latest");
+  const previous = await fetchRelease(registry, config.version);
+  const previousFiles = previous && releaseFiles(previous, config.framework);
+  const { known, removed } = splitInstalled(latest, config.items);
+  const items = resolveItems(
+    latest,
+    config.framework,
+    names.length > 0 ? names : known
+  );
+  const update2 = `\`${CLI_COMMAND} update\``;
+  const overwrite = `\`${CLI_COMMAND} update --overwrite\``;
+  function advice(state, file) {
+    if (state === "outdated") return `${update2} replaces it`;
+    if (state === "missing") return `${update2} restores it`;
+    if (state === "conflicted") {
+      return `has conflict markers; resolve them, or ${overwrite} replaces it`;
+    }
+    const base = baseOf(previousFiles, file.path);
+    if (base === void 0) {
+      return `has your edits; ${update2} keeps it, ${overwrite} replaces it`;
+    }
+    if (sameContent(base, file.content)) {
+      return `has your edits; nxds hasn't changed it since ${config.version}`;
+    }
+    return `has your edits; ${update2} merges nxds's changes into it, ${overwrite} replaces it`;
+  }
+  const files = items.flatMap(
+    (item) => variantOf(item, config.framework).files.map((file) => {
+      const state = fileState(cwd, config, file, previousFiles);
+      return {
+        item: item.name,
+        path: file.path,
+        state,
+        advice: state === "current" ? null : advice(state, file)
+      };
+    })
+  );
+  const differing = files.filter((file) => file.state !== "current");
+  return {
+    data: { version: config.version, latest: latest.version, files, removed },
+    lines: [
+      ...differing.map(
+        (file) => `${file.state.padEnd(10)}  ${file.path}  (${file.advice})`
+      ),
+      ...removed.map(
+        (name) => `${"removed".padEnd(10)}  ${name}  (no longer in nxds; \`${CLI_COMMAND} update\` drops it)`
+      ),
+      ...differing.length === 0 && removed.length === 0 ? [`Every file matches nxds ${latest.version}.`] : []
+    ],
+    ok: true
+  };
+}
+function tailwindMessage(project) {
+  const declared = project.dependencies.tailwindcss;
+  if (declared === void 0) {
+    return `Tailwind 4 is not installed. Run \`${CLI_COMMAND} init\`.`;
+  }
+  const tailwindMajor = majorVersion(project, "tailwindcss");
+  if (tailwindMajor === 4) return `tailwindcss ${declared}`;
+  if (tailwindMajor === null) {
+    return `tailwindcss ${declared} names no version, and none is installed. Install your dependencies, then run doctor again.`;
+  }
+  return `tailwindcss ${declared}. nxds needs Tailwind CSS 4.`;
+}
+function read2(root, file) {
+  if (!file || !existsSync7(path8.join(root, file))) return "";
+  return readFileSync4(path8.join(root, file), "utf8");
+}
+function sourcesNxdsDir(config, css) {
+  const entryDir2 = path8.posix.dirname(config.css);
+  return [...css.matchAll(/@source\s+(['"])(.*?)\1/g)].some(([, , source]) => {
+    const base = (source ?? "").split(/[*{[]/)[0] ?? "";
+    const folder = path8.posix.join(entryDir2, base).replace(/\/+$/, "");
+    return folder === "." || /^\.\.(\/\.\.)*$/.test(folder) || config.dir === folder || config.dir.startsWith(`${folder}/`);
+  });
+}
+function unscannedReason(cwd, config, css) {
+  if (/source\(\s*none\s*\)/.test(css) && !sourcesNxdsDir(config, css)) {
+    return `${config.css} turns off Tailwind's source detection with source(none), and no @source covers ${config.dir}.`;
+  }
+  const ignored = spawnSync2("git", ["check-ignore", "-q", config.dir], { cwd });
+  if (ignored.status === 0) {
+    return `${config.dir} is git-ignored, so Tailwind skips it. Commit the nxds folder.`;
+  }
+  return null;
+}
+function packageProblems(project, config, items) {
+  const needed = Object.assign(
+    {},
+    ...items.map((item) => variantOf(item, config.framework).packages.npm)
+  );
+  return Object.entries(needed).flatMap(([name, range]) => {
+    if (!(name in project.dependencies))
+      return [`${name} is not in package.json`];
+    const version = installedVersion(project, name);
+    if (version === null) return [`${name} is not installed`];
+    if (!satisfies2(version, range)) {
+      return [
+        `${name} ${version} is installed, and this release needs ${range}`
+      ];
+    }
+    return [];
+  });
+}
+async function doctor(cwd, registry) {
+  const project = readProject(cwd);
+  const config = readConfig(cwd);
+  const checks = [];
+  const check = (name, ok, message) => checks.push({ name, ok, message });
+  check(
+    "config",
+    config !== null,
+    config ? "nxds.json found" : `No nxds.json. Run \`${CLI_COMMAND} init\`.`
+  );
+  if (!project.setup) {
+    check("app", false, "Not a Next.js App Router or Vite + React app.");
+  }
+  if (!config || !project.setup) return report(checks);
+  const catalog = await fetchRelease(registry, config.version);
+  check(
+    "release",
+    catalog !== null,
+    catalog ? `Files come from nxds ${config.version}` : `${registry} has no nxds ${config.version}. Run \`${CLI_COMMAND} update\`.`
+  );
+  check(
+    "tailwind",
+    majorVersion(project, "tailwindcss") === 4,
+    tailwindMessage(project)
+  );
+  const css = read2(cwd, config.css);
+  const importsTokens = css.includes("tailwind/nxds.css");
+  check(
+    "css entry",
+    importsTokens,
+    !css ? `${config.css} is missing. Run \`${CLI_COMMAND} init\`.` : importsTokens ? `${config.css} imports the nxds tokens` : `${config.css} does not import ${config.dir}/tailwind/nxds.css. Add the @import back.`
+  );
+  const unscanned = unscannedReason(cwd, config, css);
+  check(
+    "classes",
+    unscanned === null,
+    unscanned ?? `Tailwind scans ${config.dir}, so its nx: classes are generated`
+  );
+  const entry = project.setup === "next-app" ? `${entryDir(project)}/layout.tsx` : findFile(project, VITE_ENTRIES);
+  const entrySource = read2(cwd, entry);
+  const cssFile = path8.basename(config.css);
+  const importsCss = entrySource.includes(cssFile);
+  check(
+    "css import",
+    importsCss,
+    `${entry} ${importsCss ? "imports" : "does not import"} ${cssFile}`
+  );
+  check(
+    "provider",
+    entrySource.includes("NxdsAppearanceProvider"),
+    `${entry} ${entrySource.includes("NxdsAppearanceProvider") ? "renders" : "does not render"} NxdsAppearanceProvider`
+  );
+  const scriptSource = project.setup === "next-app" ? entrySource : read2(cwd, findFile(project, VITE_CONFIGS));
+  const scriptMarker = project.setup === "next-app" ? "NxdsAppearanceScript" : "nxdsAppearance";
+  check(
+    "theme script",
+    scriptSource.includes(scriptMarker),
+    scriptSource.includes(scriptMarker) ? "The theme script runs before first paint" : `The theme script is missing, so the page can flash the wrong theme. Run \`${CLI_COMMAND} init\`.`
+  );
+  if (!catalog) return report(checks);
+  const { known, removed } = splitInstalled(catalog, config.items);
+  check(
+    "items",
+    removed.length === 0,
+    removed.length === 0 ? `${known.length} installed items, all in this release` : `No longer in nxds: ${removed.join(", ")}. Run \`${CLI_COMMAND} update\`.`
+  );
+  const items = resolveItems(catalog, config.framework, known);
+  const missingFiles = items.flatMap(
+    (item) => variantOf(item, config.framework).files.filter(
+      (file) => !existsSync7(path8.join(cwd, config.dir, file.path))
+    ).map((file) => `${item.name}: ${file.path}`)
+  );
+  check(
+    "files",
+    missingFiles.length === 0,
+    missingFiles.length === 0 ? `All files for ${known.length} installed items are present` : `Missing ${missingFiles.join(", ")}. Run \`${CLI_COMMAND} add\` for those items.`
+  );
+  const conflicted = conflictedFiles(
+    cwd,
+    config,
+    items.flatMap(
+      (item) => variantOf(item, config.framework).files.map((file) => file.path)
+    )
+  ).map((file) => `${config.dir}/${file}`);
+  check(
+    "conflicts",
+    conflicted.length === 0,
+    conflicted.length === 0 ? "No conflict markers left from an update" : `Resolve the <<<<<<< markers in ${conflicted.join(", ")}.`
+  );
+  const problems = packageProblems(project, config, items);
+  check(
+    "packages",
+    problems.length === 0,
+    problems.length === 0 ? "Every package the installed items need is installed in range, @nxds/core included" : `${problems.join("; ")}. Run \`${CLI_COMMAND} update\`, then your package manager's install.`
+  );
+  return report(checks);
+}
+function report(checks) {
+  const ok = checks.every((item) => item.ok);
+  return {
+    data: { checks },
+    lines: [
+      ...checks.map(
+        (item) => `${item.ok ? "ok  " : "FAIL"}  ${item.name}: ${item.message}`
+      ),
+      ok ? "nxds is set up correctly." : "Fix the failed checks above."
+    ],
+    ok
+  };
+}
+
+// src/commands/install.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
+import path10 from "path";
+
+// src/install.ts
+import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import path9 from "path";
+function emptyInstallResult() {
+  return {
+    items: [],
+    written: [],
+    unchanged: [],
+    merged: [],
+    conflicted: [],
+    unresolved: [],
+    skipped: [],
+    packages: [],
+    cssImports: []
+  };
+}
+function addCssImports(project, config, files, dryRun) {
+  if (files.length === 0) return [];
+  const entry = path9.join(project.root, config.css);
+  const current = existsSync8(entry) ? readFileSync5(entry, "utf8") : "";
+  const added = [...new Set(files)].map((file) => cssImportLine(config, file)).filter((line) => !current.includes(line));
+  if (added.length > 0 && !dryRun) {
+    writeFileSync3(entry, `${current.trimEnd()}
+${added.join("\n")}
+`);
+  }
+  return added;
+}
+function installItems(catalog, project, config, names, previous, options) {
+  const items = resolveItems(catalog, config.framework, names);
+  const variants = items.map((item) => variantOf(item, config.framework));
+  const files = new Map(
+    variants.flatMap((variant) => variant.files).map((file) => [file.path, file])
+  );
+  const written = writeFiles(
+    project.root,
+    config,
+    [...files.values()],
+    previous,
+    { ...options, version: catalog.version }
+  );
+  const packages = packagesToInstall(
+    project,
+    Object.assign({}, ...variants.map((variant) => variant.packages.npm))
+  );
+  if (options.install && !options.dryRun) {
+    installPackages(project, packages, { dev: false });
+  }
+  const cssImports = addCssImports(
+    project,
+    config,
+    variants.flatMap((variant) => variant.css),
+    options.dryRun
+  );
+  for (const item of items) {
+    if (!config.items.includes(item.name)) config.items.push(item.name);
+  }
+  return {
+    ...written,
+    items: items.map((item) => item.name),
+    packages,
+    cssImports
+  };
+}
+
+// src/commands/install.ts
+function packagesVerb({ dryRun, install }) {
+  if (dryRun) return "Would install";
+  return install ? "Installed" : "Not installed (--no-install):";
+}
+function installLines(config, result, options) {
+  const { dryRun } = options;
+  const verb = dryRun ? "Would write" : "Wrote";
+  return [
+    ...result.written.map((file) => `${verb} ${config.dir}/${file}`),
+    ...result.merged.map(
+      (file) => `${dryRun ? "Would merge" : "Merged"} nxds's changes into your edits in ${config.dir}/${file}`
+    ),
+    ...result.conflicted.map(
+      (file) => `${dryRun ? "Would conflict" : "Conflict"} in ${config.dir}/${file}: nxds changed lines you edited. Resolve the <<<<<<< markers, then run \`${CLI_COMMAND} update\` again.`
+    ),
+    ...result.unresolved.map(
+      (file) => `Still conflicted: ${config.dir}/${file}. Resolve the <<<<<<< markers, then run \`${CLI_COMMAND} update\` again.`
+    ),
+    ...result.skipped.map(
+      (file) => `Kept ${config.dir}/${file}: it differs from nxds's copy, so it may hold your edits. Pass --overwrite to replace it.`
+    ),
+    ...result.packages.length > 0 ? [`${packagesVerb(options)} ${result.packages.join(" ")}`] : [],
+    ...result.cssImports.map(
+      (line) => `${dryRun ? "Would add" : "Added"} ${line}`
+    )
+  ];
+}
+function settled(result) {
+  return result.skipped.length === 0 && result.conflicted.length === 0 && result.unresolved.length === 0;
+}
+function nxdsDir(dir) {
+  const normalized = relativePath(dir);
+  if (normalized) return normalized;
+  throw new UsageError(
+    `--dir takes a folder inside your app, such as components/nxds, not "${dir}".`
+  );
+}
+function assertTailwind4(project) {
+  const declared = project.dependencies.tailwindcss;
+  const tailwindMajor = majorVersion(project, "tailwindcss");
+  if (tailwindMajor === 4) return;
+  if (tailwindMajor === null) {
+    throw new CliError(
+      `This app declares tailwindcss ${declared}, which names no version, and none is installed. Install your dependencies, then run init again.`
+    );
+  }
+  throw new CliError(
+    `nxds needs Tailwind CSS 4, and this app declares tailwindcss ${declared}. Upgrade it (https://tailwindcss.com/docs/upgrade-guide), then run init again.`
+  );
+}
+async function init(cwd, registry, options) {
+  const project = readProject(cwd);
+  if (!project.setup) {
+    throw new CliError(
+      `\`${CLI_COMMAND} init\` supports Next.js App Router and Vite + React apps. For other setups, follow the manual steps at https://nxds.dev/getting-started/install.`
+    );
+  }
+  if (!project.typescript) {
+    throw new CliError(
+      "nxds components are TypeScript. Add a tsconfig.json to your app, then run init again."
+    );
+  }
+  const addTailwind = !("tailwindcss" in project.dependencies);
+  if (!addTailwind) assertTailwind4(project);
+  const dir = options.dir ? nxdsDir(options.dir) : void 0;
+  const existing = readConfig(cwd);
+  const catalog = await loadRelease(registry, existing?.version ?? "latest");
+  if (existing && dir && dir !== existing.dir) {
+    throw new CliError(
+      `nxds is already set up in ${existing.dir}. Run init without --dir, or move the folder and change "dir" in nxds.json.`
+    );
+  }
+  const config = existing ?? {
+    framework: "react",
+    version: catalog.version,
+    dir: dir ?? defaultDir(project),
+    css: cssEntryPath(project),
+    items: []
+  };
+  const setup = setupVariant(catalog, config.framework);
+  const wiring = planWiring(project, config, addTailwind, setup.steps);
+  const tailwind = packagesToInstall(
+    project,
+    addTailwind ? tailwindPackages(project.setup, setup.packages.tailwind) : {}
+  );
+  if (options.install && !options.dryRun) {
+    installPackages(project, tailwind, { dev: true });
+  }
+  const installed = installItems(
+    catalog,
+    project,
+    config,
+    [SETUP],
+    null,
+    options
+  );
+  if (!options.dryRun) {
+    for (const change of wiring.changes) {
+      const target = path10.join(project.root, change.path);
+      mkdirSync2(path10.dirname(target), { recursive: true });
+      writeFileSync4(target, change.content);
+    }
+    writeConfig(cwd, config);
+  }
+  const packages = [...tailwind, ...installed.packages];
+  const [createVerb, editVerb] = options.dryRun ? ["Would create", "Would edit"] : ["Created", "Edited"];
+  const done = wiring.manual.length === 0 && settled(installed);
+  return {
+    data: {
+      setup: project.setup,
+      version: config.version,
+      dir: config.dir,
+      css: config.css,
+      dryRun: options.dryRun,
+      ...installed,
+      packages,
+      created: wiring.changes.filter((change) => change.created).map((change) => change.path),
+      edited: wiring.changes.filter((change) => !change.created).map((change) => change.path),
+      manual: wiring.manual
+    },
+    lines: [
+      `nxds ${config.version} in ${config.dir}`,
+      ...installLines(config, { ...installed, packages }, options),
+      ...wiring.changes.map(
+        (change) => `${change.created ? createVerb : editVerb} ${change.path}`
+      ),
+      ...manualLines(wiring.manual),
+      ...done && !options.dryRun ? [
+        `nxds is set up. Add a component with \`${CLI_COMMAND} add button\`.`
+      ] : []
+    ],
+    ok: done
+  };
+}
+function manualLines(manual) {
+  if (manual.length === 0) return [];
+  return [
+    `Finish these steps by hand, then run \`${CLI_COMMAND} doctor\`:`,
+    ...manual.map(({ file, step }) => `  ${file}: ${step}`)
+  ];
+}
+async function add(cwd, registry, names, options) {
+  const config = requireConfig(cwd);
+  const catalog = await loadRelease(registry, config.version);
+  const installed = installItems(
+    catalog,
+    readProject(cwd),
+    config,
+    names,
+    null,
+    options
+  );
+  if (!options.dryRun) writeConfig(cwd, config);
+  return {
+    data: { dryRun: options.dryRun, ...installed },
+    lines: [
+      ...installLines(config, installed, options),
+      ...installed.written.length === 0 && settled(installed) ? [
+        `${names.join(", ")} ${names.length === 1 ? "is" : "are"} already up to date.`
+      ] : []
+    ],
+    ok: settled(installed)
+  };
+}
+function filesOf(catalog, framework, names) {
+  return new Set(
+    resolveItems(catalog, framework, names).flatMap(
+      (item) => variantOf(item, framework).files.map((file) => file.path)
+    )
+  );
+}
+async function update(cwd, registry, options) {
+  const config = requireConfig(cwd);
+  const from = config.version;
+  const latest = await loadRelease(registry, "latest");
+  const { known, removed } = splitInstalled(latest, config.items);
+  const current = filesOf(latest, config.framework, known);
+  const previous = await fetchRelease(registry, from);
+  const installedBefore = previous ? filesOf(
+    previous,
+    config.framework,
+    splitInstalled(previous, config.items).known
+  ) : /* @__PURE__ */ new Set();
+  const unresolved = from === latest.version || options.overwrite ? [] : conflictedFiles(cwd, config, /* @__PURE__ */ new Set([...current, ...installedBefore]));
+  if (unresolved.length > 0) {
+    const data2 = {
+      ...emptyInstallResult(),
+      dryRun: options.dryRun,
+      from,
+      version: from,
+      unresolved,
+      removed: [],
+      orphaned: []
+    };
+    return {
+      data: data2,
+      lines: [
+        ...unresolved.map((file) => `Still conflicted: ${config.dir}/${file}`),
+        `Changed nothing, and nxds.json stays on ${from}. Resolve the <<<<<<< markers, then run \`${CLI_COMMAND} update\` again.`
+      ],
+      ok: false
+    };
+  }
+  const orphaned = [...installedBefore].filter(
+    (file) => !current.has(file) && existsSync9(path10.join(cwd, config.dir, file))
+  );
+  config.items = known;
+  const installed = installItems(
+    latest,
+    readProject(cwd),
+    config,
+    known,
+    previous && releaseFiles(previous, config.framework),
+    options
+  );
+  const stays = from !== latest.version && installed.skipped.length > 0;
+  if (!stays) config.version = latest.version;
+  if (!options.dryRun) writeConfig(cwd, config);
+  const data = {
+    dryRun: options.dryRun,
+    from,
+    version: config.version,
+    ...installed,
+    removed,
+    orphaned
+  };
+  return {
+    data,
+    lines: [
+      ...previous ? [] : [
+        `${registry} has no nxds ${from}, so every file that differs from ${latest.version} counts as changed.`
+      ],
+      ...installLines(config, installed, options),
+      ...removed.length > 0 ? [
+        `No longer in nxds, so dropped from nxds.json: ${removed.join(", ")}`
+      ] : [],
+      ...orphaned.map(
+        (file) => `No installed item uses ${config.dir}/${file} any more. Delete it once nothing in your app imports it.`
+      ),
+      stays ? `nxds.json stays on ${from} until every file above is resolved or replaced.` : `nxds ${from === latest.version ? "is on" : `${options.dryRun ? "would move" : "moved"} from ${from} to`} ${latest.version}.`
+    ],
+    ok: settled(installed)
+  };
+}
+
+// src/cli.ts
+function context(command) {
+  const { cwd, registry } = command.optsWithGlobals();
+  return {
+    cwd: path11.resolve(cwd ?? process.cwd()),
+    registry: resolveRegistry(registry)
+  };
+}
+function installOptions(command) {
+  const flags = command.opts();
+  return {
+    overwrite: flags.overwrite ?? false,
+    dryRun: flags.dryRun ?? false,
+    install: flags.install
+  };
+}
+function withInstallFlags(command) {
+  return command.option("--dry-run", "show what would change, without changing anything").option("--overwrite", "replace files that differ from nxds's copy").option("--no-install", "skip installing npm packages");
+}
+function program(done, write) {
+  const cli = new Command().configureOutput({
+    writeOut: write,
+    writeErr: write,
+    // Errors are printed once, by `main`, as text or JSON.
+    outputError: () => {
+    }
+  }).exitOverride().name(CLI_COMMAND).description("Add nxds to your app.").version("0.2.0", "-v, --version", "print the version").helpOption("-h, --help", "show help").helpCommand("help [command]", "show help for a command").option("--json", "print machine-readable JSON").option("--cwd <path>", "run in another folder").addOption(
+    new Option(
+      "--registry <url|path>",
+      "where to get nxds releases (default: https://nxds.dev/r)"
+    ).env("NXDS_REGISTRY_URL")
+  ).configureHelp({ showGlobalOptions: true }).addHelpText(
+    "after",
+    `
+Exit codes: 0 done, 1 error, 2 usage error, 3 done with something left for you (conflicts, kept files, manual steps, failed checks).
+Docs: https://nxds.dev/getting-started/install`
+  );
+  withInstallFlags(
+    cli.command("init").description("set up nxds: token CSS, provider, and the layout wiring").option(
+      "--dir <path>",
+      "nxds folder (default: components/nxds, or src/components/nxds)"
+    )
+  ).action(async (_options, command) => {
+    const { cwd, registry } = context(command);
+    const { dir } = command.opts();
+    done(await init(cwd, registry, { ...installOptions(command), dir }));
+  });
+  withInstallFlags(
+    cli.command("add").description("add components or blocks, and everything they need").argument("<items...>", "item names, such as button")
+  ).action(async (items, _options, command) => {
+    const { cwd, registry } = context(command);
+    done(await add(cwd, registry, items, installOptions(command)));
+  });
+  withInstallFlags(
+    cli.command("update").description(
+      "update every installed item to the latest release, merging nxds changes into your edits"
+    )
+  ).action(async (_options, command) => {
+    const { cwd, registry } = context(command);
+    done(await update(cwd, registry, installOptions(command)));
+  });
+  cli.command("list").description("list components and blocks").addOption(
+    new Option("--kind <kind>", "only this kind").choices([
+      "component",
+      "block"
+    ])
+  ).action(async (_options, command) => {
+    const { cwd, registry } = context(command);
+    const { kind } = command.opts();
+    done(await list(cwd, registry, kind));
+  });
+  cli.command("search").description("find items by name or description").argument("<term...>", "words to look for").action(async (term, _options, command) => {
+    const { cwd, registry } = context(command);
+    done(await search(cwd, registry, term.join(" ")));
+  });
+  cli.command("view").description("show an item's files, packages and docs link").argument("<item>", "item name").action(async (item, _options, command) => {
+    const { cwd, registry } = context(command);
+    done(await view(cwd, registry, item));
+  });
+  cli.command("info").description("show what the CLI detects in this app").action((_options, command) => {
+    done(info(context(command).cwd));
+  });
+  cli.command("diff").description("compare your nxds files with the latest release").argument("[items...]", "item names (default: every installed item)").action(async (items, _options, command) => {
+    const { cwd, registry } = context(command);
+    done(await diff(cwd, registry, items));
+  });
+  cli.command("doctor").description("check that nxds is wired up correctly").action(async (_options, command) => {
+    const { cwd, registry } = context(command);
+    done(await doctor(cwd, registry));
+  });
+  return cli;
+}
+function printed(text, key) {
+  const trimmed = text.trimEnd();
+  return {
+    exitCode: EXIT_CODES.ok,
+    data: { [key]: trimmed },
+    lines: [trimmed]
+  };
+}
+function commanderOutcome(error, printedText) {
+  if (error.code === "commander.version") {
+    return printed(printedText, "version");
+  }
+  if (error.exitCode === 0) return printed(printedText, "help");
+  if (error.code === "commander.help") {
+    return { exitCode: EXIT_CODES.usage, error: printedText.trimEnd() };
+  }
+  return {
+    exitCode: EXIT_CODES.usage,
+    error: `${error.message.replace(/^error: /, "")}
+Run \`${CLI_COMMAND} --help\` for the commands and options.`
+  };
+}
+async function outcome(argv) {
+  let result;
+  let printedText = "";
+  const cli = program(
+    (done) => {
+      result = done;
+    },
+    (text) => {
+      printedText += text;
+    }
+  );
+  try {
+    await cli.parseAsync(argv, { from: "user" });
+    if (!result) throw new Error("The command stored no result.");
+    return {
+      exitCode: result.ok ? EXIT_CODES.ok : EXIT_CODES.attention,
+      data: result.data,
+      lines: result.lines
+    };
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      return commanderOutcome(error, printedText);
+    }
+    if (error instanceof CliError) {
+      return { exitCode: error.exitCode, error: error.message };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : void 0;
+    return {
+      exitCode: EXIT_CODES.error,
+      error: message,
+      stack: stack ?? message
+    };
+  }
+}
+async function main(argv, output) {
+  const json = argv.includes("--json");
+  const result = await outcome(argv);
+  const ok = result.exitCode === EXIT_CODES.ok;
+  if (json) {
+    const body = "error" in result ? { ok: false, exitCode: result.exitCode, error: result.error } : { ok, exitCode: result.exitCode, data: result.data };
+    output.out(`${JSON.stringify(body, null, 2)}
+`);
+  } else if ("lines" in result) {
+    output.out(`${result.lines.join("\n")}
+`);
+  } else if (result.stack !== void 0) {
+    output.err(`${result.stack}
+`);
+  } else {
+    output.err(`${result.error}
+`);
+  }
+  return result.exitCode;
+}
+
+// src/index.ts
+process.exitCode = await main(process.argv.slice(2), {
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text)
+});