@ergonui/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ErgonUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @ergonui/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create Bun + Vite + React 19 + Tailwind 4 applications and install editable ErgonUI component source. No ErgonUI repository clone is needed by consumers.
+
+This package is prepared for its first npm release. The `bunx @ergonui/cli` commands below become publicly available after publication. Until then, use the built executable or install its packed tarball locally.
+
+```sh
+bunx @ergonui/cli create my-app --components line-chart,pie-chart
+cd my-app
+bun run dev
+```
+
+Selected components are copied to `src/components/ui`; import them using the examples in the [handbook](https://ergonui.netlify.app/#/components). The starter configures aliases, Tailwind bindings, light/dark tokens, animation utilities, and `components.json`. Canvas and zoom helpers retain their dynamic import boundaries.
+
+For an existing Vite + React 19 TypeScript application:
+
+```sh
+bunx @ergonui/cli init
+bunx @ergonui/cli add button table-plus
+bunx @ergonui/cli add line-chart --dry-run
+```
+
+Initialization merges TypeScript aliases and a Vite configuration adapter while preserving existing plugins/settings, JSONC comments, CSS rules and existing token values. Version 1 supports a `@/*` source alias, aliases rooted at `@/`, a `src/main.tsx` entry (or its configured source-directory equivalent), and a TypeScript Vite configuration with one default export. Unsupported configurations fail before writing; use the manual handbook for other stacks/configurations.
+
+`add` refuses differing existing files before writing any files. Review your changes, then explicitly use `--overwrite` to replace customized components. Select `theme` with `--overwrite` to replace theme token values. Initialization preserves existing tokens by default. `--keep-theme` also prevents explicitly selected theme values from being replaced. Licenses shipped by the registry are retained.
+
+Options: `--cwd <path>`, `--components <comma-separated-names>`, `--registry <origin>`, `--overwrite`, `--keep-theme`, `--dry-run`, `--no-install`, `--help`, and `--version`. With `--no-install`, dependencies are recorded in package.json; run `bun install` before running your application.
+
+The default registry is `https://ergonui.netlify.app`. For unpublished component work:
+
+```sh
+bunx @ergonui/cli create local-app --components line-chart,pie-chart --registry http://localhost:5174
+```
+
+`init` saves that registry in `components.json`. Future `add` calls reuse it; a one-off `--registry` on `add` does not change the saved configuration. A missing entry reports its URL/status and exits before writing source. The CLI supports ErgonUI's generated UI/theme registry items, bundled local source and exact npm versions; it is not a general-purpose installer for every third-party registry format.
+
+Dependency installation happens after files are written. If Bun installation fails, resolve the reported error and retry the same command to install the declared dependencies. Registry source is copied at installation time; applications run independently of the registry afterward.
+
+## Development and publication
+
+From this directory:
+
+```sh
+bun install --frozen-lockfile
+bun run check
+bun run test
+bun run build
+npm pack --dry-run
+```
+
+See [the publishing guide](../../docs/PUBLISHING.md) for npm scope ownership, first-release validation and publishing. The repository root remains private; publish from `packages/cli` only.
+
+ErgonUI is built on shadcn/ui component source and community work, including copied/adapted MIT-licensed components alongside original work. This CLI is original ErgonUI code. Registry payloads preserve the applicable source licenses; retain them in consuming applications. See the repository's `THIRD-PARTY-NOTICES.md` for provenance.

package/dist/index.js

@@ -0,0 +1,619 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/index.ts
+import { parseArgs } from "util";
+
+// src/engine.ts
+import { readdir, realpath } from "fs/promises";
+import { fileURLToPath } from "url";
+import { basename, resolve as resolve3 } from "path";
+import { spawnSync } from "child_process";
+
+// src/files.ts
+import { lstat, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+async function read(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
+}
+function json(content, path) {
+  const errors = [];
+  const value = parse(content, errors, { allowTrailingComma: true });
+  if (errors.length || !value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid JSON configuration: ${path}`);
+  return value;
+}
+function setJSON(content, path, value) {
+  return applyEdits(content, modify(content, path, value, {
+    formattingOptions: { insertSpaces: true, tabSize: 2, eol: `
+` }
+  }));
+}
+async function destination(root, path) {
+  if (!path || path.includes("\\") || path.includes(":") || /[\x00-\x1f]/.test(path) || isAbsolute(path) || path.split("/").some((part) => !part || part === "." || part === ".."))
+    throw new Error(`Unsafe destination: ${path}`);
+  const target = resolve(root, path);
+  const inside = relative(root, target);
+  if (inside.startsWith(`..${sep}`) || inside === ".." || isAbsolute(inside))
+    throw new Error(`Destination escapes application: ${path}`);
+  let current = target;
+  while (current !== dirname(root)) {
+    try {
+      if ((await lstat(current)).isSymbolicLink())
+        throw new Error(`Refusing symlink destination: ${path}`);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+    }
+    if (current === root)
+      break;
+    current = dirname(current);
+  }
+  return target;
+}
+async function apply(root, changes, overwrite, dryRun) {
+  const seen = new Set;
+  const prepared = [];
+  for (const change of changes) {
+    const key = change.path.toLowerCase();
+    if (seen.has(key))
+      throw new Error(`Duplicate destination: ${change.path}`);
+    seen.add(key);
+    const target = await destination(root, change.path);
+    const before = await read(target);
+    if (before === change.content)
+      continue;
+    const conflict = before !== undefined && !change.replace && !overwrite;
+    prepared.push({ ...change, target, conflict, before });
+  }
+  const conflicts = prepared.filter((change) => change.conflict);
+  if (conflicts.length && !dryRun)
+    throw new Error(`Existing files differ: ${conflicts.map((change) => change.path).join(", ")}. Review them, then use --overwrite to replace them. No files were written.`);
+  for (const change of prepared) {
+    console.log(`${change.conflict ? "conflict" : change.before === undefined ? "create" : "update"} ${change.path}`);
+    if (!dryRun) {
+      await destination(root, change.path);
+      await mkdir(dirname(change.target), { recursive: true });
+      await writeFile(change.target, change.content);
+    }
+  }
+  return prepared;
+}
+
+// src/config.ts
+import ts from "typescript";
+import postcss from "postcss";
+import { dirname as dirname2, posix, resolve as resolve2 } from "path";
+var DEFAULT_REGISTRY = "https://ergonui.netlify.app";
+var tooling = ["tailwindcss@4.3.3", "@tailwindcss/vite@4.3.3", "@types/node@26.6.6"];
+function registryOrigin(value) {
+  const url = new URL(value);
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+    throw new Error("Registry must be an HTTP(S) origin/base path without credentials, query or hash.");
+  return url.toString().replace(/\/$/, "");
+}
+function viteConfiguration(content, source) {
+  const file = ts.createSourceFile("vite.config.ts", content, ts.ScriptTarget.Latest, true);
+  const exports = file.statements.filter(ts.isExportAssignment);
+  if (exports.length !== 1 || exports[0].isExportEquals)
+    throw new Error("Vite configuration must have one default export. Configure Tailwind and the @ alias manually before retrying.");
+  if (content.includes("// ErgonUI configuration adapter"))
+    return content;
+  let hasAlias = false;
+  let hasTailwind = false;
+  const tailwindImports = new Set;
+  for (const node of file.statements) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text === "@tailwindcss/vite" && node.importClause?.name)
+      tailwindImports.add(node.importClause.name.text);
+  }
+  function visit(node) {
+    if (ts.isPropertyAssignment(node) && (ts.isStringLiteral(node.name) || ts.isIdentifier(node.name)) && node.name.text === "@")
+      hasAlias = true;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && tailwindImports.has(node.expression.text))
+      hasTailwind = true;
+    ts.forEachChild(node, visit);
+  }
+  visit(file);
+  if (hasAlias && hasTailwind)
+    return content;
+  if (content.includes("__ergon"))
+    throw new Error("Reserved __ergon identifiers already exist in Vite config; configure it manually.");
+  const declaration = exports[0];
+  const imports = [
+    "import { defineConfig as __ergonDefineConfig, mergeConfig as __ergonMergeConfig } from 'vite'"
+  ];
+  if (!hasTailwind)
+    imports.push("import __ergonTailwind from '@tailwindcss/vite'");
+  if (!hasAlias)
+    imports.push("import { fileURLToPath as __ergonPath } from 'node:url'");
+  const additions = [
+    ...!hasTailwind ? ["plugins: [__ergonTailwind()]"] : [],
+    ...!hasAlias ? [
+      `resolve: { alias: { '@': __ergonPath(new URL(${JSON.stringify(`./${source}`)}, import.meta.url)) } }`
+    ] : []
+  ];
+  const replacement = `// ErgonUI configuration adapter
+const __ergonOriginal = ${declaration.expression.getText(file)}
+async function __ergonResolve(__ergonConfig: import('vite').UserConfigExport, __ergonEnv: import('vite').ConfigEnv) {
+  return typeof __ergonConfig === 'function' ? await __ergonConfig(__ergonEnv) : await __ergonConfig
+}
+export default __ergonDefineConfig(async (__ergonEnv) => __ergonMergeConfig(
+  await __ergonResolve(__ergonOriginal, __ergonEnv),
+  { ${additions.join(", ")} },
+))`;
+  return `${imports.join(`
+`)}
+${content.slice(0, declaration.getStart(file))}${replacement}${content.slice(declaration.end)}
+`;
+}
+async function configure(root, registry, initialize) {
+  const changes = [];
+  const pkgContent = await read(resolve2(root, "package.json"));
+  if (!pkgContent)
+    throw new Error("Run inside a Vite + React application, or use ergonui create <directory>.");
+  const pkg = json(pkgContent, "package.json");
+  if (!pkg.dependencies?.react?.match(/(?:19|\*)/) || !(pkg.devDependencies?.vite || pkg.dependencies?.vite))
+    throw new Error("Version 1 supports Vite + React 19 applications. Keep other stacks on manual installation.");
+  const existing = await read(resolve2(root, "components.json"));
+  if (!existing && !initialize)
+    throw new Error("Run ergonui init before adding components.");
+  const config = existing ? json(existing, "components.json") : {};
+  const configPath = config.registries?.["@ergonui"];
+  const savedRegistry = typeof configPath === "string" && configPath.endsWith("/r/{name}.json") ? configPath.slice(0, -"/r/{name}.json".length) : undefined;
+  const origin = registryOrigin(registry ?? savedRegistry ?? DEFAULT_REGISTRY);
+  let source = "src";
+  const aliasesFound = [];
+  for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
+    const before = await read(resolve2(root, name));
+    if (!before) {
+      if (name === "tsconfig.json")
+        throw new Error("A TypeScript Vite project with tsconfig.json is required.");
+      continue;
+    }
+    const current = json(before, name);
+    const alias = current.compilerOptions?.paths?.["@/*"];
+    if (alias) {
+      if (!Array.isArray(alias) || alias.length !== 1 || !alias[0].endsWith("/*"))
+        throw new Error(`Unsupported @/* alias in ${name}`);
+      aliasesFound.push(alias[0].replace(/^\.\//, "").slice(0, -2));
+    }
+  }
+  if (new Set(aliasesFound).size > 1)
+    throw new Error("The @/* aliases in your TypeScript configurations disagree.");
+  source = aliasesFound[0] ?? source;
+  await destination(root, `${source}/main.tsx`);
+  const aliases = {
+    ui: config.aliases?.ui ?? "@/components/ui",
+    lib: config.aliases?.lib ?? "@/lib",
+    utils: config.aliases?.utils ?? "@/lib/utils"
+  };
+  for (const alias of Object.values(aliases)) {
+    if (typeof alias !== "string" || !alias.startsWith("@/"))
+      throw new Error("Version 1 supports aliases rooted at @/; preserve your setup using manual installation for other alias prefixes.");
+    await destination(root, `${source}/${alias.slice(2)}`);
+  }
+  let css = config.tailwind?.css;
+  const mainPath = `${source}/main.tsx`;
+  const main = await read(resolve2(root, mainPath));
+  if (initialize && !main)
+    throw new Error(`Expected ${mainPath}. Version 1 supports the standard Vite React TypeScript entry; configure other entries manually.`);
+  if (!css && main) {
+    const file = ts.createSourceFile(mainPath, main, ts.ScriptTarget.Latest, true);
+    const imported = file.statements.find((node) => ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith(".") && node.moduleSpecifier.text.endsWith(".css"));
+    if (imported)
+      css = posix.normalize(posix.join(source, imported.moduleSpecifier.text));
+  }
+  css ??= `${source}/index.css`;
+  await destination(root, css);
+  if (initialize) {
+    for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
+      const before = await read(resolve2(root, name));
+      if (before)
+        changes.push({
+          path: name,
+          content: setJSON(before, ["compilerOptions", "paths", "@/*"], [`./${source}/*`]),
+          replace: true
+        });
+    }
+    const vitePath = await read(resolve2(root, "vite.config.ts")) !== undefined ? "vite.config.ts" : "vite.config.mts";
+    const vite = await read(resolve2(root, vitePath));
+    if (!vite)
+      throw new Error("A vite.config.ts or vite.config.mts default export is required.");
+    changes.push({ path: vitePath, content: viteConfiguration(vite, source), replace: true });
+    if (main && !main.includes(`./${posix.relative(source, css)}`)) {
+      changes.push({
+        path: mainPath,
+        content: `import ${JSON.stringify(`./${posix.relative(dirname2(mainPath), css)}`)}
+${main}`,
+        replace: true
+      });
+    }
+    let updated = existing ?? `{}
+`;
+    const defaults = {
+      $schema: "https://ui.shadcn.com/schema.json",
+      style: "new-york",
+      rsc: false,
+      tsx: true,
+      tailwind: { config: "", css, baseColor: "neutral", cssVariables: true },
+      aliases: {
+        components: "@/components",
+        ui: aliases.ui,
+        lib: aliases.lib,
+        utils: aliases.utils,
+        hooks: "@/hooks"
+      }
+    };
+    for (const [key, value] of Object.entries(defaults)) {
+      if (config[key] === undefined)
+        updated = setJSON(updated, [key], value);
+      else if (typeof value === "object" && value !== null) {
+        for (const [nested, v] of Object.entries(value))
+          if (config[key]?.[nested] === undefined)
+            updated = setJSON(updated, [key, nested], v);
+      }
+    }
+    updated = setJSON(updated, ["registries", "@ergonui"], `${origin}/r/{name}.json`);
+    changes.push({ path: "components.json", content: updated, replace: true });
+  }
+  return { changes, source, css, aliases, registry: origin, config };
+}
+function stylesheet(content, vars, overwrite) {
+  const root = postcss.parse(content);
+  for (const name of ["tailwindcss", "tw-animate-css"]) {
+    let exists = false;
+    root.walkAtRules("import", (node) => {
+      if (node.params.match(/^['"]([^'"]+)['"]/)?.[1] === name)
+        exists = true;
+    });
+    if (!exists)
+      root.prepend(postcss.atRule({ name: "import", params: JSON.stringify(name) }));
+  }
+  let dark = false;
+  root.walkAtRules("custom-variant", (node) => {
+    if (node.params.startsWith("dark "))
+      dark = true;
+  });
+  if (!dark)
+    root.append(postcss.atRule({ name: "custom-variant", params: "dark (&:is(.dark *))" }));
+  let theme;
+  root.walkAtRules("theme", (node) => {
+    if (node.params === "inline")
+      theme = node;
+  });
+  if (!theme) {
+    theme = postcss.atRule({ name: "theme", params: "inline" });
+    root.append(theme);
+  }
+  const bound = new Set;
+  root.walkAtRules("theme", (node) => {
+    if (node.params === "inline")
+      node.walkDecls((declaration) => {
+        bound.add(declaration.prop);
+      });
+  });
+  for (const key of Object.keys(vars.light ?? {})) {
+    if (key === "radius")
+      continue;
+    const prop = `--color-${key}`;
+    if (!bound.has(prop))
+      theme.append({ prop, value: `var(--${key})` });
+  }
+  for (const [size, value] of Object.entries({
+    sm: "calc(var(--radius) - 4px)",
+    md: "calc(var(--radius) - 2px)",
+    lg: "var(--radius)",
+    xl: "calc(var(--radius) + 4px)"
+  }))
+    if (!bound.has(`--radius-${size}`))
+      theme.append({ prop: `--radius-${size}`, value });
+  for (const [mode, values] of Object.entries(vars)) {
+    if (!["light", "dark"].includes(mode))
+      continue;
+    const selector = mode === "light" ? ":root" : ".dark";
+    let rule;
+    root.each((node) => {
+      if (node.type === "rule" && node.selector === selector)
+        rule = node;
+    });
+    if (!rule) {
+      rule = postcss.rule({ selector });
+      root.append(rule);
+    }
+    for (const [key, value] of Object.entries(values)) {
+      let exists = false;
+      root.walkRules(selector, (candidate) => {
+        candidate.walkDecls(`--${key}`, (declaration) => {
+          exists = true;
+          if (overwrite)
+            declaration.value = value;
+        });
+      });
+      if (!exists)
+        rule.append({ prop: `--${key}`, value });
+    }
+  }
+  if (!content.includes("/* ErgonUI base styles */"))
+    root.append(postcss.comment({ text: "ErgonUI base styles" }), postcss.parse("@layer base { * { @apply border-border outline-ring/50; } body { @apply bg-background text-foreground; } }"));
+  return root.toString().trimEnd() + `
+`;
+}
+
+// src/engine.ts
+function componentNames(names) {
+  return [
+    ...new Set(names.flatMap((name) => name.split(",")).filter(Boolean).map((name) => {
+      const normalized = name.toLowerCase().replace(/\+$/, "-plus");
+      if (!/^[a-z][a-z0-9-]*$/.test(normalized))
+        throw new Error(`Invalid component name: ${name}`);
+      return normalized;
+    }))
+  ];
+}
+async function registryItem(origin, name) {
+  const url = `${registryOrigin(origin)}/r/${name}.json`;
+  const response = await fetch(url, { signal: AbortSignal.timeout(20000) });
+  if (!response.ok)
+    throw new Error(`Registry returned ${response.status} for ${name}: ${url}. Check that this component is deployed.`);
+  let item;
+  try {
+    item = await response.json();
+  } catch {
+    throw new Error(`Registry did not return JSON for ${name}: ${url}`);
+  }
+  if (item.name !== name || !["registry:ui", "registry:theme"].includes(item.type))
+    throw new Error(`Invalid registry entry: ${name}`);
+  if (item.type === "registry:ui" && (!Array.isArray(item.files) || !item.files.length))
+    throw new Error(`Registry source is missing for ${name}`);
+  if (item.type === "registry:theme" && (!item.cssVars?.light || !item.cssVars?.dark))
+    throw new Error(`Theme tokens are missing for ${name}`);
+  for (const dependency of item.dependencies ?? []) {
+    if (typeof dependency !== "string" || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*@\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(dependency))
+      throw new Error(`Registry dependency must be a pinned npm version: ${dependency}`);
+  }
+  return item;
+}
+function sourceFile(file, setup) {
+  if (typeof file.path !== "string" || typeof file.content !== "string" || file.path.includes("\\") || file.path.split("/").some((p) => p === ".." || p === "." || !p))
+    throw new Error("Invalid registry source file");
+  const { source, aliases } = setup;
+  let path;
+  if (/^src\/components\/ui\/[a-zA-Z0-9-]+\.tsx?$/.test(file.path))
+    path = `${source}/${aliases.ui.slice(2)}/${file.path.split("/").at(-1)}`;
+  else if (file.path === "src/lib/utils.ts")
+    path = `${source}/${aliases.utils.slice(2)}.ts`;
+  else if (/^src\/lib\/[a-zA-Z0-9-]+\.tsx?$/.test(file.path))
+    path = `${source}/${aliases.lib.slice(2)}/${file.path.split("/").at(-1)}`;
+  else if (/^LICENSES\/[a-zA-Z0-9._-]+$/.test(file.path))
+    path = file.path;
+  else
+    throw new Error(`Unsupported registry destination: ${file.path}`);
+  const content = file.path.startsWith("src/") ? file.content.replace(/(['"])@\/components\/ui\//g, `$1${aliases.ui}/`).replace(/(['"])@\/lib\/utils(['"])/g, `$1${aliases.utils}$2`).replace(/(['"])@\/lib\//g, `$1${aliases.lib}/`) : file.content;
+  return { path, content };
+}
+async function planEntries(root, setup, names, overwrite) {
+  const items = await Promise.all(names.map((name) => registryItem(setup.registry, name)));
+  const changes = new Map;
+  const dependencies = new Set;
+  for (const item of items) {
+    for (const dependency of item.dependencies ?? [])
+      dependencies.add(dependency);
+    for (const file of item.files ?? []) {
+      const change = sourceFile(file, setup);
+      await destination(root, change.path);
+      const key = change.path.toLowerCase();
+      const previous = changes.get(key);
+      if (previous && (previous.path !== change.path || previous.content !== change.content))
+        throw new Error(`Registry entries disagree about ${change.path}`);
+      changes.set(key, change);
+    }
+    if (item.cssVars) {
+      const before = await read(resolve3(root, setup.css)) ?? "";
+      changes.set(setup.css.toLowerCase(), {
+        path: setup.css,
+        content: stylesheet(before, item.cssVars, overwrite),
+        replace: true
+      });
+    }
+  }
+  const versions = new Map;
+  for (const dependency of dependencies) {
+    const name = dependency.slice(0, dependency.lastIndexOf("@"));
+    if (versions.has(name) && versions.get(name) !== dependency)
+      throw new Error(`Registry dependencies disagree on the version of ${name}`);
+    versions.set(name, dependency);
+  }
+  return { changes: [...changes.values()], dependencies: [...dependencies] };
+}
+function command(root, args) {
+  console.log(`bun ${args.join(" ")}`);
+  const result = spawnSync(process.execPath, args, { cwd: root, stdio: "inherit", shell: false });
+  if (result.error)
+    throw result.error;
+  if (result.status !== 0)
+    throw new Error(`bun ${args[0]} failed. Files are in place; resolve the dependency error and run bun install.`);
+}
+function declareDependencies(content, runtime, dev = []) {
+  for (const [section, dependencies] of [
+    ["dependencies", runtime],
+    ["devDependencies", dev]
+  ]) {
+    for (const dependency of dependencies) {
+      const separator = dependency.lastIndexOf("@");
+      const name = dependency.slice(0, separator);
+      content = setJSON(content, [section, name], dependency.slice(separator + 1));
+      const other = section === "dependencies" ? "devDependencies" : "dependencies";
+      if (json(content, "package.json")[other]?.[name] !== undefined)
+        content = setJSON(content, [other, name], undefined);
+    }
+  }
+  return content;
+}
+async function add(root, options, initialize) {
+  const setup = await configure(root, options.registry, initialize);
+  const names = componentNames(options.components ?? []);
+  const includeTheme = names.includes("theme") || initialize;
+  const entries = await planEntries(root, setup, [...new Set([...names, ...includeTheme ? ["theme"] : []])], !!options.overwrite && names.includes("theme") && !options.keepTheme);
+  const deps = [
+    ...new Set([...entries.dependencies, ...initialize ? ["tw-animate-css@1.4.0"] : []])
+  ];
+  const manifest = declareDependencies(await read(resolve3(root, "package.json")), deps, initialize ? tooling : []);
+  await apply(root, [
+    ...setup.changes,
+    ...entries.changes,
+    { path: "package.json", content: manifest, replace: true }
+  ], !!options.overwrite, !!options.dryRun);
+  if (options.dryRun)
+    console.log(`Dependencies: ${[...deps, ...initialize ? tooling : []].join(", ") || "none"}`);
+  else if (options.install !== false)
+    command(root, ["install"]);
+  else
+    console.log("Dependencies recorded in package.json. Run bun install before using the components.");
+  return { root, names };
+}
+async function run(commandName, positionals, options = {}) {
+  if (commandName === "create") {
+    if (positionals.length !== 1)
+      throw new Error("Usage: ergonui create <directory> [--components line-chart,pie-chart]");
+    const parent = options.cwd ?? process.cwd();
+    const root = resolve3(parent, positionals[0]);
+    if (await read(resolve3(root, "package.json")) !== undefined)
+      throw new Error("Target already contains an application. Use init inside it.");
+    try {
+      await realpath(root);
+      throw new Error("Create requires a new directory; existing directories are preserved.");
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+    }
+    const origin = registryOrigin(options.registry ?? DEFAULT_REGISTRY);
+    const names = componentNames(options.components?.length ? options.components : ["button"]);
+    const setup = {
+      changes: [],
+      source: "src",
+      css: "src/index.css",
+      aliases: { ui: "@/components/ui", lib: "@/lib", utils: "@/lib/utils" },
+      registry: origin,
+      config: {}
+    };
+    const entries = await planEntries(root, setup, [...new Set(["theme", ...names])], false);
+    const template = fileURLToPath(new URL("./template/", import.meta.url));
+    const changes = [];
+    async function walk(path = "") {
+      for (const entry of await readdir(resolve3(template, path), { withFileTypes: true })) {
+        const name = path ? `${path}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+          await walk(name);
+        else {
+          let content = await read(resolve3(template, name));
+          if (name === "package.json") {
+            const pkg = json(content, name);
+            pkg.name = basename(root).toLowerCase().replace(/[^a-z0-9-]/g, "-") || "ergonui-app";
+            content = JSON.stringify(pkg, null, 2) + `
+`;
+          }
+          changes.push({ path: name === "gitignore" ? ".gitignore" : name, content });
+        }
+      }
+    }
+    await walk();
+    const configured = {
+      $schema: "https://ui.shadcn.com/schema.json",
+      style: "new-york",
+      rsc: false,
+      tsx: true,
+      tailwind: { config: "", css: setup.css, baseColor: "neutral", cssVariables: true },
+      aliases: { components: "@/components", ...setup.aliases, hooks: "@/hooks" },
+      registries: { "@ergonui": `${origin}/r/{name}.json` }
+    };
+    changes.push({ path: "components.json", content: JSON.stringify(configured, null, 2) + `
+` });
+    const all = new Map(changes.map((change) => [change.path, change]));
+    for (const change of entries.changes)
+      all.set(change.path, change);
+    all.get("package.json").content = declareDependencies(all.get("package.json").content, entries.dependencies);
+    await apply(root, [...all.values()], false, !!options.dryRun);
+    if (!options.dryRun && options.install !== false) {
+      command(root, ["install"]);
+    } else if (!options.dryRun)
+      console.log("Dependencies recorded in package.json. Run bun install before starting the application.");
+    console.log(`${options.dryRun ? "Dry run: no files written." : "Created application."}
+${root}
+Next: cd ${JSON.stringify(positionals[0])} and bun run dev`);
+    return { root, names };
+  }
+  if (!["init", "add"].includes(commandName))
+    throw new Error(`Unknown command: ${commandName}`);
+  if (commandName === "init" && positionals.length)
+    throw new Error("Pass initial components with --components, not positional arguments, to init.");
+  const root = await realpath(resolve3(options.cwd ?? process.cwd()));
+  const components = [...options.components ?? [], ...commandName === "add" ? positionals : []];
+  if (commandName === "add" && !components.length)
+    throw new Error("Usage: ergonui add <component...>");
+  const result = await add(root, { ...options, components }, commandName === "init");
+  console.log(options.dryRun ? "Dry run: no files or dependencies changed." : "ErgonUI source is ready.");
+  return result;
+}
+
+// src/index.ts
+var help = `ErgonUI CLI 0.1.0 \u2014 Bun + Vite + React 19 + Tailwind 4
+
+Usage:
+  ergonui create my-app --components line-chart,pie-chart
+  ergonui init
+  ergonui add button table-plus
+
+Options:
+  --components <names>  Comma-separated component names
+  --cwd, -c <path>      Application/parent directory
+  --registry <origin>  Override the hosted ErgonUI registry (e.g. local preview)
+  --overwrite          Replace differing component files and explicitly selected theme values
+  --keep-theme         On init, preserve existing tokens while filling missing bindings/tokens
+  --dry-run            Preview changes without writing or installing
+  --no-install         Write files without installing npm dependencies
+  --help, -h           Show help
+  --version, -v        Show version
+
+Components are editable source with retained shadcn/ui and community attribution.
+`;
+try {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    options: {
+      components: { type: "string" },
+      cwd: { type: "string", short: "c" },
+      registry: { type: "string" },
+      overwrite: { type: "boolean" },
+      "keep-theme": { type: "boolean" },
+      "dry-run": { type: "boolean" },
+      "no-install": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
+    }
+  });
+  if (values.version)
+    console.log("0.1.0");
+  else if (values.help || !positionals.length)
+    console.log(help);
+  else
+    await run(positionals[0], positionals.slice(1), {
+      cwd: values.cwd,
+      registry: values.registry,
+      components: values.components?.split(","),
+      overwrite: values.overwrite,
+      dryRun: values["dry-run"],
+      install: !values["no-install"],
+      keepTheme: values["keep-theme"]
+    });
+} catch (error) {
+  console.error(`ErgonUI: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/dist/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.env*

package/dist/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ErgonUI application</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/dist/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "ergonui-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "4.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "tailwindcss": "4.3.3",
+    "tw-animate-css": "1.4.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.5"
+  }
+}

package/dist/template/src/App.tsx

@@ -0,0 +1,13 @@
+export default function App() {
+  return (
+    <main className="mx-auto max-w-3xl space-y-6 p-8">
+      <h1 className="text-3xl font-semibold">Make yourself at home.</h1>
+      <p className="text-muted-foreground">
+        Your ErgonUI application is ready. Import your selected components from @/components/ui.
+      </p>
+      <a className="text-primary underline" href="https://ergonui.netlify.app/#/components">
+        Explore components and usage examples
+      </a>
+    </main>
+  )
+}

package/dist/template/src/index.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/dist/template/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/dist/template/tsconfig.app.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src"]
+}

package/dist/template/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "files": [],
+  "compilerOptions": { "paths": { "@/*": ["./src/*"] } },
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

package/dist/template/tsconfig.node.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}

package/dist/template/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import { fileURLToPath, URL } from 'node:url'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
+})

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@ergonui/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Create Bun + Vite + React applications and install editable ErgonUI components.",
+  "type": "module",
+  "bin": {
+    "ergonui": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ganonym741/ergon-shadcn-ui.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://ergonui.netlify.app",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "scripts": {
+    "build": "bun build.ts",
+    "test": "bun run build && bun test test",
+    "check": "tsc -p tsconfig.json",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "jsonc-parser": "3.3.1",
+    "postcss": "8.5.6",
+    "typescript": "5.9.3"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.4"
+  }
+}