@dbx-tools/cli 0.1.21 → 0.1.23

package/package.json

@@ -6,8 +6,7 @@
     "directory": "workspaces/cli/dbx-tools"
   },
   "bin": {
-    "dbxtools": "./bin/dbxtools.ts",
-    "dbxtools.ts": "bin/dbxtools.ts"
+    "dbxtools": "./bin/dbxtools.ts"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
@@ -18,15 +17,15 @@
     "@clack/prompts": "^1.7.0",
     "commander": "^15.0.0",
     "pnpm": "^11.0.6",
-    "@dbx-tools/core": "0.1.21",
-    "@dbx-tools/shared-core": "0.1.21"
+    "@dbx-tools/core": "0.1.23",
+    "@dbx-tools/shared-core": "0.1.23"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.21",
+  "version": "0.1.23",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/bootstrap.ts

@@ -1,14 +1,17 @@
 /**
  * Bootstrap a brand-new folder into a working dbx-tools workspace before projen runs.
  */
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { intro, outro } from "@clack/prompts";
 import { exec } from "@dbx-tools/core";
 import { resolvePnpmArgv, runPnpm } from "./pnpm";
 import { rootLabel } from "./root";
 
-const DEFAULT_PROJEN_SPECIFIER = "@dbx-tools/projen";
+// Pin to `@latest` explicitly: a bare `@dbx-tools/projen` can land on a stray
+// `0.0.0` (whose `^0.0.0` caret then can't reach any real release), leaving the
+// workspace on a stale engine. `@latest` always takes the newest published.
+const DEFAULT_PROJEN_SPECIFIER = "@dbx-tools/projen@latest";
 
 const PROJENRC_TEMPLATE = `import { DBXToolsNodeProject } from "@dbx-tools/projen";
 
@@ -23,11 +26,19 @@ allowBuilds:
 `;
 
 /**
- * Turn an empty folder into a functioning dbx-tools workspace: `pnpm init`, seed
+ * Turn a folder into a functioning dbx-tools workspace: `pnpm init`, seed
  * `pnpm-workspace.yaml`, add `projen`/`typescript`/`tsx` + the engine package,
  * write a minimal `.projenrc.ts`, synth once (with `PROJEN_DISABLE_POST`), then
  * install. Does not run barrels - run `dbxtools barrels` or a full projen synth
  * post-install to generate package barrels.
+ *
+ * Every step is idempotent and self-guarded, so this is safe to run against a
+ * folder that ALREADY has a hand-authored `.projenrc.ts` (and even a committed
+ * `package.json`) but is missing the installed toolchain - e.g. a freshly copied
+ * project whose generated files (including manifests) are gitignored. In that
+ * case `pnpm init` and the `.projenrc.ts` scaffold are skipped, but the engine +
+ * projen + tsx are (re)installed so the subsequent synth can regenerate
+ * everything. See {@link seedToolchain}.
  */
 export function bootstrapWorkspace(
   root: string,
@@ -35,8 +46,39 @@ export function bootstrapWorkspace(
 ): void {
   intro(`Bootstrapping dbx-tools workspace in ${rootLabel(root)}`);
 
-  if (!existsSync(join(root, "package.json"))) {
+  seedToolchain(root, projenSpecifier);
+
+  const projenrc = join(root, ".projenrc.ts");
+  if (!existsSync(projenrc)) {
+    writeFileSync(projenrc, PROJENRC_TEMPLATE);
+  }
+
+  runInitialSynth(root);
+
+  runPnpm(["install", "--no-frozen-lockfile", "--force"], root);
+  outro("Workspace ready - re-run dbxtools or add packages under workspaces/");
+}
+
+/**
+ * Install the toolchain a synth needs (`projen`, `typescript`, `tsx`, and the
+ * dbx-tools engine), seeding a `package.json` and `pnpm-workspace.yaml` first
+ * when absent. Idempotent: run it whenever the engine is missing, so a copied
+ * project with a `.projenrc.ts` but no `node_modules`/manifests can be brought
+ * up to a synth-ready state without full bootstrapping.
+ */
+export function seedToolchain(
+  root: string,
+  projenSpecifier: string = DEFAULT_PROJEN_SPECIFIER,
+): void {
+  const manifestPath = join(root, "package.json");
+  if (!existsSync(manifestPath)) {
     runPnpm(["init"], root);
+    // pnpm 11 `init` writes `devEngines.packageManager: { name: "pnpm",
+    // onFail: "download" }`. Any npm-based tool later in the chain (an
+    // `npx`/dlx fallback) then refuses with EBADDEVENGINES because its own
+    // runner is npm, not pnpm. projen regenerates the whole manifest at synth
+    // anyway, so drop the block from this throwaway seed.
+    stripDevEngines(manifestPath);
   }
 
   const workspaceFile = join(root, "pnpm-workspace.yaml");
@@ -45,19 +87,27 @@ export function bootstrapWorkspace(
   }
 
   runPnpm(["add", "-D", "projen", "typescript@^5.9.3", "tsx@^4.23.0", projenSpecifier], root);
+}
 
-  const projenrc = join(root, ".projenrc.ts");
-  if (!existsSync(projenrc)) {
-    writeFileSync(projenrc, PROJENRC_TEMPLATE);
+/** Remove the `devEngines` block pnpm `init` seeds, so npm-based tooling doesn't reject the manifest. */
+function stripDevEngines(manifestPath: string): void {
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+    if (manifest.devEngines === undefined) return;
+    delete manifest.devEngines;
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  } catch {
+    // A malformed/absent manifest here just means the later `pnpm add` recreates it.
   }
-
-  runSynth(root);
-
-  runPnpm(["install", "--no-frozen-lockfile", "--force"], root);
-  outro("Workspace ready - re-run dbxtools or add packages under workspaces/");
 }
 
-function runSynth(root: string): void {
+/**
+ * Run the initial synth by executing `.projenrc.ts` directly with tsx (with
+ * `PROJEN_DISABLE_POST` set), NOT `projen <task>`. Use right after seeding a
+ * fresh workspace: the projen TASKS (`sync`, `barrels`, ...) only exist once
+ * `.projenrc.ts` has run once, so `projen sync` can't be the bootstrapping step.
+ */
+export function runInitialSynth(root: string): void {
   const [command, ...prefix] = resolvePnpmArgv();
   exec.spawnSync(command, [...prefix, "exec", "tsx", ".projenrc.ts"], {
     cwd: root,

package/src/cli.ts

@@ -2,20 +2,36 @@
  * `dbxtools` commander entry: detect root, bootstrap or install, forward to projen.
  */
 import { Command } from "commander";
-import { bootstrapWorkspace } from "./bootstrap";
-import { ensureWorkspaceReady, runProjen } from "./pnpm";
-import { findWorkspaceRoot, needsBootstrap } from "./root";
+import { bootstrapWorkspace, runInitialSynth, seedToolchain } from "./bootstrap";
+import { ensureWorkspaceReady, runPnpm, runProjen } from "./pnpm";
+import { findWorkspaceRoot, needsBootstrap, needsToolchain } from "./root";
 
 /**
  * Prepare the workspace at `root`, then run `pnpm exec projen` with `projenArgs`.
+ *
+ * Three cases, in order:
+ *   - no `.projenrc.ts` at all -> full bootstrap (scaffold + install + synth),
+ *     which already runs the initial synth; nothing more to forward.
+ *   - a `.projenrc.ts` but the engine/toolchain isn't installed (e.g. a freshly
+ *     copied project whose generated files + manifests are gitignored) -> seed
+ *     the toolchain, then run the INITIAL synth directly (the projen tasks the
+ *     args would name, like `sync`, don't exist until `.projenrc.ts` has run
+ *     once), and install. Don't forward `projenArgs` - the synth is the work.
+ *   - otherwise (established workspace) -> ensure deps, then forward to projen.
  */
 async function prepareAndRunProjen(projenArgs: string[], startDir?: string): Promise<void> {
   const root = await findWorkspaceRoot(startDir);
   if (needsBootstrap(root)) {
     bootstrapWorkspace(root);
-  } else {
-    ensureWorkspaceReady(root);
+    return;
   }
+  if (needsToolchain(root)) {
+    seedToolchain(root);
+    runInitialSynth(root);
+    runPnpm(["install", "--no-frozen-lockfile", "--force"], root);
+    return;
+  }
+  ensureWorkspaceReady(root);
   runProjen(projenArgs, root);
 }
 

package/src/pnpm.ts

@@ -10,7 +10,24 @@ import { needsInstall } from "./root";
 /** A package.json `bin` field: either a single command string, or a name -> path map. */
 type BinField = string | Record<string, string>;
 
+/** True when `pnpm --version` runs, i.e. pnpm is already on PATH. */
+function pnpmOnPath(): boolean {
+  try {
+    exec.spawnSync("pnpm", ["--version"], {
+      stderr: "ignore",
+      stdin: "ignore",
+      stdout: "ignore",
+      check: true,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function resolvePnpmArgvImpl(): string[] {
+  // 1. A resolvable `pnpm` dependency (the normal in-workspace case): run its
+  //    bin directly with the current node - no PATH or package-manager shim.
   try {
     const require = createRequire(import.meta.url);
     const pkgJsonPath = require.resolve("pnpm/package.json");
@@ -18,24 +35,32 @@ function resolvePnpmArgvImpl(): string[] {
     const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin.pnpm;
     return [process.execPath, join(dirname(pkgJsonPath), bin)];
   } catch {
-    try {
-      exec.spawnSync("corepack", ["enable", "pnpm"], {
-        stderr: "ignore",
-        stdin: "ignore",
-        stdout: "ignore",
-        check: true,
-      });
-      exec.spawnSync("pnpm", ["--version"], {
-        stderr: "ignore",
-        stdin: "ignore",
-        stdout: "ignore",
-        check: true,
-      });
-      return ["pnpm"];
-    } catch {
-      return ["npx", "-y", "pnpm"];
-    }
+    // fall through
   }
+
+  // 2. A bare `pnpm` already on PATH (e.g. running under `pnpm dlx`). Prefer
+  //    this over the corepack/npx fallbacks so we never shell through npm -
+  //    `npx -y pnpm` runs under npm, which rejects a bootstrapped
+  //    `devEngines.packageManager: pnpm` manifest with EBADDEVENGINES.
+  if (pnpmOnPath()) return ["pnpm"];
+
+  // 3. Try to enable pnpm via corepack, then use it.
+  try {
+    exec.spawnSync("corepack", ["enable", "pnpm"], {
+      stderr: "ignore",
+      stdin: "ignore",
+      stdout: "ignore",
+      check: true,
+    });
+    if (pnpmOnPath()) return ["pnpm"];
+  } catch {
+    // fall through
+  }
+
+  // 4. Last resort: fetch pnpm on demand via npx. Pass `--engine-strict=false`
+  //    (and skip npm's devEngines gate) so npm doesn't refuse to run just
+  //    because the target manifest declares `devEngines.packageManager: pnpm`.
+  return ["npx", "-y", "--engine-strict=false", "pnpm"];
 }
 
 /** Memoized `[command, ...prefix]` argv prefix to run pnpm (resolved install, else corepack, else npx). */

package/src/root.ts

@@ -54,6 +54,23 @@ export function needsInstall(root: string): boolean {
   return false;
 }
 
+/**
+ * True when the synth TOOLCHAIN isn't installed yet: no `node_modules`, or the
+ * dbx-tools engine / `projen` aren't resolvable under it. Distinct from a full
+ * bootstrap (which keys off a MISSING `.projenrc.ts`): here the projenrc exists
+ * but its dependencies don't - e.g. a copied project whose generated manifests
+ * and `node_modules` are gitignored. Seeding the toolchain (not scaffolding)
+ * makes it synth-ready without touching the hand-authored `.projenrc.ts`.
+ */
+export function needsToolchain(root: string): boolean {
+  const modules = join(root, "node_modules");
+  if (!existsSync(modules)) return true;
+  return (
+    !existsSync(join(modules, "projen")) ||
+    !existsSync(join(modules, "@dbx-tools", "projen"))
+  );
+}
+
 /** Async, memoized root lookup from the process cwd at first use. */
 export const workspaceRoot = functionModule.memoize(() => findWorkspaceRoot());