@dbx-tools/cli 0.1.9

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

@@ -0,0 +1,74 @@
+# dbx-tools
+
+CLI package for the dbx-tools projen workspace engine.
+
+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.
+
+Key features:
+
+- `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.
+
+## Bootstrap Or Sync A Workspace
+
+```sh
+dbxtools sync
+dbxtools sync --watch
+```
+
+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.
+
+## Generate Barrels And OpenAPI Clients
+
+```sh
+dbxtools barrels
+dbxtools openapi
+```
+
+`barrels` rebuilds package-root `index.ts` files from exported modules under
+`src/`. `openapi` scans tsoa controllers and writes generated OpenAPI packages.
+
+## Clean Generated Output
+
+```sh
+dbxtools clean
+dbxtools clean -y
+```
+
+`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.
+
+## Use The CLI Internals
+
+```ts
+import { cli, root, pnpm } from "dbx-tools";
+
+await cli.runCli(["sync"]);
+const workspaceRoot = await root.findWorkspaceRoot();
+pnpm.runProjen(["barrels"], workspaceRoot);
+```
+
+Importing internals is mainly useful for tests or wrapper scripts; most users
+should run the `dbxtools` bin.
+
+## Modules
+
+- `cli` - Commander entrypoint and `runCli()`.
+- `bootstrap` - empty-workspace bootstrap.
+- `root` - workspace-root detection and bootstrap/install checks.
+- `pnpm` - pnpm/projen command resolution and delegation.
+
+The reusable project classes and generators live in
+[`@dbx-tools/projen`](../../node/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

@@ -0,0 +1,55 @@
+{
+  "name": "@dbx-tools/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/cli/dbx-tools"
+  },
+  "bin": {
+    "dbxtools": "./bin/dbxtools.ts",
+    "dbxtools.ts": "bin/dbxtools.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "pnpm": "^11.0.6",
+    "@dbx-tools/core": "0.1.9",
+    "@dbx-tools/shared-core": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./pnpm": "./src/pnpm.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "cli"
+    ]
+  },
+  "//": "~~ 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,67 @@
+/**
+ * Bootstrap a brand-new folder into a working dbx-tools workspace before projen runs.
+ */
+import { existsSync, 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";
+
+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 an empty 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.
+ */
+export function bootstrapWorkspace(
+  root: string,
+  projenSpecifier: string = DEFAULT_PROJEN_SPECIFIER,
+): void {
+  intro(`Bootstrapping dbx-tools workspace in ${rootLabel(root)}`);
+
+  if (!existsSync(join(root, "package.json"))) {
+    runPnpm(["init"], root);
+  }
+
+  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);
+
+  const projenrc = join(root, ".projenrc.ts");
+  if (!existsSync(projenrc)) {
+    writeFileSync(projenrc, PROJENRC_TEMPLATE);
+  }
+
+  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 {
+  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,34 @@
+/**
+ * `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";
+
+/**
+ * Prepare the workspace at `root`, then run `pnpm exec projen` with `projenArgs`.
+ */
+async function prepareAndRunProjen(projenArgs: string[], startDir?: string): Promise<void> {
+  const root = await findWorkspaceRoot(startDir);
+  if (needsBootstrap(root)) {
+    bootstrapWorkspace(root);
+  } else {
+    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,60 @@
+/**
+ * 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>;
+
+function resolvePnpmArgvImpl(): string[] {
+  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 {
+    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"];
+    }
+  }
+}
+
+/** 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);
+}

package/src/root.ts

@@ -0,0 +1,63 @@
+/**
+ * Workspace root detection for the `dbxtools` CLI.
+ */
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { exec } from "@dbx-tools/core";
+import { functionModule } from "@dbx-tools/shared-core";
+
+async function gitToplevel(): Promise<string | undefined> {
+  const { exitCode, stdout } = await exec.spawn("git", ["rev-parse", "--show-toplevel"], {
+    stdout: "capture",
+    stderr: "ignore",
+    stdin: "ignore",
+  });
+  if (exitCode !== 0) return undefined;
+  return stdout || undefined;
+}
+
+/**
+ * Walk upward from `startDir` for `.projenrc.ts`. If none is found, try git
+ * top-level only when that directory also contains `.projenrc.ts`; otherwise return
+ * `resolve(startDir)` (which may not be a workspace root).
+ */
+export async function findWorkspaceRoot(startDir: string = process.cwd()): Promise<string> {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, ".projenrc.ts"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  const fromGit = await gitToplevel();
+  if (fromGit && existsSync(join(fromGit, ".projenrc.ts"))) return fromGit;
+
+  return resolve(startDir);
+}
+
+/**
+ * True when the folder has no `.projenrc.ts` yet and needs full bootstrapping.
+ * Keying off `.projenrc.ts` (not `package.json`) avoids clobbering a cleaned
+ * workspace that still has a hand-authored projenrc.
+ */
+export function needsBootstrap(root: string): boolean {
+  return !existsSync(join(root, ".projenrc.ts"));
+}
+
+/** True when `node_modules` or projen itself is missing under `root`. */
+export function needsInstall(root: string): boolean {
+  if (!existsSync(join(root, "node_modules"))) return true;
+  if (existsSync(join(root, ".projenrc.ts")) && !existsSync(join(root, "node_modules", "projen"))) {
+    return true;
+  }
+  return false;
+}
+
+/** Async, memoized root lookup from the process cwd at first use. */
+export const workspaceRoot = functionModule.memoize(() => findWorkspaceRoot());
+
+/** Short label for log output (`basename` of the resolved root). */
+export function rootLabel(root: string): string {
+  return basename(root) || root;
+}

package/test/tsconfig.json

@@ -0,0 +1,14 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,43 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "index.ts",
+    "bin/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}