@smoothbricks/cli 0.1.0 → 0.2.0

package/src/cli.ts

@@ -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)): Promise<void> {
@@ -20,7 +21,12 @@ export async function runCli(argv = process.argv.slice(2)): Promise<void> {
 
 function buildProgram(): Command {
   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
@@ -33,11 +39,21 @@ function buildProgram(): Command {
     });
   monorepo
     .command('validate')
+    .option('--fix', 'apply safe monorepo policy fixes before validation')
     .option('--fail-fast', 'stop after the first failing validation pack')
-    .action(async (options: { failFast?: boolean }) => {
-      const { validateMonorepo } = await import('./monorepo/index.js');
-      await validateMonorepo(await findRepoRoot(), options);
-    });
+    .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: {
+        fix?: boolean;
+        failFast?: boolean;
+        onlyIfNewWorkspacePackage?: boolean;
+        verbose?: boolean;
+      }) => {
+        const { validateMonorepo } = await import('./monorepo/index.js');
+        await validateMonorepo(await findRepoRoot(), options);
+      },
+    );
   monorepo.command('update').action(async () => {
     const { updateManagedFiles } = await import('./monorepo/index.js');
     updateManagedFiles(await findRepoRoot());
@@ -50,72 +66,209 @@ function buildProgram(): Command {
     const { diffManagedFiles } = await import('./monorepo/index.js');
     diffManagedFiles(await findRepoRoot());
   });
-  monorepo.command('validate-commit-msg <commitMsgFile>').action(async (commitMsgFile: string) => {
-    const { validateCommitMessageFile } = await import('./monorepo/index.js');
-    validateCommitMessageFile(commitMsgFile);
-  });
+  monorepo
+    .command('validate-commit-msg <commitMsgFile>')
+    .option('--fix', 'format the commit message before validation')
+    .action(async (commitMsgFile: string, options: { fix?: boolean }) => {
+      const { validateCommitMessageFile } = await import('./monorepo/index.js');
+      validateCommitMessageFile(commitMsgFile, options, await findRepoRoot());
+    });
   monorepo.command('sync-bun-lockfile-versions').action(async () => {
     const { syncBunLockfileVersions } = await import('./monorepo/index.js');
     syncBunLockfileVersions(await findRepoRoot());
   });
-  monorepo.command('list-public-projects').action(async () => {
-    const { listPublicProjects } = await import('./monorepo/index.js');
-    console.log(listPublicProjects(await findRepoRoot()));
-  });
+  monorepo
+    .command('list-release-packages')
+    .option('--fail-empty', 'fail when no owned release packages are found')
+    .option('--github-output <path>', 'append projects=<nx-projects> to a GitHub Actions output file')
+    .action(async (options: { failEmpty?: boolean; githubOutput?: string }) => {
+      const { listReleaseProjectNamesForNx } = await import('./monorepo/index.js');
+      const packages = listReleaseProjectNamesForNx(await findRepoRoot(), options);
+      if (!options.githubOutput) {
+        console.log(packages);
+      }
+    });
   monorepo.command('validate-public-tags').action(async () => {
     const { validatePublicPackageTags } = await import('./monorepo/index.js');
     validatePublicPackageTags(await findRepoRoot());
   });
-  monorepo.command('release-state').action(async () => {
+  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: {
+        all?: boolean;
+        projects?: string;
+        opContextExport?: string;
+        tracerModule?: string;
+        dryRun?: boolean;
+      }) => {
+        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');
     await printReleaseState(await findRepoRoot());
   });
-
-  const release = program.command('release').description('Version, publish, and create GitHub Releases');
+  release
+    .command('repair-pending')
+    .description('Repair incomplete older release commits before releasing the current HEAD')
+    .option('--dry-run [dryRun]', 'run without pushing, publishing, or writing GitHub Releases')
+    .action(async (options: { dryRun?: string | boolean }) => {
+      const { releaseRepairPending } = await import('./release/index.js');
+      await releaseRepairPending(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
+    });
   release
     .command('version')
     .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-    .option('--dry-run [dryRun]', 'run without writing versions, tags, or pushes')
-    .action(async (options: { bump: string; dryRun?: string | boolean }) => {
+    .option('--dry-run [dryRun]', 'run without writing versions or tags')
+    .option('--github-output <path>', 'append mode=<mode> and projects=<nx-projects> to a GitHub Actions output file')
+    .action(async (options: { bump: string; dryRun?: string | boolean; githubOutput?: string }) => {
       const { releaseVersion } = await import('./release/index.js');
-      await releaseVersion(await findRepoRoot(), { bump: options.bump, dryRun: booleanOption(options.dryRun) });
+      await releaseVersion(await findRepoRoot(), {
+        bump: options.bump,
+        dryRun: booleanOption(options.dryRun),
+        githubOutput: options.githubOutput,
+      });
     });
   release
     .command('publish')
     .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-    .option('--tag <tag>', 'explicit npm dist-tag; must match bump-derived tag')
-    .option('--npm-tag <npmTag>', 'explicit npm dist-tag; must match bump-derived tag')
-    .option('--dry-run [dryRun]', 'run without publishing')
-    .action(async (options: { bump: string; tag?: string; npmTag?: string; dryRun?: string | boolean }) => {
+    .option('--dry-run [dryRun]', 'run without pushing, publishing, or writing GitHub Releases')
+    .action(async (options: { bump: string; dryRun?: string | boolean }) => {
       const { releasePublish } = await import('./release/index.js');
       await releasePublish(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
     });
   release
-    .command('github-release')
-    .option('--tags <tags>', 'space-separated release tags')
-    .option('--bump <bump>', 'auto, patch, minor, major, or prerelease', 'auto')
-    .option('--tag <tag>', 'explicit npm dist-tag; must match bump-derived tag')
-    .option('--npm-tag <npmTag>', 'explicit npm dist-tag; must match bump-derived tag')
-    .option('--dry-run [dryRun]', 'skip GitHub Release writes')
+    .command('retag-unpublished')
+    .description('Move unpublished owned release tags to a later commit without bumping versions')
+    .argument('<tag...>', 'owned release tags to move, for example @scope/pkg@1.2.3')
+    .option('--to <ref>', 'commit or ref to move tags to', 'HEAD')
+    .option('--push', 'push moved tags with force-with-lease')
+    .option('--dispatch', 'push moved tags and start publish.yml with bump=auto')
+    .option('--remote <remote>', 'git remote used for pushed tags')
+    .option('--branch <branch>', 'branch used for publish workflow dispatch')
+    .option('--dry-run [dryRun]', 'validate and print the retag operation without mutating refs')
     .action(
-      async (options: { tags?: string; bump: string; tag?: string; npmTag?: string; dryRun?: string | boolean }) => {
-        const { releaseGithubRelease } = await import('./release/index.js');
-        await releaseGithubRelease(await findRepoRoot(), { ...options, dryRun: booleanOption(options.dryRun) });
+      async (
+        tags: string[],
+        options: {
+          to?: string;
+          push?: boolean;
+          dispatch?: boolean;
+          remote?: string;
+          branch?: string;
+          dryRun?: string | boolean;
+        },
+      ) => {
+        const { releaseRetagUnpublished } = await import('./release/index.js');
+        await releaseRetagUnpublished(await findRepoRoot(), {
+          tags,
+          to: options.to,
+          push: options.push === true,
+          dispatch: options.dispatch === true,
+          remote: options.remote,
+          branch: options.branch,
+          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: { dryRun?: string | boolean; skipLogin?: boolean; otp?: string; package?: string[] }) => {
+      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 public packages')
+    .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: { dryRun?: string | boolean; otp?: string; skipLogin?: boolean }) => {
-      const { releaseTrustPublisher } = await import('./release/index.js');
-      await releaseTrustPublisher(await findRepoRoot(), {
-        dryRun: booleanOption(options.dryRun),
-        otp: options.otp,
-        skipLogin: options.skipLogin === true,
-      });
+    .action(
+      async (options: {
+        dryRun?: string | boolean;
+        bootstrap?: boolean;
+        otp?: string;
+        bootstrapOtp?: string;
+        skipLogin?: boolean;
+      }) => {
+        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: { withTarget?: string }) => {
+      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');

package/src/devenv/index.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'bun:test';
+import type { DevenvCommandShell } from './index.js';
+import { reloadDevenv, updateDevenv, updateNixpkgsOverlay } from './index.js';
+
+describe('devenv commands', () => {
+  it('runs devenv update in tooling/direnv', async () => {
+    const shell = new RecordingShell();
+
+    await updateDevenv('/repo', shell);
+
+    expect(shell.commands).toEqual([{ command: 'devenv', args: ['update'], cwd: '/repo/tooling/direnv' }]);
+  });
+
+  it('clears cached devenv directories before reloading direnv', async () => {
+    const shell = new RecordingShell();
+
+    await reloadDevenv('/repo', shell);
+
+    expect(shell.removals).toEqual(['/repo/tooling/direnv/.direnv', '/repo/tooling/direnv/.devenv']);
+    expect(shell.commands).toEqual([{ command: 'direnv', args: ['reload'], cwd: '/repo/tooling/direnv' }]);
+  });
+
+  it('runs nvfetcher through nix shell in the overlay directory', async () => {
+    const shell = new RecordingShell();
+
+    await updateNixpkgsOverlay('/repo', shell);
+
+    expect(shell.commands).toEqual([
+      {
+        command: 'nix',
+        args: ['shell', 'nixpkgs#nvfetcher', '-c', 'nvfetcher', '-o', '_sources'],
+        cwd: '/repo/tooling/direnv/nixpkgs-overlay',
+      },
+    ]);
+  });
+});
+
+class RecordingShell implements DevenvCommandShell {
+  readonly commands: { command: string; args: string[]; cwd: string }[] = [];
+  readonly removals: string[] = [];
+
+  async run(command: string, args: string[], cwd: string): Promise<void> {
+    this.commands.push({ command, args, cwd });
+  }
+
+  async remove(path: string): Promise<void> {
+    this.removals.push(path);
+  }
+}

package/src/devenv/index.ts

@@ -0,0 +1,38 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { run } from '../lib/run.js';
+
+export interface DevenvCommandShell {
+  run(command: string, args: string[], cwd: string): Promise<void>;
+  remove(path: string): Promise<void>;
+}
+
+const defaultShell: DevenvCommandShell = {
+  run,
+  async remove(path) {
+    await rm(path, { recursive: true, force: true });
+  },
+};
+
+export async function updateDevenv(root: string, shell: DevenvCommandShell = defaultShell): Promise<void> {
+  await shell.run('devenv', ['update'], direnvRoot(root));
+}
+
+export async function reloadDevenv(root: string, shell: DevenvCommandShell = defaultShell): Promise<void> {
+  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: string, shell: DevenvCommandShell = defaultShell): Promise<void> {
+  await shell.run('nix', ['shell', 'nixpkgs#nvfetcher', '-c', 'nvfetcher', '-o', '_sources'], nixpkgsOverlayRoot(root));
+}
+
+export function direnvRoot(root: string): string {
+  return join(root, 'tooling', 'direnv');
+}
+
+export function nixpkgsOverlayRoot(root: string): string {
+  return join(direnvRoot(root), 'nixpkgs-overlay');
+}

package/src/lib/cli-package.ts

@@ -0,0 +1,18 @@
+import { fileURLToPath } from 'node:url';
+import { readJsonObject, stringProperty } from './json.js';
+
+export const smoothBricksCodebasePackageName = '@smoothbricks/codebase';
+export const cliPackageVersion = readCliPackageVersion();
+
+function readCliPackageVersion(): string {
+  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: string | undefined): boolean {
+  return name === smoothBricksCodebasePackageName;
+}

package/src/lib/devenv.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'bun:test';
+import { mergeDevenvEnv, parseNulEnv } from './devenv.js';
+
+describe('devenv environment loader', () => {
+  it('parses NUL-separated env output without splitting values on newlines or equals signs', () => {
+    const bytes = new TextEncoder().encode('SIMPLE=value\0MULTILINE=line 1\nline 2\0TOKEN=a=b=c\0');
+
+    expect(parseNulEnv(bytes)).toEqual({
+      SIMPLE: 'value',
+      MULTILINE: 'line 1\nline 2',
+      TOKEN: 'a=b=c',
+    });
+  });
+
+  it('merges devenv output over the existing environment instead of replacing it', () => {
+    expect(
+      mergeDevenvEnv(
+        { GH_TOKEN: 'existing-token', NODE_AUTH_TOKEN: 'npm-token', PATH: '/usr/bin' },
+        { DEVENV_ROOT: '/repo/tooling/direnv', PATH: '/nix/bin' },
+      ),
+    ).toEqual({
+      DEVENV_ROOT: '/repo/tooling/direnv',
+      GH_TOKEN: 'existing-token',
+      NODE_AUTH_TOKEN: 'npm-token',
+      PATH: '/nix/bin',
+    });
+  });
+});

package/src/lib/devenv.ts

@@ -0,0 +1,89 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { $ } from 'bun';
+import { decode } from './run.js';
+
+type EnvSnapshot = Record<string, string>;
+
+export async function withDevenvEnv<T>(root: string, runWithEnv: () => Promise<T>): Promise<T> {
+  const snapshot = snapshotProcessEnv();
+  const env = await loadDevenvEnv(root);
+  replaceProcessEnv(mergeDevenvEnv(snapshot, env));
+  try {
+    return await runWithEnv();
+  } finally {
+    restoreProcessEnv(snapshot);
+  }
+}
+
+async function loadDevenvEnv(root: string): Promise<EnvSnapshot> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'smoo-devenv-env-'));
+  const envPath = join(tempDir, 'env');
+  try {
+    const result = await $`devenv shell -- bash -lc ${'env -0 > "$1"'} bash ${envPath}`
+      .cwd(join(root, 'tooling', 'direnv'))
+      .quiet()
+      .nothrow();
+    if (result.exitCode !== 0) {
+      throw new Error('devenv shell failed. Ensure devenv is installed and the tooling/direnv shell is valid.');
+    }
+    return parseNulEnv(await readFile(envPath));
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function parseNulEnv(bytes: Uint8Array): EnvSnapshot {
+  const env: EnvSnapshot = {};
+  let entryStart = 0;
+  for (let index = 0; index <= bytes.length; index += 1) {
+    if (index !== bytes.length && bytes[index] !== 0) {
+      continue;
+    }
+    if (index === entryStart) {
+      entryStart = index + 1;
+      continue;
+    }
+    const entry = decode(bytes.subarray(entryStart, index));
+    const separator = entry.indexOf('=');
+    if (separator <= 0) {
+      throw new Error('devenv shell produced an invalid environment entry.');
+    }
+    env[entry.slice(0, separator)] = entry.slice(separator + 1);
+    entryStart = index + 1;
+  }
+  return env;
+}
+
+export function mergeDevenvEnv(baseEnv: EnvSnapshot, devenvEnv: EnvSnapshot): EnvSnapshot {
+  return { ...baseEnv, ...devenvEnv };
+}
+
+function snapshotProcessEnv(): EnvSnapshot {
+  const snapshot: EnvSnapshot = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      snapshot[key] = value;
+    }
+  }
+  return snapshot;
+}
+
+function replaceProcessEnv(env: EnvSnapshot): void {
+  for (const key of Object.keys(process.env)) {
+    delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(env)) {
+    process.env[key] = value;
+  }
+}
+
+function restoreProcessEnv(snapshot: EnvSnapshot): void {
+  for (const key of Object.keys(process.env)) {
+    delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(snapshot)) {
+    process.env[key] = value;
+  }
+}

package/src/lib/run.ts

@@ -26,6 +26,25 @@ export async function runStatus(
   return result.exitCode;
 }
 
+export async function runResult(
+  command: string,
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  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: Record<string, string>): Record<string, string> {
   const merged: Record<string, string> = {};
   for (const [key, value] of Object.entries(process.env)) {