layro-cli 0.3.0 → 0.5.0

package/dist/layro.mjs

@@ -3,23 +3,1552 @@
 // src/index.ts
 import { parseArgs } from "node:util";
 
+// src/add.ts
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { constants, existsSync as existsSync3, readFileSync, unlinkSync } from "node:fs";
+import { mkdir, open, readFile as readFile3, rename, unlink } from "node:fs/promises";
+import { delimiter, dirname as dirname4, join as join3, relative as relative4, resolve as resolve4 } from "node:path";
+
+// src/init.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/install-project.ts
+import { existsSync } from "node:fs";
+import { readFile, realpath as realpath2, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname as dirname3, isAbsolute, join, relative as relative3, resolve as resolve3 } from "node:path";
+
+// src/install-safety.ts
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+
+// src/ui.ts
+import { createInterface } from "node:readline/promises";
+import { stripVTControlCharacters } from "node:util";
+
+// src/install-error.ts
+var CliError = class extends Error {
+};
+
+// src/ui.ts
+var safeText = (text) => stripVTControlCharacters(text).replace(
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject hostile control characters.
+  /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g,
+  " "
+);
+function terminalData(value) {
+  if (typeof value === "string") return safeText(value);
+  if (Array.isArray(value)) return value.map(terminalData);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, terminalData(entry)])
+    );
+  return value;
+}
+var color = process.stdout.isTTY && process.env.NO_COLOR === void 0;
+var paint = (code) => (text) => color ? `\x1B[${code}m${text}\x1B[0m` : text;
+var bold = paint(1);
+var dim = paint(2);
+var green = paint(32);
+var red = paint(31);
+var yellow = paint(33);
+var say = (text = "") => process.stdout.write(`${text}
+`);
+var warn = (text) => process.stderr.write(`${text}
+`);
+var canAsk = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+async function ask(question, fallback = "") {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const hint = fallback ? dim(` (${fallback})`) : "";
+    const answer = (await rl.question(`${question}${hint}: `)).trim();
+    return answer || fallback;
+  } catch (error) {
+    if (error.name === "AbortError")
+      throw new CliError("Cancelled.");
+    throw error;
+  } finally {
+    rl.close();
+  }
+}
+async function confirm(question) {
+  const answer = (await ask(`${question} ${dim("[Y/n]")}`)).toLowerCase();
+  return answer === "" || answer === "y" || answer === "yes";
+}
+async function choose(question, options, fallback) {
+  options.forEach((option, i) => {
+    say(`  ${dim(String(i + 1).padStart(2))}  ${option.label}`);
+  });
+  const fallbackIndex = options.findIndex((o) => o.value === fallback);
+  for (; ; ) {
+    const answer = await ask(
+      question,
+      fallbackIndex >= 0 ? String(fallbackIndex + 1) : ""
+    );
+    const byNumber = options[Number(answer) - 1];
+    const byValue = options.find((o) => o.value === answer);
+    const picked = byNumber ?? byValue;
+    if (picked) return picked.value;
+    say(red(`Pick a number from 1 to ${options.length}.`));
+  }
+}
+
+// src/install-data.ts
+function safePath(path) {
+  if (!path || path.length > 500 || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject hostile control characters.
+  /[\\:<>"|?*\x00-\x1f\x7f]/.test(path) || path.startsWith("/") || path.split("/").some(
+    (part) => !part || part === "." || part === ".." || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part) || part.startsWith(".") || /^(node_modules|package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|npm-shrinkwrap\.json|.*\.ya?ml|.*\.cmd|.*\.bat|.*\.ps1|.*\.sh)$/i.test(
+      part
+    )
+  ))
+    throw new CliError(`Refused unsafe file path: ${JSON.stringify(path)}.`);
+  return path;
+}
+var NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+var VERSION_TOKEN = "(?:[0-9]+|[xX*])(?:\\.(?:[0-9]+|[xX*])){0,2}(?:-[0-9a-zA-Z.-]+)?(?:\\+[0-9a-zA-Z.-]+)?";
+var RANGE = new RegExp(
+  `^(?:(?:\\^|~|>=?|<=?|=)?\\s*${VERSION_TOKEN})(?:(?:\\s+|\\s*\\|\\|\\s*|\\s+-\\s+)(?:\\^|~|>=?|<=?|=)?\\s*${VERSION_TOKEN})*$`
+);
+function packageSpec(spec) {
+  const at = spec.indexOf("@", 1);
+  const name = at < 0 ? spec : spec.slice(0, at);
+  const version = at < 0 ? void 0 : spec.slice(at + 1);
+  if (!NAME.test(name) || name.length > 214 || version !== void 0 && (!version || version.length > 500 || !RANGE.test(version) || /[\r\n\t]/.test(version) || !/[0-9xX*]/.test(version)))
+    throw new CliError(
+      `Refused unsafe npm dependency: ${JSON.stringify(spec)}.`
+    );
+  return { name, version };
+}
+
+// src/install-semver.ts
+var compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+function partial(text) {
+  if (!/^(?:0|[1-9]\d*|[xX*])(?:\.(?:0|[1-9]\d*|[xX*])){0,2}$/.test(text))
+    return;
+  const parts = text.split(".");
+  const numbers = [];
+  let wildcard = false;
+  for (const part of parts) {
+    if (/^[xX*]$/.test(part)) wildcard = true;
+    else {
+      if (wildcard || !Number.isSafeInteger(Number(part))) return;
+      numbers.push(Number(part));
+    }
+  }
+  return {
+    version: [numbers[0] ?? 0, numbers[1] ?? 0, numbers[2] ?? 0],
+    length: numbers.length
+  };
+}
+function next(version, index) {
+  return version.map(
+    (value, i) => i < index ? value : i === index ? value + 1 : 0
+  );
+}
+function primitive(text) {
+  const match = /^(\^|~|>=|<=|>|<|=)?\s*(\S+)$/.exec(text);
+  if (!match) return;
+  const value = partial(match[2]);
+  if (!value) return;
+  const { version, length } = value;
+  const op = match[1] ?? "=";
+  if (!length)
+    return op === "=" || op === "^" || op === "~" || op === ">=" || op === "<=" ? {} : void 0;
+  const lower = { version, inclusive: true };
+  const upper = { version: next(version, length - 1), inclusive: false };
+  switch (op) {
+    case "=":
+      return length === 3 ? { lower, upper: lower } : { lower, upper };
+    case ">=":
+      return { lower };
+    case ">":
+      return {
+        lower: length === 3 ? { version, inclusive: false } : { version: upper.version, inclusive: true }
+      };
+    case "<":
+      return { upper: { version, inclusive: false } };
+    case "<=":
+      return { upper: length === 3 ? lower : upper };
+    case "~":
+      return {
+        lower,
+        upper: {
+          version: next(version, length === 1 ? 0 : 1),
+          inclusive: false
+        }
+      };
+    case "^": {
+      const index = version[0] || length === 1 ? 0 : version[1] || length === 2 ? 1 : 2;
+      return {
+        lower,
+        upper: { version: next(version, index), inclusive: false }
+      };
+    }
+  }
+}
+function ranges(wanted) {
+  if (!wanted.trim() || wanted.length > 500) return;
+  const alternatives = [];
+  for (const raw of wanted.split("||")) {
+    const text = raw.trim();
+    if (!text) return;
+    const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(text);
+    if (hyphen) {
+      const lower = partial(hyphen[1]);
+      const upper = partial(hyphen[2]);
+      if (!lower || !upper || !lower.length || !upper.length) return;
+      alternatives.push([
+        {
+          lower: { version: lower.version, inclusive: true },
+          upper: {
+            version: upper.length === 3 ? upper.version : next(upper.version, upper.length - 1),
+            inclusive: upper.length === 3
+          }
+        }
+      ]);
+    } else {
+      const tokens = text.replace(/(\^|~|>=|<=|>|<|=)\s+/g, "$1").split(/\s+/);
+      const intervals = [];
+      for (const token of tokens) {
+        const interval = primitive(token);
+        if (!interval) return;
+        intervals.push(interval);
+      }
+      alternatives.push(intervals);
+    }
+  }
+  return alternatives;
+}
+function satisfies(installed, wanted) {
+  if (!wanted) return true;
+  const parsed = ranges(wanted);
+  if (!parsed) return installed === wanted ? true : void 0;
+  if (/^\d+\.\d+\.\d+-/.test(installed)) return false;
+  const value = partial(installed);
+  if (value?.length !== 3) return;
+  return parsed.some(
+    (intervals) => intervals.every(
+      ({ lower, upper }) => (!lower || compare(value.version, lower.version) > 0 || lower.inclusive && compare(value.version, lower.version) === 0) && (!upper || compare(value.version, upper.version) < 0 || upper.inclusive && compare(value.version, upper.version) === 0)
+    )
+  );
+}
+
+// src/install-safety.ts
+async function safeDestination(root, path) {
+  safePath(path);
+  const base = await realpath(root);
+  const target = resolve(base, path);
+  if (relative(base, target).startsWith(`..${sep}`) || target === base)
+    throw new CliError(`Refused path outside the project: ${path}.`);
+  let check = target;
+  while (check !== base) {
+    try {
+      if ((await lstat(check)).isSymbolicLink())
+        throw new CliError(`Refused symlink in destination: ${path}.`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    check = dirname(check);
+  }
+  return target;
+}
+
+// src/install-paths.ts
+import { dirname as dirname2, relative as relative2, resolve as resolve2 } from "node:path";
+
+// src/install-imports.ts
+function moduleSpecifiers(source) {
+  const found = [];
+  const tokens = [];
+  const pattern = /\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`|[a-zA-Z_$][\w$]*|[^\s]/g;
+  for (const match of source.matchAll(pattern)) {
+    const token = match[0];
+    if (token.startsWith("//") || token.startsWith("/*")) continue;
+    const previous = tokens.at(-1);
+    const before = tokens.at(-2);
+    if (/^["'`]/.test(token) && !token.includes("${") && (previous === "from" || previous === "import" || previous === "(" && (before === "import" || before === "require"))) {
+      found.push({
+        spec: token.slice(1, -1),
+        start: match.index,
+        end: match.index + token.length,
+        quote: token[0]
+      });
+    }
+    tokens.push(token);
+    if (tokens.length > 2) tokens.shift();
+  }
+  return found;
+}
+
+// src/install-paths.ts
+function aliasPath(project, alias) {
+  for (const [key, values] of Object.entries(project.paths).sort(
+    ([a], [b]) => b.length - a.length
+  )) {
+    const prefix = key.endsWith("*") ? key.slice(0, -1) : key;
+    if ((key.endsWith("*") ? alias.startsWith(prefix) : alias === key) && Array.isArray(values) && values[0]) {
+      const mapped = values[0].replace("*", alias.slice(prefix.length)).replace(/^\.\//, "");
+      return safePath(
+        relative2(
+          project.root,
+          resolve2(project.root, project.base, mapped)
+        ).replaceAll("\\", "/")
+      );
+    }
+  }
+  throw new CliError(
+    `Can't resolve alias ${alias}. Set its paths mapping in tsconfig.json or jsconfig.json.`
+  );
+}
+function rewriteAliases(content, project, destination) {
+  const mappings = [
+    ["@/lib/utils", project.aliases.utils],
+    ["@/components/ui", project.aliases.ui],
+    ["@/components", project.aliases.components],
+    ["@/lib", project.aliases.lib],
+    ["@/hooks", project.aliases.hooks]
+  ];
+  for (const { spec, start, end, quote } of moduleSpecifiers(
+    content
+  ).reverse()) {
+    const entry = mappings.find(
+      ([from]) => spec === from || spec.startsWith(`${from}/`)
+    );
+    if (!entry) continue;
+    const alias = entry[1] + spec.slice(entry[0].length);
+    let path = relative2(
+      dirname2(destination),
+      aliasPath(project, alias)
+    ).replaceAll("\\", "/");
+    if (!path.startsWith(".")) path = `./${path}`;
+    content = `${content.slice(0, start)}${quote}${path}${quote}${content.slice(end)}`;
+  }
+  return content;
+}
+
+// src/install-project.ts
+async function readJson(path, jsonc = false) {
+  try {
+    let source = await readFile(path, "utf8");
+    if (jsonc) {
+      source = source.replace(
+        /"(?:[^"\\]|\\.)*"|\/\/[^\n]*|\/\*[\s\S]*?\*\//g,
+        (s) => s.startsWith('"') ? s : s.replace(/[^\n]/g, " ")
+      );
+      source = source.replace(
+        /"(?:[^"\\]|\\.)*"|,\s*([}\]])/g,
+        (match, close) => close ?? match
+      );
+    }
+    return JSON.parse(source);
+  } catch {
+    throw new CliError(`Can't read ${path}. Fix its JSON and try again.`);
+  }
+}
+var object = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+async function extendedConfig(spec, from) {
+  const file = async (path) => (await stat(path).catch(() => null))?.isFile() ? path : void 0;
+  if (isAbsolute(spec) || /^\.\.?\//.test(spec)) {
+    const path = resolve3(dirname3(from), spec);
+    const found = await file(path) ?? await file(`${path}.json`);
+    if (found) return found;
+  } else if (/^(?:@[\w.-]+\/)?[\w.-]+(?:\/[\w./-]+)*$/.test(spec)) {
+    const parts = spec.split("/");
+    const name = parts.splice(0, spec.startsWith("@") ? 2 : 1).join("/");
+    const subpath = parts.join("/");
+    const require2 = createRequire(from);
+    for (const directory of require2.resolve.paths(name) ?? []) {
+      const folder = join(directory, name);
+      const pkg = existsSync(join(folder, "package.json")) ? await readJson(join(folder, "package.json")) : {};
+      if (pkg.exports !== void 0) {
+        const exported = (() => {
+          try {
+            return require2.resolve(spec);
+          } catch {
+            return void 0;
+          }
+        })();
+        if (exported?.endsWith(".json") && await file(exported))
+          return exported;
+        break;
+      }
+      if (subpath) {
+        const path = join(folder, subpath);
+        const found = await file(path) ?? await file(`${path}.json`) ?? await file(join(path, "tsconfig.json"));
+        if (found) return found;
+      } else {
+        if (typeof pkg.tsconfig === "string") {
+          const path = resolve3(folder, pkg.tsconfig);
+          const found2 = await file(path) ?? await file(`${path}.json`);
+          if (found2) return found2;
+        }
+        const found = await file(join(folder, "tsconfig.json"));
+        if (found) return found;
+      }
+    }
+  }
+  throw new CliError(
+    `Cannot resolve tsconfig extends ${spec} from ${from}. Install the config package or fix extends, then rerun. Nothing written.`
+  );
+}
+async function configPaths(path, stack = /* @__PURE__ */ new Set()) {
+  path = await realpath2(path);
+  if (stack.has(path) || stack.size >= 32)
+    throw new CliError(
+      "Circular or too deep tsconfig extends. Fix the project config first."
+    );
+  const next2 = new Set(stack).add(path);
+  const config = await readJson(path, true);
+  const parents = config.extends === void 0 ? [] : Array.isArray(config.extends) ? config.extends : [config.extends];
+  let result = {};
+  for (const parent of parents) {
+    if (typeof parent !== "string")
+      throw new CliError(
+        "tsconfig extends must be a string or an array of strings."
+      );
+    result = {
+      ...result,
+      ...await configPaths(await extendedConfig(parent, path), next2)
+    };
+  }
+  const options = object(config.compilerOptions);
+  if (typeof options.baseUrl === "string")
+    result.baseUrl = resolve3(dirname3(path), options.baseUrl);
+  if (options.paths !== void 0) {
+    const paths = object(options.paths);
+    if (Object.values(paths).some(
+      (values) => !Array.isArray(values) || values.some((value) => typeof value !== "string")
+    ))
+      throw new CliError(
+        "tsconfig paths must map aliases to arrays of strings."
+      );
+    result.paths = paths;
+    result.pathsOrigin = dirname3(path);
+  }
+  return result;
+}
+async function detectProject(cwd) {
+  let root = await realpath2(resolve3(cwd)).catch(() => {
+    throw new CliError(`No folder ${cwd}. Check --cwd.`);
+  });
+  while (!existsSync(join(root, "package.json"))) {
+    const parent = dirname3(root);
+    if (parent === root)
+      throw new CliError(
+        "No project found. Create an app first: npm create vite@latest my-app -- --template react-ts, then cd my-app and npm install --ignore-scripts. Then run npx layro-cli init --yes for the Tailwind and alias setup steps. Init does not create an app. Nothing written."
+      );
+    root = parent;
+  }
+  const pkg = await readJson(join(root, "package.json"));
+  const dependencies = {
+    ...object(pkg.devDependencies),
+    ...object(pkg.dependencies)
+  };
+  let framework = "React";
+  if (dependencies.next)
+    framework = existsSync(join(root, "app")) || existsSync(join(root, "src/app")) ? "Next.js app" : "Next.js pages";
+  else if (dependencies.astro) framework = "Astro";
+  else if (dependencies["@remix-run/react"]) framework = "Remix";
+  else if (dependencies["@react-router/dev"]) framework = "React Router";
+  else if (dependencies.vite) framework = "Vite";
+  if (!dependencies.react && framework === "React")
+    throw new CliError(
+      "This package is not a React app. Run in the app package, or pass --cwd <app>. To start: npm create vite@latest my-app -- --template react-ts."
+    );
+  let manager;
+  let dir = root;
+  let declared = pkg.packageManager;
+  for (; ; ) {
+    const locks = [
+      ["pnpm-lock.yaml", "pnpm"],
+      ["yarn.lock", "yarn"],
+      ["bun.lock", "bun"],
+      ["bun.lockb", "bun"],
+      ["package-lock.json", "npm"],
+      ["npm-shrinkwrap.json", "npm"]
+    ].filter(([lock]) => existsSync(join(dir, lock)));
+    const managers = [...new Set(locks.map(([, pm]) => pm))];
+    if (managers.length > 1)
+      throw new CliError(
+        `Conflicting lockfiles in ${dir}. Keep the lockfile for the package manager you use.`
+      );
+    if (managers.length) {
+      manager = managers[0];
+      break;
+    }
+    const parent = dirname3(dir);
+    if (parent === dir) break;
+    if (existsSync(join(parent, "package.json"))) {
+      const ancestor = await readJson(join(parent, "package.json"));
+      if (!ancestor.workspaces && !existsSync(join(parent, "pnpm-workspace.yaml")))
+        break;
+      declared ??= ancestor.packageManager;
+    }
+    dir = parent;
+  }
+  manager ??= typeof declared === "string" && /^(npm|pnpm|yarn|bun)@/.test(declared) ? declared.split("@")[0] : "npm";
+  const yarnModern = manager === "yarn" && (/^yarn@(?:[2-9]|\d{2})/.test(String(declared)) || existsSync(join(dir, ".yarnrc.yml")) || existsSync(join(dir, "yarn.lock")) && /^__metadata:/m.test(await readFile(join(dir, "yarn.lock"), "utf8")));
+  let paths = {};
+  let base = "";
+  for (const file of ["jsconfig.json", "tsconfig.json", "tsconfig.app.json"]) {
+    if (existsSync(join(root, file))) {
+      const config2 = await configPaths(join(root, file));
+      if (config2.paths) {
+        paths = config2.paths;
+        base = relative3(
+          root,
+          config2.baseUrl ?? config2.pathsOrigin ?? root
+        ).replaceAll("\\", "/");
+      }
+    }
+  }
+  const config = existsSync(join(root, "components.json")) ? await readJson(join(root, "components.json")) : null;
+  const source = framework === "React Router" || framework === "Remix" ? "app" : existsSync(join(root, "src")) ? "src" : "";
+  const prefix = Object.entries(paths).find(
+    ([key, values]) => key.endsWith("/*") && Array.isArray(values) && values[0]?.replace(/^\.\//, "").replace(/\/\*$/, "") === (source || ".")
+  )?.[0].slice(0, -2);
+  const defaultPrefix = prefix ?? "@";
+  const inferredPaths = !prefix && !paths[`${defaultPrefix}/*`];
+  if (inferredPaths)
+    paths[`${defaultPrefix}/*`] = [
+      `${relative3(resolve3(root, base), resolve3(root, source)).replaceAll("\\", "/") || "."}/*`
+    ];
+  const defaults = {
+    components: `${defaultPrefix}/components`,
+    ui: `${defaultPrefix}/components/ui`,
+    lib: `${defaultPrefix}/lib`,
+    utils: `${defaultPrefix}/lib/utils`,
+    hooks: `${defaultPrefix}/hooks`
+  };
+  const aliases = { ...defaults, ...object(config?.aliases) };
+  for (const value of Object.values(aliases))
+    if (typeof value !== "string")
+      throw new CliError("components.json aliases must be strings.");
+  const tailwind = object(config?.tailwind);
+  const candidates = framework.startsWith("Next.js") ? [
+    `${source ? `${source}/` : ""}app/globals.css`,
+    `${source ? `${source}/` : ""}styles/globals.css`
+  ] : [
+    ...framework === "Vite" ? [`${source ? `${source}/` : ""}index.css`] : [],
+    `${source ? `${source}/` : ""}app.css`,
+    `${source ? `${source}/` : ""}index.css`,
+    `${source ? `${source}/` : ""}styles/global.css`,
+    "app.css"
+  ];
+  const css = typeof tailwind.css === "string" && tailwind.css ? tailwind.css : candidates.find((p) => existsSync(join(root, p)));
+  if (css) safePath(css);
+  return {
+    root,
+    manager,
+    yarnModern,
+    framework,
+    config,
+    paths,
+    inferredPaths,
+    base,
+    aliases,
+    css,
+    rsc: typeof config?.rsc === "boolean" ? config.rsc : framework === "Next.js app",
+    tsx: typeof config?.tsx === "boolean" ? config.tsx : existsSync(join(root, "tsconfig.json")),
+    style: typeof config?.style === "string" ? config.style : "new-york",
+    dependencies
+  };
+}
+
+// src/install-setup.ts
+var safeText2 = (text) => text.replace(/[\r\n]/g, " ");
+var CN_SOURCE = 'import { clsx, type ClassValue } from "clsx";\nimport { twMerge } from "tailwind-merge";\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n';
+function dependencyCommand(project, packages) {
+  const noScripts = project.yarnModern ? "--mode=skip-build" : "--ignore-scripts";
+  return `${project.manager} ${project.manager === "npm" ? "install" : "add"} -D ${noScripts} ${packages}`;
+}
+function setupGuide(project, hasSrc = true) {
+  const vite = ["Vite", "React Router", "Remix", "Astro"].includes(
+    project.framework
+  );
+  const source = project.framework === "React Router" || project.framework === "Remix" ? "app" : hasSrc ? "src" : ".";
+  const css = project.css ?? (project.framework.startsWith("Next.js") ? `${source === "." ? "" : `${source}/`}${project.rsc ? "app" : "styles"}/globals.css` : `${source === "." ? "" : `${source}/`}index.css`);
+  const lines = [
+    `Project: ${project.framework}, ${project.manager}. From ${safeText2(project.root)}:`,
+    dependencyCommand(
+      project,
+      vite ? "tailwindcss@4 @tailwindcss/vite@4" : "tailwindcss@4 @tailwindcss/postcss@4 postcss"
+    )
+  ];
+  if (project.framework === "Astro") {
+    lines.push(
+      'In astro.config.mjs, import tailwindcss from "@tailwindcss/vite" and add tailwindcss() to vite.plugins (keep existing plugins).'
+    );
+  } else if (vite) {
+    lines.push(
+      'In vite.config.ts, import tailwindcss from "@tailwindcss/vite" and add tailwindcss() to plugins (keep existing plugins).'
+    );
+  } else {
+    lines.push(
+      'In postcss.config.mjs, configure: export default { plugins: { "@tailwindcss/postcss": {} } }; Merge with any existing plugins.'
+    );
+  }
+  lines.push(
+    `In ${css}, add @import "tailwindcss"; before other CSS. Keep your styles. Import that stylesheet in your app entry or root layout.`
+  );
+  if (project.inferredPaths) {
+    const mapping = source === "." ? "./*" : `./${source}/*`;
+    lines.push(
+      `In tsconfig.json compilerOptions, merge "paths": { "@/*": ["${mapping}"] }. In Vite's split TypeScript template, also add it to tsconfig.app.json. Paths are relative to baseUrl when present; adjust that mapping to reach ${source}.`
+    );
+    if (vite)
+      lines.push(
+        `For Vite, also import { fileURLToPath, URL } from "node:url" in vite.config.ts and merge resolve: { alias: { "@": fileURLToPath(new URL("./${source === "." ? "" : source}", import.meta.url)) } }. Keep existing aliases. If node:url lacks types: ${dependencyCommand(project, "@types/node")}. For Astro, put the alias under vite.resolve in astro.config.mjs.`
+      );
+  }
+  lines.push(
+    "Then run: npx layro-cli init --yes",
+    "Tailwind setup: https://tailwindcss.com/docs/installation/using-vite (Next.js: https://tailwindcss.com/docs/installation/framework-guides/nextjs)"
+  );
+  return lines.join("\n");
+}
+
+// src/init.ts
+var SetupRequired = class extends CliError {
+  constructor(message, instructions) {
+    super(`${message}
+${instructions}`);
+  }
+};
+function setupGuide2(project) {
+  return setupGuide(project, existsSync2(join2(project.root, "src")));
+}
+async function initConfig(project) {
+  if (!project.dependencies.react)
+    throw new CliError(
+      "React is missing. Install React in the app package before running init. Nothing written."
+    );
+  const css = project.css ? await readFile2(
+    await safeDestination(project.root, project.css),
+    "utf8"
+  ).catch((error) => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }) : "";
+  const active = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const v4 = /@import\s+(?:url\(\s*)?["']tailwindcss(?:\/utilities(?:\.css)?)?["']/.test(
+    active
+  );
+  const v3 = /@tailwind\s+utilities\s*;/.test(active);
+  if (!project.dependencies.tailwindcss || !(v4 || v3))
+    throw new SetupRequired(
+      "Tailwind is not ready: init needs its package and a stylesheet with Tailwind directives. Nothing written.",
+      setupGuide2(project)
+    );
+  if (project.inferredPaths)
+    throw new SetupRequired(
+      "Set up real import aliases before init. Layro will not guess how to rewrite your TypeScript or bundler config. Nothing written.",
+      setupGuide2(project)
+    );
+  for (const alias of Object.values(project.aliases)) aliasPath(project, alias);
+  if (project.config) return null;
+  const tailwindConfig = v4 ? "" : [
+    "tailwind.config.ts",
+    "tailwind.config.js",
+    "tailwind.config.cjs",
+    "tailwind.config.mjs"
+  ].find((file) => existsSync2(join2(project.root, file)));
+  if (tailwindConfig === void 0)
+    throw new CliError(
+      "Tailwind v3 needs a tailwind.config file. Set it up, then run init again. Nothing written."
+    );
+  return `${JSON.stringify(
+    {
+      $schema: "https://ui.shadcn.com/schema.json",
+      style: project.style,
+      rsc: project.rsc,
+      tsx: true,
+      tailwind: {
+        config: tailwindConfig,
+        css: project.css,
+        baseColor: "neutral",
+        cssVariables: true
+      },
+      aliases: project.aliases
+    },
+    null,
+    2
+  )}
+`;
+}
+
+// src/install-css.ts
+import { createHash } from "node:crypto";
+function mergeCss(source, item, tailwind4) {
+  let css = source;
+  const manual = [];
+  const append = (block) => {
+    const hash = createHash("sha256").update(block).digest("hex").slice(0, 16);
+    const marker = `/* layro:${hash} */`;
+    if (!css.includes(marker))
+      css = `${css.trimEnd()}
+
+${marker}
+${block}
+`;
+  };
+  for (const [group, values] of Object.entries(item.cssVars ?? {})) {
+    if (!["theme", "light", "dark"].includes(group) || !values || typeof values !== "object" || Array.isArray(values)) {
+      manual.push(`Apply cssVars.${group} manually: ${JSON.stringify(values)}`);
+      continue;
+    }
+    if (group === "theme" && !tailwind4) {
+      manual.push(`Tailwind v4 theme needed: ${JSON.stringify(values)}`);
+      continue;
+    }
+    const selector = group === "theme" ? "@theme inline" : group === "dark" ? ".dark" : ":root";
+    const pattern = group === "theme" ? /@theme(?: inline)?\s*\{([^{}]*)\}/g : group === "dark" ? /(?:^|\n)\.dark\s*\{([^{}]*)\}/g : /(?:^|\n):root\s*\{([^{}]*)\}/g;
+    const scopes = [...css.matchAll(pattern)];
+    const scope = scopes.map((match) => match[1]).join("\n");
+    const declarations = [];
+    for (const [raw, value] of Object.entries(values)) {
+      const key = raw.replace(/^--/, "");
+      if (!/^[a-zA-Z0-9_-]+$/.test(key) || typeof value !== "string" || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject hostile control characters.
+      /[{};\x00-\x1f]/.test(value)) {
+        manual.push(
+          `Apply CSS variable ${raw} manually: ${JSON.stringify(value)}`
+        );
+        continue;
+      }
+      const declaration = `--${key}: ${value};`;
+      if (scope.includes(declaration)) continue;
+      if (new RegExp(`--${key}\\s*:`).test(scope)) {
+        manual.push(`Check existing --${key}; requested ${value} (${group}).`);
+        continue;
+      }
+      declarations.push(`  ${declaration}`);
+    }
+    if (declarations.length) {
+      const last = scopes.at(-1);
+      if (last && last.index !== void 0) {
+        const at = last.index + last[0].lastIndexOf("}");
+        css = `${css.slice(0, at).trimEnd()}
+${declarations.join("\n")}
+${css.slice(at)}`;
+      } else append(`${selector} {
+${declarations.join("\n")}
+}`);
+    }
+  }
+  const render = (selector, value, depth = 0) => {
+    if (depth > 10 || !value || typeof value !== "object" || Array.isArray(value) || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject hostile control characters.
+    /[{};\x00-\x1f]/.test(selector))
+      return null;
+    if (selector.startsWith("@") && !/^@(keyframes [a-zA-Z0-9_-]+|layer (base|components|utilities)|utility [a-zA-Z0-9_-]+)$/.test(
+      selector
+    ))
+      return null;
+    const lines = [];
+    for (const [key, v] of Object.entries(value)) {
+      if (typeof v === "object") {
+        const nested = render(key, v, depth + 1);
+        if (!nested) return null;
+        lines.push(nested);
+      } else {
+        if (!/^[-a-zA-Z0-9]+$/.test(key) || typeof v !== "string" && typeof v !== "number" || // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject hostile control characters.
+        /[{};\x00-\x1f]/.test(String(v)))
+          return null;
+        const property = key.startsWith("--") ? key : key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+        lines.push(`${property}: ${v};`);
+      }
+    }
+    return `${selector} {
+${lines.map((line) => `  ${line}`).join("\n")}
+}`;
+  };
+  for (const [selector, value] of Object.entries(item.css ?? {})) {
+    const block = render(selector, value);
+    if (!block)
+      manual.push(
+        `Apply CSS manually: ${JSON.stringify({ [selector]: value })}`
+      );
+    else if (css.includes(block)) continue;
+    else if (new RegExp(
+      `${selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\{`
+    ).test(css))
+      manual.push(`Existing CSS rule ${selector}; merge manually: ${block}`);
+    else append(block);
+  }
+  if (item.tailwind)
+    manual.push(
+      `Apply Tailwind config manually: ${JSON.stringify(item.tailwind)}`
+    );
+  return { css, manual };
+}
+
+// src/install-guidance.ts
+function nextPrerenderGuidance(project, sources) {
+  const major = Number(project.dependencies.next?.match(/\d+/)?.[0]);
+  if (project.framework !== "Next.js app" || major < 16 || !Number.isFinite(major))
+    return [];
+  if (!sources.some(
+    (source) => /\b(?:Math\s*\.\s*random|Date\s*\.\s*now|crypto\s*\.\s*(?:randomUUID|getRandomValues))\s*\(|\bnew\s+Date\s*\(\s*\)|\buseSearchParams\s*\(/.test(
+      source
+    )
+  ))
+    return [];
+  return [
+    'Next.js 16+ App Router: installed source mentions randomness, current time or useSearchParams. With Cache Components/prerendering, calls during render can require a Suspense fallback. Calls only in effects or event handlers do not need this random/time fix. If next build reports a missing fallback, wrap your component usage in an ancestor boundary: import { Suspense } from "react"; then <Suspense fallback={<p>Loading component...</p>}><YourComponent {...props} /></Suspense>. Put the boundary outside the component that makes the call (for example, wrap your client demo in app/page.tsx). Keep the author source unchanged. A Suspense boundary does not repair an unrelated hydration mismatch. https://nextjs.org/docs/messages/next-prerender-random-client'
+  ];
+}
+
+// src/version.ts
+var VERSION = true ? "0.5.0" : "dev";
+
+// src/install-registry.ts
+var record = (v) => Boolean(v && typeof v === "object" && !Array.isArray(v));
+function validateItem(raw) {
+  if (!record(raw) || typeof raw.name !== "string" || !raw.name || typeof raw.type !== "string" || !raw.type.startsWith("registry:") || !Array.isArray(raw.files))
+    throw new CliError(
+      "Registry returned the wrong item shape (expected name, type and files)."
+    );
+  if (raw.files.length > 200)
+    throw new CliError("Registry item has too many files (maximum 200).");
+  for (const file of raw.files) {
+    if (!record(file) || typeof file.path !== "string" || typeof file.content !== "string" || typeof file.type !== "string" || file.target !== void 0 && typeof file.target !== "string")
+      throw new CliError(
+        "Registry returned an invalid file (expected path, type and content)."
+      );
+    safePath(file.path);
+    if (file.target)
+      safePath(file.target.replace(/^@(components|ui|lib|hooks)\//, "$1/"));
+  }
+  const strings = (key) => {
+    if (raw[key] === void 0) return [];
+    if (!Array.isArray(raw[key]) || !raw[key].every((v) => typeof v === "string"))
+      throw new CliError(`Registry ${key} must be an array of strings.`);
+    return raw[key];
+  };
+  const dependencies = strings("dependencies");
+  const devDependencies = strings("devDependencies");
+  [...dependencies, ...devDependencies].forEach(packageSpec);
+  if (raw.css !== void 0 && !record(raw.css) || raw.cssVars !== void 0 && !record(raw.cssVars))
+    throw new CliError("Registry css and cssVars must be objects.");
+  return {
+    ...raw,
+    dependencies,
+    devDependencies,
+    registryDependencies: strings("registryDependencies")
+  };
+}
+function registryBase(server2) {
+  let url;
+  try {
+    url = new URL(server2);
+  } catch {
+    throw new CliError(
+      "Invalid LAYRO_URL. Use https://layro.dev, or http://localhost:<port> for local development."
+    );
+  }
+  if (url.username || url.password || url.pathname !== "/" || url.search || url.hash || url.protocol !== "https:" && !(process.env.LAYRO_URL && url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+    throw new CliError(
+      "Registry requires HTTPS. Only localhost through LAYRO_URL may use HTTP."
+    );
+  return url.origin;
+}
+function itemUrl(input, base) {
+  let id = input.replace(/^@/, "");
+  if (/^https?:/.test(input)) {
+    let url;
+    try {
+      url = new URL(input);
+    } catch {
+      throw new CliError("Invalid component URL.");
+    }
+    if (url.origin !== base && url.origin !== "https://layro.dev")
+      throw new CliError(
+        `Refused registry host ${url.host}. Use a Layro component.`
+      );
+    if (url.username || url.password || url.search || url.hash)
+      throw new CliError(
+        "Use a plain Layro component URL without credentials, a query or fragment."
+      );
+    id = url.pathname.replace(/^\/@/, "").replace(/^\/r\//, "").replace(/\.json$/, "");
+  }
+  if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i.test(id))
+    throw new CliError(
+      `Use @author/slug or a Layro component URL: ${JSON.stringify(input)}.`
+    );
+  return `${base}/r/${id}.json`;
+}
+var MAX_BYTES = 5e6;
+async function fetchItem(url, attempts = 3) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      const response = await fetch(url, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(2e4),
+        headers: {
+          Accept: "application/json",
+          "User-Agent": `layro-cli/${VERSION}`
+        }
+      });
+      if (response.status >= 300 && response.status < 400) {
+        const target = new URL(response.headers.get("location") ?? url, url);
+        await response.body?.cancel();
+        throw new CliError(
+          `Registry redirect refused (${target.host}). Use the direct registry URL.`
+        );
+      }
+      if (response.status === 429 && attempt + 1 < attempts) {
+        const retry = response.headers.get("retry-after");
+        const seconds = retry && /^\d+$/.test(retry) ? Number(retry) : retry ? Math.ceil((Date.parse(retry) - Date.now()) / 1e3) : 2 ** attempt;
+        await response.body?.cancel();
+        if (!Number.isFinite(seconds) || seconds > 60)
+          throw new CliError(
+            "Registry rate limit reached. Wait for Retry-After (over 60 seconds), then run add again."
+          );
+        await new Promise((r) => setTimeout(r, Math.max(1, seconds) * 1e3));
+        continue;
+      }
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new CliError(
+          response.status === 404 ? `Component or dependency not found: ${url}. Check its name.` : response.status === 429 ? "Registry rate limit reached (429). Wait a minute and try again." : `Registry answered ${response.status} for ${url}. Try again later.`
+        );
+      }
+      if (Number(response.headers.get("content-length")) > MAX_BYTES) {
+        await response.body?.cancel();
+        throw new CliError("Registry response is too large (maximum 5 MB).");
+      }
+      const reader = response.body?.getReader();
+      if (!reader) throw new CliError("Registry returned an empty response.");
+      const chunks = [];
+      let length = 0;
+      for (; ; ) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        length += value.length;
+        if (length > MAX_BYTES) {
+          await reader.cancel();
+          throw new CliError("Registry response is too large (maximum 5 MB).");
+        }
+        chunks.push(value);
+      }
+      let raw;
+      try {
+        raw = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      } catch {
+        throw new CliError("Registry returned invalid JSON. Try again later.");
+      }
+      return validateItem(raw);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (["TimeoutError", "AbortError"].includes(error.name))
+        throw new CliError(
+          `Registry request timed out: ${url}. Check your connection and try again.`
+        );
+      throw new CliError(
+        `Can't reach the registry at ${new URL(url).host}. Check your connection or LAYRO_URL.`
+      );
+    }
+  }
+  throw new CliError("Registry request failed. Try again later.");
+}
+async function resolveItems(roots, base, style, load2 = fetchItem) {
+  if (!/^[a-z0-9-]+$/.test(style))
+    throw new CliError("Unsupported shadcn style in components.json.");
+  const result = [];
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = async (url) => {
+    if (visiting.has(url))
+      throw new CliError(
+        `Circular registry dependency: ${url}. Nothing written.`
+      );
+    if (visited.has(url)) return;
+    if (visiting.size + visited.size >= 200)
+      throw new CliError(
+        "Too many registry dependencies (maximum 200). Nothing written."
+      );
+    visiting.add(url);
+    const item = await load2(url);
+    for (const dependency of item.registryDependencies) {
+      if (dependency === "utils") continue;
+      let next2;
+      if (/^https?:/.test(dependency)) {
+        const parsed = new URL(dependency);
+        if (parsed.origin !== base && !(parsed.origin === "https://layro.dev" && base !== "https://layro.dev"))
+          throw new CliError(
+            `Refused dependency host ${parsed.host}. Only Layro registry URLs and shadcn names are accepted.`
+          );
+        next2 = itemUrl(dependency, base);
+      } else if (/^[a-z0-9][a-z0-9-]*$/.test(dependency)) {
+        next2 = `https://ui.shadcn.com/r/styles/${style}/${dependency}.json`;
+      } else
+        throw new CliError(
+          `Invalid registry dependency: ${JSON.stringify(dependency)}.`
+        );
+      await visit(next2);
+    }
+    visiting.delete(url);
+    visited.add(url);
+    result.push({ url, item });
+  };
+  for (const url of roots) await visit(url);
+  return result;
+}
+
+// src/install-destination.ts
+function fileDestination(file, project, override) {
+  safePath(file.path);
+  if (file.target) {
+    const target = file.target.replace(
+      /^@(components|ui|lib|hooks)(?=\/)/,
+      "$1"
+    );
+    safePath(target);
+    const mappings = [
+      ["components/ui", "ui"],
+      ["ui", "ui"],
+      ["components", "components"],
+      ["lib", "lib"],
+      ["hooks", "hooks"]
+    ];
+    const entry = mappings.find(([prefix]) => target.startsWith(`${prefix}/`));
+    if (entry)
+      return safePath(
+        `${override && entry[1] === "components" ? override : aliasPath(project, project.aliases[entry[1]])}/${target.slice(entry[0].length + 1)}`
+      );
+    return target;
+  }
+  const kind = file.type;
+  const key = kind === "registry:ui" ? "ui" : kind === "registry:lib" ? "lib" : kind === "registry:hook" ? "hooks" : "components";
+  const folder = override && key === "components" ? override : aliasPath(project, project.aliases[key]);
+  const canonical = /^(components\/ui|components|lib|hooks)\/(.+)$/.exec(
+    file.path
+  );
+  if (canonical)
+    return fileDestination({ ...file, target: file.path }, project, override);
+  const suffix = file.path.split("/").at(-1);
+  return safePath(`${folder}/${suffix}`);
+}
+
+// src/add.ts
+async function existing(root, path) {
+  const target = await safeDestination(root, path);
+  try {
+    return await readFile3(target, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function managerCommand(manager, args, platform = process.platform, pathEnv = process.env.PATH ?? "") {
+  if (platform !== "win32") return { command: manager, args };
+  for (const directory of pathEnv.split(
+    platform === process.platform ? delimiter : ";"
+  )) {
+    const exe = join3(directory, `${manager}.exe`);
+    if (existsSync3(exe)) return { command: exe, args };
+    const shim = join3(directory, `${manager}.cmd`);
+    if (!existsSync3(shim)) continue;
+    const body = readFileSync(shim, "utf8");
+    const hit = body.match(/"%(?:~dp0|dp0%)%?\\([^"\r\n]+\.(?:c?js|mjs))"/i);
+    if (hit) {
+      const entry = resolve4(directory, hit[1].replaceAll("\\", "/"));
+      if (existsSync3(entry))
+        return { command: process.execPath, args: [entry, ...args] };
+    }
+    throw new CliError(
+      `Cannot safely run ${manager}.cmd. Install ${manager} with a Node JS entry or use a native executable.`
+    );
+  }
+  throw new CliError(
+    `${manager} is not on PATH. Install it and run add again.`
+  );
+}
+var installing;
+function yarnIsModern(root) {
+  const { command, args } = managerCommand("yarn", ["--version"]);
+  return new Promise((done) => {
+    const child = spawn(command, args, {
+      cwd: root,
+      shell: false,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3e4
+    });
+    let out = "";
+    child.stdout?.on("data", (data) => {
+      out += data;
+    });
+    child.once("error", () => done(false));
+    child.once("close", () => done(Number.parseInt(out, 10) >= 2));
+  });
+}
+async function installPackages(project, specs, dev, json) {
+  if (!specs.length) return;
+  specs.forEach(packageSpec);
+  const fresh = specs.filter(
+    (spec) => !project.dependencies[packageSpec(spec).name]
+  );
+  const yarnSettings = project.manager === "yarn" && await yarnIsModern(project.root);
+  const noScripts = yarnSettings ? [] : ["--ignore-scripts"];
+  const invocations = [];
+  if (fresh.length !== specs.length)
+    invocations.push(["install", ...noScripts]);
+  if (fresh.length)
+    invocations.push([
+      project.manager === "npm" ? "install" : "add",
+      ...noScripts,
+      ...dev ? ["-D"] : [],
+      ...fresh
+    ]);
+  for (const args of invocations) {
+    const invocation = managerCommand(project.manager, args);
+    await new Promise((resolveDone, reject) => {
+      const child = spawn(invocation.command, invocation.args, {
+        cwd: project.root,
+        shell: false,
+        stdio: json ? ["ignore", "pipe", "pipe"] : "inherit",
+        timeout: 18e4,
+        env: yarnSettings ? { ...process.env, YARN_ENABLE_SCRIPTS: "false" } : process.env
+      });
+      installing = child;
+      child.stdout?.resume();
+      child.stderr?.resume();
+      child.once(
+        "error",
+        () => reject(
+          new CliError(
+            `Could not start ${project.manager}. Install it, then run add again.`
+          )
+        )
+      );
+      child.once(
+        "exit",
+        (code, signal) => code === 0 ? resolveDone() : reject(
+          new CliError(
+            `${project.manager} ${args[0]} ${signal ? `stopped (${signal})` : `failed (exit ${code})`}. Files are listed below; inspect package.json and the lockfile, then rerun the command to finish.`
+          )
+        )
+      );
+    });
+  }
+}
+function printReport(report, json = false) {
+  if (json) {
+    say(JSON.stringify(report, null, 2));
+    return;
+  }
+  say(
+    safeText(
+      `${report.dryRun ? "Dry run" : report.error ? "Install stopped" : "Install complete"}: ${report.components.join(", ")} in ${report.project} (${report.framework}, ${report.packageManager}).`
+    )
+  );
+  for (const [label, values] of [
+    ["Planned", report.planned],
+    ["Written", report.written],
+    ["Unchanged", report.unchanged],
+    ["Skipped", report.skipped],
+    ["Packages requested", report.packages],
+    ["Dev packages requested", report.devPackages],
+    ["Installed", report.installed],
+    ["Import", report.imports],
+    ["Note", report.warnings]
+  ])
+    for (const value of values) say(safeText(`  ${label}: ${value}`));
+}
+async function add(server2, inputs, flags, initOnly = false) {
+  if (!inputs.length && !initOnly)
+    throw new CliError(
+      "Give a component: layro add @author/slug [more...] --yes. See layro add --help."
+    );
+  const base = registryBase(server2);
+  const project = await detectProject(flags.cwd ?? process.cwd());
+  if (!project.tsx)
+    throw new CliError(
+      "JavaScript (tsx:false) projects are not supported: Layro does not convert TypeScript source. Create a TypeScript app (npm create vite@latest my-app -- --template react-ts), or use the Manual tab and convert the source yourself. Nothing written."
+    );
+  const config = initOnly ? await initConfig(project) : null;
+  if (flags.path) {
+    safePath(flags.path);
+    const mapped = relative4(
+      resolve4(project.root, project.base),
+      resolve4(project.root, flags.path)
+    ).replaceAll("\\", "/");
+    project.paths["#layro"] = [mapped];
+    project.paths["#layro/*"] = [`${mapped}/*`];
+    project.aliases.components = "#layro";
+    project.aliases.ui = "#layro/ui";
+  }
+  const roots = [...new Set(inputs.map((input) => itemUrl(input, base)))];
+  const report = {
+    command: initOnly ? "init" : "add",
+    project: project.root,
+    framework: project.framework,
+    packageManager: project.manager,
+    components: initOnly ? ["project setup"] : inputs,
+    dryRun: Boolean(flags["dry-run"]),
+    planned: [],
+    written: [],
+    unchanged: [],
+    skipped: [],
+    packages: [],
+    devPackages: [],
+    installed: [],
+    warnings: [],
+    imports: []
+  };
+  const writes = /* @__PURE__ */ new Map();
+  const plan = async (path, content, kind) => {
+    const previous = writes.get(path);
+    if (previous && previous.content !== content)
+      throw new CliError(
+        `Conflicting registry files for ${path}. Nothing written.`
+      );
+    if (!previous)
+      writes.set(path, {
+        path,
+        content,
+        kind,
+        before: await existing(project.root, path)
+      });
+  };
+  const items = initOnly ? [] : await resolveItems(roots, base, project.style);
+  if (config !== null) await plan("components.json", config, "config");
+  else if (initOnly) report.unchanged.push("components.json");
+  if (!initOnly && !project.config)
+    report.warnings.push(
+      "Run npx layro-cli init --yes to create shared project configuration. Existing component installs still use relative imports."
+    );
+  const packages = /* @__PURE__ */ new Map();
+  const need = (spec, dev = false) => {
+    const { name, version } = packageSpec(spec);
+    const previous = packages.get(name);
+    if (previous?.version && version && previous.version !== version)
+      throw new CliError(
+        `Conflicting dependency versions: ${previous.spec} and ${spec}. Nothing written.`
+      );
+    packages.set(name, {
+      spec: version || !previous ? spec : previous.spec,
+      version: version ?? previous?.version,
+      dev: previous ? previous.dev && dev : dev
+    });
+  };
+  const utils = `${aliasPath(project, project.aliases.utils)}.ts`;
+  const helperCandidates = [
+    utils,
+    utils.replace(/\.ts$/, ".js"),
+    utils.replace(/\.ts$/, ".tsx"),
+    utils.replace(/\.ts$/, ".jsx"),
+    utils.replace(/\.ts$/, "/index.ts"),
+    utils.replace(/\.ts$/, "/index.js")
+  ];
+  const hasHelper = (await Promise.all(
+    helperCandidates.map((path) => existing(project.root, path))
+  )).some((content) => content !== null);
+  if (!hasHelper) {
+    await plan(utils, CN_SOURCE, "helper");
+    need("clsx");
+    need("tailwind-merge");
+  } else if (initOnly) {
+    for (const path of helperCandidates) {
+      const content = await existing(project.root, path);
+      if (content === null) continue;
+      report.unchanged.push(path);
+      for (const { spec } of moduleSpecifiers(content))
+        if (spec === "clsx" || spec === "tailwind-merge") need(spec);
+      break;
+    }
+  }
+  const tailwind4 = /^\D*4(?:\.|$)/.test(
+    project.dependencies.tailwindcss ?? ""
+  );
+  if (!project.dependencies.react)
+    report.warnings.push(
+      "React is missing. Add React before rendering these components."
+    );
+  if (!project.dependencies.tailwindcss)
+    report.warnings.push(
+      `Tailwind CSS is missing. Components will be unstyled until setup is complete. Run npx layro-cli init for the next steps. ${setupGuide2(project)}`
+    );
+  let css = project.css ? await existing(project.root, project.css) : null;
+  const originalCss = css;
+  for (const { url, item } of items) {
+    for (const spec of item.dependencies) need(spec);
+    for (const spec of item.devDependencies) need(spec, true);
+    for (const file of item.files) {
+      if (file.type === "registry:example" || /(?:^|\/)(?:demos?|examples?)(?:\/|\.)/i.test(file.path))
+        continue;
+      if (![
+        "registry:component",
+        "registry:ui",
+        "registry:lib",
+        "registry:hook",
+        "registry:block",
+        "registry:file",
+        "registry:page"
+      ].includes(file.type))
+        throw new CliError(
+          `Unsupported file type ${file.type}. Nothing written; use the Manual tab.`
+        );
+      const imports = /\.[jt]sx?$/.test(file.path) ? moduleSpecifiers(file.content) : [];
+      for (const { spec } of imports) {
+        if (spec.startsWith(".") || spec.startsWith("@/") || spec.startsWith("node:"))
+          continue;
+        const name = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+        need(name);
+      }
+      const path = fileDestination(file, project);
+      if (!/\.(tsx?|jsx?|css)$/.test(path))
+        throw new CliError(
+          `Refused file extension in ${path}. Only source and CSS files are installed.`
+        );
+      const content = rewriteAliases(file.content, project, path);
+      await plan(path, content, "component");
+      if (roots.includes(url) && /\.[jt]sx?$/.test(path)) {
+        const source = path.replace(/\.[jt]sx?$/, "");
+        const named = [
+          ...content.matchAll(
+            /export\s+(?:async\s+)?(?:function|const|class)\s+(\w+)/g
+          )
+        ].map((m) => m[1]);
+        const exports = named.length ? `{ ${named.join(", ")} }` : /export\s+default\b/.test(content) ? "Component" : "{ /* see file exports */ }";
+        report.imports.push(
+          `import ${exports} from "./${source}"; (from a file at the project root; adjust relative to your route)`
+        );
+      }
+    }
+    if ((item.cssVars?.theme || Object.keys(item.css ?? {}).length) && !tailwind4)
+      report.warnings.push(
+        `${item.name} may need Tailwind v4; this project has ${project.dependencies.tailwindcss ?? "none"}.`
+      );
+    const merged = mergeCss(css ?? "", item, tailwind4);
+    report.warnings.push(...merged.manual);
+    if (merged.css !== (css ?? "")) {
+      if (!project.css || css === null)
+        report.warnings.push(
+          `No stylesheet found. Add this CSS to the stylesheet your app imports: ${merged.css}`
+        );
+      else css = merged.css;
+    }
+  }
+  if (project.css && css !== null && css !== originalCss)
+    await plan(project.css, css, "css");
+  report.warnings.push(
+    ...nextPrerenderGuidance(
+      project,
+      [...writes.values()].filter((entry) => entry.kind === "component").map((entry) => entry.content)
+    )
+  );
+  const pnp = existsSync3(join3(project.root, ".pnp.cjs"));
+  for (const { spec, version, dev } of packages.values()) {
+    const { name } = packageSpec(spec);
+    let installed;
+    let dir = project.root;
+    for (; ; ) {
+      try {
+        installed = JSON.parse(
+          await readFile3(
+            join3(dir, "node_modules", name, "package.json"),
+            "utf8"
+          )
+        ).version;
+        break;
+      } catch {
+      }
+      const parent = dirname4(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    const declared = project.dependencies[name];
+    if (declared && !installed && pnp) continue;
+    if (declared) {
+      const known = satisfies("0.0.0", declared);
+      const wanted = satisfies(installed ?? "0.0.0", version);
+      if (known === void 0 || wanted === void 0) {
+        report.warnings.push(
+          `Left ${name} unchanged: cannot safely read project range ${declared} or requested range ${version ?? "any"}. Review and install a compatible version yourself.`
+        );
+        continue;
+      }
+      if (installed) {
+        if (!satisfies(installed, declared) || !wanted)
+          report.warnings.push(
+            `Left ${name}@${declared} unchanged (installed ${installed}; component requests ${version ?? "any"}). Review the ranges and install a compatible version yourself.`
+          );
+        continue;
+      }
+      const preserved = `${name}@${declared}`;
+      packageSpec(preserved);
+      (dev ? report.devPackages : report.packages).push(preserved);
+      if (version)
+        report.warnings.push(
+          `Preserving ${name}@${declared}; component requests ${version}. Check compatibility after installing.`
+        );
+      continue;
+    }
+    if (version && satisfies("0.0.0", version) === void 0) {
+      report.warnings.push(
+        `Left ${name} uninstalled: cannot safely read requested range ${version}. Review and install a compatible version yourself.`
+      );
+      continue;
+    }
+    (dev ? report.devPackages : report.packages).push(spec);
+  }
+  const accepted = [];
+  for (const entry of writes.values()) {
+    if (entry.before === entry.content) {
+      report.unchanged.push(entry.path);
+      continue;
+    }
+    if (entry.before !== null && entry.kind !== "css" && !flags.overwrite) {
+      if (flags["dry-run"]) {
+        report.skipped.push(entry.path);
+        report.warnings.push(
+          `${entry.path} differs; --overwrite would replace it, --yes would skip it.`
+        );
+        continue;
+      }
+      if (flags.yes) {
+        report.skipped.push(entry.path);
+        continue;
+      }
+      if (!canAsk() || flags.json)
+        throw new CliError(
+          `File differs: ${entry.path}. Use --yes to skip it, or --overwrite to replace it. Nothing written.`
+        );
+      if (!flags["dry-run"] && !await confirm(`Replace ${safeText(entry.path)}?`)) {
+        report.skipped.push(entry.path);
+        continue;
+      }
+    }
+    accepted.push(entry);
+    report.planned.push(entry.path);
+  }
+  if (flags["dry-run"]) {
+    printReport(report, flags.json);
+    return report;
+  }
+  if (!flags.json) {
+    say(
+      safeText(
+        `Installing ${inputs.join(", ") || "shared project setup"} into ${project.root}.`
+      )
+    );
+    say(
+      safeText(
+        `Files: ${report.planned.join(", ") || "none"}. Packages: ${[...report.packages, ...report.devPackages].join(", ") || "none"}. Package scripts are disabled.`
+      )
+    );
+  }
+  let temporary;
+  const stopped = (signal) => {
+    installing?.kill(signal);
+    if (temporary) {
+      try {
+        unlinkSync(temporary);
+      } catch {
+      }
+    }
+    report.error = `Stopped by ${signal}. Rerun ${report.command} to finish. Package installation may be incomplete; inspect package.json and the lockfile.`;
+    printReport(report, flags.json);
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  };
+  const interrupt = () => stopped("SIGINT");
+  const terminate = () => stopped("SIGTERM");
+  process.once("SIGINT", interrupt);
+  process.once("SIGTERM", terminate);
+  try {
+    for (const entry of accepted) {
+      const target = await safeDestination(project.root, entry.path);
+      if (await existing(project.root, entry.path) !== entry.before)
+        throw new CliError(
+          `File changed during install: ${entry.path}. Rerun add.`
+        );
+      await mkdir(dirname4(target), { recursive: true });
+      await safeDestination(project.root, entry.path);
+      temporary = `${target}.layro-${randomBytes(8).toString("hex")}`;
+      const handle = await open(
+        temporary,
+        constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+        420
+      );
+      try {
+        await handle.writeFile(entry.content);
+      } finally {
+        await handle.close();
+      }
+      await safeDestination(project.root, entry.path);
+      await rename(temporary, target);
+      temporary = void 0;
+      report.written.push(entry.path);
+    }
+    await installPackages(project, report.packages, false, Boolean(flags.json));
+    report.installed.push(...report.packages);
+    await installPackages(
+      project,
+      report.devPackages,
+      true,
+      Boolean(flags.json)
+    );
+    report.installed.push(...report.devPackages);
+    for (const spec of report.installed) {
+      const { name } = packageSpec(spec);
+      const folder = join3(project.root, "node_modules", name);
+      let manifest;
+      try {
+        manifest = JSON.parse(
+          await readFile3(join3(folder, "package.json"), "utf8")
+        );
+      } catch {
+        continue;
+      }
+      const lifecycle = ["preinstall", "install", "postinstall"].filter(
+        (script) => typeof manifest.scripts?.[script] === "string"
+      );
+      if (lifecycle.length)
+        report.warnings.push(
+          `${name} has disabled install scripts (${lifecycle.join(", ")}). If it needs its build step, review node_modules/${name}/package.json first. From the app root, run explicitly: cd node_modules/${name} && ${lifecycle.map((script) => `${project.manager} run ${script}`).join(" && ")}`
+        );
+      else if (existsSync3(join3(folder, "binding.gyp")))
+        report.warnings.push(
+          `${name} has a native binding whose build script was disabled. Review node_modules/${name}/binding.gyp; if needed, run from the app root: npm rebuild ${name} --ignore-scripts=false`
+        );
+    }
+  } catch (error) {
+    if (temporary) await unlink(temporary).catch(() => {
+    });
+    report.error = error instanceof CliError ? error.message : `Could not finish writing the project (${error.code ?? "I/O error"}). Rerun ${report.command} after checking permissions.`;
+    printReport(report, flags.json);
+    if (!flags.json) warn(safeText(report.error));
+    process.exitCode = 1;
+    return report;
+  } finally {
+    installing = void 0;
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", terminate);
+  }
+  printReport(report, flags.json);
+  return report;
+}
+
 // src/auth.ts
-import { spawn } from "node:child_process";
-import { createHash, randomBytes } from "node:crypto";
+import { spawn as spawn2 } from "node:child_process";
+import { createHash as createHash2, randomBytes as randomBytes2 } from "node:crypto";
 import { createServer } from "node:http";
 
 // src/credentials.ts
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir as mkdir2, readFile as readFile4, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-var credentialsPath = () => join(
-  process.env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+import { dirname as dirname5, join as join4 } from "node:path";
+var credentialsPath = () => join4(
+  process.env.XDG_CONFIG_HOME || join4(homedir(), ".config"),
   "layro",
   "credentials.json"
 );
 async function load() {
   try {
-    const parsed = JSON.parse(await readFile(credentialsPath(), "utf8"));
+    const parsed = JSON.parse(await readFile4(credentialsPath(), "utf8"));
     return parsed && typeof parsed.servers === "object" ? parsed : { servers: {} };
   } catch {
     return { servers: {} };
@@ -27,7 +1556,7 @@ async function load() {
 }
 async function save(file) {
   const path = credentialsPath();
-  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await mkdir2(dirname5(path), { recursive: true, mode: 448 });
   if (Object.keys(file.servers).length === 0) {
     await rm(path, { force: true });
     return;
@@ -59,55 +1588,19 @@ async function forgetClient(server2) {
   await save(file);
 }
 
-// src/ui.ts
-import { createInterface } from "node:readline/promises";
-var color = process.stdout.isTTY && !process.env.NO_COLOR;
-var paint = (code) => (text) => color ? `\x1B[${code}m${text}\x1B[0m` : text;
-var bold = paint(1);
-var dim = paint(2);
-var green = paint(32);
-var red = paint(31);
-var yellow = paint(33);
-var say = (text = "") => process.stdout.write(`${text}
-`);
-var warn = (text) => process.stderr.write(`${text}
-`);
-var CliError = class extends Error {
-};
-var canAsk = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
-async function ask(question, fallback = "") {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+// src/http.ts
+async function request(url, init = {}, timeoutMs = 2e4) {
   try {
-    const hint = fallback ? dim(` (${fallback})`) : "";
-    const answer = (await rl.question(`${question}${hint}: `)).trim();
-    return answer || fallback;
+    return await fetch(url, {
+      ...init,
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs)
+    });
   } catch (error) {
-    if (error.name === "AbortError")
-      throw new CliError("Cancelled.");
-    throw error;
-  } finally {
-    rl.close();
-  }
-}
-async function confirm(question) {
-  const answer = (await ask(`${question} ${dim("[Y/n]")}`)).toLowerCase();
-  return answer === "" || answer === "y" || answer === "yes";
-}
-async function choose(question, options, fallback) {
-  options.forEach((option, i) => {
-    say(`  ${dim(String(i + 1).padStart(2))}  ${option.label}`);
-  });
-  const fallbackIndex = options.findIndex((o) => o.value === fallback);
-  for (; ; ) {
-    const answer = await ask(
-      question,
-      fallbackIndex >= 0 ? String(fallbackIndex + 1) : ""
+    const timeout = error instanceof Error && ["TimeoutError", "AbortError"].includes(error.name);
+    throw new CliError(
+      timeout ? "Request timed out. Check your connection and LAYRO_URL, then retry." : "Could not reach the Layro server (network failure or refused redirect). Check your connection and LAYRO_URL, then retry."
     );
-    const byNumber = options[Number(answer) - 1];
-    const byValue = options.find((o) => o.value === answer);
-    const picked = byNumber ?? byValue;
-    if (picked) return picked.value;
-    say(red(`Pick a number from 1 to ${options.length}.`));
   }
 }
 
@@ -120,7 +1613,7 @@ async function metadata(server2) {
   const url = `${server2}/.well-known/oauth-authorization-server/api/auth`;
   let response;
   try {
-    response = await fetch(url);
+    response = await request(url);
   } catch (error) {
     throw new CliError(
       `Can't reach ${server2} (${error.message}). Check your connection, or LAYRO_URL.`
@@ -132,7 +1625,7 @@ async function metadata(server2) {
 }
 var base64url = (bytes) => bytes.toString("base64url");
 async function register(meta, server2, redirect) {
-  const response = await fetch(meta.registration_endpoint, {
+  const response = await request(meta.registration_endpoint, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
@@ -157,7 +1650,7 @@ async function register(meta, server2, redirect) {
 function openBrowser(url) {
   const custom = process.env.LAYRO_OPEN_BROWSER;
   const [command, ...args] = custom ? [...custom.split(" ").filter(Boolean), url] : process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", '""', url.replaceAll("&", "^&")] : ["xdg-open", url];
-  const child = spawn(command, args, {
+  const child = spawn2(command, args, {
     stdio: custom ? "inherit" : "ignore",
     detached: !custom
   });
@@ -169,11 +1662,11 @@ var page = (title, text) => `<!doctype html><meta charset="utf-8"><title>${title
 async function callbackServer(state) {
   let settle = () => {
   };
-  const result = new Promise((resolve2) => {
-    settle = resolve2;
+  const result = new Promise((resolve6) => {
+    settle = resolve6;
   });
-  const server2 = createServer((request, response) => {
-    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+  const server2 = createServer((request2, response) => {
+    const url = new URL(request2.url ?? "/", "http://127.0.0.1");
     if (url.pathname !== "/callback") {
       response.writeHead(404).end();
       return;
@@ -196,15 +1689,15 @@ async function callbackServer(state) {
       }
     );
   });
-  await new Promise((resolve2, reject) => {
+  await new Promise((resolve6, reject) => {
     server2.once("error", reject);
-    server2.listen(0, "127.0.0.1", resolve2);
+    server2.listen(0, "127.0.0.1", resolve6);
   });
   const { port } = server2.address();
   return { port, result, close: () => server2.close() };
 }
 async function tokenRequest(meta, params) {
-  const response = await fetch(meta.token_endpoint, {
+  const response = await request(meta.token_endpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams(params)
@@ -226,15 +1719,15 @@ var toSession = (clientId, tokens) => ({
 });
 async function login(server2, options) {
   const meta = await metadata(server2);
-  const state = base64url(randomBytes(16));
+  const state = base64url(randomBytes2(16));
   const callback = await callbackServer(state);
   try {
     const redirect = `http://127.0.0.1:${callback.port}/callback`;
     const known = await getSession(server2);
     const clientId = known?.clientId ?? await register(meta, server2, redirect);
     await setSession(server2, { ...known ?? {}, clientId });
-    const verifier = base64url(randomBytes(32));
-    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    const verifier = base64url(randomBytes2(32));
+    const challenge = base64url(createHash2("sha256").update(verifier).digest());
     const authorize = new URL(meta.authorization_endpoint);
     authorize.search = new URLSearchParams({
       response_type: "code",
@@ -246,16 +1739,27 @@ async function login(server2, options) {
       code_challenge_method: "S256",
       resource: apiResource(server2)
     }).toString();
-    say("Opening your browser to sign in to Layro with GitHub.");
-    say(dim(`If it doesn't open, visit:
-${authorize}`));
+    if (options.json)
+      say(
+        JSON.stringify({
+          status: "authorization_required",
+          url: authorize.toString(),
+          expiresIn: options.timeout ?? LOGIN_TIMEOUT_MS / 1e3
+        })
+      );
+    else {
+      say(
+        options.browser ? "Opening your browser to sign in to Layro with GitHub." : "Visit this link to sign in to Layro with GitHub:"
+      );
+      say(dim(safeText(authorize.toString())));
+    }
     if (options.browser) openBrowser(authorize.toString());
     const outcome = await Promise.race([
       callback.result,
       new Promise(
-        (resolve2) => setTimeout(
-          () => resolve2({ error: "timed out waiting for the browser" }),
-          LOGIN_TIMEOUT_MS
+        (resolve6) => setTimeout(
+          () => resolve6({ error: "timed out waiting for the browser" }),
+          options.timeout ? options.timeout * 1e3 : LOGIN_TIMEOUT_MS
         ).unref()
       )
     ]);
@@ -295,13 +1799,13 @@ async function refresh(server2, session) {
     await clearTokens(server2);
     return null;
   }
-  const next = {
+  const next2 = {
     ...toSession(session.clientId, renewed.tokens),
     refreshToken: renewed.tokens.refresh_token ?? session.refreshToken,
     handle: session.handle
   };
-  await setSession(server2, next);
-  return next;
+  await setSession(server2, next2);
+  return next2;
 }
 var notSignedIn = () => new CliError("Not signed in. Run `npx layro-cli login` first.");
 async function accessToken(server2, force = false) {
@@ -323,7 +1827,7 @@ async function logout(server2) {
   try {
     const meta = await metadata(server2);
     if (meta.revocation_endpoint && session.refreshToken) {
-      await fetch(meta.revocation_endpoint, {
+      await request(meta.revocation_endpoint, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
@@ -340,7 +1844,6 @@ async function logout(server2) {
 }
 
 // src/api.ts
-var VERSION = true ? "0.3.0" : "dev";
 var ApiFailure = class extends CliError {
   constructor(detail) {
     super(detail.error);
@@ -351,7 +1854,7 @@ var ApiFailure = class extends CliError {
 async function api(server2, path, init = {}) {
   const call = async (token) => {
     try {
-      return await fetch(`${server2}/api/v1${path}`, {
+      return await request(`${server2}/api/v1${path}`, {
         method: init.method ?? "GET",
         headers: {
           Accept: "application/json",
@@ -374,6 +1877,10 @@ async function api(server2, path, init = {}) {
   }
   const body = await response.json().catch(() => null);
   if (response.ok && body) return body;
+  if (response.ok)
+    throw new CliError(
+      "The Layro API returned invalid JSON or an empty answer. Retry, or check LAYRO_URL."
+    );
   if (response.status === 401) {
     if (process.env.LAYRO_TOKEN)
       throw new CliError(
@@ -389,46 +1896,433 @@ async function api(server2, path, init = {}) {
   });
 }
 
+// src/command-help.ts
+var commandHelp = {
+  mcp: `layro mcp [--client <agent>] [options]
+
+Add Layro's MCP server to a coding agent, so you never type its URL.
+Without --client it asks which, listing the agents it finds first.
+
+  claude   claude mcp add --transport http --scope user (every project)
+  cursor   adds "layro" to ~/.cursor/mcp.json
+  vscode   code --add-mcp (your profile), or .vscode/mcp.json here
+  codex    codex mcp add layro --url
+
+An existing "layro" entry is left alone; other servers are never touched.
+Sign-in is your agent's own: it opens the browser on first use.
+
+  -c, --client <agent>  claude, cursor, vscode or codex
+  --cwd <folder>        Project for .vscode/mcp.json (default current folder)
+  --dry-run             Show what would change; change nothing
+  -y, --yes             Don't ask before changing
+  --json                Machine-readable result
+
+Examples:
+  npx layro-cli mcp
+  npx layro-cli mcp --client cursor --yes`,
+  search: `layro search <words...> [options]
+
+Find public components and print their Layro add commands. No sign-in.
+  --category <slug>  Filter category
+  --author <handle> Filter author
+  --limit <n>       1 to 50 (default 20)
+  --json            Return results with Layro install commands as JSON
+
+Examples:
+  npx layro-cli search animated text
+  layro search chart --author legions-developer --limit 5 --json`,
+  publish: `layro publish <files...> [options]
+
+Submit a new component or a version of your same-named component for review.
+The first file is the entry. Sign in with login or set LAYRO_TOKEN for CI.
+  --name <name>         Defaults to entry file's name
+  --description <text>  20 to 200 characters for a new component
+  --category <slug>     Category from layro.dev/components
+  --license <id>        MIT (default), Apache-2.0, ISC or BSD-3-Clause
+  --version <x.y.z>     Existing component: next patch by default
+  --notes <text>        What changed
+  --preview <file.json> How to record the preview
+  --dark-only           New component only works on a dark page
+  --if-changed          Unchanged/pending version: nothing sent, exit 0
+  -y, --yes             Send flags as given without prompts
+  --json                No prompts; return result or field errors as JSON
+
+Examples:
+  layro publish src/components/card.tsx --name "My Card" --description "A useful card for your dashboard" --category cards --yes
+  layro publish src/components/card.tsx --if-changed --json`,
+  status: `layro status [slug | author/slug] [--json]
+
+Show your submissions and reviewers' reasons. Sign in or set LAYRO_TOKEN.
+Without a component, list all of yours. --json returns the API response.
+
+Examples:
+  layro status
+  layro status author/card --json`,
+  login: `layro login [--no-browser] [--timeout <seconds>] [--json]
+
+Sign in with GitHub and approve Layro CLI in your browser.
+  --no-browser   Print the link; explicitly wait for its loopback callback
+  --timeout <n>  Wait 1 to 300 seconds for consent (default 300)
+  --json         Print newline-delimited JSON: authorization_required, then
+                 signed_in or error. Never includes access/refresh tokens.
+
+Without a terminal, --no-browser is required. CI should use LAYRO_TOKEN.
+Network requests time out after 20 seconds. Consent uses the timeout above.
+
+Examples:
+  layro login
+  layro login --no-browser --timeout 120 --json`,
+  logout: `layro logout [--json]
+
+Revoke and forget the saved session. Offline: forget local tokens anyway.
+--json returns signedOut and tokenEnvironmentSet. An environment token stays set.
+
+Examples:
+  layro logout
+  layro logout --json`,
+  whoami: `layro whoami [--json]
+
+Show the signed-in handle, profile and submissions left today.
+Uses LAYRO_TOKEN when set, otherwise the saved session. --json returns API JSON.
+
+Examples:
+  layro whoami
+  layro whoami --json`
+};
+var commands = [
+  "init",
+  "mcp",
+  "add",
+  "search",
+  "publish",
+  "status",
+  "login",
+  "logout",
+  "whoami",
+  "help"
+];
+function distance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const next2 = [i];
+    for (let j = 1; j <= b.length; j++)
+      next2[j] = Math.min(
+        next2[j - 1] + 1,
+        row[j] + 1,
+        row[j - 1] + Number(a[i - 1] !== b[j - 1])
+      );
+    row = next2;
+  }
+  return row[b.length];
+}
+function suggestCommand(input) {
+  if (input.length > 32) return "";
+  const found = commands.map((command) => ({ command, distance: distance(input, command) })).sort((a, b) => a.distance - b.distance)[0];
+  return found.distance <= 2 ? ` Did you mean layro ${found.command}?` : "";
+}
+
+// src/mcp.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync4 } from "node:fs";
+import { mkdir as mkdir3, readFile as readFile5, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname6, join as join5 } from "node:path";
+var byHand = (message, manual) => new SetupRequired(message, manual);
+var MCP_NAME = "layro";
+var clients = ["claude", "cursor", "vscode", "codex"];
+var labels = {
+  claude: "Claude Code",
+  cursor: "Cursor",
+  vscode: "VS Code",
+  codex: "Codex"
+};
+function mcpUrl(server2) {
+  return server2 === "https://layro.dev" ? "https://mcp.layro.dev" : `${server2}/mcp`;
+}
+var windows = process.platform === "win32";
+function onPath(program) {
+  const dirs = (process.env.PATH ?? "").split(windows ? ";" : ":");
+  const names = windows ? [`${program}.cmd`, `${program}.exe`, program] : [program];
+  return dirs.some(
+    (dir) => dir && names.some((name) => existsSync4(join5(dir, name)))
+  );
+}
+function run(program, args, quiet = false) {
+  const result = spawnSync(program, args, {
+    stdio: quiet ? "ignore" : "inherit",
+    // .cmd shims need a shell on Windows; every argument here is ours.
+    shell: windows
+  });
+  return result.status === 0;
+}
+async function mergeJson(file, key, entry, manual) {
+  let config = {};
+  if (existsSync4(file)) {
+    const text = await readFile5(file, "utf8");
+    try {
+      config = text.trim() ? JSON.parse(text) : {};
+    } catch {
+      throw byHand(
+        `${file} isn't plain JSON (comments?), so it was left alone. Add this by hand:`,
+        manual
+      );
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config))
+      throw byHand(`${file} isn't a JSON object. Add this by hand:`, manual);
+  }
+  const servers = config[key] ?? {};
+  if (typeof servers !== "object" || Array.isArray(servers))
+    throw byHand(
+      `"${key}" in ${file} isn't an object. Add this by hand:`,
+      manual
+    );
+  if (servers[MCP_NAME]) return "exists";
+  config[key] = { ...servers, [MCP_NAME]: entry };
+  await mkdir3(dirname6(file), { recursive: true });
+  await writeFile2(file, `${JSON.stringify(config, null, 2)}
+`);
+  return "added";
+}
+function planFor(client, server2, cwd) {
+  const url = mcpUrl(server2);
+  switch (client) {
+    case "claude": {
+      const args = [
+        "mcp",
+        "add",
+        "--transport",
+        "http",
+        "--scope",
+        "user",
+        MCP_NAME,
+        url
+      ];
+      const manual = `claude ${args.join(" ")}`;
+      return {
+        client,
+        url,
+        action: `Run: ${manual}`,
+        manual,
+        apply: async () => {
+          if (!onPath("claude"))
+            throw byHand(
+              `Claude Code's CLI (claude) isn't on PATH. Run this where it is:`,
+              manual
+            );
+          if (run("claude", ["mcp", "get", MCP_NAME], true)) return "exists";
+          if (!run("claude", args))
+            throw byHand(`claude mcp add failed. Run it yourself:`, manual);
+          return "added";
+        }
+      };
+    }
+    case "codex": {
+      const args = ["mcp", "add", MCP_NAME, "--url", url];
+      const manual = `codex ${args.join(" ")}`;
+      return {
+        client,
+        url,
+        action: `Run: ${manual}`,
+        manual,
+        apply: async () => {
+          if (!onPath("codex"))
+            throw byHand(
+              `Codex's CLI (codex) isn't on PATH. Run this where it is:`,
+              manual
+            );
+          if (run("codex", ["mcp", "get", MCP_NAME], true)) return "exists";
+          if (!run("codex", args))
+            throw byHand(`codex mcp add failed. Run it yourself:`, manual);
+          return "added";
+        }
+      };
+    }
+    case "cursor": {
+      if (!homedir2())
+        throw new CliError("Can't find your home folder (HOME isn't set).");
+      const file = join5(homedir2(), ".cursor", "mcp.json");
+      const manual = JSON.stringify(
+        { mcpServers: { [MCP_NAME]: { url } } },
+        null,
+        2
+      );
+      return {
+        client,
+        url,
+        action: `Add "${MCP_NAME}" to ${file}`,
+        manual,
+        apply: () => mergeJson(file, "mcpServers", { url }, manual)
+      };
+    }
+    case "vscode": {
+      const entry = { type: "http", url };
+      const json = JSON.stringify({ name: MCP_NAME, ...entry });
+      if (!windows && onPath("code")) {
+        const manual2 = `code --add-mcp '${json}'`;
+        return {
+          client,
+          url,
+          action: `Run: ${manual2}`,
+          manual: manual2,
+          apply: async () => {
+            if (!run("code", ["--add-mcp", json]))
+              throw byHand(`code --add-mcp failed. Run it yourself:`, manual2);
+            return "added";
+          }
+        };
+      }
+      const file = join5(cwd, ".vscode", "mcp.json");
+      const manual = JSON.stringify(
+        { servers: { [MCP_NAME]: entry } },
+        null,
+        2
+      );
+      return {
+        client,
+        url,
+        action: `Add "${MCP_NAME}" to ${file} (this project)`,
+        manual,
+        apply: () => mergeJson(file, "servers", entry, manual)
+      };
+    }
+  }
+}
+function detected() {
+  const home = homedir2();
+  const found = /* @__PURE__ */ new Set();
+  if (onPath("claude") || existsSync4(join5(home, ".claude")))
+    found.add("claude");
+  if (onPath("cursor") || existsSync4(join5(home, ".cursor")))
+    found.add("cursor");
+  if (onPath("code")) found.add("vscode");
+  if (onPath("codex") || existsSync4(join5(home, ".codex"))) found.add("codex");
+  return found;
+}
+var nextStep = {
+  claude: "Ask Claude for a component. The first call opens your browser to sign in with GitHub and approve Layro.",
+  cursor: "Restart Cursor if it's open. It opens your browser to sign in on first use.",
+  vscode: "Open Copilot Chat in agent mode. VS Code asks you to sign in to Layro on first use.",
+  codex: `If Codex didn't open your browser, sign in once: codex mcp login ${MCP_NAME}`
+};
+async function addMcp(server2, flags) {
+  const cwd = flags.cwd ?? process.cwd();
+  let client = flags.client?.toLowerCase().replace(/[\s-]+/g, "");
+  if (client === "claudecode") client = "claude";
+  if (client === "code") client = "vscode";
+  if (client && !clients.includes(client))
+    throw new CliError(
+      `Unknown agent "${safeText(flags.client ?? "")}". Use --client with one of: ${clients.join(", ")}.`
+    );
+  if (!client) {
+    if (flags.json || flags.yes || !canAsk())
+      throw new CliError(
+        `Say which agent: --client ${clients.join(" | ")}. Any other MCP client takes ${mcpUrl(server2)}.`
+      );
+    const found = detected();
+    const order = [...clients].sort(
+      (a, b) => Number(found.has(b)) - Number(found.has(a))
+    );
+    client = await choose(
+      "Add Layro to",
+      order.map((value) => ({
+        value,
+        label: `${labels[value]}${found.has(value) ? dim("  found") : ""}`
+      })),
+      order[0]
+    );
+  }
+  const plan = planFor(client, server2, cwd);
+  if (flags["dry-run"]) {
+    if (flags.json)
+      return say(
+        JSON.stringify({
+          client: plan.client,
+          url: plan.url,
+          action: plan.action,
+          manual: plan.manual,
+          dryRun: true
+        })
+      );
+    say(`${bold(labels[plan.client])}: ${plan.action}`);
+    return say(dim("Dry run: nothing changed."));
+  }
+  if (!flags.yes && !flags.json && canAsk()) {
+    say(`${bold(labels[plan.client])}: ${plan.action}`);
+    if (!await confirm("Go ahead?")) throw new CliError("Cancelled.");
+  }
+  const result = await plan.apply();
+  if (flags.json)
+    return say(
+      JSON.stringify({ client: plan.client, url: plan.url, status: result })
+    );
+  say(
+    result === "added" ? green(`\u2713 Layro added to ${labels[plan.client]}.`) : `Layro is already set up in ${labels[plan.client]}. Nothing changed.`
+  );
+  say(dim(nextStep[plan.client]));
+}
+
 // src/publish.ts
-import { readFile as readFile2 } from "node:fs/promises";
-import { basename, dirname as dirname2, relative, resolve, sep } from "node:path";
+import { readFile as readFile6 } from "node:fs/promises";
+import {
+  basename,
+  dirname as dirname7,
+  isAbsolute as isAbsolute2,
+  relative as relative5,
+  resolve as resolve5,
+  sep as sep2
+} from "node:path";
 function nameFromFile(path) {
   const stem = basename(path).replace(/\.[^.]+$/, "");
   return stem.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[-_\s.]+/).filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join(" ");
 }
 async function readFiles(paths) {
-  const absolute = paths.map((p) => resolve(p));
-  let root = dirname2(absolute[0]);
-  for (const path of absolute) {
-    while (!`${dirname2(path)}${sep}`.startsWith(`${root}${sep}`)) {
-      root = dirname2(root);
-    }
-  }
+  if (!paths.length)
+    throw new CliError("Give at least one source file to publish.");
+  const absolute = paths.map((p) => resolve5(p));
+  const root = commonFileRoot(absolute);
   return Promise.all(
     absolute.map(async (path, i) => {
       let content;
       try {
-        content = await readFile2(path, "utf8");
+        content = await readFile6(path, "utf8");
       } catch {
         throw new CliError(`Can't read ${paths[i]}.`);
       }
-      return { path: relative(root, path).split(sep).join("/"), content };
+      return { path: relative5(root, path).split(sep2).join("/"), content };
     })
   );
 }
+function commonFileRoot(paths, path = { dirname: dirname7, relative: relative5, isAbsolute: isAbsolute2 }) {
+  let root = path.dirname(paths[0]);
+  for (const file of paths) {
+    for (; ; ) {
+      const rel = path.relative(root, path.dirname(file));
+      if (!path.isAbsolute(rel) && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("..\\"))
+        break;
+      const parent = path.dirname(root);
+      if (parent === root)
+        throw new CliError(
+          "Publish files must share a directory on the same drive. Copy them into one project first."
+        );
+      root = parent;
+    }
+  }
+  return root;
+}
 async function readPreview(path) {
   if (!path) return void 0;
   try {
-    return JSON.parse(await readFile2(path, "utf8"));
+    return JSON.parse(await readFile6(path, "utf8"));
   } catch {
     throw new CliError(`--preview: ${path} isn't a readable JSON file.`);
   }
 }
-function explain(error) {
+function explain(error, json = false) {
+  if (json) throw error;
   if (error instanceof ApiFailure && error.detail.errors) {
     say(red("Not sent. Fix these and try again:"));
     for (const [field, message] of Object.entries(error.detail.errors)) {
-      say(`  ${bold(field)}: ${message}`);
+      say(`  ${bold(safeText(field))}: ${safeText(message)}`);
     }
     process.exit(1);
   }
@@ -439,15 +2333,18 @@ async function publish(server2, paths, flags) {
     throw new CliError(
       "Name the files to publish, entry first: layro publish components/pricing-card.tsx"
     );
-  const interactive = canAsk() && !flags.yes;
+  const interactive = canAsk() && !flags.yes && !flags.json;
+  const note = (text) => {
+    if (!flags.json) say(safeText(text));
+  };
   const files = await readFiles(paths);
   const preview = await readPreview(flags.preview);
   const me = await api(server2, "/me");
-  say(dim(`Publishing as @${me.handle} to ${server2}`));
+  note(`Publishing as @${me.handle} to ${server2}`);
   const name = flags.name ?? (interactive ? await ask("Name", nameFromFile(paths[0])) : nameFromFile(paths[0]));
-  let existing = null;
+  let existing2 = null;
   try {
-    existing = await api(
+    existing2 = await api(
       server2,
       `/status?name=${encodeURIComponent(name)}`
     );
@@ -456,17 +2353,17 @@ async function publish(server2, paths, flags) {
       throw error;
   }
   let result;
-  if (existing) {
-    say(
-      `${bold(existing.name)} is already yours (${existing.liveVersion ? `${existing.liveVersion} live` : existing.status}): sending a new version.`
+  if (existing2) {
+    note(
+      `${bold(existing2.name)} is already yours (${existing2.liveVersion ? `${existing2.liveVersion} live` : existing2.status}): sending a new version.`
     );
-    const version = flags.version ?? (interactive ? await ask("Version", existing.nextVersion) : existing.nextVersion);
+    const version = flags.version ?? (interactive ? await ask("Version", existing2.nextVersion) : existing2.nextVersion);
     const notes = flags.notes ?? (interactive ? await ask("What changed", "") : "");
-    if (interactive && !await confirm(`Send ${existing.id} ${version} for review?`))
+    if (interactive && !await confirm(`Send ${existing2.id} ${version} for review?`))
       return say("Nothing sent.");
     const sent = await api(
       server2,
-      `/components/${existing.id}/versions`,
+      `/components/${existing2.id}/versions`,
       {
         method: "POST",
         body: { version, notes, files, preview }
@@ -474,17 +2371,18 @@ async function publish(server2, paths, flags) {
     ).catch((error) => {
       if (flags.ifChanged && error instanceof ApiFailure && (error.detail.code === "unchanged" || error.detail.code === "pending"))
         return error;
-      return explain(error);
+      return explain(error, flags.json);
     });
     if (sent instanceof ApiFailure) {
-      say(
-        `Nothing sent: ${Object.values(sent.detail.errors ?? {})[0] ?? sent.message}`
-      );
+      const message = Object.values(sent.detail.errors ?? {})[0] ?? sent.message;
+      if (flags.json)
+        say(JSON.stringify({ sent: false, status: sent.detail.code, message }));
+      else note(`Nothing sent: ${message}`);
       return;
     }
     result = sent;
   } else {
-    if (flags.version && flags.version !== "1.0.0")
+    if (!flags.json && flags.version && flags.version !== "1.0.0")
       warn(
         yellow(
           `New components start at 1.0.0; ignoring --version ${flags.version}.`
@@ -526,8 +2424,13 @@ async function publish(server2, paths, flags) {
         darkOnly: flags.darkOnly ?? false,
         preview
       }
-    }).catch(explain);
+    }).catch((error) => explain(error, flags.json));
   }
+  if (flags.json)
+    return say(
+      JSON.stringify({ sent: true, status: "review", ...result }, null, 2)
+    );
+  result = terminalData(result);
   say(green(`\u2713 ${result.component} ${result.version} is in review.`));
   say(`  ${result.message}`);
   say(`  Studio: ${result.studio}`);
@@ -538,23 +2441,34 @@ async function publish(server2, paths, flags) {
 async function search(server2, words, flags) {
   const q = words.join(" ").trim();
   if (!q) throw new CliError("Give some words: layro search <words\u2026>");
+  if (flags.limit && (!/^\d+$/.test(flags.limit) || Number(flags.limit) < 1 || Number(flags.limit) > 50))
+    throw new CliError(
+      "--limit must be an integer from 1 to 50. Example: layro search chart --limit 10."
+    );
   const params = new URLSearchParams({ q });
   if (flags.category) params.set("category", flags.category);
   if (flags.author) params.set("author", flags.author);
   if (flags.limit) params.set("limit", flags.limit);
   const found = await api(server2, `/search?${params}`, { auth: false });
+  for (const result of found.results) {
+    if (!/^@?[a-zA-Z0-9][a-zA-Z0-9_-]*\/[a-z0-9][a-z0-9-]*$/.test(result.id))
+      throw new CliError(
+        "The search API returned an invalid component id. Check LAYRO_URL and retry."
+      );
+    result.install = `npx layro-cli add @${result.id.replace(/^@/, "")}`;
+  }
   if (flags.json) return say(JSON.stringify(found, null, 2));
   if (found.results.length === 0) {
-    say(`Nothing matches "${q}".`);
+    say(`Nothing matches "${safeText(q)}".`);
     if (found.suggestion)
       say(
-        `The closest category is ${bold(found.suggestion.name)}: ${found.suggestion.url}`
+        `The closest category is ${bold(safeText(found.suggestion.name))}: ${safeText(found.suggestion.url)}`
       );
     return;
   }
   for (const c of found.results) {
-    say(`${bold(c.name)} ${dim(c.id)}`);
-    say(`  ${c.description}`);
+    say(`${bold(safeText(c.name))} ${dim(c.id)}`);
+    say(`  ${safeText(c.description)}`);
     say(dim(`  ${c.install}`));
   }
   say(
@@ -572,14 +2486,16 @@ var LABEL = {
   processing: "processing",
   approved: "approved"
 };
-async function status(server2, target) {
+async function status(server2, target, json = false) {
   if (target) {
     const me = target.includes("/") ? null : await api(server2, "/me");
     const id = me ? `${me.handle}/${target}` : target;
-    const one = await api(
+    let one = await api(
       server2,
       `/status?component=${encodeURIComponent(id)}`
     );
+    if (json) return say(JSON.stringify(one, null, 2));
+    one = terminalData(one);
     say(`${bold(one.name)} ${dim(one.id)}: ${LABEL[one.status] ?? one.status}`);
     if (one.url) say(`  ${one.url}`);
     say(`  Studio: ${one.studio}`);
@@ -597,18 +2513,20 @@ async function status(server2, target) {
     }
     return;
   }
-  const all = await api(server2, "/status");
+  let all = await api(server2, "/status");
+  if (json) return say(JSON.stringify(all, null, 2));
+  all = terminalData(all);
   say(`@${all.author}`);
   if (all.components.length === 0) {
     say(dim("No components yet. Send one with layro publish <files>."));
   }
   for (const c of all.components) {
-    const open = c.latestSubmission;
+    const open2 = c.latestSubmission;
     say(
-      `  ${c.id.padEnd(36)} ${(LABEL[c.status] ?? c.status).padEnd(18)} ${c.version}${open && c.status === "live" ? dim(` \xB7 ${open.version} ${LABEL[open.status] ?? open.status}`) : ""}`
+      `  ${c.id.padEnd(36)} ${(LABEL[c.status] ?? c.status).padEnd(18)} ${c.version}${open2 && c.status === "live" ? dim(` \xB7 ${open2.version} ${LABEL[open2.status] ?? open2.status}`) : ""}`
     );
-    if (open?.status === "rejected" && open.decisionNote)
-      say(`    ${red("Reason:")} ${open.decisionNote}`);
+    if (open2?.status === "rejected" && open2.decisionNote)
+      say(`    ${red("Reason:")} ${open2.decisionNote}`);
   }
   say(
     dim(
@@ -626,7 +2544,10 @@ Usage
   layro whoami                Who you're signed in as
   layro publish <files\u2026>      Send a new component, or a new version of yours
   layro status [component]    Where your submissions stand (component: slug or author/slug)
-  layro add <author/slug>     How to install a component (shadcn does it)
+  layro add <author/slug>     Install a component into your project
+  layro init                  Set up shared helpers and check Tailwind
+  layro mcp                   Add Layro to your coding agent (Claude Code,
+                              Cursor, VS Code, Codex): no URL to type
   layro logout                Sign out on this computer
 
 Publish options
@@ -640,6 +2561,7 @@ Publish options
   --preview <plan.json>       How to film its preview (see the docs)
   --if-changed                Unchanged code, or a version still in review: say so, exit 0 (CI)
   -y, --yes                   Don't ask; send what's given (for CI)
+  --json                      No prompts; machine-readable result and errors
 
 Search options
   --category <slug>           Only this category
@@ -649,6 +2571,10 @@ Search options
 
 Login options
   --no-browser                Print the sign-in link instead of opening it
+  --timeout <seconds>         Wait 1 to 300 seconds for consent (default 300)
+  --json                      Newline-delimited authorization/result events
+
+Use layro <command> --help for options and examples for each command.
 
 Environment
   LAYRO_TOKEN                 A token to use instead of signing in: an access
@@ -660,9 +2586,13 @@ var server = (process.env.LAYRO_URL || "https://layro.dev").replace(
   /\/+$/,
   ""
 );
-async function whoami() {
+async function whoami(json = false) {
   const me = await api(server, "/me");
-  say(`@${me.handle} ${dim(`on ${server}`)}`);
+  if (json) {
+    say(JSON.stringify(me, null, 2));
+    return me;
+  }
+  say(`@${safeText(me.handle)} ${dim(`on ${safeText(server)}`)}`);
   say(
     dim(
       `Submissions left today: ${me.submissions.left} of ${me.submissions.limit}`
@@ -671,34 +2601,116 @@ async function whoami() {
   return me;
 }
 async function main(argv) {
+  if (argv[0] === "help" && argv[1]) return main([argv[1], "--help"]);
   const [command, ...rest] = argv;
   if (!command || command === "help" || command === "--help" || command === "-h")
     return say(HELP);
   if (command === "--version" || command === "-v") return say(VERSION);
+  if ((rest.includes("--help") || rest.includes("-h")) && commandHelp[command])
+    return say(commandHelp[command]);
   switch (command) {
+    case "init": {
+      if (rest.includes("--help") || rest.includes("-h"))
+        return say(`layro init [options]
+
+Check React, TypeScript, import aliases and Tailwind. Create components.json
+and lib/utils.ts (cn), then install clsx and tailwind-merge with scripts off.
+Existing shadcn configuration and helpers are preserved. Run twice safely.
+If setup is missing, print the exact next steps and stop before writing.
+Init does not create an app or rewrite bundler configuration.
+
+  --cwd <folder>   App package (default current folder)
+  --dry-run        Show the plan; change nothing
+  -y, --yes        Never prompt
+  --json          Machine-readable result or error
+
+Examples:
+  npx layro-cli init --yes
+  layro init --cwd apps/web --dry-run --json`);
+      const { values } = parseArgs({
+        args: rest,
+        options: {
+          cwd: { type: "string" },
+          "dry-run": { type: "boolean" },
+          yes: { type: "boolean", short: "y" },
+          json: { type: "boolean" }
+        }
+      });
+      await add(server, [], values, true);
+      return;
+    }
+    case "mcp": {
+      const args = rest[0] === "add" || rest[0] === "init" ? rest.slice(1) : rest;
+      const { values } = parseArgs({
+        args,
+        options: {
+          client: { type: "string", short: "c" },
+          cwd: { type: "string" },
+          "dry-run": { type: "boolean" },
+          yes: { type: "boolean", short: "y" },
+          json: { type: "boolean" }
+        }
+      });
+      await addMcp(server, values);
+      return;
+    }
     case "login": {
       const { values } = parseArgs({
         args: rest,
-        options: { "no-browser": { type: "boolean" } }
+        options: {
+          "no-browser": { type: "boolean" },
+          json: { type: "boolean" },
+          timeout: { type: "string" }
+        }
+      });
+      if (!canAsk() && !values["no-browser"])
+        throw new CliError(
+          "Login needs a browser and consent. In a terminal run layro login; for an explicit headless flow use layro login --no-browser --timeout 300. For CI use LAYRO_TOKEN from /settings/tokens."
+        );
+      const timeout = values.timeout === void 0 ? 300 : Number(values.timeout);
+      if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300)
+        throw new CliError(
+          "--timeout must be an integer from 1 to 300 seconds."
+        );
+      const session = await login(server, {
+        browser: !values["no-browser"],
+        json: values.json,
+        timeout
       });
-      const session = await login(server, { browser: !values["no-browser"] });
       const me = await api(server, "/me");
       await setSession(server, { ...session, handle: me.handle });
-      say(green(`\u2713 Signed in as @${me.handle}.`));
+      if (values.json)
+        return say(JSON.stringify({ status: "signed_in", handle: me.handle }));
+      say(green(`\u2713 Signed in as @${safeText(me.handle)}.`));
       say(dim(`Tokens saved in ${credentialsPath()}`));
       return;
     }
     case "logout": {
+      const { values } = parseArgs({
+        args: rest,
+        options: { json: { type: "boolean" } }
+      });
       const out = await logout(server);
+      if (values.json)
+        return say(
+          JSON.stringify({
+            signedOut: out,
+            tokenEnvironmentSet: Boolean(process.env.LAYRO_TOKEN)
+          })
+        );
       say(out ? "Signed out." : "You weren't signed in.");
       if (process.env.LAYRO_TOKEN)
         say(dim("LAYRO_TOKEN is still set in this shell."));
       return;
     }
     case "whoami": {
+      const { values } = parseArgs({
+        args: rest,
+        options: { json: { type: "boolean" } }
+      });
       if (!process.env.LAYRO_TOKEN && !(await getSession(server))?.accessToken)
         throw new CliError("Not signed in. Run `npx layro-cli login`.");
-      await whoami();
+      await whoami(values.json);
       return;
     }
     case "publish": {
@@ -715,7 +2727,8 @@ async function main(argv) {
           preview: { type: "string" },
           "dark-only": { type: "boolean" },
           "if-changed": { type: "boolean" },
-          yes: { type: "boolean", short: "y" }
+          yes: { type: "boolean", short: "y" },
+          json: { type: "boolean" }
         }
       });
       const {
@@ -745,20 +2758,55 @@ async function main(argv) {
       return;
     }
     case "status": {
-      const { positionals } = parseArgs({ args: rest, allowPositionals: true });
-      await status(server, positionals[0]);
+      const { positionals, values } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: { json: { type: "boolean" } }
+      });
+      if (positionals.length > 1)
+        throw new CliError(
+          "Use one component: layro status author/slug --json."
+        );
+      await status(server, positionals[0]?.replace(/^@/, ""), values.json);
       return;
     }
     case "add": {
-      const id = rest[0] ?? "<author>/<slug>";
-      say("Layro components install with the shadcn CLI:");
-      say(`  npx shadcn@latest add ${server}/r/${id}.json`);
-      say(dim("Or add Layro as a registry in components.json, then:"));
-      say(dim(`  npx shadcn@latest add @layro/${id}`));
+      if (rest.includes("--help") || rest.includes("-h"))
+        return say(`layro add @author/slug [more...] [options]
+
+Install Layro source, shared cn, CSS and npm dependencies in a React TypeScript app.
+Reads components.json and project aliases. Dependencies resolve before any writes.
+Package scripts are disabled. Review third-party code before running your app.
+
+  --cwd <folder>   App package to install into (default current folder)
+  --path <folder>  Destination for component files, relative to app root
+  --dry-run        Show the plan without changing files or packages
+  -y, --yes        Skip differing existing files; never prompt
+  --overwrite     Replace differing files
+  --json          Machine-readable plan/result
+
+Examples:
+  npx layro-cli add @magicuidesign/aurora-text --yes
+  layro add author/one author/two --cwd apps/web --dry-run --json`);
+      const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+          cwd: { type: "string" },
+          path: { type: "string" },
+          "dry-run": { type: "boolean" },
+          yes: { type: "boolean", short: "y" },
+          overwrite: { type: "boolean" },
+          json: { type: "boolean" }
+        }
+      });
+      await add(server, positionals, values);
       return;
     }
     default:
-      throw new CliError(`Unknown command "${command}". Run layro --help.`);
+      throw new CliError(
+        `Unknown command "${safeText(command)}".${suggestCommand(command)} Run layro --help.`
+      );
   }
 }
 process.stdout.on("error", (error) => {
@@ -766,12 +2814,34 @@ process.stdout.on("error", (error) => {
   throw error;
 });
 main(process.argv.slice(2)).catch((error) => {
-  if (error instanceof CliError) {
-    warn(red(error.message));
+  if (process.argv.includes("--json")) {
+    say(
+      JSON.stringify({
+        error: error instanceof Error ? error.message : "Could not finish the command.",
+        ...error instanceof ApiFailure ? {
+          status: error.detail.status,
+          code: error.detail.code,
+          errors: error.detail.errors
+        } : {}
+      })
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (error instanceof SetupRequired) {
+    for (const line of error.message.split("\n")) warn(safeText(line));
+  } else if (error instanceof CliError) {
+    warn(red(safeText(error.message)));
   } else if (error?.code?.startsWith("ERR_PARSE_ARGS")) {
-    warn(red(error.message));
+    warn(red(safeText(error.message)));
   } else {
-    warn(red(`Unexpected error: ${error?.stack ?? error}`));
+    warn(
+      red(
+        safeText(
+          `Could not finish: ${error?.message ?? "unknown error"}.`
+        )
+      )
+    );
   }
   process.exit(1);
 });