@smoothbricks/cli 0.10.3 → 0.10.5

package/src/lib/workspace.ts

@@ -1,7 +1,16 @@
 import { readdirSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { isSmoothBricksCodebasePackageName } from './cli-package.js';
-import { hasOwn, hasOwnString, isRecord, readJson, readJsonObject, stringProperty } from './json.js';
+import {
+  isPackageJson,
+  type PackageJson,
+  type PackageNxConfig,
+  type PackageRepository,
+  readJson,
+  readJsonObject,
+} from './json.js';
+
+export type { PackageJson, PackageNxConfig, PackageRepository };
 
 export interface PackageInfo {
   name: string;
@@ -11,7 +20,7 @@ export interface PackageInfo {
   tags: string[];
   path: string;
   packageJsonPath: string;
-  json: Record<string, unknown>;
+  json: PackageJson;
 }
 
 export interface WorkspacePackageManifest {
@@ -20,18 +29,7 @@ export interface WorkspacePackageManifest {
   private: boolean;
   path: string;
   packageJsonPath: string;
-  json: Record<string, unknown>;
-}
-
-export interface PackageJson extends Record<string, unknown> {
-  name?: string;
-  version?: string;
-  private?: boolean;
-  workspaces?: unknown;
-  devDependencies?: unknown;
-  dependencies?: unknown;
-  nx?: unknown;
-  repository?: unknown;
+  json: PackageJson;
 }
 
 export interface RepositoryInfo {
@@ -46,6 +44,8 @@ export const workspaceDependencyFields = [
   'optionalDependencies',
 ] as const;
 
+export type WorkspaceDependencyField = (typeof workspaceDependencyFields)[number];
+
 export function listPublicPackages(root: string): PackageInfo[] {
   return getWorkspacePackages(root).filter((pkg) => !pkg.private && pkg.tags.includes('npm:public'));
 }
@@ -54,26 +54,21 @@ export function listReleasePackages(
   root: string,
   rootPackage = readPackageJson(join(root, 'package.json')),
 ): PackageInfo[] {
-  if (!rootPackage) {
-    return [];
-  }
-  const rootRepository = repositoryInfo(rootPackage.json);
+  const rootRepository = rootPackage ? repositoryInfo(rootPackage.json) : null;
   if (!rootRepository) {
     return [];
   }
-  return getWorkspacePackagesForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage.json)).filter(
-    (pkg) => !pkg.private && pkg.tags.includes('npm:public') && isOwnedPackage(rootRepository, pkg),
-  );
+  return listPublicPackages(root).filter((pkg) => isOwnedPackage(rootRepository, pkg));
 }
 
 export function rootRepositoryInfo(root: string): RepositoryInfo | null {
-  const rootPackage = readJsonObject(join(root, 'package.json'));
-  return rootPackage ? repositoryInfo(rootPackage) : null;
+  const rootPackage = readPackageJson(join(root, 'package.json'));
+  return rootPackage ? repositoryInfo(rootPackage.json) : null;
 }
 
 export function rootPackageName(root: string): string | null {
   const rootPackage = readPackageJsonObject(join(root, 'package.json'));
-  return rootPackage ? stringProperty(rootPackage, 'name') : null;
+  return rootPackage?.name ?? null;
 }
 
 export function isSmoothBricksCodebase(root: string): boolean {
@@ -90,37 +85,23 @@ export function isOwnedPackage(rootRepository: RepositoryInfo, pkg: PackageInfo)
 }
 
 export function getWorkspacePackages(root: string): PackageInfo[] {
-  const rootPackage = readPackageJson(join(root, 'package.json'));
-  if (!rootPackage) {
-    throw new Error('package.json not found or invalid');
-  }
-  return getWorkspacePackagesForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage.json));
+  return getWorkspacePackagesForPatterns(root, getWorkspacePatterns(root));
 }
 
 export function getWorkspacePackageManifests(root: string): WorkspacePackageManifest[] {
-  const rootPackage = readPackageJsonObject(join(root, 'package.json'));
-  if (!rootPackage) {
-    throw new Error('package.json not found or invalid');
-  }
-  return getWorkspacePackageManifestsForPatterns(root, getWorkspacePatternsFromPackageJson(rootPackage));
+  return getWorkspacePackageManifestsForPatterns(root, getWorkspacePatterns(root));
 }
 
 function getWorkspacePackagesForPatterns(root: string, workspacePatterns: string[]): PackageInfo[] {
   const packages: PackageInfo[] = [];
-  for (const pkgPath of listWorkspacePackageJsonPaths(root, workspacePatterns)) {
-    const pkg = readPackageJson(pkgPath);
-    if (!pkg?.name || !pkg.version) {
+  for (const path of listWorkspacePackageJsonPaths(root, workspacePatterns)) {
+    const pkg = readPackageJson(path);
+    if (!pkg) {
       continue;
     }
     packages.push({
-      name: pkg.name,
-      projectName: pkg.projectName,
-      version: pkg.version,
-      private: pkg.private,
-      tags: pkg.tags,
-      path: relative(root, dirname(pkgPath)),
-      packageJsonPath: pkg.packageJsonPath,
-      json: pkg.json,
+      ...pkg,
+      path: relative(root, dirname(path)),
     });
   }
   return packages.sort((a, b) => a.name.localeCompare(b.name));
@@ -130,30 +111,42 @@ function getWorkspacePackageManifestsForPatterns(
   root: string,
   workspacePatterns: string[],
 ): WorkspacePackageManifest[] {
-  const manifests: WorkspacePackageManifest[] = [];
-  for (const pkgPath of listWorkspacePackageJsonPaths(root, workspacePatterns)) {
-    const pkg = readWorkspacePackageManifest(pkgPath);
-    if (pkg) {
-      manifests.push(pkg);
+  const packages: WorkspacePackageManifest[] = [];
+  for (const path of listWorkspacePackageJsonPaths(root, workspacePatterns)) {
+    const pkg = readWorkspacePackageManifest(path);
+    if (!pkg) {
+      continue;
     }
+    packages.push({
+      ...pkg,
+      path: relative(root, dirname(path)),
+    });
   }
-  return manifests.sort((a, b) => a.name.localeCompare(b.name));
+  return packages.sort((a, b) => a.name.localeCompare(b.name));
 }
 
 function listWorkspacePackageJsonPaths(root: string, workspacePatterns: string[]): string[] {
   const paths: string[] = [];
   for (const pattern of workspacePatterns) {
     if (!pattern.endsWith('/*')) {
-      paths.push(join(root, pattern, 'package.json'));
       continue;
     }
-
     const parent = join(root, pattern.slice(0, -2));
-    if (!statSync(parent, { throwIfNoEntry: false })?.isDirectory()) {
+    let entries: string[];
+    try {
+      entries = readdirSync(parent);
+    } catch {
       continue;
     }
-    for (const entry of readdirSync(parent)) {
-      paths.push(join(parent, entry, 'package.json'));
+    for (const entry of entries) {
+      const packageJsonPath = join(parent, entry, 'package.json');
+      try {
+        if (statSync(packageJsonPath).isFile()) {
+          paths.push(packageJsonPath);
+        }
+      } catch {
+        // skip missing package.json
+      }
     }
   }
   return paths;
@@ -162,7 +155,7 @@ function listWorkspacePackageJsonPaths(root: string, workspacePatterns: string[]
 export function listPackageJsonRecords(root: string): PackageInfo[] {
   const rootPackage = readPackageJson(join(root, 'package.json'));
   if (!rootPackage) {
-    throw new Error('package.json not found or invalid');
+    return getWorkspacePackages(root);
   }
   return [
     { ...rootPackage, path: '.' },
@@ -172,18 +165,16 @@ export function listPackageJsonRecords(root: string): PackageInfo[] {
 
 export function getWorkspacePatterns(root: string): string[] {
   const raw = readJson(join(root, 'package.json'));
-  return isRecord(raw) ? getWorkspacePatternsFromPackageJson(raw) : ['packages/*'];
+  const pkg = isPackageJson(raw) ? raw : null;
+  return pkg ? getWorkspacePatternsFromPackageJson(pkg) : ['packages/*'];
 }
 
-function getWorkspacePatternsFromPackageJson(pkg: Record<string, unknown>): string[] {
-  if (!hasOwn(pkg, 'workspaces')) {
-    return ['packages/*'];
-  }
+function getWorkspacePatternsFromPackageJson(pkg: PackageJson): string[] {
   const workspaces = pkg.workspaces;
   if (Array.isArray(workspaces)) {
     return workspaces.filter((entry): entry is string => typeof entry === 'string');
   }
-  if (isRecord(workspaces) && hasOwn(workspaces, 'packages') && Array.isArray(workspaces.packages)) {
+  if (workspaces && typeof workspaces === 'object' && Array.isArray(workspaces.packages)) {
     return workspaces.packages.filter((entry): entry is string => typeof entry === 'string');
   }
   return ['packages/*'];
@@ -191,17 +182,15 @@ function getWorkspacePatternsFromPackageJson(pkg: Record<string, unknown>): stri
 
 export function readPackageJson(path: string): PackageInfo | null {
   const parsed = readPackageJsonObject(path);
-  if (!isRecord(parsed) || !hasOwnString(parsed, 'name') || !hasOwnString(parsed, 'version')) {
+  if (!parsed?.name || !parsed.version) {
     return null;
   }
-  const privateValue = hasOwn(parsed, 'private') && typeof parsed.private === 'boolean' ? parsed.private : false;
-  const tags = getNxTags(parsed);
   return {
     name: parsed.name,
     projectName: packageNxProjectName(parsed),
     version: parsed.version,
-    private: privateValue,
-    tags,
+    private: parsed.private === true,
+    tags: getNxTags(parsed),
     path: dirname(path),
     packageJsonPath: path,
     json: parsed,
@@ -210,50 +199,48 @@ export function readPackageJson(path: string): PackageInfo | null {
 
 export function readWorkspacePackageManifest(path: string): WorkspacePackageManifest | null {
   const parsed = readPackageJsonObject(path);
-  if (!isRecord(parsed) || !hasOwnString(parsed, 'name')) {
+  if (!parsed?.name) {
     return null;
   }
-  const privateValue = hasOwn(parsed, 'private') && typeof parsed.private === 'boolean' ? parsed.private : false;
   return {
     name: parsed.name,
     projectName: packageNxProjectName(parsed),
-    private: privateValue,
+    private: parsed.private === true,
     path: dirname(path),
     packageJsonPath: path,
     json: parsed,
   };
 }
 
-function packageNxProjectName(pkg: Record<string, unknown>): string {
-  const nx = isRecord(pkg.nx) ? pkg.nx : null;
-  return (nx ? stringProperty(nx, 'name') : null) ?? stringProperty(pkg, 'name') ?? '';
+function packageNxProjectName(pkg: PackageJson): string {
+  return pkg.nx?.name ?? pkg.name ?? '';
 }
 
 export function readPackageJsonObject(path: string): PackageJson | null {
-  const parsed = readJsonObject(path);
-  return parsed;
+  return readJsonObject(path);
 }
 
-export function getNxTags(pkg: Record<string, unknown>): string[] {
-  if (!hasOwn(pkg, 'nx') || !isRecord(pkg.nx) || !hasOwn(pkg.nx, 'tags') || !Array.isArray(pkg.nx.tags)) {
+export function getNxTags(pkg: PackageJson): string[] {
+  const tags = pkg.nx?.tags;
+  if (!Array.isArray(tags)) {
     return [];
   }
-  return pkg.nx.tags.filter((tag): tag is string => typeof tag === 'string');
+  return tags.filter((tag): tag is string => typeof tag === 'string');
 }
 
-export function repositoryInfo(pkg: Record<string, unknown>): RepositoryInfo | null {
+export function repositoryInfo(pkg: PackageJson): RepositoryInfo | null {
   const repository = pkg.repository;
   if (typeof repository === 'string') {
     return { type: 'git', url: repository };
   }
-  if (!isRecord(repository)) {
+  if (!repository || typeof repository !== 'object') {
     return null;
   }
-  const url = stringProperty(repository, 'url');
+  const url = repository.url;
   if (!url) {
     return null;
   }
-  return { type: stringProperty(repository, 'type') ?? 'git', url };
+  return { type: repository.type ?? 'git', url };
 }
 
 export function sameRepositoryAfterNormalization(left: string, right: string): boolean {
@@ -261,25 +248,26 @@ export function sameRepositoryAfterNormalization(left: string, right: string): b
 }
 
 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 trimmed = url.trim().replace(/\.git$/i, '');
+  const ssh = /^git@github\.com:(.+)$/i.exec(trimmed);
+  if (ssh?.[1]) {
+    const [owner, repo] = ssh[1].split('/');
+    if (owner && repo) {
+      return githubRepositoryKey(owner, repo);
+    }
   }
-  const shorthand = /^github:([^/]+)\/([^/]+)$/i.exec(trimmed);
-  if (shorthand?.[1] && shorthand[2]) {
-    return githubRepositoryKey(shorthand[1], shorthand[2]);
+  try {
+    const parsed = new URL(trimmed.includes('://') ? trimmed : `https://${trimmed}`);
+    if (parsed.hostname.replace(/^www\./i, '').toLowerCase() === 'github.com') {
+      const [owner, repo] = parsed.pathname.replace(/^\//, '').split('/');
+      if (owner && repo) {
+        return githubRepositoryKey(owner, repo);
+      }
+    }
+  } catch {
+    // fall through
   }
-  return trimmed;
+  return trimmed.toLowerCase();
 }
 
 function githubRepositoryKey(owner: string, repo: string): string {

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

@@ -17,14 +17,14 @@ describe('CI workflow definition', () => {
     const steps = defineCiWorkflow({ deploy: true, pushBranches: ['main'] });
     const rendered = renderCiWorkflowYaml({ deploy: true, pushBranches: ['main'] });
 
-    expect(steps.map((step) => [step.kind, step.number])).toContainEqual([CiWorkflowStepKind.Deploy, 9]);
+    expect(steps.map((step) => [step.kind, step.number])).toContainEqual([CiWorkflowStepKind.Deploy, 11]);
     expect(rendered).toContain('- name: 🚀 Deploy Staging');
     expect(rendered).not.toContain('CLOUDFLARE_API_TOKEN');
     expect(rendered).not.toContain('CLOUDFLARE_ACCOUNT_ID');
     expect(rendered).toContain(
-      'smoo github-ci nx-deploy --configuration staging --mode affected --name "Deploy Staging" --step 9',
+      'smoo github-ci nx-deploy --configuration staging --mode affected --name "Deploy Staging" --step 11',
     );
-    expect(rendered).toContain("# Step 10\n      # Nx's database cache needs artifact files");
+    expect(rendered).toContain("# Step 12\n      # Nx's database cache needs artifact files");
   });
 
   it('adds Cloudflare credentials for Wrangler-backed deploys', () => {

package/src/monorepo/ci-workflow.ts

@@ -8,6 +8,8 @@ export enum CiWorkflowStepKind {
   Build = 'build',
   Lint = 'lint',
   UnitTests = 'unit-tests',
+  ManagedFilesCheck = 'managed-files-check',
+  ManagedFilesDispatch = 'managed-files-dispatch',
   Deploy = 'deploy',
   SaveNxCache = 'save-nx-cache',
   UploadTraceDbs = 'upload-trace-dbs',
@@ -37,6 +39,8 @@ export function defineCiWorkflow(options: CiWorkflowDefinitionOptions): CiWorkfl
     { kind: CiWorkflowStepKind.Build, name: '🔨 Build' },
     { kind: CiWorkflowStepKind.Lint, name: '🔍 Lint' },
     { kind: CiWorkflowStepKind.UnitTests, name: '🧪 Unit Tests' },
+    { kind: CiWorkflowStepKind.ManagedFilesCheck, name: '🩺 Check managed-file drift' },
+    { kind: CiWorkflowStepKind.ManagedFilesDispatch, name: '🔁 Dispatch managed-file drift healing' },
   ];
   if (options.deploy) {
     steps.push({ kind: CiWorkflowStepKind.Deploy, name: '🚀 Deploy Staging' });
@@ -64,7 +68,8 @@ ${renderYamlList(options.pushBranches, 6)}
   pull_request:
 
 permissions:
-  actions: read
+  # actions:write lets the drift step dispatch the managed-files workflow.
+  actions: write
   contents: read
   statuses: write
 
@@ -161,6 +166,27 @@ function yamlLinesForStep(step: CiWorkflowStep, options: CiWorkflowDefinitionOpt
       return nxSmartStep(step, 'lint', 'Lint');
     case CiWorkflowStepKind.UnitTests:
       return nxSmartStep(step, 'test', 'Unit Tests');
+    case CiWorkflowStepKind.ManagedFilesCheck:
+      // The authoritative drift check is nearly free here (devenv is already
+      // up). --warn never fails the job and publishes the step output
+      // `drifted=<count>` for the dispatch step below.
+      return [
+        `      - name: ${step.name}`,
+        '        id: managed-drift',
+        '        if:',
+        "          ${{ github.event_name == 'push' && github.ref == format('refs/heads/{0}',",
+        '          github.event.repository.default_branch) }}',
+        '        run: smoo monorepo check --warn',
+      ];
+    case CiWorkflowStepKind.ManagedFilesDispatch:
+      // Dispatches the managed-files workflow, which maintains the persistent
+      // review PR. workflow_dispatch is exempt from GitHub's GITHUB_TOKEN
+      // recursion guard, so the default token suffices.
+      return [
+        `      - name: ${step.name}`,
+        "        if: ${{ steps.managed-drift.outputs.drifted != '' && steps.managed-drift.outputs.drifted != '0' }}",
+        '        run: gh workflow run managed-files.yml --ref "$GITHUB_REF_NAME"',
+      ];
     case CiWorkflowStepKind.Deploy:
       return [
         `      - name: ${step.name}`,

package/src/monorepo/git-config.ts

@@ -17,8 +17,8 @@ export async function applyWorkspaceGitConfig(root: string): Promise<void> {
   // Keep the newer runtime version pins on any merge (nvfetcher overlay +
   // devenv.lock) so a mirror sync's `git am --3way` never stalls on a version
   // conflict. Mapped by the managed .gitattributes (merge=smoo-newer-pins);
-  // implemented in tooling/direnv/merge-newer-pins.sh. The next `devenv shell`
-  // regenerates package.json fields from the resulting runtime.
+  // implemented in tooling/direnv/merge-newer-pins.sh. Runtime package.json
+  // pin repair is explicit via `smoo monorepo init --runtime-only`.
   await $`git config --local merge.smoo-newer-pins.name ${'keep the newer devenv/nvfetcher runtime pins'}`.cwd(root);
   await $`git config --local merge.smoo-newer-pins.driver ${'bash tooling/direnv/merge-newer-pins.sh %O %A %B %P'}`.cwd(
     root,

package/src/monorepo/index.ts

@@ -5,10 +5,11 @@ import { escapeRegex, getWorkspacePackages, getWorkspacePatterns, listReleasePac
 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 { applyManagedFiles, printResults, warnOnManagedFileDrift } from './managed-files.js';
 import { listValidCommitScopes, validatePublicTags } from './package-policy.js';
 import { runInitPacks, runValidatePacks } from './packs/index.js';
 import { syncRootRuntimeVersions } from './runtime.js';
+import { applyToolConfigDefaults } from './tool-validation.js';
 
 export interface InitOptions {
   runtimeOnly?: boolean;
@@ -74,11 +75,26 @@ export async function validateMonorepo(root: string, options: ValidateOptions =
   }
 }
 
-export function updateManagedFiles(root: string): void {
+export async function updateManagedFiles(root: string): Promise<void> {
   printResults(applyManagedFiles(root, 'update'));
+  // Tool dependency policy (typescript API 6, @typescript/native for ttsc, nx, …)
+  // lives next to managed templates — update must install them, not only rewrite files.
+  await applyToolConfigDefaults(root);
+  syncBunLockfileVersions(root, { mode: 'install' });
+  console.log('installing     workspace dependencies (bun install)');
+  const install = await $`bun install --no-summary`.cwd(root).nothrow();
+  if (install.exitCode !== 0) {
+    const stderr = decode(install.stderr).trim();
+    const stdout = decode(install.stdout).trim();
+    throw new Error(`bun install failed after monorepo update${stderr || stdout ? `:\n${stderr || stdout}` : ''}`);
+  }
 }
 
-export function checkManagedFiles(root: string): void {
+export function checkManagedFiles(root: string, options: { warn?: boolean } = {}): void {
+  if (options.warn === true) {
+    warnOnManagedFileDrift(root);
+    return;
+  }
   const results = applyManagedFiles(root, 'check');
   printResults(results);
   if (results.some((result) => result.action === 'drifted')) {

package/src/monorepo/lockfile.test.ts

@@ -17,15 +17,6 @@ function git(root: string, args: string): string {
   return execSync(`git ${args}`, {
     cwd: root,
     encoding: 'utf8',
-    env: {
-      ...process.env,
-      GIT_CONFIG_GLOBAL: '/dev/null',
-      GIT_CONFIG_SYSTEM: '/dev/null',
-      GIT_AUTHOR_NAME: 'fixture',
-      GIT_AUTHOR_EMAIL: 'fixture@invalid',
-      GIT_COMMITTER_NAME: 'fixture',
-      GIT_COMMITTER_EMAIL: 'fixture@invalid',
-    },
     stdio: ['pipe', 'pipe', 'pipe'],
   });
 }
@@ -40,6 +31,9 @@ function makeFixtureRepo(options: FixtureOptions): string {
   const root = mkdtempSync(join(tmpdir(), 'smoo-lockfile-'));
   cleanupRoots.push(root);
   git(root, 'init -q');
+  // Local identity only — CI runners have no global git user.
+  git(root, 'config user.name Test');
+  git(root, 'config user.email test@example.com');
   git(root, 'commit -q --allow-empty -m init');
   writeFileSync(
     join(root, 'package.json'),
@@ -56,8 +50,8 @@ function makeFixtureRepo(options: FixtureOptions): string {
 
 function writeFixturePackage(root: string, version: string): void {
   writeFileSync(
-    join(root, 'packages', 'foo', 'package.json'),
-    JSON.stringify({ name: '@fixture/foo', version, nx: { name: 'foo' } }),
+    join(root, 'packages/foo/package.json'),
+    `${JSON.stringify({ name: '@fixture/foo', version, private: false, nx: { name: 'foo' } }, null, 2)}\n`,
   );
 }
 
@@ -71,9 +65,9 @@ function writeFixtureLock(root: string, version: string): void {
       '    "": { "name": "fixture-root" },',
       '    "packages/foo": {',
       '      "name": "@fixture/foo",',
-      `      "version": "${version}",`,
-      '    },',
-      '  },',
+      `      "version": "${version}"`,
+      '    }',
+      '  }',
       '}',
       '',
     ].join('\n'),
@@ -87,59 +81,64 @@ function lockVersionIn(root: string): string {
 }
 
 describe('bun.lock workspace version sync', () => {
-  it('a bun-install revert of the release-synced version fails validation', () => {
-    // The b3298fc4c shape: package.json holds the next prerelease, a stable tag
-    // exists, and `bun install` rewrote the lockfile back to the prerelease.
+  it('install validate requires lockfile ≡ package.json including -next', () => {
     const root = makeFixtureRepo({
       packageVersion: '0.1.3-next.0',
-      lockVersion: '0.1.3-next.0',
+      lockVersion: '0.1.2',
       stableTag: 'foo@0.1.2',
     });
     expect(validateBunLockfileVersions(root)).toBe(1);
   });
 
-  it('sync restores the latest stable tag version and validation passes', () => {
+  it('install mode sync restores package.json -next for frozen CI', () => {
+    const root = makeFixtureRepo({
+      packageVersion: '0.1.3-next.0',
+      lockVersion: '0.1.2',
+      stableTag: 'foo@0.1.2',
+    });
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'install' })).toBe(1);
+    expect(lockVersionIn(root)).toBe('0.1.3-next.0');
+    expect(validateBunLockfileVersions(root)).toBe(0);
+  });
+
+  it('publish mode rewrites unpublished -next to last stable tag for pack', () => {
     const root = makeFixtureRepo({
       packageVersion: '0.1.3-next.0',
       lockVersion: '0.1.3-next.0',
       stableTag: 'foo@0.1.2',
     });
-    expect(syncBunLockfileVersions(root, { log: false })).toBe(1);
-    expect(lockVersionIn(root)).toBe('0.1.2');
+    // Install/CI is happy with -next matching package.json.
     expect(validateBunLockfileVersions(root)).toBe(0);
+    // Pre-publish rewrite embeds last stable for bun pm pack.
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'publish' })).toBe(1);
+    expect(lockVersionIn(root)).toBe('0.1.2');
   });
 
-  it('a never-published prerelease package falls back to its manifest version', () => {
-    // The new-workspace-package shape (e.g. cowshed): no stable tag exists yet.
+  it('never-published prerelease keeps package.json version in both modes', () => {
     const root = makeFixtureRepo({ packageVersion: '0.2.0-next.0', lockVersion: '0.2.0-next.0' });
     expect(validateBunLockfileVersions(root)).toBe(0);
-    expect(syncBunLockfileVersions(root, { log: false })).toBe(0);
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'install' })).toBe(0);
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'publish' })).toBe(0);
   });
 
-  it('a stable manifest version is required verbatim in the lockfile', () => {
+  it('stable manifest version is required verbatim', () => {
     const root = makeFixtureRepo({ packageVersion: '0.1.0', lockVersion: '0.0.9' });
     expect(validateBunLockfileVersions(root)).toBe(1);
-    expect(syncBunLockfileVersions(root, { log: false })).toBe(1);
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'install' })).toBe(1);
     expect(lockVersionIn(root)).toBe('0.1.0');
   });
 
   it('stage: true stages the healed bun.lock', () => {
     const root = makeFixtureRepo({
       packageVersion: '0.1.3-next.0',
-      lockVersion: '0.1.3-next.0',
+      lockVersion: '0.1.2',
       stableTag: 'foo@0.1.2',
     });
-    expect(syncBunLockfileVersions(root, { log: false, stage: true })).toBe(1);
+    expect(syncBunLockfileVersions(root, { log: false, mode: 'install', stage: true })).toBe(1);
     expect(git(root, 'diff --cached --name-only')).toContain('bun.lock');
   });
 
-  it('stage: true leaves a clean lockfile unstaged', () => {
-    const root = makeFixtureRepo({ packageVersion: '0.1.2', lockVersion: '0.1.2', stableTag: 'foo@0.1.2' });
-    expect(syncBunLockfileVersions(root, { log: false, stage: true })).toBe(0);
-    expect(git(root, 'diff --cached --name-only').trim()).toBe('');
-  });
-
-  it('property: after sync, validation always passes', () => {
+  it('property: after install-mode sync, validation always passes', () => {
     const version = fc
       .tuple(fc.nat({ max: 20 }), fc.nat({ max: 20 }), fc.nat({ max: 20 }), fc.option(fc.nat({ max: 5 })))
       .map(([major, minor, patch, next]) => `${major}.${minor}.${patch}${next === null ? '' : `-next.${next}`}`);
@@ -148,7 +147,7 @@ describe('bun.lock workspace version sync', () => {
       fc.property(version, version, (packageVersion, lockVersion) => {
         writeFixturePackage(root, packageVersion);
         writeFixtureLock(root, lockVersion);
-        syncBunLockfileVersions(root, { log: false });
+        syncBunLockfileVersions(root, { log: false, mode: 'install' });
         return validateBunLockfileVersions(root) === 0;
       }),
       { numRuns: 25 },