@smoothbricks/cli 0.1.0 → 0.2.0

package/src/monorepo/commit-msg.ts

@@ -1,3 +1,5 @@
+import { spawnSync } from 'node:child_process';
+
 const validCommitTypes = new Set([
   'build',
   'chore',
@@ -10,26 +12,124 @@ const validCommitTypes = new Set([
   'revert',
   'style',
   'test',
+  'types',
 ]);
 
-export function validateCommitMessage(message: string): string | null {
+export interface FormatCommitMessageOptions {
+  wrapBody?: (paragraph: string) => string;
+}
+
+export interface ValidateCommitMessageOptions {
+  validScopes?: ReadonlySet<string>;
+}
+
+export function validateCommitMessage(message: string, options: ValidateCommitMessageOptions = {}): string | null {
   const subject = message.split('\n', 1)[0]?.trim() ?? '';
   if (!subject) {
     return 'Commit message subject is empty.';
   }
-  if (/^(Merge|Revert ")/.test(subject) || /^(fixup|squash)! /.test(subject)) {
+  if (isGitGeneratedSubject(subject)) {
     return null;
   }
-  const match = /^(?<type>[a-z]+)(\([a-z0-9._/-]+\))?(?<breaking>!)?: .+$/.exec(subject);
+  const match = /^(?<type>[a-z]+)(\((?<scope>[a-z0-9._/@-]+(?:,[a-z0-9._/@-]+)*)\))?(?<breaking>!)?: .+$/.exec(subject);
   const type = match?.groups?.type;
-  if (type && validCommitTypes.has(type)) {
-    return null;
-  }
-  return `Invalid conventional commit subject: ${subject}
+  if (!type || !validCommitTypes.has(type)) {
+    return `Invalid conventional commit subject: ${subject}
 
 Expected examples:
   feat(statebus-core): add optimistic transactions
   fix(money): round negative amounts consistently
   chore(release): publish 1.2.3
   feat!: remove deprecated API`;
+  }
+  const scope = match.groups?.scope;
+  if (scope && options.validScopes) {
+    const invalidScopes = scope.split(',').filter((entry) => !options.validScopes?.has(entry));
+    if (invalidScopes.length > 0) {
+      return `Invalid conventional commit scope: ${invalidScopes.join(',')}
+
+Use package.json nx.name values, for example:
+  feat(statebus-core): add optimistic transactions
+  fix(money): round negative amounts consistently`;
+    }
+  }
+  return null;
+}
+
+export function formatCommitMessage(message: string, options: FormatCommitMessageOptions = {}): string {
+  const wrapBody = options.wrapBody ?? wrapBodyWithFmt;
+  const normalized = message.replace(/\r\n?/g, '\n');
+  const lines = normalized.split('\n');
+  const subject = lines.shift()?.trimEnd() ?? '';
+  const formatted = [subject];
+  let paragraph: string[] = [];
+  let inFence = false;
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0) {
+      return;
+    }
+    formatted.push(wrapBody(paragraph.join('\n')).trimEnd());
+    paragraph = [];
+  };
+
+  for (const line of lines) {
+    const trimmedEnd = line.trimEnd();
+    if (trimmedEnd.startsWith('```') || trimmedEnd.startsWith('~~~')) {
+      flushParagraph();
+      inFence = !inFence;
+      formatted.push(trimmedEnd);
+      continue;
+    }
+    if (inFence || shouldPreserveLine(trimmedEnd)) {
+      flushParagraph();
+      formatted.push(trimmedEnd);
+      continue;
+    }
+    if (trimmedEnd === '') {
+      flushParagraph();
+      formatted.push('');
+      continue;
+    }
+    paragraph.push(trimmedEnd);
+  }
+  flushParagraph();
+
+  while (formatted.length > 1 && formatted.at(-1) === '') {
+    formatted.pop();
+  }
+  return `${formatted.join('\n')}\n`;
+}
+
+function wrapBodyWithFmt(paragraph: string): string {
+  const result = spawnSync('fmt', ['-w', '72'], { input: `${paragraph}\n`, encoding: 'utf8' });
+  if (result.error) {
+    throw new Error(
+      `fmt is required to format commit messages. Install it through devenv and retry.\n${result.error.message}`,
+    );
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join('\n') ||
+        'fmt failed to wrap commit message body.',
+    );
+  }
+  return result.stdout;
+}
+
+function shouldPreserveLine(line: string): boolean {
+  return (
+    line.startsWith('#') ||
+    line.startsWith('>') ||
+    /^\s/.test(line) ||
+    /^[-*+]\s+/.test(line) ||
+    /^\d+\.\s+/.test(line) ||
+    /^https?:\/\//.test(line) ||
+    /^[A-Za-z][A-Za-z0-9-]*: /.test(line) ||
+    /^BREAKING CHANGE: /.test(line)
+  );
+}
+
+function isGitGeneratedSubject(subject: string): boolean {
+  return /^(Merge|Revert ")/.test(subject) || /^(fixup|squash)! /.test(subject);
 }

package/src/monorepo/index.ts

@@ -1,10 +1,12 @@
-import { readFileSync } from 'node:fs';
-import { listPublicPackages } from '../lib/workspace.js';
-import { validateCommitMessage } from './commit-msg.js';
+import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { $ } from 'bun';
+import { decode, run } from '../lib/run.js';
+import { escapeRegex, getWorkspacePackages, getWorkspacePatterns, listReleasePackages } from '../lib/workspace.js';
+import { formatCommitMessage, validateCommitMessage } from './commit-msg.js';
 import { applyWorkspaceGitConfig } from './git-config.js';
 import { syncBunLockfileVersions } from './lockfile.js';
 import { applyManagedFiles, printResults } from './managed-files.js';
-import { validatePublicTags } from './package-policy.js';
+import { listValidCommitScopes, validatePublicTags } from './package-policy.js';
 import { runInitPacks, runValidatePacks } from './packs/index.js';
 import { syncRootRuntimeVersions } from './runtime.js';
 
@@ -15,6 +17,31 @@ export interface InitOptions {
 
 export interface ValidateOptions {
   failFast?: boolean;
+  onlyIfNewWorkspacePackage?: boolean;
+  fix?: boolean;
+  verbose?: boolean;
+}
+
+export interface ValidateCommitMessageOptions {
+  fix?: boolean;
+}
+
+export interface ListReleasePackagesOptions {
+  failEmpty?: boolean;
+  githubOutput?: string;
+}
+
+export interface SetupTestTracingOptions {
+  all?: boolean;
+  projects?: string;
+  opContextExport?: string;
+  tracerModule?: string;
+  dryRun?: boolean;
+}
+
+export interface SetupTestTracingShell {
+  run(command: string, args: string[], cwd: string): Promise<void>;
+  log(message: string): void;
 }
 
 export async function initMonorepo(root: string, options: InitOptions): Promise<void> {
@@ -28,12 +55,23 @@ export async function initMonorepo(root: string, options: InitOptions): Promise<
 }
 
 export async function validateMonorepo(root: string, options: ValidateOptions = {}): Promise<void> {
-  const failures = await runValidatePacks({ root, syncRuntime: false }, options);
-  if (failures > 0) {
-    throw new Error(`Monorepo validation failed with ${failures} problem(s).`);
+  if (options.onlyIfNewWorkspacePackage && !(await hasNewWorkspacePackage(root))) {
+    return;
+  }
+  const result = await runValidatePacks({ root, syncRuntime: false, verbose: options.verbose === true }, options);
+  if (result.failures > 0) {
+    const checkNoun = result.failedChecks === 1 ? 'check' : 'checks';
+    const problemNoun = result.failures === 1 ? 'problem' : 'problems';
+    throw new Error(
+      `\n🔴 Monorepo validation failed: ${result.failedChecks} ${checkNoun} failed with ${result.failures} ${problemNoun}.`,
+    );
+  }
+  if (options.verbose) {
+    console.log('\n== summary ==');
+    console.log('Monorepo configuration is valid.');
+  } else {
+    console.log('🟢 Monorepo configuration is valid.');
   }
-  console.log('\n== summary ==');
-  console.log('Monorepo configuration is valid.');
 }
 
 export function updateManagedFiles(root: string): void {
@@ -52,21 +90,39 @@ export function diffManagedFiles(root: string): void {
   printResults(applyManagedFiles(root, 'diff'));
 }
 
-export function validateCommitMessageFile(path: string | undefined): void {
+export function validateCommitMessageFile(
+  path: string | undefined,
+  options: ValidateCommitMessageOptions = {},
+  root = process.cwd(),
+): void {
   if (!path) {
     throw new Error('Usage: smoo monorepo validate-commit-msg <commit-msg-file>');
   }
-  const message = readFileSync(path, 'utf8');
-  const error = validateCommitMessage(message);
+  let message = readFileSync(path, 'utf8');
+  if (options.fix) {
+    const formatted = formatCommitMessage(message);
+    if (formatted !== message) {
+      writeFileSync(path, formatted);
+      message = formatted;
+    }
+  }
+  const error = validateCommitMessage(message, { validScopes: listValidCommitScopes(root) });
   if (error) {
     throw new Error(error);
   }
 }
 
-export function listPublicProjects(root: string): string {
-  return listPublicPackages(root)
-    .map((pkg) => pkg.name)
+export function listReleaseProjectNamesForNx(root: string, options: ListReleasePackagesOptions = {}): string {
+  const packages = listReleasePackages(root)
+    .map((pkg) => pkg.projectName)
     .join(',');
+  if (!packages && options.failEmpty) {
+    throw new Error('No owned release packages found.');
+  }
+  if (options.githubOutput) {
+    appendFileSync(options.githubOutput, `projects=${packages}\n`);
+  }
+  return packages;
 }
 
 export function validatePublicPackageTags(root: string): void {
@@ -75,4 +131,114 @@ export function validatePublicPackageTags(root: string): void {
   }
 }
 
+export async function setupTestTracing(
+  root: string,
+  options: SetupTestTracingOptions,
+  shell: SetupTestTracingShell = defaultSetupTestTracingShell,
+): Promise<void> {
+  const selectedPackages = selectTestTracingPackages(root, options);
+  const opContextExport = options.opContextExport ?? 'opContext';
+  const tracerModule = options.tracerModule ?? '@smoothbricks/lmao/testing/bun';
+
+  if (selectedPackages.length === 0) {
+    throw new Error('No workspace packages matched LMAO test tracing setup selection.');
+  }
+
+  for (const pkg of selectedPackages) {
+    const args = [
+      'g',
+      '@smoothbricks/nx-plugin:bun-test-tracing',
+      '--project',
+      pkg.projectName,
+      '--opContextModule',
+      pkg.name,
+      '--opContextExport',
+      opContextExport,
+      '--tracerModule',
+      tracerModule,
+    ];
+    const commandPreview = `nx ${args.join(' ')}`;
+    if (options.dryRun) {
+      shell.log(`would run      ${commandPreview}`);
+      continue;
+    }
+    shell.log(`running        ${commandPreview}`);
+    await shell.run('nx', args, root);
+  }
+}
+
 export { applyWorkspaceGitConfig, syncBunLockfileVersions };
+
+const defaultSetupTestTracingShell: SetupTestTracingShell = {
+  run,
+  log(message) {
+    console.log(message);
+  },
+};
+
+function selectTestTracingPackages(root: string, options: SetupTestTracingOptions) {
+  const packages = getWorkspacePackages(root);
+  const requested = splitCommaList(options.projects);
+
+  if (options.all && requested.length > 0) {
+    throw new Error('Use either --all or --projects, not both.');
+  }
+  if (!options.all && requested.length === 0) {
+    throw new Error('Pass --all or --projects <projects> to select packages for LMAO test tracing setup.');
+  }
+  if (options.all) {
+    return packages;
+  }
+
+  const bySelector = new Map<string, (typeof packages)[number]>();
+  for (const pkg of packages) {
+    bySelector.set(pkg.projectName, pkg);
+    bySelector.set(pkg.name, pkg);
+    bySelector.set(pkg.path, pkg);
+  }
+
+  const selected = [];
+  const missing = [];
+  for (const selector of requested) {
+    const pkg = bySelector.get(selector);
+    if (pkg) {
+      selected.push(pkg);
+    } else {
+      missing.push(selector);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Unknown workspace package selection for LMAO test tracing setup: ${missing.join(', ')}`);
+  }
+
+  return selected;
+}
+
+function splitCommaList(value: string | undefined): string[] {
+  return (value ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+async function hasNewWorkspacePackage(root: string): Promise<boolean> {
+  const result = await $`git diff --cached --name-only --diff-filter=A -- ${'*/package.json'}`
+    .cwd(root)
+    .quiet()
+    .nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error('Unable to inspect staged package manifests.');
+  }
+  const manifests = decode(result.stdout)
+    .split('\n')
+    .map((path) => path.trim())
+    .filter(Boolean);
+  if (manifests.length === 0) {
+    return false;
+  }
+  const patterns = getWorkspacePatterns(root)
+    .filter((pattern) => pattern.endsWith('/*'))
+    .map((pattern) => new RegExp(`^${escapeRegex(pattern.slice(0, -2))}/[^/]+/package\\.json$`));
+  return manifests.some((manifest) => patterns.some((pattern) => pattern.test(manifest)));
+}

package/src/monorepo/lockfile.ts

@@ -2,7 +2,12 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { escapeRegex, getWorkspacePackages } from '../lib/workspace.js';
 
-export function syncBunLockfileVersions(root: string): void {
+export interface SyncBunLockfileVersionsOptions {
+  log?: boolean;
+}
+
+export function syncBunLockfileVersions(root: string, options: SyncBunLockfileVersionsOptions = {}): number {
+  const log = options.log ?? true;
   const lockfilePath = join(root, 'bun.lock');
   if (!existsSync(lockfilePath)) {
     throw new Error('bun.lock not found');
@@ -16,22 +21,62 @@ export function syncBunLockfileVersions(root: string): void {
     const pattern = new RegExp(`("${escaped}":\\s*\\{[^}]*"version":\\s*")([^"]+)(")`);
     const match = lockfile.match(pattern);
     if (!match) {
-      console.log(`skip: ${relativePath} (not found in lockfile)`);
+      if (log) {
+        console.log(`skip: ${relativePath} (not found in lockfile)`);
+      }
       continue;
     }
     const lockVersion = match[2];
     if (lockVersion === pkg.version) {
-      console.log(`ok:   ${relativePath} = ${pkg.version}`);
+      if (log) {
+        console.log(`ok:   ${relativePath} = ${pkg.version}`);
+      }
       continue;
     }
     lockfile = lockfile.replace(pattern, `$1${pkg.version}$3`);
-    console.log(`fix:  ${relativePath}: ${lockVersion} -> ${pkg.version}`);
+    if (log) {
+      console.log(`fix:  ${relativePath}: ${lockVersion} -> ${pkg.version}`);
+    }
     updated++;
   }
   if (updated > 0) {
     writeFileSync(lockfilePath, lockfile);
   }
-  console.log(
-    updated > 0 ? `Updated ${updated} workspace version(s) in bun.lock` : 'All workspace versions already in sync.',
-  );
+  if (log) {
+    console.log(
+      updated > 0 ? `Updated ${updated} workspace version(s) in bun.lock` : 'All workspace versions already in sync.',
+    );
+  }
+  return updated;
+}
+
+export function validateBunLockfileVersions(root: string): number {
+  const lockfilePath = join(root, 'bun.lock');
+  if (!existsSync(lockfilePath)) {
+    console.error('bun.lock not found');
+    return 1;
+  }
+  const packages = getWorkspacePackages(root);
+  const lockfile = readFileSync(lockfilePath, 'utf8');
+  let failures = 0;
+  for (const pkg of packages) {
+    const relativePath = pkg.path.replaceAll('\\', '/');
+    const escaped = escapeRegex(relativePath);
+    const pattern = new RegExp(`("${escaped}":\\s*\\{[^}]*"version":\\s*")([^"]+)(")`);
+    const match = lockfile.match(pattern);
+    if (!match) {
+      console.error(`bun.lock missing workspace entry for ${relativePath}`);
+      failures++;
+      continue;
+    }
+    const lockVersion = match[2];
+    if (lockVersion !== pkg.version) {
+      console.error(`${relativePath}: bun.lock workspace version must be ${pkg.version}, got ${lockVersion}`);
+      failures++;
+    }
+  }
+  if (failures === 0) {
+    console.log('bun.lock workspace versions are valid.');
+  }
+  return failures;
 }

package/src/monorepo/managed-files.ts

@@ -1,20 +1,28 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readPackageJson } from '../lib/workspace.js';
+import { listReleasePackages, readPackageJson } from '../lib/workspace.js';
+import { renderPublishWorkflowYaml } from './publish-workflow.js';
 
-type ManagedKind = 'raw' | 'template';
+type ManagedKind = 'raw' | 'template' | 'generated';
 
 interface ManagedFile {
   kind: ManagedKind;
   source: string;
   target: string;
   executable?: boolean;
+  releasePackagesOnly?: boolean;
 }
 
 export interface FileResult {
   target: string;
-  action: 'created' | 'updated' | 'unchanged' | 'skipped-symlink' | 'drifted' | 'ok-symlink';
+  action: 'created' | 'updated' | 'unchanged' | 'skipped' | 'skipped-symlink' | 'drifted' | 'ok-symlink';
+}
+
+interface ManagedFileContext {
+  hasReleasePackages: boolean;
+  nodeModulesCacheKey: string;
+  repoName: string;
 }
 
 const managedFiles: ManagedFile[] = [
@@ -38,7 +46,7 @@ const managedFiles: ManagedFile[] = [
   },
   {
     kind: 'raw',
-    source: '.git-format-staged.yml',
+    source: 'git-format-staged.yml',
     target: '.git-format-staged.yml',
   },
   {
@@ -47,9 +55,10 @@ const managedFiles: ManagedFile[] = [
     target: '.github/workflows/ci.yml',
   },
   {
-    kind: 'template',
-    source: 'github/workflows/publish.yml',
+    kind: 'generated',
+    source: 'publish-workflow',
     target: '.github/workflows/publish.yml',
+    releasePackagesOnly: true,
   },
   {
     kind: 'template',
@@ -81,12 +90,21 @@ const managedFiles: ManagedFile[] = [
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 export function applyManagedFiles(root: string, mode: 'update' | 'check' | 'diff'): FileResult[] {
-  return managedFiles.map((file) => applyManagedFile(root, file, mode));
+  const context = getManagedFileContext(root);
+  return managedFiles.map((file) => applyManagedFile(root, file, mode, context));
 }
 
-function applyManagedFile(root: string, file: ManagedFile, mode: 'update' | 'check' | 'diff'): FileResult {
+function applyManagedFile(
+  root: string,
+  file: ManagedFile,
+  mode: 'update' | 'check' | 'diff',
+  context: ManagedFileContext,
+): FileResult {
+  if (file.releasePackagesOnly === true && !context.hasReleasePackages) {
+    return { target: file.target, action: 'skipped' };
+  }
   const target = resolve(root, file.target);
-  const content = getManagedContent(root, file);
+  const content = getManagedContent(file, context);
   if (existsSync(target)) {
     const info = lstatSync(target);
     if (info.isSymbolicLink()) {
@@ -112,23 +130,35 @@ function applyManagedFile(root: string, file: ManagedFile, mode: 'update' | 'che
   return { target: file.target, action: 'created' };
 }
 
-function getManagedContent(root: string, file: ManagedFile): string {
+function getManagedContent(file: ManagedFile, context: ManagedFileContext): string {
+  if (file.kind === 'generated') {
+    if (file.source === 'publish-workflow') {
+      return renderPublishWorkflowYaml({ repoName: context.repoName });
+    }
+    throw new Error(`Unknown generated managed file source ${file.source}`);
+  }
   const sourceRoot = file.kind === 'raw' ? 'managed/raw' : 'managed/templates';
   const sourcePath = join(packageRoot, sourceRoot, file.source);
   const content = readFileSync(sourcePath, 'utf8');
   if (file.kind === 'raw') {
     return content;
   }
-  return renderTemplate(root, content);
+  return renderTemplate(context, content);
 }
 
-function renderTemplate(root: string, template: string): string {
+function getManagedFileContext(root: string): ManagedFileContext {
   const packageJson = readPackageJson(join(root, 'package.json'));
   const repoName = packageJson?.name ?? 'monorepo';
   const nodeModulesCacheKey = existsSync(join(root, 'bun.lock'))
     ? `$${"{{ hashFiles('bun.lock', 'package.json', 'packages/*/package.json') }}"}`
     : `$${"{{ hashFiles('bun.lockb', 'package.json', 'packages/*/package.json') }}"}`;
-  return template.replaceAll('{{REPO_NAME}}', repoName).replaceAll('{{NODE_MODULES_CACHE_KEY}}', nodeModulesCacheKey);
+  return { hasReleasePackages: listReleasePackages(root, packageJson).length > 0, nodeModulesCacheKey, repoName };
+}
+
+function renderTemplate(context: ManagedFileContext, template: string): string {
+  return template
+    .replaceAll('{{REPO_NAME}}', context.repoName)
+    .replaceAll('{{NODE_MODULES_CACHE_KEY}}', context.nodeModulesCacheKey);
 }
 
 function writeManagedFile(path: string, content: string, executable: boolean): void {

package/src/monorepo/nx-sync.ts

@@ -1,6 +1,13 @@
 import { runStatus } from '../lib/run.js';
 
-export async function validateNxSync(root: string): Promise<number> {
-  const status = await runStatus('nx', ['sync:check'], root);
+export async function fixNxSync(root: string, verbose = false): Promise<void> {
+  const status = await runStatus('nx', ['sync'], root, !verbose);
+  if (status !== 0) {
+    throw new Error(`nx sync failed with exit code ${status}`);
+  }
+}
+
+export async function validateNxSync(root: string, verbose = false): Promise<number> {
+  const status = await runStatus('nx', ['sync:check'], root, !verbose);
   return status === 0 ? 0 : 1;
 }

package/src/monorepo/package-hygiene.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'bun:test';
+import { fixPackageHygiene, type PackageHygieneShell, validatePackageHygiene } from './package-hygiene.js';
+
+describe('package hygiene', () => {
+  it('runs sherif in autofix mode and selects highest dependency versions', async () => {
+    const shell = new RecordingShell();
+
+    await fixPackageHygiene('/repo', shell);
+
+    expect(shell.statuses).toEqual([{ command: 'sherif', args: ['-f', '--select', 'highest'], cwd: '/repo' }]);
+  });
+
+  it('validates sherif warnings as failures', async () => {
+    const shell = new RecordingShell();
+
+    await validatePackageHygiene('/repo', shell);
+
+    expect(shell.statuses).toEqual([{ command: 'sherif', args: ['--fail-on-warnings'], cwd: '/repo' }]);
+  });
+});
+
+class RecordingShell implements PackageHygieneShell {
+  readonly runs: { command: string; args: string[]; cwd: string }[] = [];
+  readonly statuses: { command: string; args: string[]; cwd: string }[] = [];
+
+  async run(command: string, args: string[], cwd: string): Promise<void> {
+    this.runs.push({ command, args, cwd });
+  }
+
+  async runStatus(command: string, args: string[], cwd: string): Promise<number> {
+    this.statuses.push({ command, args, cwd });
+    return 0;
+  }
+}

package/src/monorepo/package-hygiene.ts

@@ -1,11 +1,33 @@
 import { run, runStatus } from '../lib/run.js';
 
-export async function fixPackageHygiene(root: string): Promise<void> {
-  await run('sherif', ['--fix', '--select', 'highest'], root);
+export interface PackageHygieneShell {
+  run(command: string, args: string[], cwd: string): Promise<void>;
+  runStatus(command: string, args: string[], cwd: string, quiet?: boolean): Promise<number>;
 }
 
-export async function validatePackageHygiene(root: string): Promise<number> {
-  const status = await runStatus('sherif', [], root);
+const defaultShell: PackageHygieneShell = { run, runStatus };
+
+export async function fixPackageHygiene(
+  root: string,
+  verboseOrShell: boolean | PackageHygieneShell = false,
+  maybeShell: PackageHygieneShell = defaultShell,
+): Promise<void> {
+  const verbose = typeof verboseOrShell === 'boolean' ? verboseOrShell : false;
+  const shell = typeof verboseOrShell === 'boolean' ? maybeShell : verboseOrShell;
+  const status = await shell.runStatus('sherif', ['-f', '--select', 'highest'], root, !verbose);
+  if (status !== 0) {
+    throw new Error(`sherif -f --select highest failed with exit code ${status}`);
+  }
+}
+
+export async function validatePackageHygiene(
+  root: string,
+  verboseOrShell: boolean | PackageHygieneShell = false,
+  maybeShell: PackageHygieneShell = defaultShell,
+): Promise<number> {
+  const verbose = typeof verboseOrShell === 'boolean' ? verboseOrShell : false;
+  const shell = typeof verboseOrShell === 'boolean' ? maybeShell : verboseOrShell;
+  const status = await shell.runStatus('sherif', ['--fail-on-warnings'], root, !verbose);
   if (status !== 0) {
     console.error('sherif package hygiene validation failed');
     return 1;