@smoothbricks/cli 0.1.0 → 0.1.1

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/workspace.ts

@@ -23,11 +23,45 @@ export function listPublicPackages(root: string): PackageInfo[] {
   return getWorkspacePackages(root).filter((pkg) => !pkg.private && pkg.tags.includes('npm:public'));
 }
 
+export function listReleasePackages(
+  root: string,
+  rootPackage = readPackageJson(join(root, 'package.json')),
+): PackageInfo[] {
+  if (!rootPackage) {
+    return [];
+  }
+  const rootRepository = repositoryInfo(rootPackage.json);
+  if (!rootRepository) {
+    return [];
+  }
+  return getWorkspacePackagesForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage.json)).filter(
+    (pkg) => !pkg.private && pkg.tags.includes('npm:public') && isOwnedPackage(rootRepository, pkg),
+  );
+}
+
+export function rootRepositoryInfo(root: string): RepositoryInfo | null {
+  const rootPackage = readJsonObject(join(root, 'package.json'));
+  return rootPackage ? repositoryInfo(rootPackage) : null;
+}
+
+export function packageRepositoryInfo(pkg: PackageInfo): RepositoryInfo | null {
+  return repositoryInfo(pkg.json);
+}
+
+export function isOwnedPackage(rootRepository: RepositoryInfo, pkg: PackageInfo): boolean {
+  const packageRepository = packageRepositoryInfo(pkg);
+  return packageRepository !== null && packageRepository.url === rootRepository.url;
+}
+
 export function getWorkspacePackages(root: string): PackageInfo[] {
-  if (!readPackageJson(join(root, 'package.json'))) {
+  const rootPackage = readPackageJson(join(root, 'package.json'));
+  if (!rootPackage) {
     throw new Error('package.json not found or invalid');
   }
-  const workspacePatterns = getWorkspacePatterns(root);
+  return getWorkspacePackagesForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage.json));
+}
+
+function getWorkspacePackagesForPatterns(root: string, workspacePatterns: string[]): PackageInfo[] {
   const packages: PackageInfo[] = [];
   for (const pattern of workspacePatterns) {
     if (!pattern.endsWith('/*')) {
@@ -62,15 +96,22 @@ export function listPackageJsonRecords(root: string): PackageInfo[] {
   if (!rootPackage) {
     throw new Error('package.json not found or invalid');
   }
-  return [{ ...rootPackage, path: '.' }, ...getWorkspacePackages(root)];
+  return [
+    { ...rootPackage, path: '.' },
+    ...getWorkspacePackagesForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage.json)),
+  ];
 }
 
 export function getWorkspacePatterns(root: string): string[] {
   const raw = readJson(join(root, 'package.json'));
-  if (!isRecord(raw) || !hasOwn(raw, 'workspaces')) {
+  return isRecord(raw) ? getWorkspacePatternsFromPackageJson(raw) : ['packages/*'];
+}
+
+function getWorkspacePatternsFromPackageJson(pkg: Record<string, unknown>): string[] {
+  if (!hasOwn(pkg, 'workspaces')) {
     return ['packages/*'];
   }
-  const workspaces = raw.workspaces;
+  const workspaces = pkg.workspaces;
   if (Array.isArray(workspaces)) {
     return workspaces.filter((entry): entry is string => typeof entry === 'string');
   }
@@ -120,6 +161,36 @@ export function repositoryInfo(pkg: Record<string, unknown>): RepositoryInfo | n
   return { type: stringProperty(repository, 'type') ?? 'git', url };
 }
 
+export function sameRepositoryAfterNormalization(left: string, right: string): boolean {
+  return normalizedRepositoryUrl(left) === normalizedRepositoryUrl(right);
+}
+
+function normalizedRepositoryUrl(url: string): string {
+  const trimmed = url
+    .trim()
+    .replace(/^git\+/, '')
+    .replace(/#.*$/, '')
+    .replace(/\/$/, '')
+    .replace(/\.git$/, '');
+  const https = /^https:\/\/github\.com\/([^/]+)\/([^/]+)$/i.exec(trimmed);
+  if (https?.[1] && https[2]) {
+    return githubRepositoryKey(https[1], https[2]);
+  }
+  const ssh = /^git@github\.com:([^/]+)\/([^/]+)$/i.exec(trimmed);
+  if (ssh?.[1] && ssh[2]) {
+    return githubRepositoryKey(ssh[1], ssh[2]);
+  }
+  const shorthand = /^github:([^/]+)\/([^/]+)$/i.exec(trimmed);
+  if (shorthand?.[1] && shorthand[2]) {
+    return githubRepositoryKey(shorthand[1], shorthand[2]);
+  }
+  return trimmed;
+}
+
+function githubRepositoryKey(owner: string, repo: string): string {
+  return `github:${owner.toLowerCase()}/${repo.toLowerCase()}`;
+}
+
 export function escapeRegex(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/src/monorepo/__tests__/nx-version-actions.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'bun:test';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { $ } from 'bun';
+import { syncBunLockfileVersions } from '../lockfile.js';
+
+describe('nx-version-actions Bun lockfile workaround', () => {
+  it('repairs stale workspace versions that Bun still uses when packing workspace:* dependencies', async () => {
+    await withBunWorkspace(async (root) => {
+      await writePackage(root, 'a', {
+        name: '@fixture/a',
+        version: '1.0.0',
+        dependencies: { '@fixture/b': 'workspace:*' },
+      });
+      await writePackage(root, 'b', { name: '@fixture/b', version: '1.0.0' });
+      await $`bun install --lockfile-only`.cwd(root).quiet();
+
+      await writePackage(root, 'b', { name: '@fixture/b', version: '1.0.1' });
+      await $`bun install --lockfile-only`.cwd(root).quiet();
+
+      const stalePackedVersion = await packedDependencyVersion(root, 1);
+      if (stalePackedVersion !== '1.0.0') {
+        throw new Error(
+          'Hurrah! Bun no longer reproduces the stale workspace lockfile pack bug. ' +
+            `Raw bun pm pack resolved @fixture/b to ${stalePackedVersion}; remove the nx-version-actions hook and update the release docs.`,
+        );
+      }
+
+      expect(syncBunLockfileVersions(root, { log: false })).toBe(1);
+      await expect(packedDependencyVersion(root, 2)).resolves.toBe('1.0.1');
+    });
+  });
+});
+
+async function withBunWorkspace(fn: (root: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(join(tmpdir(), 'smoo-bun-lock-test-'));
+  try {
+    await writeFile(
+      join(root, 'package.json'),
+      `${JSON.stringify({ name: 'fixture-root', version: '0.0.0', private: true, packageManager: 'bun@1.3.13', workspaces: ['packages/*'] }, null, 2)}\n`,
+    );
+    await fn(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+async function writePackage(
+  root: string,
+  directory: string,
+  manifest: { name: string; version: string; dependencies?: Record<string, string> },
+): Promise<void> {
+  const packageRoot = join(root, 'packages', directory);
+  await mkdir(packageRoot, { recursive: true });
+  await writeFile(join(packageRoot, 'index.js'), 'export {}\n');
+  await writeFile(
+    join(packageRoot, 'package.json'),
+    `${JSON.stringify({ ...manifest, type: 'module', exports: './index.js', files: ['index.js'] }, null, 2)}\n`,
+  );
+}
+
+async function packedDependencyVersion(root: string, index: number): Promise<string> {
+  const tarball = join(root, `a-${index}.tgz`);
+  const unpacked = join(root, `unpacked-${index}`);
+  await mkdir(unpacked);
+  await $`bun pm pack --filename ${tarball} --ignore-scripts --quiet`.cwd(join(root, 'packages/a')).quiet();
+  await $`tar -xzf ${tarball} -C ${unpacked}`.quiet();
+  const manifest = JSON.parse(await readFile(join(unpacked, 'package', 'package.json'), 'utf8'));
+  const version = manifest.dependencies?.['@fixture/b'];
+  if (typeof version !== 'string') {
+    throw new Error('Packed @fixture/a manifest did not include @fixture/b dependency.');
+  }
+  return version;
+}

package/src/monorepo/__tests__/publish-workflow.test.ts

@@ -0,0 +1,315 @@
+import { describe, expect, it } from 'bun:test';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  definePublishWorkflow,
+  type PublishWorkflowBump,
+  type PublishWorkflowCallbacks,
+  type PublishWorkflowNxTarget,
+  type PublishWorkflowVersionOutputs,
+  renderPublishWorkflowYaml,
+  runPublishWorkflow,
+} from '../publish-workflow.js';
+
+describe('publish workflow definition', () => {
+  it('renders the checked-in local publish workflow copy', async () => {
+    const rendered = renderPublishWorkflowYaml({ repoName: '@smoothbricks/codebase' });
+    const packageRoot = join(import.meta.dir, '..', '..', '..');
+    await expect(readFile(join(packageRoot, '..', '..', '.github/workflows/publish.yml'), 'utf8')).resolves.toBe(
+      rendered,
+    );
+  });
+
+  it('bootstraps the self-hosted CLI before release commands only for the SmoothBricks repo', async () => {
+    const smoothbricks = await publishWorkflowScenario({
+      repoName: '@smoothbricks/codebase',
+      repairs: [],
+      current: [],
+      bump: 'patch',
+      dryRun: false,
+      version: { mode: 'none', projects: [] },
+    }).run();
+    const downstream = await publishWorkflowScenario({
+      repoName: '@other/repo',
+      repairs: [],
+      current: [],
+      bump: 'patch',
+      dryRun: false,
+      version: { mode: 'none', projects: [] },
+    }).run();
+
+    expect(smoothbricks.selfHostedCliBuilt).toBe(true);
+    expect(smoothbricks.repairSawSelfHostedCli).toBe(true);
+    expect(smoothbricks.versionSawSelfHostedCli).toBe(true);
+    expect(downstream.selfHostedCliBuilt).toBe(false);
+    expect(downstream.repairSawSelfHostedCli).toBe(false);
+    expect(downstream.versionSawSelfHostedCli).toBe(false);
+  });
+
+  it('repairs older gaps, skips validation for mode none, and still completes current HEAD publish', async () => {
+    const scenario = publishWorkflowScenario({
+      repairs: [
+        { tag: '@scope/a@1.1.0', npmMissing: false, githubMissing: true },
+        { tag: '@scope/b@2.0.0-beta.1', npmMissing: true, githubMissing: true },
+      ],
+      current: [{ tag: '@scope/a@1.2.0', npmMissing: true, githubMissing: false }],
+      bump: 'auto',
+      dryRun: false,
+      version: { mode: 'none', projects: [] },
+    });
+
+    const outcome = await scenario.run();
+
+    expect(outcome.fixtureRepoSetup).toBe(true);
+    expect(outcome.releaseAuthorConfigured).toBe(true);
+    expect(outcome.repairedTags).toEqual(['@scope/a@1.1.0', '@scope/b@2.0.0-beta.1']);
+    expect(outcome.repairBuildArtifacts).toEqual(['@scope/b']);
+    expect(outcome.validation).toEqual({ checks: 0, builds: [], lints: [], tests: [], validates: 0 });
+    expect(outcome.publishRan).toBe(true);
+    expect(outcome.publishCompletedTags).toEqual(['@scope/a@1.2.0']);
+    expect(outcome.remainingDurableGaps).toEqual([]);
+  });
+
+  it('validates a new release before publishing current HEAD gaps', async () => {
+    const scenario = publishWorkflowScenario({
+      repairs: [],
+      current: [
+        { tag: '@scope/a@1.2.0', npmMissing: true, githubMissing: true },
+        { tag: '@scope/b@2.0.0', npmMissing: false, githubMissing: true },
+      ],
+      bump: 'patch',
+      dryRun: false,
+      version: { mode: 'new', projects: ['@scope/a', '@scope/b'] },
+    });
+
+    const outcome = await scenario.run();
+
+    expect(outcome.validation).toEqual({
+      checks: 1,
+      builds: ['@scope/a', '@scope/b'],
+      lints: ['@scope/a', '@scope/b'],
+      tests: ['@scope/a', '@scope/b'],
+      validates: 1,
+    });
+    expect(outcome.publishSawValidatedRelease).toBe(true);
+    expect(outcome.publishCompletedTags).toEqual(['@scope/a@1.2.0', '@scope/b@2.0.0']);
+    expect(outcome.remainingDurableGaps).toEqual([]);
+  });
+
+  it('dry-run walks the workflow outcomes without mutating durable release state', async () => {
+    const scenario = publishWorkflowScenario({
+      repairs: [{ tag: '@scope/a@1.1.0', npmMissing: true, githubMissing: true }],
+      current: [{ tag: '@scope/a@1.2.0', npmMissing: true, githubMissing: true }],
+      bump: 'prerelease',
+      dryRun: true,
+      version: { mode: 'new', projects: ['@scope/a'] },
+    });
+
+    const outcome = await scenario.run();
+
+    expect(outcome.fixtureRepoSetup).toBe(true);
+    expect(outcome.repairedTags).toEqual([]);
+    expect(outcome.repairBuildArtifacts).toEqual([]);
+    expect(outcome.validation).toEqual({
+      checks: 1,
+      builds: ['@scope/a'],
+      lints: ['@scope/a'],
+      tests: ['@scope/a'],
+      validates: 1,
+    });
+    expect(outcome.publishRan).toBe(true);
+    expect(outcome.publishCompletedTags).toEqual([]);
+    expect(outcome.remainingDurableGaps).toEqual([
+      '@scope/a@1.1.0:github',
+      '@scope/a@1.1.0:npm',
+      '@scope/a@1.2.0:github',
+      '@scope/a@1.2.0:npm',
+    ]);
+  });
+});
+
+interface ReleaseGap {
+  tag: string;
+  npmMissing: boolean;
+  githubMissing: boolean;
+}
+
+interface WorkflowScenarioConfig {
+  repoName?: string;
+  repairs: ReleaseGap[];
+  current: ReleaseGap[];
+  bump: PublishWorkflowBump;
+  dryRun: boolean;
+  version: PublishWorkflowVersionOutputs;
+}
+
+interface WorkflowOutcome {
+  fixtureRepoSetup: boolean;
+  releaseAuthorConfigured: boolean;
+  selfHostedCliBuilt: boolean;
+  repairSawSelfHostedCli: boolean;
+  versionSawSelfHostedCli: boolean;
+  repairedTags: string[];
+  repairBuildArtifacts: string[];
+  validation: { checks: number; builds: string[]; lints: string[]; tests: string[]; validates: number };
+  publishRan: boolean;
+  publishSawValidatedRelease: boolean;
+  publishCompletedTags: string[];
+  remainingDurableGaps: string[];
+}
+
+function publishWorkflowScenario(config: WorkflowScenarioConfig): { run(): Promise<WorkflowOutcome> } {
+  return {
+    async run() {
+      const state = new WorkflowScenarioState(config);
+      await runPublishWorkflow(definePublishWorkflow({ repoName: config.repoName }), {
+        inputs: { bump: config.bump, dryRun: config.dryRun },
+        nodeAuthToken: true,
+        callbacks: state.callbacks(),
+      });
+      return state.outcome();
+    },
+  };
+}
+
+class WorkflowScenarioState {
+  private fixtureSetup = false;
+  private authorConfigured = false;
+  private selfHostedCli = false;
+  private repairObservedSelfHostedCli = false;
+  private versionObservedSelfHostedCli = false;
+  private publishReleaseRan = false;
+  private publishSawValidation = false;
+  private readonly repaired = new Set<string>();
+  private readonly repairBuilds = new Set<string>();
+  private readonly publishedCurrent = new Set<string>();
+  private readonly durableGaps = new Set<string>();
+  private readonly validationState = {
+    checks: 0,
+    builds: [] as string[],
+    lints: [] as string[],
+    tests: [] as string[],
+    validates: 0,
+  };
+
+  constructor(private readonly config: WorkflowScenarioConfig) {
+    for (const gap of [...config.repairs, ...config.current]) {
+      if (gap.githubMissing) {
+        this.durableGaps.add(`${gap.tag}:github`);
+      }
+      if (gap.npmMissing) {
+        this.durableGaps.add(`${gap.tag}:npm`);
+      }
+    }
+  }
+
+  callbacks(): PublishWorkflowCallbacks {
+    return {
+      checkout: async () => {},
+      setupDevenv: async () => {
+        this.fixtureSetup = true;
+        return { nixCacheHit: 'false', devenvCacheHit: 'false' };
+      },
+      configureReleaseAuthor: async () => {
+        this.authorConfigured = true;
+      },
+      buildSelfHostedCli: async () => {
+        this.selfHostedCli = true;
+      },
+      repairPendingReleases: async ({ dryRun }) => {
+        this.repairObservedSelfHostedCli = this.selfHostedCli;
+        if (dryRun) {
+          return;
+        }
+        for (const gap of this.config.repairs) {
+          if (gap.npmMissing) {
+            this.repairBuilds.add(packageNameFromTag(gap.tag));
+            this.durableGaps.delete(`${gap.tag}:npm`);
+          }
+          if (gap.githubMissing) {
+            this.durableGaps.delete(`${gap.tag}:github`);
+          }
+          this.repaired.add(gap.tag);
+        }
+      },
+      versionRelease: async ({ bump, dryRun }) => {
+        this.versionObservedSelfHostedCli = this.selfHostedCli;
+        expect(bump).toBe(this.config.bump);
+        expect(dryRun).toBe(this.config.dryRun);
+        return this.config.version;
+      },
+      checkManagedMonorepoFiles: async () => {
+        this.validationState.checks += 1;
+      },
+      nxRunMany: async ({ target, projects }) => {
+        this.validationProjects(target).push(...projects);
+      },
+      uploadTraceDbs: async () => {},
+      validateMonorepoConfig: async () => {
+        this.validationState.validates += 1;
+      },
+      publishRelease: async ({ bump, dryRun }) => {
+        expect(bump).toBe(this.config.bump);
+        expect(dryRun).toBe(this.config.dryRun);
+        this.publishReleaseRan = true;
+        this.publishSawValidation = this.config.version.mode === 'none' || this.validationState.validates > 0;
+        if (dryRun) {
+          return;
+        }
+        for (const gap of this.config.current) {
+          if (gap.npmMissing) {
+            this.durableGaps.delete(`${gap.tag}:npm`);
+          }
+          if (gap.githubMissing) {
+            this.durableGaps.delete(`${gap.tag}:github`);
+          }
+          if (gap.npmMissing || gap.githubMissing) {
+            this.publishedCurrent.add(gap.tag);
+          }
+        }
+      },
+      saveNixDevenv: async () => {},
+    };
+  }
+
+  outcome(): WorkflowOutcome {
+    return {
+      fixtureRepoSetup: this.fixtureSetup,
+      releaseAuthorConfigured: this.authorConfigured,
+      selfHostedCliBuilt: this.selfHostedCli,
+      repairSawSelfHostedCli: this.repairObservedSelfHostedCli,
+      versionSawSelfHostedCli: this.versionObservedSelfHostedCli,
+      repairedTags: [...this.repaired].sort(),
+      repairBuildArtifacts: [...this.repairBuilds].sort(),
+      validation: {
+        checks: this.validationState.checks,
+        builds: [...this.validationState.builds],
+        lints: [...this.validationState.lints],
+        tests: [...this.validationState.tests],
+        validates: this.validationState.validates,
+      },
+      publishRan: this.publishReleaseRan,
+      publishSawValidatedRelease: this.publishSawValidation,
+      publishCompletedTags: [...this.publishedCurrent].sort(),
+      remainingDurableGaps: [...this.durableGaps].sort(),
+    };
+  }
+
+  private validationProjects(target: PublishWorkflowNxTarget): string[] {
+    if (target === 'build') {
+      return this.validationState.builds;
+    }
+    if (target === 'lint') {
+      return this.validationState.lints;
+    }
+    return this.validationState.tests;
+  }
+}
+
+function packageNameFromTag(tag: string): string {
+  const versionSeparator = tag.lastIndexOf('@');
+  if (versionSeparator <= 0) {
+    throw new Error(`Invalid release tag fixture ${tag}.`);
+  }
+  return tag.slice(0, versionSeparator);
+}

package/src/monorepo/index.ts

@@ -1,5 +1,7 @@
-import { readFileSync } from 'node:fs';
-import { listPublicPackages } from '../lib/workspace.js';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { $ } from 'bun';
+import { decode } from '../lib/run.js';
+import { escapeRegex, getWorkspacePatterns, listReleasePackages } from '../lib/workspace.js';
 import { validateCommitMessage } from './commit-msg.js';
 import { applyWorkspaceGitConfig } from './git-config.js';
 import { syncBunLockfileVersions } from './lockfile.js';
@@ -15,6 +17,12 @@ export interface InitOptions {
 
 export interface ValidateOptions {
   failFast?: boolean;
+  onlyIfNewWorkspacePackage?: boolean;
+}
+
+export interface ListReleasePackagesOptions {
+  failEmpty?: boolean;
+  githubOutput?: string;
 }
 
 export async function initMonorepo(root: string, options: InitOptions): Promise<void> {
@@ -28,9 +36,13 @@ export async function initMonorepo(root: string, options: InitOptions): Promise<
 }
 
 export async function validateMonorepo(root: string, options: ValidateOptions = {}): Promise<void> {
+  if (options.onlyIfNewWorkspacePackage && !(await hasNewWorkspacePackage(root))) {
+    return;
+  }
   const failures = await runValidatePacks({ root, syncRuntime: false }, options);
   if (failures > 0) {
-    throw new Error(`Monorepo validation failed with ${failures} problem(s).`);
+    const noun = failures === 1 ? 'problem' : 'problems';
+    throw new Error(`\n== summary ==\n❌ Monorepo validation failed with ${failures} ${noun}.`);
   }
   console.log('\n== summary ==');
   console.log('Monorepo configuration is valid.');
@@ -63,10 +75,17 @@ export function validateCommitMessageFile(path: string | undefined): void {
   }
 }
 
-export function listPublicProjects(root: string): string {
-  return listPublicPackages(root)
+export function listReleasePackagesForNx(root: string, options: ListReleasePackagesOptions = {}): string {
+  const packages = listReleasePackages(root)
     .map((pkg) => pkg.name)
     .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 {
@@ -76,3 +95,24 @@ export function validatePublicPackageTags(root: string): void {
 }
 
 export { applyWorkspaceGitConfig, syncBunLockfileVersions };
+
+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)));
+}