@dbx-tools/cli 0.1.112 → 0.3.1

package/.projen/deps.json

@@ -0,0 +1,43 @@
+{
+  "dependencies": [
+    {
+      "name": "@types/node",
+      "version": "catalog:",
+      "type": "build"
+    },
+    {
+      "name": "tsx",
+      "version": "^4.23.0",
+      "type": "build"
+    },
+    {
+      "name": "typescript",
+      "type": "build"
+    },
+    {
+      "name": "@clack/prompts",
+      "version": "catalog:",
+      "type": "runtime"
+    },
+    {
+      "name": "@dbx-tools/core",
+      "version": "workspace:*",
+      "type": "runtime"
+    },
+    {
+      "name": "@dbx-tools/shared-core",
+      "version": "workspace:*",
+      "type": "runtime"
+    },
+    {
+      "name": "commander",
+      "version": "catalog:",
+      "type": "runtime"
+    },
+    {
+      "name": "pnpm",
+      "type": "runtime"
+    }
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/files.json

@@ -0,0 +1,10 @@
+{
+  "files": [
+    ".projen/deps.json",
+    ".projen/files.json",
+    ".projen/tasks.json",
+    "test/tsconfig.json",
+    "tsconfig.json"
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/tasks.json

@@ -0,0 +1,121 @@
+{
+  "manifestVersion": 3,
+  "env": {
+    "PATH": "$(pnpm -c exec \"node --print process.env.PATH\")"
+  },
+  "tasks": {
+    "build": {
+      "name": "build",
+      "description": "Full release build",
+      "steps": [
+        {
+          "spawn": "pre-compile"
+        },
+        {
+          "spawn": "compile"
+        },
+        {
+          "spawn": "post-compile"
+        },
+        {
+          "spawn": "test"
+        },
+        {
+          "spawn": "package"
+        }
+      ]
+    },
+    "compile": {
+      "name": "compile",
+      "description": "Only compile",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build"
+          ]
+        }
+      ]
+    },
+    "default": {
+      "name": "default",
+      "description": "Synthesize project files",
+      "steps": [
+        {
+          "exec": "pnpm exec projen default",
+          "cwd": "../../.."
+        }
+      ]
+    },
+    "install": {
+      "name": "install",
+      "description": "Install project dependencies and update lockfile (non-frozen)",
+      "steps": [
+        {
+          "exec": "pnpm i --no-frozen-lockfile"
+        }
+      ]
+    },
+    "install:ci": {
+      "name": "install:ci",
+      "description": "Install project dependencies using frozen lockfile",
+      "steps": [
+        {
+          "exec": "pnpm i --frozen-lockfile"
+        }
+      ]
+    },
+    "package": {
+      "name": "package",
+      "description": "Creates the distribution package",
+      "steps": [
+        {
+          "execArgs": [
+            "mkdir",
+            "-p",
+            "dist/js"
+          ]
+        },
+        {
+          "execArgs": [
+            "pnpm",
+            "pack",
+            "--pack-destination",
+            "dist/js"
+          ]
+        }
+      ]
+    },
+    "post-compile": {
+      "name": "post-compile",
+      "description": "Runs after successful compilation"
+    },
+    "pre-compile": {
+      "name": "pre-compile",
+      "description": "Prepare the project for compilation"
+    },
+    "test": {
+      "name": "test",
+      "description": "Run tests",
+      "steps": [
+        {
+          "exec": "tsx --test 'test/**/*.test.ts'"
+        }
+      ]
+    },
+    "watch": {
+      "name": "watch",
+      "description": "Watch & compile in the background",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build",
+            "-w"
+          ]
+        }
+      ]
+    }
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/README.md

@@ -1,88 +1,74 @@
-# @dbx-tools/cli
+# dbx-tools
 
-Scaffold, formatting, codegen, verification, build, and release helpers for Bun +
-workspaces monorepos. It wraps the shared `tsdown` config for building and a
-Bun-based publish flow; `dbxtools` keeps only the workspace automation that is
-orthogonal to writing package code.
+CLI package for the dbx-tools projen workspace engine.
 
-## Installation
+Run the `dbxtools` command to bootstrap a repo, synthesize generated files,
+rebuild barrels, generate OpenAPI clients, or clean generated output. Import the
+package modules when custom tooling needs the same root detection, pnpm
+delegation, or CLI program behavior.
 
-```bash
-bun add -d @dbx-tools/cli
-```
+Key features:
 
-Then point your root `package.json` scripts at the `dbxtools` bin for the helper
-commands you want:
-
-```jsonc
-{
-  "scripts": {
-    "format": "dbxtools format",
-    "build": "dbxtools build",
-    "codegen": "dbxtools codegen",
-    "verify": "dbxtools verify",
-    "create": "dbxtools create",
-    "release": "dbxtools release",
-    "tag": "dbxtools tag",
-  },
-}
-```
+- `sync` bootstrap path for empty folders plus normal projen synthesis for
+  existing workspaces.
+- Focused `--watch` loop for projenrc changes, barrel generation, and OpenAPI
+  generation.
+- Standalone barrel and OpenAPI commands for post-synth workflows.
+- Generated-file cleanup with an interactive or non-interactive mode.
+- Importable CLI/root/pnpm helpers for tests and thin wrapper commands.
 
-## Commands
+## Bootstrap Or Sync A Workspace
+
+```sh
+dbxtools sync
+dbxtools sync --watch
+```
 
-| Command                                     | What it does                                                                                         |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `dbxtools format`                             | `syncpack format`, regroup lifecycle hooks, then `prettier --write`.                                 |
-| `dbxtools build`                              | Compile every publishable package with the shared `tsdown` config.                                   |
-| `dbxtools codegen`                            | Regenerate each package's `generated/` zod tree from the `.d.ts` inputs its `package.json` declares. |
-| `dbxtools verify [--workspace-deps]`          | Workspace verify pass; `--workspace-deps` fails on undeclared sibling imports.                       |
-| `dbxtools create [--plugin\|--shared] <slug>` | Scaffold a new package under `packages/<slug>/`.                                                     |
-| `dbxtools release [--dry-run]`                | Build, then publish each package with a stamped (complete) manifest.                                 |
-| `dbxtools tag [patch\|minor\|major]`          | Version bump, commit, tag, push, and create a GitHub Release. `--notes-since v0.1.75` widens the notes baseline; default is the previous tag. `--no-ai-notes` skips Codex release notes. |
-| `dbxtools agent [prompt]`                     | Run `ucode codex exec` (`-t` / `--timeout` seconds). Prompt via args or stdin. Requires `ucode codex --version`. |
+In an empty folder, `sync` creates the minimum pnpm/projen structure needed for
+`@dbx-tools/projen`. In an existing workspace, it runs projen and the post-synth
+generators. `--watch` starts focused watchers for structural changes, barrels,
+and OpenAPI generation.
 
-Typecheck stays a plain `tsc` call:
+## Generate Barrels And OpenAPI Clients
 
-```bash
-tsc --noEmit -p tsconfig.json
+```sh
+dbxtools barrels
+dbxtools openapi
 ```
 
-## Configuration
+`barrels` rebuilds package-root `index.ts` files from exported modules under
+`src/`. `openapi` scans tsoa controllers and writes generated OpenAPI packages.
 
-Configuration is optional. Everything is auto-derived from the workspace; the
-only knobs live under a `dbxtools` key in the root `package.json`:
+## Clean Generated Output
 
-```jsonc
-{
-  "dbxtools": {
-    "scope": "@acme", // npm scope used by `create` (default: most common scope in the workspace)
-    "repo": "acme/widgets", // owner/name for release links (default: the `origin` git remote)
-  },
-}
+```sh
+dbxtools clean
+dbxtools clean -y
 ```
 
-Each package's optional `codegen.inputs` field is read by convention.
+`clean` removes generated read-only files and can also remove install output. Use
+it before debugging synthesis drift or validating that the repo can regenerate
+from source.
 
-## Library API
-
-The same commands are exported as functions for projects that want to compose
-their own automation:
+## Use The CLI Internals
 
 ```ts
-import { build, codegen, create, release, tag, verify } from "@dbx-tools/cli";
-
-await build();
-await codegen();
-await verify();
-await create({ slug: "example" });
-await release({ dryRun: true });
-await tag({ bump: "patch", publish: false });
+import { cli, root, pnpm } from "dbx-tools";
+
+await cli.runCli(["sync"]);
+const workspaceRoot = await root.findWorkspaceRoot();
+pnpm.runProjen(["barrels"], workspaceRoot);
 ```
 
-Also exported: `format`, plus the workspace helpers
-(`discoverPackages`, `discoverPackageJsons`, `writeJson`, `getProject`, `sh`,
-`git`, ...).
+Importing internals is mainly useful for tests or wrapper scripts; most users
+should run the `dbxtools` bin.
+
+## Modules
 
-## License
+- `cli` - Commander entrypoint and `runCli()`.
+- `bootstrap` - empty-workspace bootstrap.
+- `root` - workspace-root detection and bootstrap/install checks.
+- `pnpm` - pnpm/projen command resolution and delegation.
 
-Apache-2.0
+The reusable project classes and generators live in
+[`@dbx-tools/projen`](../../../projen).

package/bin/dbxtools.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * `dbxtools` bootstraps uninitialized workspaces, then forwards to projen.
+ */
+import { runCli } from "../src/cli";
+
+runCli(process.argv).catch((err: unknown) => {
+  console.error(err);
+  process.exit(1);
+});

package/index.ts

@@ -0,0 +1,8 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as bootstrap from "./src/bootstrap";
+export * as cli from "./src/cli";
+export * as pnpm from "./src/pnpm";
+export * as root from "./src/root";

package/package.json

@@ -1,41 +1,53 @@
 {
   "name": "@dbx-tools/cli",
-  "version": "0.1.112",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/cli/dbx-tools"
+  },
   "bin": {
-    "dbxtools": "./dist/bin/dbxtools.js"
+    "dbxtools": "./bin/dbxtools.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@types/semver": "^7.7.1",
+    "@clack/prompts": "^1.7.0",
     "commander": "^15.0.0",
-    "consola": "^3.4.2",
-    "p-memoize": "^8.0.0",
-    "pacwich": "^0.1.2",
-    "prettier": "^3.9.3",
-    "prettier-plugin-organize-imports": "^4.3.0",
-    "semver": "^7.8.5",
-    "ts-to-zod": "^5.1.0",
-    "typescript": "^5.9.3"
+    "pnpm": "^11.0.6",
+    "@dbx-tools/core": "0.3.1",
+    "@dbx-tools/shared-core": "0.3.1"
   },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.1",
+  "types": "index.ts",
+  "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
+    ".": "./index.ts",
+    "./pnpm": "./src/pnpm.ts",
+    "./package.json": "./package.json"
   },
-  "knip": {
-    "ignoreDependencies": [
-      "prettier",
-      "prettier-plugin-organize-imports"
+  "dbxToolsConfig": {
+    "tags": [
+      "cli"
     ]
   },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
   }
-}
+}

package/src/bootstrap.ts

@@ -0,0 +1,117 @@
+/**
+ * Bootstrap a brand-new folder into a working dbx-tools workspace before projen runs.
+ */
+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";
+
+// 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";
+
+const project = new DBXToolsNodeProject();
+project.synth();
+`;
+
+/** Seed `pnpm-workspace.yaml` so the first \`pnpm add\` can allow esbuild non-interactively. */
+const WORKSPACE_SEED = `packages: []
+allowBuilds:
+  esbuild: true
+`;
+
+/**
+ * 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,
+  projenSpecifier: string = DEFAULT_PROJEN_SPECIFIER,
+): void {
+  intro(`Bootstrapping dbx-tools workspace in ${rootLabel(root)}`);
+
+  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");
+  if (!existsSync(workspaceFile)) {
+    writeFileSync(workspaceFile, WORKSPACE_SEED);
+  }
+
+  runPnpm(["add", "-D", "projen", "typescript@^5.9.3", "tsx@^4.23.0", projenSpecifier], root);
+}
+
+/** 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.
+  }
+}
+
+/**
+ * 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,
+    env: { ...process.env, PROJEN_DISABLE_POST: "true" },
+    check: true,
+  });
+}

package/src/cli.ts

@@ -0,0 +1,50 @@
+/**
+ * `dbxtools` commander entry: detect root, bootstrap or install, forward to projen.
+ */
+import { Command } from "commander";
+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);
+    return;
+  }
+  if (needsToolchain(root)) {
+    seedToolchain(root);
+    runInitialSynth(root);
+    runPnpm(["install", "--no-frozen-lockfile", "--force"], root);
+    return;
+  }
+  ensureWorkspaceReady(root);
+  runProjen(projenArgs, root);
+}
+
+/** Parse `argv` with commander and forward remaining args to projen. */
+export async function runCli(argv: string[]): Promise<void> {
+  const program = new Command()
+    .name("dbxtools")
+    .description("Bootstrap dbx-tools workspaces and forward to projen")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .showHelpAfterError()
+    .helpOption("-h, --help", "Show dbxtools help");
+
+  program.parse(argv);
+  await prepareAndRunProjen(program.args);
+}

package/src/pnpm.ts

@@ -0,0 +1,85 @@
+/**
+ * pnpm discovery, workspace install, and projen forwarding for the `dbxtools` CLI.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { exec } from "@dbx-tools/core";
+import { functionModule } from "@dbx-tools/shared-core";
+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");
+    const pkg = require(pkgJsonPath) as { bin: BinField };
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin.pnpm;
+    return [process.execPath, join(dirname(pkgJsonPath), bin)];
+  } catch {
+    // 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). */
+export const resolvePnpmArgv = functionModule.memoize(resolvePnpmArgvImpl);
+
+/** Run pnpm with inherited stdio from `cwd`. */
+export function runPnpm(args: string[], cwd: string): void {
+  const [command, ...prefix] = resolvePnpmArgv();
+  exec.spawnSync(command, [...prefix, ...args], { cwd, check: true });
+}
+
+/** Install workspace dependencies when `node_modules` or projen is missing. */
+export function ensureWorkspaceReady(root: string): void {
+  if (needsInstall(root)) {
+    runPnpm(["install", "--no-frozen-lockfile"], root);
+  }
+}
+
+/** Run `pnpm exec projen` with the given args from `root`. */
+export function runProjen(args: string[], root: string): void {
+  runPnpm(["exec", "projen", ...args], root);
+}