@webjsdev/ui 0.3.10 → 0.3.12

package/src/commands/init.js

@@ -1,8 +1,7 @@
 import { Command } from 'commander';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import prompts from 'prompts';
-import { defaultsForProject } from '../utils/detect-project.js';
 import { writeConfig, CONFIG_FILE } from '../utils/get-config.js';
 import { logger } from '../utils/logger.js';
 import { getRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
@@ -10,22 +9,96 @@ import { ensureTheme } from '../utils/theme.js';
 
 const BASE_COLORS = ['neutral', 'stone', 'zinc', 'mauve', 'olive', 'mist', 'taupe'];
 
+/**
+ * The stylesheet `init` defaults to. It is `styles/globals.css`, NOT
+ * `app/globals.css`, because in WebJs `app/` is routing-only, so a
+ * non-routing stylesheet lives outside it.
+ *
+ * Exported so `webjs create` can be checked against it rather than against a
+ * hand-copied literal (`test/scaffolds/scaffold-ui-integration.test.js`).
+ */
+export const DEFAULT_TAILWIND_CSS = 'styles/globals.css';
+
+/**
+ * The alias map `init` writes into `components.json`. These are the paths a
+ * WebJs app uses, and they match byte for byte what `webjs create` scaffolds
+ * (see `packages/cli/lib/create.js`), so `init` on a bare app and a freshly
+ * scaffolded one land on the same layout.
+ *
+ * `utils` is `lib/utils/cn`, not `lib/utils`: `get-config.js` appends `'.ts'`
+ * when resolving the alias, so this resolves to `lib/utils/cn.ts`. Writing
+ * the helper into the `lib/utils/` DIRECTORY is what lets the client-only
+ * `onBeforeCache()` helper sit beside it at `lib/utils/dom.ts` (#819), which
+ * is where `add` rewrites the registry's `'../lib/dom.ts'` import to point.
+ *
+ * Exported for the same drift check as {@link DEFAULT_TAILWIND_CSS}. The two
+ * generators used to disagree here (init said `lib/utils`, the scaffold said
+ * `lib/utils/cn`) with only a comment claiming they matched, so the agreement
+ * is asserted now rather than described.
+ */
+export const DEFAULT_ALIASES = {
+  components: 'components',
+  utils: 'lib/utils/cn',
+  ui: 'components/ui',
+  lib: 'lib',
+};
+
 export const init = new Command()
   .name('init')
-  .description('Initialize @webjsdev/ui in a project: writes components.json, theme CSS, lib/utils')
+  .description('Initialize @webjsdev/ui in a project: writes components.json, theme CSS, lib/utils/cn.ts')
   .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
   .option('-y, --yes', 'skip confirmation prompts', false)
   .option('--base-color <color>', `base color (${BASE_COLORS.join('|')})`)
   .option('--css <path>', 'path to the project Tailwind CSS file')
+  .option('-o, --overwrite', 'replace an existing alias map and existing helper files', false)
   .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
   .action(async (opts) => {
     const cwd = opts.cwd;
-    const defaults = defaultsForProject(cwd);
+
+    // Re-running `init` on a project that already has one must not RELOCATE it.
+    // The alias map decides where cn() lives and what every already-added
+    // component imports, and `tailwind.css` decides which stylesheet the app
+    // actually builds, so adopting the current defaults over an existing
+    // project's values would strand those imports and append the tokens to a
+    // file nothing compiles. Keep what the project declared; `--overwrite`
+    // opts into replacing it.
+    //
+    // Read the RAW json rather than going through `getConfig`: its schema is
+    // `.strict()`, so a config carrying any unknown key (a shadcn-shaped one
+    // with `rsc` / `tsx`, or a hand-added field) throws, and treating that as
+    // "no config" is exactly what would relocate a real project and then
+    // overwrite the file. Only a file we cannot parse AT ALL is a refusal,
+    // because silently replacing unreadable config is the same data loss.
+    const cfgPath = join(cwd, CONFIG_FILE);
+    /** @type {any} */
+    let existing = null;
+    if (existsSync(cfgPath)) {
+      try {
+        existing = JSON.parse(readFileSync(cfgPath, 'utf8'));
+      } catch {
+        if (!opts.overwrite) {
+          logger.error(`${CONFIG_FILE} exists but is not valid JSON, so its settings cannot be preserved.`);
+          logger.info('Fix or delete it, or re-run with --overwrite to replace it.');
+          process.exit(1);
+        }
+      }
+    }
+    const keep = existing && !opts.overwrite;
+    if (keep) {
+      logger.info(`${CONFIG_FILE} already exists: keeping its settings (use --overwrite to reset them).`);
+    }
+    // Layer over the defaults rather than replacing them: the schema gives
+    // several alias keys defaults, so a hand-written map may legitimately omit
+    // one, and reading it raw (above) skips that default-filling. Taking the
+    // map wholesale left `utils` undefined and crashed on the write.
+    const aliases = { ...DEFAULT_ALIASES, ...((keep && existing.aliases) || null) };
+    const initialCss = (keep && existing.tailwind && existing.tailwind.css) || DEFAULT_TAILWIND_CSS;
+    const initialBaseColor = (keep && existing.tailwind && existing.tailwind.baseColor) || 'neutral';
 
     /** @type {{ baseColor: string, css: string }} */
     let answers = {
-      baseColor: opts.baseColor || 'neutral',
-      css: opts.css || defaults.tailwindCss,
+      baseColor: opts.baseColor || initialBaseColor,
+      css: opts.css || initialCss,
     };
 
     if (!opts.yes) {
@@ -36,13 +109,13 @@ export const init = new Command()
             name: 'baseColor',
             message: 'Base color?',
             choices: BASE_COLORS.map((c) => ({ title: c, value: c })),
-            initial: 0,
+            initial: Math.max(0, BASE_COLORS.indexOf(initialBaseColor)),
           },
           {
             type: opts.css ? null : 'text',
             name: 'css',
             message: 'Tailwind CSS file path?',
-            initial: defaults.tailwindCss,
+            initial: initialCss,
           },
         ],
         { onCancel: () => process.exit(1) },
@@ -50,23 +123,29 @@ export const init = new Command()
       answers = { ...answers, ...r };
     }
 
+    // Built from KNOWN keys only. The schema is `.strict()`, so carrying an
+    // unrecognised key through here would write a file that `getConfig` (and
+    // therefore `add` / `diff` / `info`) throws on. Preserving a project's
+    // settings means its VALUES, not arbitrary extra fields.
     const config = {
       $schema: 'https://ui.webjs.dev/schema.json',
-      style: 'default',
+      style: (keep && existing.style) || 'default',
       tailwind: {
         css: answers.css,
         baseColor: answers.baseColor,
-        cssVariables: true,
+        cssVariables: keep && existing.tailwind && existing.tailwind.cssVariables !== undefined
+          ? existing.tailwind.cssVariables
+          : true,
       },
-      aliases: defaults.aliases,
-      iconLibrary: 'lucide',
+      aliases,
+      iconLibrary: (keep && existing.iconLibrary) || 'lucide',
     };
 
     writeConfig(cwd, config);
     logger.success(`Wrote ${CONFIG_FILE}`);
 
     // Pull lib/utils + the chosen theme from the registry and write them in.
-    await writeLibUtils(cwd, defaults.aliases.utils, opts.registry);
+    await writeLibUtils(cwd, aliases.utils, opts.registry, opts.overwrite);
 
     // The theme tokens are what the class helpers render against. A silent
     // failure here (the old behaviour) left an unstyled install with a clean
@@ -83,33 +162,56 @@ export const init = new Command()
     logger.break();
     logger.success('Done.');
     logger.info('');
-    logger.info(`Add components with:  ${logger.cyan('npx webjsui add button card dialog')}`);
+    logger.info(`Add components with:  ${logger.cyan('npx @webjsdev/ui add button card dialog')}`);
   });
 
-async function writeLibUtils(cwd, utilsAlias, registryUrl) {
-  // `utils` alias points at e.g. "lib/utils" so we write to lib/utils.ts
+/**
+ * Write the two shared helpers, WITHOUT clobbering a copy the project already
+ * has. The kit is source-copied and you-own-it, so `lib/utils/cn.ts` is a file
+ * users are told to edit ("change one helper to retune the entire app"), and
+ * `webjs create` puts its own copy there. An unguarded write was harmless while
+ * init targeted `lib/utils.ts`, a path nothing else owned, but the moment it
+ * writes where the scaffold and the user's edits live it becomes silent data
+ * loss, and re-running init is the documented fix for an unstyled install. So
+ * an existing file is kept unless `--overwrite` says otherwise. `add` keeps
+ * the same two files on the same terms (its `--yes` skips prompts but does not
+ * license replacing them), and the theme is idempotent, so every path into a
+ * project leaves an edited helper alone.
+ */
+async function writeLibUtils(cwd, utilsAlias, registryUrl, overwrite) {
+  // The `utils` alias omits the extension ("lib/utils/cn"), matching how
+  // get-config.js resolves it, so append '.ts' to get the target path.
   const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
   const utilsTarget = join(cwd, utilsRel);
   try {
-    const item = await getRegistryItem('lib-utils', registryUrl);
-    if (item.files) {
-      for (const f of item.files) {
-        ensureDir(dirname(utilsTarget));
-        writeFileSync(utilsTarget, f.content || '', 'utf8');
-        logger.success(`Wrote ${utilsAlias}.ts`);
+    if (existsSync(utilsTarget) && !overwrite) {
+      logger.info(`${utilsRel} already exists: keeping it.`);
+    } else {
+      const item = await getRegistryItem('lib-utils', registryUrl);
+      if (item.files) {
+        for (const f of item.files) {
+          ensureDir(dirname(utilsTarget));
+          writeFileSync(utilsTarget, f.content || '', 'utf8');
+          logger.success(`Wrote ${utilsRel}`);
+        }
       }
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write ${utilsRel} manually.`);
   }
 
   // The onBeforeCache() DOM helper lives in a SEPARATE module (#819) because
   // it references `document`, so keeping it out of cn()'s file prevents the
   // elision analyzer pinning every page that imports cn to the browser.
   // Overlay components import it from `../lib/dom.ts`, so write it as a
-  // sibling of the utils file (e.g. lib/utils/dom.ts next to cn.ts).
+  // sibling of the utils file, which lands it at lib/utils/dom.ts next to
+  // cn.ts. `add` reads that same adjacency when it rewrites the import.
   const domTarget = join(dirname(utilsTarget), 'dom.ts');
   try {
+    if (existsSync(domTarget) && !overwrite) {
+      logger.info(`${relative(cwd, domTarget)} already exists: keeping it.`);
+      return;
+    }
     const item = await getRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
     for (const f of item.files) {
@@ -118,7 +220,7 @@ async function writeLibUtils(cwd, utilsAlias, registryUrl) {
       logger.success(`Wrote ${relative(cwd, domTarget)}`);
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write lib/dom.ts manually.`);
+    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write ${relative(cwd, domTarget)} manually.`);
   }
 }
 

package/src/registry/example.js

@@ -79,10 +79,13 @@ export function extractExample(src) {
 
 /**
  * The one-line pointer left in place of a stripped example. Uses the EXPLICIT
- * `npx @webjsdev/ui view` form (not the bare `webjsui` bin name, which npx would
- * resolve to an unrelated `webjsui` package when it is not a direct dep, e.g. in
- * a scaffolded app where `@webjsdev/ui` is only transitive). Works in a WebJs
- * app and a standalone project alike.
+ * `npx @webjsdev/ui view` form, not the bare `webjsui` bin name. `webjsui` is a
+ * bin declared INSIDE `@webjsdev/ui` and is not a published package name (the
+ * registry 404s on it), so `npx webjsui` resolves through a local
+ * `node_modules/.bin` link or not at all. This pointer is written into a file
+ * the user keeps, and it cannot know whether the project reading it later has
+ * the kit in its tree. The explicit form resolves either way. See invariant 8
+ * in this package's AGENTS.md for the rule every printed hint follows (#1264).
  */
 export function pointerLine(name) {
   return `Full usage example: npx @webjsdev/ui view ${name}  (or the MCP tool: ui ${name})`;

package/src/registry/fetcher.js

@@ -4,8 +4,16 @@ import { loadRegistryItem, loadRegistryIndex } from './local.js';
 /**
  * The canonical hosted registry. Local-first resolution applies ONLY for this
  * exact URL: it is the one registry whose sources ship inside the package.
+ *
+ * This moved from `https://ui.webjs.dev/registry` when the gallery merged into
+ * the marketing site (#1099). That old URL no longer serves the registry: it
+ * now redirects to the gallery PAGE, so a fetch of it follows the redirect and
+ * gets HTML. Versions 0.3.1 through 0.3.8 hardcode it and hit the network, so
+ * `webjsui add` is broken on those and cannot be corrected after publish.
+ * Since 0.3.9 the kit resolves LOCAL-first, which is why the break stops
+ * there: `add` / `list` / `view` never reach the network on this URL.
  */
-export const HOSTED_REGISTRY_URL = 'https://ui.webjs.dev/registry';
+export const HOSTED_REGISTRY_URL = 'https://webjs.dev/ui/registry';
 
 /**
  * Default registry URL. A `REGISTRY_URL` env var points at a CUSTOM registry,
@@ -47,7 +55,7 @@ export async function getRegistryItem(name, registryUrl) {
     const item = loadRegistryItem(name);
     if (!item) {
       throw new Error(
-        `Unknown registry item "${name}". Run \`webjsui list\` to see the available components.`,
+        `Unknown registry item "${name}". Run \`npx @webjsdev/ui list\` to see the available components.`,
       );
     }
     return item;

package/src/registry/local.js

@@ -8,8 +8,8 @@
  * item shape the hosted registry serves, so a local read and a network fetch
  * are interchangeable for every consumer.
  *
- * It is the plain-JS twin of the ui-website composer
- * (`packages/ui/packages/website/app/_lib/registry.server.ts`): both read
+ * It is the plain-JS twin of the website gallery composer
+ * (`website/modules/ui/queries/registry.server.ts`): both read
  * `packages/registry/registry.json` + the `components/*.ts` sources and
  * synthesize the 6 non-neutral base-colour themes from `themes/base-colors.js`.
  * Keeping the CLI on this module (rather than always hitting the network) is

package/src/utils/index.js

@@ -1,3 +1,2 @@
 export { getConfig, writeConfig, CONFIG_FILE } from './get-config.js';
-export { detectProject, defaultsForProject } from './detect-project.js';
 export { logger } from './logger.js';

package/src/utils/detect-project.js

@@ -1,63 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-/**
- * Detect the host project type so we can pick sensible defaults for paths.
- *
- * @param {string} cwd
- * @returns {{ type: 'webjs' | 'next' | 'vite' | 'astro' | 'plain', meta: any }}
- */
-export function detectProject(cwd = process.cwd()) {
-  const pkgPath = join(cwd, 'package.json');
-  if (!existsSync(pkgPath)) return { type: 'plain', meta: {} };
-
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-
-  if (deps['@webjsdev/server'] || deps['@webjsdev/cli'] || existsSync(join(cwd, 'app', 'layout.ts')) || existsSync(join(cwd, 'app', 'layout.js'))) {
-    return { type: 'webjs', meta: { pkg } };
-  }
-  if (deps['next']) return { type: 'next', meta: { pkg } };
-  if (deps['vite'] || deps['@vitejs/plugin-react'] || deps['@vitejs/plugin-vue']) return { type: 'vite', meta: { pkg } };
-  if (deps['astro']) return { type: 'astro', meta: { pkg } };
-
-  return { type: 'plain', meta: { pkg } };
-}
-
-/**
- * Pick default `aliases` + `tailwind.css` path based on the detected project.
- *
- * @param {string} cwd
- */
-export function defaultsForProject(cwd = process.cwd()) {
-  const { type } = detectProject(cwd);
-  switch (type) {
-    case 'webjs':
-      return {
-        // styles/globals.css, NOT app/globals.css: in webjs, app/ is routing-only,
-        // so a non-routing stylesheet lives outside it.
-        tailwindCss: 'styles/globals.css',
-        aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
-      };
-    case 'next':
-      return {
-        tailwindCss: 'app/globals.css',
-        aliases: { components: '@/components', utils: '@/lib/utils', ui: '@/components/ui', lib: '@/lib' },
-      };
-    case 'vite':
-      return {
-        tailwindCss: 'src/index.css',
-        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
-      };
-    case 'astro':
-      return {
-        tailwindCss: 'src/styles/globals.css',
-        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
-      };
-    default:
-      return {
-        tailwindCss: 'styles/globals.css',
-        aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
-      };
-  }
-}