nxds-cli 0.0.0 → 0.2.0

package/dist/index.js

@@ -1,27 +1,146 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import path10 from "path";
-import { parseArgs } from "util";
+// 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 as existsSync2 } from "fs";
+import { existsSync } from "fs";
 import path2 from "path";
-import { valid as valid2, validRange } from "semver";
+import { EnvHttpProxyAgent, fetch } from "undici";
 
-// src/config.ts
-import { existsSync, writeFileSync } from "fs";
-import path from "path";
-import { valid } from "semver";
+// 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 text2 = readFileSync(file, "utf8");
+  const text = readFileSync(file, "utf8");
   try {
-    return JSON.parse(text2);
+    return JSON.parse(text);
   } catch (error) {
     throw new CliError(
       `${file} is not valid JSON (${error.message}). Fix it, then run the command again.`
@@ -29,57 +148,11 @@ function readJson(file) {
   }
 }
 
-// src/config.ts
-var CONFIG_FILE = "nxds.json";
-function configPath(root) {
-  return path.join(root, CONFIG_FILE);
-}
-function projectPath(value) {
-  const normalized = path.posix.normalize(value.replaceAll("\\", "/")).replace(/\/+$/, "");
-  if (path.posix.isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized) || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
-    return null;
-  }
-  return normalized;
-}
-function invalidField(value) {
-  if (value.framework !== "react") return "framework";
-  if (typeof value.version !== "string" || valid(value.version) !== value.version)
-    return "version";
-  for (const field of ["dir", "css"]) {
-    const file = value[field];
-    if (typeof file !== "string" || projectPath(file) !== file) return field;
-  }
-  const { items } = value;
-  if (!Array.isArray(items) || !items.every((item) => typeof item === "string"))
-    return "items";
-  return null;
-}
-function readConfig(root) {
-  const file = configPath(root);
-  if (!existsSync(file)) return null;
-  const value = readJson(file);
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new CliError(`${CONFIG_FILE} must be a JSON object.`);
-  }
-  const field = invalidField(value);
-  if (field === null) return value;
-  throw new CliError(
-    `${CONFIG_FILE} has a missing or invalid "${field}". Fix it, or delete ${CONFIG_FILE} and run \`nxds init\` again.`
-  );
-}
-function requireConfig(root) {
-  const config = readConfig(root);
-  if (config) return config;
-  throw new CliError(`nxds is not set up here. Run \`nxds init\` first.`);
-}
-function writeConfig(root, config) {
-  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}
-`);
-}
-
 // 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);
 }
@@ -87,13 +160,26 @@ 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);
+    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} (${error.message}). Check your connection, then run the command again.`
+      `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;
@@ -105,7 +191,7 @@ async function fetchJson(url) {
   try {
     return await response.json();
   } catch (error) {
-    throw new CliError(
+    throw timeoutError(url, error) ?? new CliError(
       `${url} is not valid JSON (${error.message}). Run the command again later.`
     );
   }
@@ -116,104 +202,45 @@ function registryLocation(registry, file) {
 async function readRegistryFile(registry, file) {
   const location = registryLocation(registry, file);
   if (isUrl(registry)) return fetchJson(location);
-  return existsSync2(location) ? readJson(location) : null;
-}
-var KINDS = /* @__PURE__ */ new Set(["setup", "component", "block"]);
-var STEPS = new Set(
-  Object.keys({
-    "add-css-import": true,
-    "add-head-script": true,
-    "wrap-root-with-provider": true
-  })
-);
-var NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
-function isRange(value) {
-  return typeof value === "string" && /^[ -~]+$/.test(value) && value === value.trim() && validRange(value) !== null;
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return existsSync(location) ? readJson(location) : null;
 }
-function isStrings(value) {
-  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
-}
-function fileProblem(file) {
-  if (!isRecord(file) || typeof file.content !== "string") {
-    return "has a file without content";
-  }
-  if (typeof file.path !== "string" || projectPath(file.path) !== file.path) {
-    return `has a file path outside the nxds folder: ${String(file.path)}`;
-  }
-  return null;
-}
-function variantProblem(variant, kind) {
-  if (!isRecord(variant)) return "has a variant that is not an object";
-  const { packages } = variant;
-  if (!isRecord(packages) || !isRecord(packages.npm) || !Object.entries(packages.npm).every(
-    ([name, range]) => NPM_NAME.test(name) && isRange(range)
-  ) || kind === "setup" && !isRange(packages.tailwind)) {
-    return 'has invalid "packages"';
-  }
-  for (const field of ["items", "css"]) {
-    if (!isStrings(variant[field])) return `has invalid "${field}"`;
-  }
-  const { steps } = variant;
-  if (!Array.isArray(steps) || !steps.every((step) => STEPS.has(step))) {
-    return 'has invalid "steps"';
-  }
-  if (!Array.isArray(variant.files)) return 'has invalid "files"';
-  return variant.files.map(fileProblem).find(Boolean) ?? null;
-}
-function itemProblem(item) {
-  if (!isRecord(item) || typeof item.name !== "string") {
-    return "has an item without a name";
-  }
-  const fields = ["title", "description", "docs"];
-  if (!KINDS.has(item.kind) || fields.some((field) => typeof item[field] !== "string") || !isRecord(item.variants)) {
-    return `"${item.name}" is not a catalog item`;
-  }
-  const problem = Object.values(item.variants).map((variant) => variantProblem(variant, item.kind)).find(Boolean);
-  return problem ? `"${item.name}" ${problem}` : null;
-}
-function releaseProblem(value, version) {
-  if (!isRecord(value)) return "it is not a JSON object";
-  if (value.schema !== 1) return 'its "schema" is not 1';
-  if (typeof value.version !== "string" || valid2(value.version) !== value.version) {
-    return 'its "version" is not a release version';
-  }
-  if (version !== "latest" && value.version !== version) {
-    return `it holds nxds ${value.version}`;
-  }
-  if (!isStrings(value.frameworks)) return 'its "frameworks" is invalid';
-  if (!Array.isArray(value.items)) return 'its "items" is invalid';
-  return value.items.map(itemProblem).find(Boolean) ?? 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 (isRecord(value) && typeof value.schema === "number" && value.schema > 1) {
+  if (isNewerSchema(value)) {
+    const release = version === "latest" ? "The latest nxds release" : `nxds ${version}`;
     throw new CliError(
-      `nxds ${version} needs a newer CLI. Run \`npx nxds@latest\` instead.`
+      `${release} needs a newer nxds-cli than ${"0.2.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
     );
   }
-  const problem = releaseProblem(value, version);
-  if (problem === null) return value;
-  throw new CliError(
-    `${registryLocation(registry, file)} is not a valid nxds release: ${problem}. Check \`--registry\`, or run the command again later.`
+  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 \`nxds update\` to move to the latest release.`
+    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 CliError(
-    `nxds ${catalog.version} has no item named "${name}". Run \`nxds search ${name}\` to find the right name, or \`nxds update\` if it's newer.`
+  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) {
@@ -258,15 +285,60 @@ function splitInstalled(catalog, installed) {
   };
 }
 
+// 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 path4 from "path";
+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 path3 from "path";
+import path4 from "path";
 import { minVersion, satisfies, validRange as validRange2 } from "semver";
 var ADD_COMMAND = {
   npm: ["install"],
@@ -287,11 +359,11 @@ function packagesToInstall(project, packages) {
 function installedVersion(project, name) {
   let dir = project.root;
   for (; ; ) {
-    const manifest = path3.join(dir, "node_modules", name, "package.json");
+    const manifest = path4.join(dir, "node_modules", name, "package.json");
     if (existsSync3(manifest)) {
       return readJson(manifest).version ?? null;
     }
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
@@ -307,11 +379,11 @@ function installPackages(project, specs, { dev }) {
     cwd: project.root,
     stdio: ["ignore", 2, 2]
   };
-  const run2 = process.platform === "win32" ? spawnSync(
+  const run = process.platform === "win32" ? spawnSync(
     [project.packageManager, ...args.map((arg) => `"${arg}"`)].join(" "),
     { ...options, shell: true }
   ) : spawnSync(project.packageManager, args, options);
-  if (run2.status !== 0) {
+  if (run.status !== 0) {
     throw new CliError(
       `\`${project.packageManager} ${args.join(" ")}\` failed. Fix the error above, then run the same nxds command again.`
     );
@@ -338,7 +410,7 @@ var VITE_CONFIGS = [
   "vite.config.js"
 ];
 function firstExisting(root, candidates) {
-  return candidates.find((file) => existsSync4(path4.join(root, file)));
+  return candidates.find((file) => existsSync4(path5.join(root, file)));
 }
 function detectSetup(root, dependencies) {
   if ("next" in dependencies && firstExisting(
@@ -353,10 +425,10 @@ function detectSetup(root, dependencies) {
   return null;
 }
 function readProject(root) {
-  const manifestPath = path4.join(root, "package.json");
+  const manifestPath = path5.join(root, "package.json");
   if (!existsSync4(manifestPath)) {
     throw new CliError(
-      `No package.json in ${root}. Run nxds from your app's root folder, or pass --cwd.`
+      `No package.json in ${root}. Run \`${CLI_COMMAND}\` from your app's root folder, or pass --cwd.`
     );
   }
   const manifest = readJson(manifestPath);
@@ -367,9 +439,9 @@ function readProject(root) {
   return {
     root,
     setup: detectSetup(root, dependencies),
-    packageManager: LOCKFILES.find(([file]) => existsSync4(path4.join(root, file)))?.[1] ?? "npm",
-    usesSrc: existsSync4(path4.join(root, "src")),
-    typescript: existsSync4(path4.join(root, "tsconfig.json")),
+    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
   };
 }
@@ -385,7 +457,6 @@ function majorVersion(project, name) {
 }
 
 // src/commands/browse.ts
-var KINDS2 = ["component", "block"];
 function appRelease(cwd, registry) {
   return loadRelease(registry, readConfig(cwd)?.version ?? "latest");
 }
@@ -397,8 +468,8 @@ function summary(item) {
     description: item.description
   };
 }
-function firstSentence(text2) {
-  return text2.split(/(?<=\.)\s/)[0]?.replaceAll("`", "") ?? text2;
+function firstSentence(text) {
+  return text.split(/(?<=\.)\s/)[0]?.replaceAll("`", "") ?? text;
 }
 function summaryLines(items) {
   const width = Math.max(...items.map((item) => item.name.length));
@@ -407,17 +478,12 @@ function summaryLines(items) {
   );
 }
 async function list(cwd, registry, kind) {
-  if (kind !== void 0 && !KINDS2.includes(kind)) {
-    throw new CliError(`--kind takes ${KINDS2.join(" or ")}.`);
-  }
   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) {
-  if (!query)
-    throw new CliError("Give a search term, such as `nxds search date`.");
   const needle = query.toLowerCase();
   const rank = (item) => {
     if (item.name.includes(needle)) return 0;
@@ -441,11 +507,10 @@ function projectFramework(cwd, catalog) {
   const [only, ...others] = catalog.frameworks;
   if (only && others.length === 0) return only;
   throw new CliError(
-    "This release has several frameworks. Run `nxds init` first, so nxds knows which one your app uses."
+    `This release has several frameworks. Run \`${CLI_COMMAND} init\` first, so nxds knows which one your app uses.`
   );
 }
 async function view(cwd, registry, name) {
-  if (!name) throw new CliError("Name an item, such as `nxds view button`.");
   const catalog = await appRelease(cwd, registry);
   const item = findItem(catalog, name);
   const variant = variantOf(item, projectFramework(cwd, catalog));
@@ -497,7 +562,7 @@ function info(cwd) {
       `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 `nxds init`.",
+      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"}`
       ] : []
@@ -509,42 +574,104 @@ function info(cwd) {
 // src/commands/check.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync7, readFileSync as readFileSync4 } from "fs";
-import path7 from "path";
+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 path5 from "path";
-var NO_PREVIOUS = /* @__PURE__ */ new Map();
+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 = path5.join(root, config.dir, file.path);
+  const target = path6.join(root, config.dir, file.path);
   if (!existsSync5(target)) return "missing";
   const onDisk = readFileSync2(target, "utf8");
-  if (onDisk === file.content) return "current";
-  return previous.get(file.path) === onDisk ? "outdated" : "changed";
-}
-function writeFiles(root, config, files, previous, { overwrite, dryRun }) {
-  const result = { written: [], unchanged: [], skipped: [] };
+  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 (state === "changed" && !overwrite) {
+    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;
     }
-    result.written.push(file.path);
-    if (dryRun) continue;
-    const target = path5.join(root, config.dir, file.path);
-    mkdirSync(path5.dirname(target), { recursive: true });
-    writeFileSync2(target, file.content);
+    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 = path5.relative(path5.dirname(fromFile), toFile).split(path5.sep).join("/");
+  const relative = path6.relative(path6.dirname(fromFile), toFile).split(path6.sep).join("/");
   return relative.startsWith(".") ? relative : `./${relative}`;
 }
 
@@ -561,7 +688,7 @@ import {
   isSpreadElement
 } from "@babel/types";
 import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import path6 from "path";
+import path7 from "path";
 
 // src/setup/source-edit.ts
 import { parse } from "@babel/parser";
@@ -611,24 +738,24 @@ function findJsx(root, name) {
 }
 function applyInsertions(source, insertions) {
   return [...insertions].sort((a, b) => b.at - a.at).reduce(
-    (text2, { at, text: inserted }) => text2.slice(0, at) + inserted + text2.slice(at),
+    (text, { at, text: inserted }) => text.slice(0, at) + inserted + text.slice(at),
     source
   );
 }
-function importInsertion(source, program, lines) {
-  const imports = program.body.filter((node) => isImportDeclaration(node));
+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 text2 = lines.map((line) => quote === '"' ? line.replaceAll("'", '"') : line).map((line) => semicolons ? line : line.replace(/;$/, "")).join("\n");
+  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: `
-${text2}` };
-  const lastDirective = program.directives.at(-1);
+${text}` };
+  const lastDirective = program2.directives.at(-1);
   if (lastDirective) return { at: endOf(lastDirective), text: `
 
-${text2}` };
-  return { at: 0, text: `${text2}
+${text}` };
+  return { at: 0, text: `${text}
 
 ` };
 }
@@ -667,7 +794,7 @@ function tailwindPackages(setup, range) {
 }
 function appDir(project) {
   const dir = APP_DIRS.find(
-    (candidate) => existsSync6(path6.join(project.root, candidate, "layout.tsx"))
+    (candidate) => existsSync6(path7.join(project.root, candidate, "layout.tsx"))
   );
   if (!dir)
     throw new CliError("No app/layout.tsx or src/app/layout.tsx found.");
@@ -683,7 +810,7 @@ function cssEntryPath(project) {
   return `${entryDir(project)}/nxds.css`;
 }
 function read(project, file) {
-  return readFileSync3(path6.join(project.root, file), "utf8");
+  return readFileSync3(path7.join(project.root, file), "utf8");
 }
 function cssEntry(config, withPreflight) {
   const tokens = relativeImport(config.css, `${config.dir}/tailwind/nxds.css`);
@@ -722,8 +849,8 @@ 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 program = parseModule(source, layout);
-  const html = findJsx(program, "html");
+  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) {
@@ -785,15 +912,15 @@ ${htmlIndent}${step}</head>`
     imports.push("import { defaultAppearance } from './appearance-state';");
   }
   if (imports.length === 0) return NO_CHANGES;
-  insertions.push(importInsertion(source, program, imports));
+  insertions.push(importInsertion(source, program2, imports));
   return {
     changes: [editedFile(layout, applyInsertions(source, insertions))],
     manual: []
   };
 }
-function renderedElement(program) {
+function renderedElement(program2) {
   const call = findNode(
-    program,
+    program2,
     (node) => isCallExpression(node) && isMemberExpression(node.callee) && isIdentifier(node.callee.property, { name: "render" }) && isJSXElement2(node.arguments[0])
   );
   return call?.arguments[0];
@@ -803,12 +930,12 @@ function wireViteEntry(project, config, steps) {
   if (!entry) throw new CliError("No src/main.tsx found.");
   const source = read(project, entry);
   if (source.includes("NxdsAppearanceProvider")) return NO_CHANGES;
-  const program = parseModule(source, entry);
+  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(program);
+    const app = renderedElement(program2);
     if (!app) {
       return {
         changes: [],
@@ -836,7 +963,7 @@ ${indent}</NxdsAppearanceProvider>` }
     );
   }
   if (imports.length === 0) return NO_CHANGES;
-  insertions.push(importInsertion(source, program, imports));
+  insertions.push(importInsertion(source, program2, imports));
   return {
     changes: [editedFile(entry, applyInsertions(source, insertions))],
     manual: []
@@ -863,8 +990,8 @@ export function nxdsAppearance(): Plugin {
   };
 }
 `;
-function configObject(program) {
-  const declaration = program.body.find(
+function configObject(program2) {
+  const declaration = program2.body.find(
     (node) => isExportDefaultDeclaration(node)
   )?.declaration;
   if (isObjectExpression(declaration)) return declaration;
@@ -894,11 +1021,11 @@ var NXDS_VITE_PLUGIN = {
 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(path6.join(project.root, "nxds.vite.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(path6.join(project.root, configFile)) ? read(project, configFile) : "";
-  const program = source ? parseModule(source, configFile) : void 0;
-  const object = program && configObject(program);
+  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] : [],
@@ -938,8 +1065,8 @@ function wireViteConfig(project, addTailwind, steps) {
       step: `Add resolve.alias ${VITE_ALIAS}, so imports like @/components/nxds/... resolve.`
     });
   }
-  if (program && insertions.length > 0) {
-    insertions.push(importInsertion(source, program, imports));
+  if (program2 && insertions.length > 0) {
+    insertions.push(importInsertion(source, program2, imports));
     changes.push(editedFile(configFile, applyInsertions(source, insertions)));
   }
   return { changes, manual };
@@ -984,8 +1111,8 @@ var ESLINT_CONFIGS = [
   "eslint.config.mjs",
   "eslint.config.ts"
 ];
-function exportedConfigs(program) {
-  const declaration = program.body.find(
+function exportedConfigs(program2) {
+  const declaration = program2.body.find(
     (node) => isExportDefaultDeclaration(node)
   )?.declaration;
   if (isArrayExpression(declaration)) return declaration.elements;
@@ -1057,7 +1184,7 @@ function wireNextTailwind(project) {
   };
 }
 function createdUnlessExists(project, file, content) {
-  if (existsSync6(path6.join(project.root, file))) return NO_CHANGES;
+  if (existsSync6(path7.join(project.root, file))) return NO_CHANGES;
   return { changes: [{ path: file, content, created: true }], manual: [] };
 }
 function planWiring(project, config, addTailwind, setupSteps) {
@@ -1096,34 +1223,50 @@ 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) : NO_PREVIOUS;
+  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) => ({
-      item: item.name,
-      path: file.path,
-      state: fileState(cwd, config, file, previousFiles)
-    }))
+    (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");
-  const advice = {
-    outdated: "`nxds update` replaces it",
-    changed: "differs from nxds's copy; `nxds update --overwrite` replaces it",
-    missing: "`nxds update` restores it"
-  };
   return {
     data: { version: config.version, latest: latest.version, files, removed },
     lines: [
       ...differing.map(
-        (file) => `${file.state.padEnd(8)}  ${file.path}  (${advice[file.state]})`
+        (file) => `${file.state.padEnd(10)}  ${file.path}  (${file.advice})`
       ),
       ...removed.map(
-        (name) => `removed   ${name}  (no longer in nxds; \`nxds update\` drops it)`
+        (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}.`] : []
     ],
@@ -1133,7 +1276,7 @@ async function diff(cwd, registry, names) {
 function tailwindMessage(project) {
   const declared = project.dependencies.tailwindcss;
   if (declared === void 0) {
-    return "Tailwind 4 is not installed. Run `nxds init`.";
+    return `Tailwind 4 is not installed. Run \`${CLI_COMMAND} init\`.`;
   }
   const tailwindMajor = majorVersion(project, "tailwindcss");
   if (tailwindMajor === 4) return `tailwindcss ${declared}`;
@@ -1143,14 +1286,14 @@ function tailwindMessage(project) {
   return `tailwindcss ${declared}. nxds needs Tailwind CSS 4.`;
 }
 function read2(root, file) {
-  if (!file || !existsSync7(path7.join(root, file))) return "";
-  return readFileSync4(path7.join(root, file), "utf8");
+  if (!file || !existsSync7(path8.join(root, file))) return "";
+  return readFileSync4(path8.join(root, file), "utf8");
 }
 function sourcesNxdsDir(config, css) {
-  const entryDir2 = path7.posix.dirname(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 = path7.posix.join(entryDir2, base).replace(/\/+$/, "");
+    const folder = path8.posix.join(entryDir2, base).replace(/\/+$/, "");
     return folder === "." || /^\.\.(\/\.\.)*$/.test(folder) || config.dir === folder || config.dir.startsWith(`${folder}/`);
   });
 }
@@ -1190,7 +1333,7 @@ async function doctor(cwd, registry) {
   check(
     "config",
     config !== null,
-    config ? "nxds.json found" : "No nxds.json. Run `nxds init`."
+    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.");
@@ -1200,7 +1343,7 @@ async function doctor(cwd, registry) {
   check(
     "release",
     catalog !== null,
-    catalog ? `Files come from nxds ${config.version}` : `${registry} has no nxds ${config.version}. Run \`nxds update\`.`
+    catalog ? `Files come from nxds ${config.version}` : `${registry} has no nxds ${config.version}. Run \`${CLI_COMMAND} update\`.`
   );
   check(
     "tailwind",
@@ -1212,7 +1355,7 @@ async function doctor(cwd, registry) {
   check(
     "css entry",
     importsTokens,
-    !css ? `${config.css} is missing. Run \`nxds init\`.` : importsTokens ? `${config.css} imports the nxds tokens` : `${config.css} does not import ${config.dir}/tailwind/nxds.css. Add the @import back.`
+    !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(
@@ -1222,7 +1365,7 @@ async function doctor(cwd, registry) {
   );
   const entry = project.setup === "next-app" ? `${entryDir(project)}/layout.tsx` : findFile(project, VITE_ENTRIES);
   const entrySource = read2(cwd, entry);
-  const cssFile = path7.basename(config.css);
+  const cssFile = path8.basename(config.css);
   const importsCss = entrySource.includes(cssFile);
   check(
     "css import",
@@ -1239,31 +1382,43 @@ async function doctor(cwd, registry) {
   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 `nxds init`."
+    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 \`nxds update\`.`
+    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(path7.join(cwd, config.dir, file.path))
+      (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 \`nxds add\` for those items.`
+    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 \`nxds update\`, then your package manager's install.`
+    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);
 }
@@ -1283,14 +1438,27 @@ function report(checks) {
 
 // src/commands/install.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
-import path9 from "path";
+import path10 from "path";
 
 // src/install.ts
 import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import path8 from "path";
+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 = path8.join(project.root, config.css);
+  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) {
@@ -1311,7 +1479,7 @@ function installItems(catalog, project, config, names, previous, options) {
     config,
     [...files.values()],
     previous,
-    options
+    { ...options, version: catalog.version }
   );
   const packages = packagesToInstall(
     project,
@@ -1347,6 +1515,15 @@ function installLines(config, result, 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.`
     ),
@@ -1356,10 +1533,13 @@ function installLines(config, result, options) {
     )
   ];
 }
+function settled(result) {
+  return result.skipped.length === 0 && result.conflicted.length === 0 && result.unresolved.length === 0;
+}
 function nxdsDir(dir) {
-  const normalized = projectPath(dir);
+  const normalized = relativePath(dir);
   if (normalized) return normalized;
-  throw new CliError(
+  throw new UsageError(
     `--dir takes a folder inside your app, such as components/nxds, not "${dir}".`
   );
 }
@@ -1380,7 +1560,7 @@ async function init(cwd, registry, options) {
   const project = readProject(cwd);
   if (!project.setup) {
     throw new CliError(
-      "nxds init supports Next.js App Router and Vite + React apps. For other setups, follow the manual steps at https://nxds.dev/getting-started/install."
+      `\`${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) {
@@ -1419,20 +1599,20 @@ async function init(cwd, registry, options) {
     project,
     config,
     [SETUP],
-    NO_PREVIOUS,
+    null,
     options
   );
   if (!options.dryRun) {
     for (const change of wiring.changes) {
-      const target = path9.join(project.root, change.path);
-      mkdirSync2(path9.dirname(target), { recursive: true });
+      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;
+  const done = wiring.manual.length === 0 && settled(installed);
   return {
     data: {
       setup: project.setup,
@@ -1453,7 +1633,9 @@ async function init(cwd, registry, options) {
         (change) => `${change.created ? createVerb : editVerb} ${change.path}`
       ),
       ...manualLines(wiring.manual),
-      ...done && !options.dryRun ? ["nxds is set up. Add a component with `nxds add button`."] : []
+      ...done && !options.dryRun ? [
+        `nxds is set up. Add a component with \`${CLI_COMMAND} add button\`.`
+      ] : []
     ],
     ok: done
   };
@@ -1461,14 +1643,11 @@ async function init(cwd, registry, options) {
 function manualLines(manual) {
   if (manual.length === 0) return [];
   return [
-    "Finish these steps by hand, then run `nxds doctor`:",
+    `Finish these steps by hand, then run \`${CLI_COMMAND} doctor\`:`,
     ...manual.map(({ file, step }) => `  ${file}: ${step}`)
   ];
 }
 async function add(cwd, registry, names, options) {
-  if (names.length === 0) {
-    throw new CliError("Name at least one item, such as `nxds add button`.");
-  }
   const config = requireConfig(cwd);
   const catalog = await loadRelease(registry, config.version);
   const installed = installItems(
@@ -1476,7 +1655,7 @@ async function add(cwd, registry, names, options) {
     readProject(cwd),
     config,
     names,
-    NO_PREVIOUS,
+    null,
     options
   );
   if (!options.dryRun) writeConfig(cwd, config);
@@ -1484,11 +1663,11 @@ async function add(cwd, registry, names, options) {
     data: { dryRun: options.dryRun, ...installed },
     lines: [
       ...installLines(config, installed, options),
-      ...installed.written.length === 0 && installed.skipped.length === 0 ? [
+      ...installed.written.length === 0 && settled(installed) ? [
         `${names.join(", ")} ${names.length === 1 ? "is" : "are"} already up to date.`
       ] : []
     ],
-    ok: true
+    ok: settled(installed)
   };
 }
 function filesOf(catalog, framework, names) {
@@ -1498,24 +1677,40 @@ function filesOf(catalog, framework, names) {
     )
   );
 }
-async function update(cwd, registry, names, options) {
-  if (names.length > 0) {
-    throw new CliError(
-      "`nxds update` updates every installed item, so one app never mixes two releases. Run it without item names."
-    );
-  }
+async function update(cwd, registry, options) {
   const config = requireConfig(cwd);
+  const from = config.version;
   const latest = await loadRelease(registry, "latest");
-  const previous = await fetchRelease(registry, config.version);
   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(path9.join(cwd, config.dir, file))
+    (file) => !current.has(file) && existsSync9(path10.join(cwd, config.dir, file))
   );
   config.items = known;
   const installed = installItems(
@@ -1523,22 +1718,22 @@ async function update(cwd, registry, names, options) {
     readProject(cwd),
     config,
     known,
-    previous ? releaseFiles(previous, config.framework) : NO_PREVIOUS,
+    previous && releaseFiles(previous, config.framework),
     options
   );
-  const from = config.version;
   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: {
-      dryRun: options.dryRun,
-      from,
-      version: config.version,
-      ...installed,
-      removed,
-      orphaned
-    },
+    data,
     lines: [
       ...previous ? [] : [
         `${registry} has no nxds ${from}, so every file that differs from ${latest.version} counts as changed.`
@@ -1550,121 +1745,184 @@ async function update(cwd, registry, names, options) {
       ...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 kept file is replaced.` : `nxds ${from === latest.version ? "is on" : `${options.dryRun ? "would move" : "moved"} from ${from} to`} ${latest.version}.`
+      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: !stays
+    ok: settled(installed)
   };
 }
 
-// src/index.ts
-var HELP = `nxds: add nxds to your app.
-
-Usage
-  nxds init               Set up nxds: token CSS, provider, and the layout wiring
-  nxds add <item...>      Add components or blocks, and everything they need
-  nxds list [--kind k]    List components and blocks (k: component, block)
-  nxds search <term>      Find items by name or description
-  nxds view <item>        Show an item's files, packages and docs link
-  nxds info               Show what the CLI detects in this app
-  nxds update             Update every installed item to the latest release
-  nxds diff [item...]     Compare your nxds files with the latest release
-  nxds doctor             Check that nxds is wired up correctly
-
-Options
-  --json                 Print machine-readable JSON
-  --dry-run              Show what would change, without changing anything
-  --overwrite            Replace files that differ from nxds's copy (add, update)
-  --no-install           Skip installing npm packages (init, add, update)
-  --dir <path>           nxds folder for init (default: components/nxds, or src/components/nxds)
-  --cwd <path>           Run in another folder
-  --registry <url|path>  Where to get nxds releases (default: https://nxds.dev/r)
-  -v, --version          Print the version
-
-Docs: https://nxds.dev/getting-started/install`;
-var OPTIONS = {
-  json: { type: "boolean", default: false },
-  "dry-run": { type: "boolean", default: false },
-  overwrite: { type: "boolean", default: false },
-  "no-install": { type: "boolean", default: false },
-  dir: { type: "string" },
-  cwd: { type: "string" },
-  registry: { type: "string" },
-  kind: { type: "string" },
-  help: { type: "boolean", short: "h", default: false },
-  version: { type: "boolean", short: "v", default: false }
-};
-function parseCommandLine() {
-  try {
-    return parseArgs({ allowPositionals: true, options: OPTIONS });
-  } catch (error) {
-    throw new CliError(
-      `${error.message}
-Run \`nxds --help\` for the options.`
-    );
-  }
+// 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 text(data, output) {
-  return { data, lines: [output], ok: true };
-}
-async function run(values, positionals) {
-  if (values.version) return text({ version: "0.0.0" }, "0.0.0");
-  if (values.help || positionals[0] === "help")
-    return text({ help: HELP }, HELP);
-  const [command, ...args] = positionals;
-  const cwd = path10.resolve(values.cwd ?? process.cwd());
-  const registry = resolveRegistry(values.registry);
-  const installOptions = {
-    overwrite: values.overwrite,
-    dryRun: values["dry-run"],
-    install: !values["no-install"]
+function printed(text, key) {
+  const trimmed = text.trimEnd();
+  return {
+    exitCode: EXIT_CODES.ok,
+    data: { [key]: trimmed },
+    lines: [trimmed]
   };
-  switch (command) {
-    case "init":
-      return init(cwd, registry, { ...installOptions, dir: values.dir });
-    case "add":
-      return add(cwd, registry, args, installOptions);
-    case "update":
-      return update(cwd, registry, args, installOptions);
-    case "list":
-      return list(cwd, registry, values.kind);
-    case "search":
-      return search(cwd, registry, args.join(" "));
-    case "view":
-      return view(cwd, registry, args[0]);
-    case "info":
-      return info(cwd);
-    case "diff":
-      return diff(cwd, registry, args);
-    case "doctor":
-      return doctor(cwd, registry);
-    default:
-      throw new CliError(
-        command ? `Unknown command "${command}". Run \`nxds --help\`.` : HELP
-      );
+}
+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 main() {
-  const json = process.argv.includes("--json");
+async function outcome(argv) {
+  let result;
+  let printedText = "";
+  const cli = program(
+    (done) => {
+      result = done;
+    },
+    (text) => {
+      printedText += text;
+    }
+  );
   try {
-    const { values, positionals } = parseCommandLine();
-    const result = await run(values, positionals);
-    const output = json ? JSON.stringify({ ok: result.ok, data: result.data }, null, 2) : result.lines.join("\n");
-    process.stdout.write(`${output}
-`);
-    process.exitCode = result.ok ? 0 : 1;
+    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) {
-    process.exitCode = 1;
-    const message = error instanceof Error ? error.message : String(error);
-    if (json) {
-      process.stdout.write(
-        `${JSON.stringify({ ok: false, error: message }, null, 2)}
-`
-      );
-    } else if (error instanceof CliError) {
-      console.error(message);
-    } else {
-      console.error(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;
 }
-await main();
+
+// src/index.ts
+process.exitCode = await main(process.argv.slice(2), {
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text)
+});