@webjsdev/cli 0.10.25 → 0.10.27

package/bin/webjs.js

@@ -6,6 +6,7 @@ import { resolveBin } from '../lib/resolve-bin.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
+import { importWebjsdev } from '../lib/import-webjsdev.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -121,7 +122,7 @@ async function main() {
   // instead of crashing cryptically later. `help` is exempt so a user on an
   // old Node can still read usage.
   if (cmd !== 'help' && cmd !== undefined) {
-    const { assertNodeVersion } = await import('@webjsdev/server');
+    const { assertNodeVersion } = await importWebjsdev('@webjsdev/server');
     assertNodeVersion({ onFail: 'exit' });
   }
   switch (cmd) {
@@ -129,7 +130,7 @@ async function main() {
       // If we're already inside the reload child (node --watch or bun --hot),
       // start the server directly.
       if (process.env.__WEBJS_DEV_CHILD === '1') {
-        const { startServer } = await import('@webjsdev/server');
+        const { startServer } = await importWebjsdev('@webjsdev/server');
         // Load `.env` BEFORE resolving the port so a `PORT` set there is in
         // process.env at resolution time (#447). The server loads `.env`
         // too, but that runs too late to affect the port the CLI computes.
@@ -165,7 +166,7 @@ async function main() {
       });
 
       if (plan.mode === 'inline') {
-        const { startServer } = await import('@webjsdev/server');
+        const { startServer } = await importWebjsdev('@webjsdev/server');
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
         await startServer({ appDir: process.cwd(), port, dev: true });
@@ -182,7 +183,7 @@ async function main() {
       break;
     }
     case 'start': {
-      const { startServer } = await import('@webjsdev/server');
+      const { startServer } = await importWebjsdev('@webjsdev/server');
       // Load `.env` BEFORE resolving the port so a `PORT` set there wins over
       // the 8080 default (#447), same as for `dev`.
       loadAppEnv(process.cwd());
@@ -364,7 +365,7 @@ async function main() {
       break;
     }
     case 'check': {
-      const { checkConventions, RULES } = await import('@webjsdev/server/check');
+      const { checkConventions, RULES } = await importWebjsdev('@webjsdev/server/check');
 
       if (rest.includes('--rules')) {
         console.log('webjs check, correctness rules:');
@@ -390,7 +391,7 @@ async function main() {
       if (rest.includes('--json')) {
         // The projector lives in @webjsdev/mcp (the MCP `check` tool's home),
         // so `check --json` and the MCP tool stay byte-identical (#415).
-        const { projectCheck } = await import('@webjsdev/mcp/check-report');
+        const { projectCheck } = await importWebjsdev('@webjsdev/mcp/check-report');
         console.log(JSON.stringify(projectCheck(violations)));
         if (violations.length > 0) process.exit(1);
         break;
@@ -447,7 +448,7 @@ async function main() {
       // narrowing the @webjsdev/core `Route` href union + per-route `params`.
       // Opt-in codegen: the static types in @webjsdev/core work without it
       // (un-generated apps see `Route = string`).
-      const { generateRouteTypes } = await import('@webjsdev/server');
+      const { generateRouteTypes } = await importWebjsdev('@webjsdev/server');
       const { mkdir, writeFile } = await import('node:fs/promises');
       const appDir = process.cwd();
       const text = await generateRouteTypes(appDir);
@@ -545,7 +546,7 @@ Full docs: https://docs.webjs.com`);
       const sub = rest[0];
       const args = rest.slice(1);
       const appDir = process.cwd();
-      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, ensureVendorCommittable, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
+      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, ensureVendorCommittable, SUPPORTED_PROVIDERS } = await importWebjsdev('@webjsdev/server');
 
       // Parse `--from <provider>` once at the top so subcommands share it.
       // Mirrors importmap-rails's `bin/importmap pin foo --from jsdelivr`.
@@ -808,7 +809,7 @@ Full docs: https://docs.webjs.com`);
       // runnable directly as `npx @webjsdev/mcp`); `webjs mcp` delegates to it
       // for back-compat. The version advertised in the initialize handshake is
       // @webjsdev/mcp's own, resolved by its bin, so this passes none.
-      const { runMcpServer } = await import('@webjsdev/mcp');
+      const { runMcpServer } = await importWebjsdev('@webjsdev/mcp');
       const { createRequire } = await import('node:module');
       const require = createRequire(import.meta.url);
       let version = '0.0.0';

package/lib/create.js

@@ -39,9 +39,10 @@ function detectPackageManager() {
  * Decide whether `webjs create` runs the post-scaffold install, per target
  * runtime (#682). Node installs by default (it needs `node_modules` to run);
  * Bun SKIPS by default (zero-install: `bun run dev` resolves deps on the fly,
- * #675). Under Bun zero-install deps resolve to their LATEST version (ranges
- * and any lockfile are ignored at runtime, #690), so `bun install` is the path
- * to pinned, reproducible versions. Explicit flags win: `--install` forces it
+ * #675). Under Bun zero-install webjs pins a declared dep to its package.json
+ * version via the #685/#698 onLoad rewrite (a caret range now resolves the
+ * highest match, not absolute latest), so `bun install` is the path to a frozen
+ * lockfile, not a correctness fix. Explicit flags win: `--install` forces it
  * on, `--no-install` forces it off. The CLI entry points call this and pass an
  * explicit boolean to `scaffoldApp`, so the library default (no install unless
  * `install: true`) is unchanged for programmatic callers.
@@ -57,9 +58,9 @@ export function resolveCreateInstall({ runtime, explicitInstall, noInstall } = {
 }
 
 /**
- * Read the EXACT version of `@webjsdev/<pkg>` the scaffolding CLI ships with, so
- * the generated `package.json` pins it precisely and BOTH npm and bun resolve
- * the same version (#692). Walks the `require.resolve` node_modules search paths
+ * Read the EXACT version of `@webjsdev/<pkg>` the scaffolding CLI ships with.
+ * `webjsdevRange` carets over this for the generated `package.json` (#700), so a
+ * fresh app tracks the line the CLI shipped. Walks the `require.resolve` node_modules search paths
  * and fs-reads `<pkg>/package.json` directly: `@webjsdev/server` (and `ui`) hide
  * `./package.json` behind `exports`, so a bare `require('<pkg>/package.json')`
  * fails (same constraint #687 hit). Falls back to `'latest'` when the package is
@@ -83,18 +84,35 @@ function webjsdevVersion(pkg) {
 }
 
 /**
- * Exact third-party dep versions the scaffold pins (#692). These are template
- * deps the CLI does NOT itself depend on, so they cannot be read from the CLI's
- * closure (unlike `@webjsdev/*`). Pinned EXACT so npm and bun resolve identically
- * (a `^` range diverges: npm takes latest-in-range, bun zero-install takes
- * absolute latest, #690). Drizzle is the 1.0 relations-v2 RC the scaffold's db
- * code targets (its npm `latest` tag is a 0.x line, so a range would resolve the
- * wrong major under bun). Refresh on a deliberate bump, same as the old ranges.
+ * The `@webjsdev/<pkg>` specifier for the generated `package.json` (#700): a
+ * caret range over the version the scaffolding CLI ships with, so a fresh app
+ * picks up patch updates the way an npm user expects (a `^0.x` caret stays
+ * within the minor). Bun zero-install resolves a normal caret range correctly
+ * since #698, so this no longer diverges from npm. Falls back to `'latest'` when
+ * the version is not resolvable (keeps `^latest` from ever being emitted).
+ * @param {string} pkg  e.g. 'cli', 'core', 'server'
+ * @returns {string}
+ */
+function webjsdevRange(pkg) {
+  const v = webjsdevVersion(pkg);
+  return v === 'latest' ? 'latest' : '^' + v;
+}
+
+/**
+ * Third-party dep specifiers the scaffold ships (#700). These are template deps
+ * the CLI does NOT itself depend on, so they cannot be read from the CLI's
+ * closure (unlike `@webjsdev/*`). Since #698, Bun zero-install resolves a normal
+ * caret range correctly (highest match, not absolute latest), so `pg` is an
+ * idiomatic `^` range. Drizzle is PINNED to an exact RC: its 1.0 line is a
+ * PRERELEASE (`1.0.0-rc.3`), and Bun zero-install ENOENTs on a caret-prerelease
+ * inline specifier (`drizzle-orm@^1.0.0-rc.3`, verified on Bun 1.3.14) while the
+ * exact prerelease resolves, so drizzle must stay exact until the 1.0 stable
+ * ships. Refresh on a deliberate bump.
  */
 const SCAFFOLD_DEP_VERSIONS = {
   'drizzle-orm': '1.0.0-rc.3',
   'drizzle-kit': '1.0.0-rc.3',
-  pg: '8.22.0',
+  pg: '^8.22.0',
 };
 
 /**
@@ -418,21 +436,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // for relations v2. SQLite needs NO driver dependency: the connection
       // uses the built-in node:sqlite (Node) / bun:sqlite (Bun) via Drizzle's
       // node-sqlite / bun-sqlite adapters. Postgres still needs the pg driver.
-      // Exact pins (#692): npm and bun must resolve identical versions. A `^`
-      // range diverges (npm = latest-in-range; bun zero-install = absolute
-      // latest, #690), and drizzle's npm `latest` tag is a 0.x line, so a range
-      // would pull the wrong major under bun. @webjsdev/* are pinned to the
-      // versions the scaffolding CLI itself ships with.
+      // Since #698 a normal caret range resolves correctly under bun
+      // zero-install, so @webjsdev/* and pg are idiomatic `^` ranges (#700).
+      // Drizzle stays EXACT: its 1.0 line is a prerelease RC, and bun ENOENTs
+      // on a caret-prerelease inline specifier, so a range would break it.
       'drizzle-orm': SCAFFOLD_DEP_VERSIONS['drizzle-orm'],
       ...(dialect === 'postgres' ? { pg: SCAFFOLD_DEP_VERSIONS.pg } : {}),
-      '@webjsdev/cli': webjsdevVersion('cli'),
-      '@webjsdev/core': webjsdevVersion('core'),
-      '@webjsdev/server': webjsdevVersion('server'),
+      '@webjsdev/cli': webjsdevRange('cli'),
+      '@webjsdev/core': webjsdevRange('core'),
+      '@webjsdev/server': webjsdevRange('server'),
     },
     devDependencies: {
-      // Exact pin (#692): drizzle-kit is resolved under bun zero-install via
-      // `bun run db:generate` / `db:migrate`, so it must match drizzle-orm's
-      // exact version across runtimes (a range would diverge, #690).
+      // Exact pin: drizzle-kit shares drizzle-orm's prerelease 1.0 RC, which bun
+      // cannot resolve as a caret-prerelease range, so it stays exact (#700).
       'drizzle-kit': SCAFFOLD_DEP_VERSIONS['drizzle-kit'],
       ...(dialect === 'postgres' ? { '@types/pg': '^8.11.0' } : {}),
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
@@ -1476,10 +1492,11 @@ For AI agents, read this before editing scaffolded files:
     }
   } else if (isBun) {
     // Bun zero-install (#675): no install needed; `bun run dev` resolves deps on
-    // the fly. They resolve to LATEST (ranges + lockfile ignored at runtime,
-    // #690), so point at `bun install` for pinned, reproducible versions.
+    // the fly. Since #698 they resolve to their package.json versions (a caret
+    // range to its highest match), so point at `bun install` for a frozen
+    // lockfile and editor type intelligence, not a correctness fix.
     console.log(`Skipped install. Bun resolves dependencies on the fly, so 'bun run dev' and 'bun run start' work as-is (no node_modules).`);
-    console.log(`These resolve to each dependency's LATEST version. Run 'bun install' in ${name}/ when you want pinned, reproducible versions (and editor type intelligence).\n`);
+    console.log(`These resolve to the versions in package.json. Run 'bun install' in ${name}/ to freeze a lockfile and get editor type intelligence.\n`);
   }
 
   // Next-steps banner prints LAST so the actionable command is the

package/lib/import-webjsdev.js

@@ -0,0 +1,99 @@
+// Pin `@webjsdev/*` imports under Bun zero-install (#709).
+//
+// Under Bun zero-install a bare `import('@webjsdev/server')` from the cli (run
+// out of the global cache) ENOENTs: Bun's runtime auto-install ignores the cli's
+// declared range and flakily fetches latest, which fails. An INLINE-versioned
+// specifier (`@webjsdev/server@^0.8.0`) resolves reliably. So we read the version
+// the APP declares (the scaffold adds `@webjsdev/*` to its deps) and retry inline
+// only when the bare import fails, so Node and installed apps are unaffected.
+
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The cli's OWN package.json (one level up from this lib), used as the fallback
+// pin source for `@webjsdev/*` packages the app does not declare (mcp, ui).
+const CLI_PKG = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+
+/**
+ * Whether a declared version is a Bun inline-safe specifier: an exact version or
+ * a single caret / tilde / comparator range, but NOT a range over a prerelease
+ * (`^1.0.0-rc.3`, which Bun ENOENTs on, #703), a wildcard, a multi-token range,
+ * or a protocol range (`workspace:` / `file:`).
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function inlineSafeVersion(v) {
+  if (typeof v !== 'string') return false;
+  const m = /^(>=|<=|>|<|=|\^|~)?(\d+(?:\.\d+){0,2})([-+][0-9A-Za-z.-]+)?$/.exec(v);
+  return !!m && !(m[1] && m[3]);
+}
+
+/**
+ * The version a `package.json` at `pkgPath` declares for `name`, when it is
+ * inline-safe; else null.
+ * @param {string} name
+ * @param {string} pkgPath  absolute path to a package.json
+ * @returns {string | null}
+ */
+function declaredIn(name, pkgPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const v = { ...pkg.dependencies, ...pkg.devDependencies }[name];
+    if (inlineSafeVersion(v)) return v;
+  } catch { /* no readable package.json */ }
+  return null;
+}
+
+/**
+ * The inline-safe version to pin `name` to: the app's `package.json` (in `cwd`)
+ * first (it declares `@webjsdev/server` etc.), else the cli's OWN package.json
+ * (for `@webjsdev/*` the app does not declare, like `mcp` / `ui`). Null if
+ * neither has an inline-safe declaration.
+ * @param {string} name
+ * @param {string} [cwd]
+ * @returns {string | null}
+ */
+export function appDeclaredVersion(name, cwd = process.cwd()) {
+  return declaredIn(name, join(cwd, 'package.json')) || declaredIn(name, CLI_PKG);
+}
+
+/**
+ * Whether an import error is a resolution / not-found failure (so a version
+ * retry is warranted), vs a genuine load-time throw from the module's own code
+ * (which we must NOT retry, to avoid masking it and re-running side effects).
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isResolutionError(err) {
+  if (err && /** @type {any} */ (err).code === 'ERR_MODULE_NOT_FOUND') return true;
+  const msg = err && String(/** @type {any} */ (err).message || err);
+  // Narrow on purpose: Node sets the code above; Bun's auto-install miss is
+  // `ENOENT while resolving package '...'`. A broad "cannot find" would match
+  // ordinary runtime errors ("Cannot find user") and wrongly trigger a retry.
+  return !!msg && /ENOENT|resolving package|module not found/i.test(msg);
+}
+
+/**
+ * Import an `@webjsdev/*` module, pinning the version under Bun zero-install. On
+ * Node or an installed app the bare specifier resolves from `node_modules` (no
+ * retry). On a RESOLUTION failure (Bun zero-install), retry with the app's (else
+ * the cli's own) declared version inline. A real load-time throw is rethrown,
+ * not retried. A subpath (`/check`) is preserved across the rewrite.
+ * @param {string} spec  e.g. `@webjsdev/server` or `@webjsdev/server/check`
+ * @param {(s: string) => Promise<any>} [importer]  injectable for tests
+ * @returns {Promise<any>}
+ */
+export async function importWebjsdev(spec, importer = (s) => import(s)) {
+  try {
+    return await importer(spec);
+  } catch (err) {
+    if (!isResolutionError(err)) throw err;
+    const m = /^(@webjsdev\/[^/]+)(\/.*)?$/.exec(spec);
+    const pkg = m && m[1];
+    const sub = (m && m[2]) || '';
+    const v = pkg && appDeclaredVersion(pkg);
+    if (v) return await importer(pkg + '@' + v + sub);
+    throw err;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.25",
+  "version": "0.10.27",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -415,12 +415,17 @@ bun run dev            # or: bun run start  (no install step required)
 ```
 
 `bun create` does not run an install on Bun, so a fresh app serves immediately.
-Under zero-install, deps resolve to their LATEST version: ranges and any
-`bun.lock` are ignored by the runtime auto-install (only an exact `package.json`
-pin is honored, via an `onLoad` rewrite). Run `bun install` when you want pinned,
-reproducible versions (it materializes `node_modules` from the lockfile) or
-editor type intelligence. (To run a Node-flavored app on Bun instead, force `bun --bun run
-dev`, which still expects an install.)
+Under zero-install, Bun's runtime auto-install resolves a BARE import to LATEST
+(it ignores `package.json` and `bun.lock`), so webjs rewrites each declared dep's
+specifier to an inline-versioned one via an `onLoad` transform. The version is the
+`bun.lock` exact when present, else the `package.json` value when it is an
+inline-safe semver (an exact pin, or a caret / tilde / comparator range, which
+Bun resolves to the highest match). A protocol range (`workspace:`, `file:`), a
+wildcard (`*`), and a dist-tag (`latest`) stay at latest. Run `bun install` when
+you want versions frozen identically across machines (it materializes
+`node_modules` from the lockfile) or editor type intelligence. (To run a
+Node-flavored app on Bun instead, force `bun --bun run dev`, which still expects
+an install.)
 
 On Node the `.ts` type-stripping is the built-in `module.stripTypeScriptTypes`;
 on Bun (which has no built-in) it comes from `amaro` automatically, so the same