@smoothbricks/cli 0.1.1 → 0.2.0

package/README.md

@@ -36,13 +36,15 @@ smoo monorepo validate-commit-msg <commit-msg-file>
 smoo monorepo sync-bun-lockfile-versions
 smoo monorepo list-release-packages [--fail-empty] [--github-output <path>]
 smoo monorepo validate-public-tags
+smoo monorepo setup-test-tracing (--all | --projects <projects>) [--dry-run]
 
 smoo release npm-status
 smoo release repair-pending [--dry-run]
 smoo release version --bump <auto|patch|minor|major|prerelease> [--dry-run] [--github-output <path>]
 smoo release publish --bump <auto|patch|minor|major|prerelease> [--dry-run]
 smoo release retag-unpublished <tag...> [--to <ref>] [--push] [--dispatch] [--remote <remote>] [--branch <branch>] [--dry-run]
-smoo release trust-publisher [--dry-run] [--otp <code>] [--skip-login]
+smoo release bootstrap-npm-packages [--dry-run] [--skip-login] [--package <name...>]
+smoo release trust-publisher [--bootstrap] [--dry-run] [--otp <code>] [--skip-login]
 
 smoo github-ci cleanup-cache
 smoo github-ci nx-smart --target <target> --name <check-name> --step <number>
@@ -62,6 +64,10 @@ It currently:
 - Synchronizes root runtime versions inside devenv, or when `--sync-runtime` is passed.
 - Applies safe publish metadata defaults to `npm:public` packages without inferring package ownership.
 - Normalizes internal workspace dependency ranges to `workspace:*`.
+- Rewrites safe package scripts in packages with workspace dependencies so developer commands like `bun run test` and
+  `bun run dev` stay available while delegating through Nx targets.
+- `smoo monorepo validate --fix` creates/updates `tooling/package.json`, keeps `@smoothbricks/cli` there instead of the
+  root workspace package, and fills required workspace/devenv tool declarations.
 - Runs [`sherif --fix --select highest`][sherif] for broad monorepo package hygiene.
 - Normalizes conditional export ordering so `types` comes first and `default` comes last.
 - Adds `src` to package `files` when development-only exports intentionally point at source files.
@@ -70,6 +76,19 @@ The workspace dependency rule is generic. `smoo` does not know about individual
 For every root or workspace `package.json`, if a dependency name matches an actual package in the same workspace, `smoo`
 rewrites that range to `workspace:*`.
 
+Packages with internal workspace dependencies also need Nx-aware scripts so dependent builds run before local commands.
+For safe build, test, typecheck, benchmark, dev, and preview commands, `smoo monorepo validate --fix` moves the real
+command into `package.json` `nx.targets.<target>.options.command`, sets `cwd` to `{projectRoot}`, and replaces the
+script with an `nx run <project>:<target>` alias. Continuous commands such as `astro dev`, `vite dev`, and previews get
+`--tui=false --outputStyle=stream` on the alias and `continuous: true` on the Nx target. Simple leading environment
+assignments are moved into `nx.targets.<target>.options.env` so commands such as
+`NODE_OPTIONS='--import=extensionless/register' astro dev` remain shell-independent.
+
+The rewrite is intentionally conservative. `smoo` does not rewrite deploy, database, release, sync, subtree, publish, or
+pack scripts, and it rejects Nx target commands that recurse through package scripts such as `bun run test`. The reason
+is dependency correctness without hiding unsafe operational commands behind generated Nx targets: workspace-dependent
+packages should get `^build` ordering for ordinary development commands, while publishing and deployment stay explicit.
+
 `smoo monorepo init --runtime-only` only synchronizes root runtime versions. It is used from direnv setup so
 `packageManager`, `engines.node`, and `@types/node` stay aligned with the active devenv shell without duplicating that
 policy in the direnv script.
@@ -79,6 +98,36 @@ while package manifests are not forced to depend on Bun just because a test tsco
 does explicitly declare `@types/bun`, `sherif` can keep duplicate declarations consistent, but `smoo` owns the semantic
 root `bun@x.y.z` to `@types/bun x.y.z` relationship.
 
+## LMAO Test Tracing
+
+`smoo monorepo setup-test-tracing` configures LMAO-backed Bun test tracing for workspace packages. It is a bulk wrapper
+around the `@smoothbricks/nx-plugin:bun-test-tracing` generator, so the Nx plugin remains the single source of truth for
+the files written.
+
+Configure every workspace package:
+
+```bash
+smoo monorepo setup-test-tracing --all
+```
+
+Configure selected packages by Nx project name, package name, or package root:
+
+```bash
+smoo monorepo setup-test-tracing --projects cli,@smoothbricks/lmao,packages/nx-plugin
+```
+
+The command infers the op context module from each package's `package.json` `name`, assumes an `opContext` named export,
+and imports `defineTestTracer` from `@smoothbricks/lmao/testing/bun`. Override those defaults when a repository uses a
+different convention:
+
+```bash
+smoo monorepo setup-test-tracing --projects my-lib --op-context-export myOpContext
+smoo monorepo setup-test-tracing --projects my-lib --tracer-module @scope/testing/bun
+```
+
+Use `--dry-run` to print the `nx g @smoothbricks/nx-plugin:bun-test-tracing ...` invocations without writing files.
+After setup, run `smoo monorepo validate --fix` to apply the broader SmoothBricks monorepo policy.
+
 ## Validation
 
 `smoo monorepo validate` is the read-only gate. It should pass in local shells and CI after packages have been built.
@@ -88,12 +137,16 @@ It checks:
 - Managed file drift.
 - Root package policy.
 - Root Bun type version matches the Bun package manager version.
+- Tooling policy: root `package.json` owns workspace-level tools like `nx`, `tooling/package.json` owns `smoo`, and
+  `tooling/direnv/devenv.nix` owns shell-provided tools like `bun`, `git-format-staged`, and `fmt`.
 - Nx release policy, including project package release tags, project-level GitHub Release changelogs, and the temporary
   Bun lockfile versionActions hook.
 - `bun.lock` workspace versions match package manifests.
 - Public package tag policy.
 - Public package metadata.
 - Workspace dependency ranges.
+- Workspace-dependent package scripts delegate safe commands through Nx targets without recursive script runners.
+- Nx target conventions and inferred-task setup.
 - [`sherif`] package hygiene, with warnings treated as validation failures.
 - Packed public package artifacts with [`publint`].
 - Packed public package type resolution with the [`attw`][are-the-types-wrong] CLI.
@@ -146,24 +199,70 @@ package `repository.url` is a validation failure so new packages must consciousl
 current repository or mirrored from another one. Init still sets `publishConfig.access = "public"`, repository type,
 repository directory, export ordering, and source-file publish entries when those can be derived safely.
 
-`smoo monorepo list-release-packages` prints the comma-separated package names that are both `npm:public` and owned by
-the current repository. Release commands, trusted-publisher setup, and the managed publish workflow use this owned
-release package list instead of every public package in the workspace.
+`smoo monorepo list-release-packages` prints the comma-separated Nx project names for packages that are both
+`npm:public` and owned by the current repository. Release commands, trusted-publisher setup, and the managed publish
+workflow use this owned release package list instead of every public package in the workspace. smoo keeps both names in
+release metadata: Nx commands receive `projectName`, while npm publish, GitHub Releases, and release tags use the real
+package `name`.
 
 For [GitHub Actions], `smoo monorepo list-release-packages --fail-empty --github-output "$GITHUB_OUTPUT"` appends the
-`projects=<package-list>` output expected by the managed publish workflow and fails with a clear error when no owned
+`projects=<nx-project-list>` output expected by the managed publish workflow and fails with a clear error when no owned
 release packages exist.
 
 `smoo release npm-status` shows whether each owned release package's current `name@version` already exists on npm. It is
 an npm registry check, not a full release workflow status check.
 
+`smoo release version --bump auto` first selects direct release candidates, then delegates versioning to [Nx]. Direct
+candidates are owned public packages with package-local changes that can affect published users: files matched by the
+package's resolved Nx `build`/`production` inputs, packaged assets listed in `package.json` `files`, package metadata
+docs such as README/LICENSE/CHANGELOG, or user-visible `package.json` fields such as `exports`, `bin`, `types`,
+`dependencies`, `peerDependencies`, and `publishConfig`. Test-only and local automation changes such as `scripts`, `nx`,
+`devDependencies`, and `tsconfig.test.json` do not select a package by themselves.
+
+Downstream dependency bumps are intentionally left to Nx release. If package A is selected and bumped, Nx may also bump
+public package B when B depends on A, even when B has no direct file changes. `smoo` should not pre-expand direct
+candidates to downstream dependents because that would duplicate Nx's dependency graph and can over-select packages.
+
+## Nx Conventions
+
+`smoo` keeps Nx target names predictable and separates tool work from aggregate workflows.
+
+Official Nx plugins own targets they already know how to infer. For example, `@nx/js/typescript` owns TypeScript library
+builds, so a package `tsconfig.lib.json` produces the concrete target `tsc-js`.
+
+`@smoothbricks/nx-plugin` only fills SmoothBricks convention gaps that official plugins do not provide. Today that means
+Bun test typechecking, non-TypeScript build-tool steps, and aggregate targets.
+
+Concrete targets describe the tool that runs and the artifact or purpose it produces:
+
+- `tsc-js` comes from the official TypeScript plugin and runs `tsc` for package JavaScript/declaration output.
+- Packages that run `bun test` must have `tsconfig.test.json`. Bun executes tests without typechecking, so smoo creates
+  a no-emit `typecheck-tests` target from that config and wires it into validation. Other test runners may own their own
+  typecheck path.
+- Test tsconfigs are validation configs, not TypeScript build-mode projects. They must use `noEmit`, must not set
+  `composite: true`, and package root `tsconfig.json` must not reference `./tsconfig.test.json`. The inferred
+  `typecheck-tests` target runs `tsc --noEmit -p tsconfig.test.json` after `build` instead.
+- Non-TypeScript build steps come from explicit tool configuration. For example, a package `build.zig` must expose named
+  `b.step("name", ...)` entries; each non-reserved step becomes a `zig-name` target such as `zig-wasm`.
+- `build` is an aggregate. It exists only when there is at least one concrete build target such as `tsc-js` or another
+  tool-output target, and it depends on those targets instead of duplicating their commands.
+- `lint` is an aggregate validation target. It is not a formatting target.
+
+Explicit Nx target names must not contain `:`. Nx already uses colon syntax at the CLI boundary:
+`project:target:configuration`. Allowing target names like `build:wasm` makes command parsing and package-script aliases
+look like configurations, and it prevents a clean split between concrete tool-output targets and aggregate targets.
+
+Use tool-output names for concrete targets, such as `tsc-js` and `zig-wasm`. Use `build` and `lint` only as aggregate
+targets. Package scripts may still use developer-friendly colon names, for example `build:wasm`, but those scripts
+should delegate to unambiguous Nx targets such as `nx run pkg:zig-wasm`.
+
 ## Managed Files
 
 `smoo monorepo update` writes the managed files into a repository.
 
 Managed files include:
 
-- [`.git-format-staged.yml`][git-format-staged]
+- [`tooling/git-hooks/git-format-staged.yml`][git-format-staged]
 - Git hook scripts under `tooling/git-hooks`
 - [direnv]/[GitHub Actions] bootstrap scripts under `tooling/direnv`
 - [GitHub Actions] workflows under `.github/workflows`
@@ -185,10 +284,13 @@ smoo monorepo diff
 
 `check` fails when a managed file is missing or stale. `diff` reports drift without writing files.
 
-## Git Hooks
+## Formatting And Git Hooks
 
-The generated pre-commit hook runs [`git-format-staged`][git-format-staged] from the repository root with `tooling`,
-`node_modules/.bin`, and the [devenv] profile on `PATH`.
+The root `lint:fix` script runs [`git-format-staged`][git-format-staged] with
+`--config tooling/git-hooks/git-format-staged.yml --unstaged`. The formatter config intentionally excludes `bun.lock`.
+
+The generated pre-commit hook runs the same formatter path from the repository root with `tooling`, `node_modules/.bin`,
+and the [devenv] profile on `PATH`.
 
 After formatting, the hook runs `smoo monorepo validate --fail-fast --only-if-new-workspace-package`. This keeps normal
 commits fast while still catching incomplete package setup and conditional managed-file drift when a new workspace
@@ -197,10 +299,16 @@ package manifest is staged.
 The generated commit-msg hook delegates conventional commit validation to:
 
 ```bash
-smoo monorepo validate-commit-msg <commit-msg-file>
+smoo monorepo validate-commit-msg --fix <commit-msg-file>
 ```
 
-This keeps hook behavior consistent with CI and avoids duplicating commit message parsing in shell.
+This keeps hook behavior consistent with CI and avoids duplicating commit message parsing in shell. With `--fix`, smoo
+wraps prose body paragraphs through `fmt -w 72` while preserving fenced code blocks, quoted markdown, indented blocks,
+bullets, trailers, URLs, and comment lines.
+
+Conventional commit scopes should use Nx project names. For packages in the same npm scope as the root package, smoo
+requires `package.json` `nx.name` to be the unscoped package name, such as `cli` for `@smoothbricks/cli`, so subjects
+like `fix(cli): repair release notes` map cleanly to Nx Release.
 
 ## GitHub Actions
 
@@ -246,14 +354,25 @@ Release commands wrap [Nx Release][nx-release] but keep SmoothBricks policy in o
 
 Versioning:
 
-- `--bump auto` uses [Nx Release][nx-release] [Conventional Commits] versioning.
-- `--bump patch|minor|major|prerelease` forces the release specifier.
+- `--bump auto` first filters owned release packages to package-local candidates, then lets [Nx Release][nx-release]
+  derive the semver bump from [Conventional Commits]. A tagged package is an auto candidate only when files under its
+  package root changed since its current `name@version` release tag. An untagged package is an auto candidate only when
+  its package root has git history. Root-only changes, workflow edits, lockfile-only churn, and other workspace-global
+  changes may still affect Nx tasks, but they do not make unrelated package artifacts releasable.
+- `--bump patch|minor|major|prerelease` forces the release specifier for the full owned release package set. Forced
+  bumps intentionally bypass the package-local auto filter.
 - Release packages are discovered from `npm:public` packages whose `repository.url` exactly matches the root package.
 - [Nx Release][nx-release] config must use `currentVersionResolver: "git-tag"` with
   `fallbackCurrentVersionResolver: "disk"`. Conventional-commit versioning requires git tags as the primary source,
   while the disk fallback supports initial releases before package tags exist.
 - [Nx Release][nx-release] config must use `versionActions: "@smoothbricks/cli/nx-version-actions"`. This wraps Nx's JS
   version actions and temporarily syncs `bun.lock` workspace versions after Nx runs `bun install --lockfile-only`.
+- Same-org scoped packages must define short `package.json` `nx.name` values, for example `@smoothbricks/money` uses
+  `"nx": { "name": "money" }`. This lets Nx Release understand commit scopes like `fix(money): ...` without requiring
+  the npm org in every commit subject.
+- Nx project names and npm package names are different release identities. Nx project filters, workflow `projects=`
+  outputs, build/lint/test validation, and project changelog lookup use `projectName`. npm publish checks, tarball
+  validation, GitHub Release titles, and durable release tags use package `name`.
 - [Nx Release][nx-release] `preVersionCommand` is intentionally not used. smoo builds exactly the packages that still
   need npm publish immediately before packing them, while the managed workflow separately builds, lints, tests, and
   validates newly created release commits.
@@ -265,8 +384,9 @@ Versioning:
   target, versioning returns `mode=none` and leaves idempotent completion to `smoo release publish`.
 - `smoo release version --github-output "$GITHUB_OUTPUT"` appends `mode=new|none` and `projects=<comma-list>`. The
   managed publish workflow uses `mode != "none"` to build, lint, test, and validate exactly the commit that
-  `smoo release publish` will publish. The validation and publish step names include the selected mode so the [GitHub
-  Actions] run shows whether it is creating a new release or recording a no-op.
+  `smoo release publish` will publish. `projects` is a comma-separated Nx project-name list, not an npm package-name
+  list. The validation and publish step names include the selected mode so the [GitHub Actions] run shows whether it is
+  creating a new release or recording a no-op.
 - Explicit bumps are mandatory when `HEAD` is not already a release target: after pending releases are repaired,
   `bump=patch|minor|major|prerelease` must make Nx create a new release commit. smoo fails if Nx returns without moving
   `HEAD`; `auto` may no-op when there are no releasable conventional commits.
@@ -278,8 +398,9 @@ Versioning:
   [oven-sh/bun#18906](https://github.com/oven-sh/bun/issues/18906),
   [oven-sh/bun#20477](https://github.com/oven-sh/bun/issues/20477), and
   [oven-sh/bun#20829](https://github.com/oven-sh/bun/issues/20829).
-- Package release tags must use `{projectName}@{version}`. smoo derives release package/version pairs from that tag
-  shape and recreates missing local tags for Nx release commits before repairing remote state.
+- Package release tags must use the npm package name and version, for example `@smoothbricks/nx-plugin@0.0.2`. smoo
+  derives release package/version pairs from that tag shape and recreates missing local tags for Nx release commits
+  before repairing remote state. Nx project names are only CLI/project-graph identifiers.
 - `smoo release retag-unpublished <tag...>` is a break-glass recovery command for the case where Nx already committed a
   version bump but npm publish failed before the package version became durable. It moves exact owned release tags to
   `HEAD` by default without bumping package manifests again. It refuses to move a tag when `package@version` already
@@ -305,8 +426,8 @@ decide which tags still need work; it does not walk normal commits looking for r
 4. Sort the remaining repair commits oldest-to-newest. Only after this sorted non-HEAD repair list exists does smoo
    start checking out commits.
 5. For each repair commit, check out the commit once and load that checkout's direnv environment once. If any grouped
-   tag still needs npm publish, run `nx run-many -t build --projects=<comma-separated npm-missing packages>` once, then
-   publish those packages using the npm dist-tag implied by each package version. If the commit only needs GitHub
+   tag still needs npm publish, run `nx run-many -t build --projects=<comma-separated npm-missing Nx projects>` once,
+   then publish those packages using the npm dist-tag implied by each package version. If the commit only needs GitHub
    Releases, skip the build. Finally, create the missing GitHub Releases for the grouped tags that need them.
 
 Pending release state should be a suffix of the release-target timeline because `repair-pending` runs before every
@@ -323,26 +444,30 @@ Publishing:
 - npm registry state gates publish idempotency only. It decides which already-versioned package tarballs still need to
   be published during a real release retry, not whether versioning should run or whether the workflow has a release to
   publish.
-- Before npm publish, smoo runs `nx run-many -t build --projects=<comma-separated npm-missing packages>` for exactly the
-  packages whose `name@version` is not on npm yet. Nx cache makes this cheap when the managed workflow already built the
-  same projects, and it keeps reruns self-sufficient when repairing a previously selected `HEAD` release target.
+- Before npm publish, smoo runs `nx run-many -t build --projects=<comma-separated npm-missing Nx projects>` for exactly
+  the packages whose `name@version` is not on npm yet. Nx cache makes this cheap when the managed workflow already built
+  the same projects, and it keeps reruns self-sufficient when repairing a previously selected `HEAD` release target.
 - Publish uses `bun pm pack` to create package tarballs, then publishes those tarballs with latest npm CLI and
   `--provenance`. Each package uses the npm dist-tag implied by its own version (`next` for prereleases, `latest` for
   stable versions). Bun pack resolves internal `workspace:*` dependency ranges to real versions in the tarball manifest;
   smoo fails before publish if a packed manifest still contains `workspace:` or if an internal dependency does not match
   the current workspace package version.
-- [npm CLI][npm] owns publish authentication. Existing packages use [trusted publishing][npm-trusted-publishing] with
-  [GitHub Actions OIDC][github-actions-oidc] from the workflow's `id-token: write` permission. Package names that do not
-  exist on npm yet use `secrets.NPM_TOKEN` as `NODE_AUTH_TOKEN` for the first publish, because trusted publishing can
-  only be configured after the package exists. Once `smoo release trust-publisher` succeeds for a package, future
-  publishes for that package use OIDC even if the bootstrap token is still present in repository secrets.
+- [npm CLI][npm] owns publish authentication. Packages use [trusted publishing][npm-trusted-publishing] with [GitHub
+  Actions OIDC][github-actions-oidc] from the workflow's `id-token: write` permission. Package names must exist on npm
+  before CI publish runs; use `smoo release trust-publisher --bootstrap` locally to publish `0.0.0-bootstrap.0` under
+  the `bootstrap` dist-tag for new package names before configuring trust.
+- `smoo release bootstrap-npm-packages` scans owned `npm:public` release packages missing from npm, runs
+  `npm login --auth-type=web` through `nix shell nixpkgs#nodejs_latest` unless `--skip-login` is passed, and publishes a
+  minimal placeholder package with `--access public --tag bootstrap`. It supports `--dry-run` and `--package <name...>`
+  for targeted bootstraps.
 - `smoo release trust-publisher` configures [npm trusted publishing][npm-trusted-publishing] for every owned release
   package. It uses the root `package.json` `repository.url` as the GitHub `owner/repo`, uses `publish.yml` as the
   trusted workflow, and runs `npm trust` through `nix shell nixpkgs#nodejs_latest` because the Lambda-pinned Node 24/npm
   toolchain may lag the npm CLI feature. By default it runs `npm login --auth-type=web` first so npm can open a browser
-  login; pass `--skip-login` when the current npm session is already authenticated. Packages must already exist on npm
-  before trust can be configured. npm may still require operation-level 2FA for `npm trust`; smoo prompts for a hidden
-  OTP per package, or you can pass `--otp <code>` for non-interactive use.
+  login; pass `--skip-login` when the current npm session is already authenticated. Pass `--bootstrap` to create missing
+  npm package names first, then configure trusted publishing in the same command. npm may still require operation-level
+  2FA for `npm trust`; smoo prompts for a hidden OTP per package, or you can pass `--otp <code>` for non-interactive
+  use.
 
 GitHub Releases:
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAexE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAexE"}

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { Command, CommanderError } from 'commander';
+import { cliPackageVersion } from './lib/cli-package.js';
 import { findRepoRoot } from './lib/run.js';
 export async function runCli(argv = process.argv.slice(2)) {
     const program = buildProgram();
@@ -19,7 +20,12 @@ export async function runCli(argv = process.argv.slice(2)) {
 }
 function buildProgram() {
     const program = new Command();
-    program.name('smoo').description('SmoothBricks monorepo tooling').exitOverride().showHelpAfterError();
+    program
+        .name('smoo')
+        .description('SmoothBricks monorepo tooling')
+        .version(cliPackageVersion, '-v, --version', 'print smoo version')
+        .exitOverride()
+        .showHelpAfterError();
     const monorepo = program.command('monorepo').description('Manage SmoothBricks-style monorepos');
     monorepo
         .command('init')
@@ -31,8 +37,10 @@ function buildProgram() {
     });
     monorepo
         .command('validate')
+        .option('--fix', 'apply safe monorepo policy fixes before validation')
         .option('--fail-fast', 'stop after the first failing validation pack')
         .option('--only-if-new-workspace-package', 'skip validation unless a new workspace package manifest is staged')
+        .option('--verbose', 'print validation progress and successful checks')
         .action(async (options) => {
         const { validateMonorepo } = await import('./monorepo/index.js');
         await validateMonorepo(await findRepoRoot(), options);
@@ -49,9 +57,12 @@ function buildProgram() {
         const { diffManagedFiles } = await import('./monorepo/index.js');
         diffManagedFiles(await findRepoRoot());
     });
-    monorepo.command('validate-commit-msg <commitMsgFile>').action(async (commitMsgFile) => {
+    monorepo
+        .command('validate-commit-msg <commitMsgFile>')
+        .option('--fix', 'format the commit message before validation')
+        .action(async (commitMsgFile, options) => {
         const { validateCommitMessageFile } = await import('./monorepo/index.js');
-        validateCommitMessageFile(commitMsgFile);
+        validateCommitMessageFile(commitMsgFile, options, await findRepoRoot());
     });
     monorepo.command('sync-bun-lockfile-versions').action(async () => {
         const { syncBunLockfileVersions } = await import('./monorepo/index.js');
@@ -60,10 +71,10 @@ function buildProgram() {
     monorepo
         .command('list-release-packages')
         .option('--fail-empty', 'fail when no owned release packages are found')
-        .option('--github-output <path>', 'append projects=<packages> to a GitHub Actions output file')
+        .option('--github-output <path>', 'append projects=<nx-projects> to a GitHub Actions output file')
         .action(async (options) => {
-        const { listReleasePackagesForNx } = await import('./monorepo/index.js');
-        const packages = listReleasePackagesForNx(await findRepoRoot(), options);
+        const { listReleaseProjectNamesForNx } = await import('./monorepo/index.js');
+        const packages = listReleaseProjectNamesForNx(await findRepoRoot(), options);
         if (!options.githubOutput) {
             console.log(packages);
         }
@@ -72,6 +83,18 @@ function buildProgram() {
         const { validatePublicPackageTags } = await import('./monorepo/index.js');
         validatePublicPackageTags(await findRepoRoot());
     });
+    monorepo
+        .command('setup-test-tracing')
+        .description('Configure LMAO Bun test tracing for workspace packages')
+        .option('--all', 'configure every workspace package')
+        .option('--projects <projects>', 'comma-separated Nx project names, package names, or package roots')
+        .option('--op-context-export <exportName>', 'named op context export imported by test-suite-tracer', 'opContext')
+        .option('--tracer-module <module>', 'module specifier that exports defineTestTracer', '@smoothbricks/lmao/testing/bun')
+        .option('--dry-run', 'print generator invocations without writing files')
+        .action(async (options) => {
+        const { setupTestTracing } = await import('./monorepo/index.js');
+        await setupTestTracing(await findRepoRoot(), options);
+    });
     const release = program.command('release').description('Version, publish, and create GitHub Releases');
     release.command('npm-status').action(async () => {
         const { printReleaseState } = await import('./release/index.js');
@@ -89,7 +112,7 @@ function buildProgram() {
         .command('version')
         .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
         .option('--dry-run [dryRun]', 'run without writing versions or tags')
-        .option('--github-output <path>', 'append mode=<mode> and projects=<packages> to a GitHub Actions output file')
+        .option('--github-output <path>', 'append mode=<mode> and projects=<nx-projects> to a GitHub Actions output file')
         .action(async (options) => {
         const { releaseVersion } = await import('./release/index.js');
         await releaseVersion(await findRepoRoot(), {
@@ -128,20 +151,81 @@ function buildProgram() {
             dryRun: booleanOption(options.dryRun),
         });
     });
+    release
+        .command('bootstrap-npm-packages')
+        .alias('bootstrap')
+        .description('Publish minimal npm placeholder packages so trusted publishing can be configured')
+        .option('--dry-run [dryRun]', 'show placeholder publishes without logging in or publishing')
+        .option('--skip-login', 'skip npm browser login before publishing placeholders')
+        .option('--otp <otp>', 'npm one-time password for placeholder publish operations')
+        .option('--package <name...>', 'only bootstrap the selected owned release package names')
+        .action(async (options) => {
+        const { releaseBootstrapNpmPackages } = await import('./release/index.js');
+        await releaseBootstrapNpmPackages(await findRepoRoot(), {
+            dryRun: booleanOption(options.dryRun),
+            skipLogin: options.skipLogin === true,
+            otp: options.otp,
+            packages: options.package ?? [],
+        });
+    });
     release
         .command('trust-publisher')
         .description('Configure npm trusted publishing for owned release packages')
         .option('--dry-run [dryRun]', 'show npm trust changes without saving them')
+        .option('--bootstrap', 'publish missing npm placeholder packages before configuring trust')
         .option('--otp <otp>', 'npm one-time password for trust operations')
+        .option('--bootstrap-otp <otp>', 'npm one-time password for placeholder publishes during --bootstrap')
         .option('--skip-login', 'skip npm browser login before configuring trust')
         .action(async (options) => {
         const { releaseTrustPublisher } = await import('./release/index.js');
         await releaseTrustPublisher(await findRepoRoot(), {
             dryRun: booleanOption(options.dryRun),
+            bootstrap: options.bootstrap === true,
             otp: options.otp,
+            bootstrapOtp: options.bootstrapOtp,
             skipLogin: options.skipLogin === true,
         });
     });
+    const devenv = program.command('devenv').description('Manage the repository devenv shell');
+    devenv.command('update').action(async () => {
+        const { updateDevenv } = await import('./devenv/index.js');
+        await updateDevenv(await findRepoRoot());
+    });
+    devenv.command('reload').action(async () => {
+        const { reloadDevenv } = await import('./devenv/index.js');
+        await reloadDevenv(await findRepoRoot());
+    });
+    const nixpkgsOverlay = program.command('nixpkgs-overlay').description('Manage the repository nixpkgs overlay');
+    nixpkgsOverlay.command('update').action(async () => {
+        const { updateNixpkgsOverlay } = await import('./devenv/index.js');
+        await updateNixpkgsOverlay(await findRepoRoot());
+    });
+    const nx = program.command('nx').description('Nx workspace helpers');
+    nx.command('list-targets')
+        .description('List project:target entries for every Nx project')
+        .action(async () => {
+        const { listTargets } = await import('./nx/index.js');
+        await listTargets(await findRepoRoot());
+    });
+    nx.command('list-projects')
+        .description('List Nx projects matching filters')
+        .requiredOption('--with-target <target>', 'only include projects defining this target')
+        .action(async (options) => {
+        const { listProjects } = await import('./nx/index.js');
+        await listProjects(await findRepoRoot(), options);
+    });
+    nx.command('reset-cache')
+        .description('Run nx reset to clear Nx daemon and cache state')
+        .action(async () => {
+        const { resetCache } = await import('./nx/index.js');
+        await resetCache(await findRepoRoot());
+    });
+    nx.command('clean-cache')
+        .description('Remove local Nx cache directories when present')
+        .action(async () => {
+        const { cleanCache } = await import('./nx/index.js');
+        await cleanCache(await findRepoRoot());
+    });
     const githubCi = program.command('github-ci').description('GitHub Actions helpers');
     githubCi.command('cleanup-cache').action(async () => {
         const { cleanupGithubCiCache } = await import('./github-ci/index.js');

package/dist/devenv/index.d.ts

@@ -0,0 +1,10 @@
+export interface DevenvCommandShell {
+    run(command: string, args: string[], cwd: string): Promise<void>;
+    remove(path: string): Promise<void>;
+}
+export declare function updateDevenv(root: string, shell?: DevenvCommandShell): Promise<void>;
+export declare function reloadDevenv(root: string, shell?: DevenvCommandShell): Promise<void>;
+export declare function updateNixpkgsOverlay(root: string, shell?: DevenvCommandShell): Promise<void>;
+export declare function direnvRoot(root: string): string;
+export declare function nixpkgsOverlayRoot(root: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/devenv/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/devenv/index.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AASD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,kBAAiC,GAAG,OAAO,CAAC,IAAI,CAAC,CAExG;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,kBAAiC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxG;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,kBAAiC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhH;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/devenv/index.js

@@ -0,0 +1,27 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { run } from '../lib/run.js';
+const defaultShell = {
+    run,
+    async remove(path) {
+        await rm(path, { recursive: true, force: true });
+    },
+};
+export async function updateDevenv(root, shell = defaultShell) {
+    await shell.run('devenv', ['update'], direnvRoot(root));
+}
+export async function reloadDevenv(root, shell = defaultShell) {
+    const cwd = direnvRoot(root);
+    await shell.remove(join(cwd, '.direnv'));
+    await shell.remove(join(cwd, '.devenv'));
+    await shell.run('direnv', ['reload'], cwd);
+}
+export async function updateNixpkgsOverlay(root, shell = defaultShell) {
+    await shell.run('nix', ['shell', 'nixpkgs#nvfetcher', '-c', 'nvfetcher', '-o', '_sources'], nixpkgsOverlayRoot(root));
+}
+export function direnvRoot(root) {
+    return join(root, 'tooling', 'direnv');
+}
+export function nixpkgsOverlayRoot(root) {
+    return join(direnvRoot(root), 'nixpkgs-overlay');
+}

package/dist/lib/cli-package.d.ts

@@ -0,0 +1,4 @@
+export declare const smoothBricksCodebasePackageName = "@smoothbricks/codebase";
+export declare const cliPackageVersion: string;
+export declare function isSmoothBricksCodebasePackageName(name: string | undefined): boolean;
+//# sourceMappingURL=cli-package.d.ts.map

package/dist/lib/cli-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-package.d.ts","sourceRoot":"","sources":["../../src/lib/cli-package.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,+BAA+B,2BAA2B,CAAC;AACxE,eAAO,MAAM,iBAAiB,QAA0B,CAAC;AAWzD,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEnF"}

package/dist/lib/cli-package.js

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url';
+import { readJsonObject, stringProperty } from './json.js';
+export const smoothBricksCodebasePackageName = '@smoothbricks/codebase';
+export const cliPackageVersion = readCliPackageVersion();
+function readCliPackageVersion() {
+    const pkg = readJsonObject(fileURLToPath(new URL('../../package.json', import.meta.url)));
+    const version = pkg ? stringProperty(pkg, 'version') : null;
+    if (!version) {
+        throw new Error('Unable to read @smoothbricks/cli package version.');
+    }
+    return version;
+}
+export function isSmoothBricksCodebasePackageName(name) {
+    return name === smoothBricksCodebasePackageName;
+}

package/dist/lib/run.d.ts

@@ -1,5 +1,10 @@
 export declare function run(command: string, args: string[], cwd: string, env?: Record<string, string>): Promise<void>;
 export declare function runStatus(command: string, args: string[], cwd: string, quiet?: boolean, env?: Record<string, string>): Promise<number>;
+export declare function runResult(command: string, args: string[], cwd: string, env?: Record<string, string>): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
 export declare function findRepoRoot(): Promise<string>;
 export declare function decode(bytes: Uint8Array): string;
 //# sourceMappingURL=run.d.ts.map

package/dist/lib/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/lib/run.ts"],"names":[],"mappings":"AAKA,wBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnH;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,KAAK,UAAQ,EACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAuCD,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAMpD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/lib/run.ts"],"names":[],"mappings":"AAKA,wBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnH;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,KAAK,UAAQ,EACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAY/D;AAuCD,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAMpD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEhD"}

package/dist/lib/run.js

@@ -17,6 +17,19 @@ export async function runStatus(command, args, cwd, quiet = false, env) {
     const result = quiet ? await shell.quiet() : await shell;
     return result.exitCode;
 }
+export async function runResult(command, args, cwd, env) {
+    const invocation = resolveCommandInvocation(cwd, command, args);
+    let shell = $ `${invocation.command} ${invocation.args}`.cwd(cwd).nothrow().quiet();
+    if (env) {
+        shell = shell.env(mergeEnv(env));
+    }
+    const result = await shell;
+    return {
+        exitCode: result.exitCode,
+        stdout: decode(result.stdout),
+        stderr: decode(result.stderr),
+    };
+}
 function mergeEnv(env) {
     const merged = {};
     for (const [key, value] of Object.entries(process.env)) {