@dbx-tools/projen 0.9.173 → 0.9.175

package/README.md

@@ -669,6 +669,24 @@ whole-tree operation driven by the root `.projenrc.ts`, so a member-level run
 re-synths the entire workspace from the member's directory. Run `bun run sync`
 from the root instead.
 
+## Commit a registry-neutral lockfile
+
+The root `bun.lock` is committed, and generated CI installs run
+`bun install --frozen-lockfile`. A private npm mirror would otherwise appear in
+every resolved tarball URL, so the generated `bun-lockfile` task runs after each
+root install and as the root `postinstall` script, which also covers `bun add`,
+`bun remove`, and `bun update`. It detects the active registry from the same
+environment, `.npmrc`, `bunfig.toml`, and pnpm configuration a package manager
+reads. When that registry is not public npm, it rewrites every tarball URL under
+it and leaves all other URLs unchanged. Bun 1.4.2 has no native setting that
+omits registry URLs from `bun.lock`.
+
+The default replacement is an empty tarball field, which Bun resolves through
+the installing machine's registry; integrity hashes still pin the content.
+Run `bun run bun-lockfile -- --check` to confirm a lockfile is clean without
+writing it. Options can also come from `PROJEN_BUN_LOCKFILE_*` environment
+variables or `.env`.
+
 ## Manage workspace versions
 
 `VERSION` is the language-neutral version seam. Real package manifests remain

package/index.ts

@@ -3,10 +3,11 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
-export const PACKAGE_VERSION = "0.9.173";
+export const PACKAGE_VERSION = "0.9.175";
 export * as appkitWorkspace from "./src/appkit-workspace.ts";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
+export * as bunLockfile from "./src/bun-lockfile.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
 export * as clean from "./src/clean.ts";
 export * as codegen from "./src/codegen.ts";
@@ -48,6 +49,8 @@ export type { AppKitWorkspaceMode, AppKitBundleOptions, AppKitWorkspaceOptions }
 export { isGeneratedBarrel, folderBarrelFile, generateBarrels } from "./src/barrels.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
 export type { BunBuildFileOptions } from "./src/bun-app.ts";
+export { BUN_LOCKFILE, BunLockfileReplacementSchema, BunLockfileOptionsSchema, bunLockfileRegistries, normalizeBunLockfile, normalizeBunLockfileAt } from "./src/bun-lockfile.ts";
+export type { BunLockfileOptions, BunLockfileOptionsInput, NormalizedBunLockfile, BunLockfileNormalization } from "./src/bun-lockfile.ts";
 export { BUN_VERSION, MINIMUM_BUN_VERSION, BUN_VERSION_CHECK_SCRIPT } from "./src/bun-workflow.ts";
 export { listGeneratedFiles, listNodeModulesDirs, removePaths } from "./src/clean.ts";
 export { codegenModulePaths, generateCodegen } from "./src/codegen.ts";
@@ -68,7 +71,7 @@ export { resolveRepoRoot, repoRoot, DEFAULT_PACKAGE_ROOTS, projectName, toPosix,
 export type { RecordedPackage } from "./src/packages.ts";
 export { PnpmWorkspaceState } from "./src/pnpm-workspace.ts";
 export type { Catalog, AllowBuilds, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace.ts";
-export { PackageIdentifier, identifier, applyCompilerOptions, applyIncludes, applyExports, addExports, addOptionalPeer, projectRepositoryUrl, projectReleaseBranch, addPackageFiles, srcFolderExports, LICENSE, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject, taskCommand } from "./src/project-js.ts";
+export { PackageIdentifier, identifier, applyCompilerOptions, applyIncludes, applyExports, addExports, addOptionalPeer, projectRepositoryUrl, projectReleaseBranch, addPackageFiles, srcFolderExports, LICENSE, BUN_LOCKFILE_TASK, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject, taskCommand } from "./src/project-js.ts";
 export type { DBXToolsJavaScriptProject, DBXToolsReleaseMode, DiscoveredTypeScriptPackageOptions, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
 export { isProject, isDBXToolsProject, isDBXToolsJavaScriptProject, hasName, hasIdentifierPackageName, hasIdentifierName, hasIdentifierScope, hasTag, hasPath } from "./src/project-predicate.ts";
 export { pythonPackagePath, pythonModuleName, DBXToolsPythonProject, DBXToolsPythonWorkspace } from "./src/project-py.ts";

package/package.json

@@ -30,11 +30,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/auth": "^0.9.173",
-    "@dbx-tools/cli-args": "^0.9.173",
-    "@dbx-tools/core": "^0.9.173",
-    "@dbx-tools/path": "^0.9.173",
-    "@dbx-tools/shared-core": "^0.9.173",
+    "@dbx-tools/auth": "^0.9.175",
+    "@dbx-tools/cli-args": "^0.9.175",
+    "@dbx-tools/core": "^0.9.175",
+    "@dbx-tools/path": "^0.9.175",
+    "@dbx-tools/shared-core": "^0.9.175",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -56,7 +56,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.173",
+  "version": "0.9.175",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/bun-lockfile.ts

@@ -0,0 +1,161 @@
+/**
+ * Registry-neutral Bun text lockfiles.
+ *
+ * Bun records each package's resolved tarball URL in `bun.lock`. When the
+ * installing machine's npm registry is a private mirror, every URL names that
+ * mirror, so a committed lockfile would leak it and fail on machines that cannot
+ * reach it. Normalization detects the active registry the same way a package
+ * manager does and, when it is not public npm, rewrites every tarball URL under
+ * it in bulk. All other URLs are left as they are.
+ *
+ * Bun accepts both replacement forms under `--frozen-lockfile`: an empty tarball
+ * field resolves through whichever registry the installing machine configures,
+ * and a public npm URL pins npmjs explicitly. Integrity hashes are unchanged, so
+ * frozen installs still verify the exact tarball content.
+ *
+ * Bun has no native setting for this as of 1.4.2: `[install.lockfile]` only
+ * supports `save` and `print`, and Bun's own `BunLockFile` type marks the npm
+ * registry field "TODO: remove if default". Replace this rewrite with that
+ * native behavior once Bun ships it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { npmRegistry } from "@dbx-tools/core";
+import { z } from "zod";
+
+/** Bun's text lockfile at a workspace root. */
+export const BUN_LOCKFILE = "bun.lock";
+
+/** Public npm registry used by the `npmjs` replacement. */
+const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org";
+
+/** Registry tarball entry: `"key": ["name@version", "<tarball>", ...`. */
+const TARBALL_ENTRY =
+  /^(\s+"[^"\n]+": \[")((?:@[^/"\n]+\/)?[^@"\n]+)@([^"\n]+)(", )"(https?:\/\/[^"\n]*)"/gm;
+
+/** How private registry tarball URLs are rewritten. */
+export const BunLockfileReplacementSchema = z
+  .enum(["empty", "npmjs"])
+  .describe(
+    "Replacement for private registry tarball URLs: empty resolves through the installing machine's registry; npmjs pins public npm",
+  );
+
+/** Options that control `bun.lock` normalization. */
+export const BunLockfileOptionsSchema = z
+  .object({
+    mode: z
+      .enum(["auto", "off"])
+      .default("auto")
+      .describe(
+        "auto rewrites tarball URLs under the detected npm registry when it is not public npm; off leaves the lockfile unchanged",
+      ),
+    replacement: BunLockfileReplacementSchema.default("empty"),
+    registries: z
+      .array(z.string().trim().url())
+      .default([])
+      .describe("Additional registry URLs whose tarball URLs are rewritten"),
+    check: z
+      .boolean()
+      .default(false)
+      .describe("Fail instead of writing when the lockfile is not normalized"),
+  })
+  .describe("Keep bun.lock free of private npm registry URLs");
+
+/** Parsed {@link BunLockfileOptionsSchema}. */
+export type BunLockfileOptions = z.output<typeof BunLockfileOptionsSchema>;
+
+/** Accepted input for {@link BunLockfileOptionsSchema}. */
+export type BunLockfileOptionsInput = z.input<typeof BunLockfileOptionsSchema>;
+
+/** Result of normalizing one lockfile body. */
+export interface NormalizedBunLockfile {
+  /** Lockfile text with private registry tarball URLs rewritten. */
+  readonly content: string;
+  /** Number of tarball URLs rewritten. */
+  readonly rewritten: number;
+  /** Registry prefixes that were rewritten. */
+  readonly registries: readonly string[];
+}
+
+/** URL origin plus path prefix of a registry, without a trailing slash. */
+function registryPrefix(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Registry URLs to rewrite for `cwd`.
+ *
+ * `auto` adds the active npm registry only when it is not public npm, so a
+ * machine on npmjs leaves the lockfile untouched.
+ */
+export function bunLockfileRegistries(
+  cwd: string,
+  options: Pick<BunLockfileOptions, "mode" | "registries">,
+): string[] {
+  if (options.mode === "off") return [];
+  const detected = npmRegistry(cwd, { overrideOnly: true })?.href;
+  return [...(detected ? [detected] : []), ...options.registries];
+}
+
+/** Public npm tarball URL for one package version. */
+function npmjsTarball(name: string, version: string): string {
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  return `${PUBLIC_NPM_REGISTRY}/${name}/-/${base}-${version}.tgz`;
+}
+
+/** Rewrite tarball URLs under any of `registries`; leave every other URL as is. */
+export function normalizeBunLockfile(
+  content: string,
+  registries: readonly string[],
+  replacement: z.output<typeof BunLockfileReplacementSchema> = "empty",
+): NormalizedBunLockfile {
+  const prefixes = [...new Set(registries.flatMap((registry) => registryPrefix(registry) ?? []))];
+  if (prefixes.length === 0) return { content, rewritten: 0, registries: prefixes };
+  let rewritten = 0;
+  const normalized = content.replace(
+    TARBALL_ENTRY,
+    (entry, head: string, name: string, version: string, separator: string, url: string) => {
+      if (!prefixes.some((prefix) => url.startsWith(`${prefix}/`))) return entry;
+      rewritten += 1;
+      const tarball = replacement === "npmjs" ? npmjsTarball(name, version) : "";
+      return `${head}${name}@${version}${separator}"${tarball}"`;
+    },
+  );
+  return { content: normalized, rewritten, registries: prefixes };
+}
+
+/** Outcome of {@link normalizeBunLockfileAt}. */
+export interface BunLockfileNormalization extends NormalizedBunLockfile {
+  /** Absolute lockfile path. */
+  readonly path: string;
+  /** Whether the lockfile exists. */
+  readonly exists: boolean;
+  /** Whether the file content differs from its normalized form. */
+  readonly changed: boolean;
+}
+
+/** Normalize `bun.lock` in `root`, writing it unless `check` is set. */
+export function normalizeBunLockfileAt(
+  root: string,
+  input: BunLockfileOptionsInput = {},
+): BunLockfileNormalization {
+  const options = BunLockfileOptionsSchema.parse(input);
+  const path = join(root, BUN_LOCKFILE);
+  if (!existsSync(path)) {
+    return { path, exists: false, changed: false, content: "", rewritten: 0, registries: [] };
+  }
+  const original = readFileSync(path, "utf8");
+  const result = normalizeBunLockfile(
+    original,
+    bunLockfileRegistries(root, options),
+    options.replacement,
+  );
+  const changed = result.content !== original;
+  if (changed && !options.check) writeFileSync(path, result.content);
+  return { ...result, path, exists: true, changed };
+}

package/src/project-js.ts

@@ -32,6 +32,7 @@ import {
 import { folderBarrelFile, generateBarrels } from "./barrels.ts";
 
 import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
+import { BUN_LOCKFILE } from "./bun-lockfile.ts";
 import { BUN_VERSION, BUN_VERSION_CHECK_SCRIPT, MINIMUM_BUN_VERSION } from "./bun-workflow.ts";
 import { codegenModulePaths, generateCodegen } from "./codegen.ts";
 import { DBXToolsConfig, type DBXToolsConfigOptions } from "./dbx-tools-config.ts";
@@ -527,6 +528,33 @@ const DEV_DEPS_ROOT: string[] = [
   "@types/node@^24.6.0",
 ];
 
+/** Root task that clears registry tarball URLs from `bun.lock`. */
+export const BUN_LOCKFILE_TASK = "bun-lockfile";
+
+/**
+ * Commit `bun.lock` without leaking the installing machine's registry.
+ *
+ * Bun writes each resolved tarball URL into the lockfile. The generated
+ * `bun-lockfile` task detects the active npm registry (resolved like a package
+ * manager does, never hard-coded) and, when it is not public npm, rewrites every
+ * tarball URL under it; all other URLs stay as they are. It runs after every
+ * root install and as the root `postinstall` script, so `bun add`, `bun remove`,
+ * and `bun update` normalize too. CI installs with `--frozen-lockfile`.
+ */
+function configureRootLockfile(project: DBXToolsJavaScriptProject): void {
+  const normalize = taskCommand(`${BUN_LOCKFILE_TASK}.ts`);
+  const task = project.addTask(BUN_LOCKFILE_TASK, {
+    description: "Rewrite private npm registry tarball URLs in bun.lock",
+    execArgs: normalize,
+    receiveArgs: true,
+  });
+  project.package.installTask.reset("bun install");
+  project.package.installTask.spawn(task);
+  project.package.installCiTask.reset(project.package.installCommand);
+  project.package.setScript("postinstall", normalize.join(" "));
+  project.annotateGenerated(`/${BUN_LOCKFILE}`);
+}
+
 function configureRootBunRuntime(project: DBXToolsJavaScriptProject): void {
   new TextFile(project, BUN_VERSION_CHECK_SCRIPT, {
     lines: dedent(// ============================================================================
@@ -1330,9 +1358,7 @@ function initProject(
   if (selfDep) project.addDevDeps(selfDep);
   project.addDevDeps(...DEV_DEPS_ROOT);
   configureRootPackage(project);
-  // Workspaces generated by this engine intentionally do not track local-registry
-  // lockfiles, so the CI-named install task must resolve from manifests as well.
-  project.package.installCiTask.reset("bun install");
+  configureRootLockfile(project);
   configureRootBunRuntime(project);
   const roots =
     options.packageRoots ??
@@ -1367,6 +1393,9 @@ function initProject(
   project.gitignore.addPatterns(
     ...[...ignore.ignorePatterns({ test: false, dot: false, lock: true })],
   );
+  // The root Bun text lockfile is committed in registry-neutral form; see
+  // configureRootLockfile. Other lockfiles stay ignored.
+  project.gitignore.include(`/${BUN_LOCKFILE}`);
   // The generic compiled-output pattern `**/lib/**` must not hide authored
   // modules beneath a package's `src/lib/`.
   project.gitignore.include("**/src/lib/**");

package/src/release.ts

@@ -118,36 +118,57 @@ export function uvSetupStep(): JobStep {
   };
 }
 
-function refreshDocsRegistryDependencies(workflow: GithubWorkflow): void {
-  const docs = workflow.getJob("deploy-docs") as Job | undefined;
-  if (!docs) return;
-  if (workflow.getJob(PUBLICATION_VERIFIER_JOB)) {
-    workflow.updateJob("deploy-docs", {
+const DOCS_JOB = "deploy-docs";
+
+function publicationRegistryJobs(workflow: GithubWorkflow): string[] {
+  return Object.keys(workflow.jobs).filter(
+    (name) => name === "publish-node" || name.startsWith("publish-pypi-"),
+  );
+}
+
+function publisherPrerequisites(registryJobs: readonly string[]): string[] {
+  return registryJobs.map((name) => {
+    const output = name === "publish-node" ? "npm" : "pypi";
+    return `needs['build-release'].outputs.${output} != 'true' || needs['${name}'].result == 'success'`;
+  });
+}
+
+/**
+ * Deploy docs after selected publishers succeed, then run the availability
+ * verifier. Docs never consume registry availability, so the slow public
+ * availability poll must not delay their deployment.
+ */
+function refreshReleaseOrdering(workflow: GithubWorkflow): void {
+  const registryJobs = publicationRegistryJobs(workflow);
+  const docs = workflow.getJob(DOCS_JOB) as Job | undefined;
+  if (docs) {
+    workflow.updateJob(DOCS_JOB, {
       ...docs,
-      needs: ["build-release", PUBLICATION_VERIFIER_JOB],
+      needs: ["build-release", ...registryJobs],
       if: releaseCondition([
         "needs['build-release'].result == 'success'",
         "needs['build-release'].outputs.docs == 'true'",
-        `needs['${PUBLICATION_VERIFIER_JOB}'].result == 'success' || needs['${PUBLICATION_VERIFIER_JOB}'].result == 'skipped'`,
+        ...publisherPrerequisites(registryJobs),
       ]),
     });
   }
+  const verifier = workflow.getJob(PUBLICATION_VERIFIER_JOB) as Job | undefined;
+  if (verifier) {
+    workflow.updateJob(PUBLICATION_VERIFIER_JOB, {
+      ...verifier,
+      needs: ["build-release", ...registryJobs, ...(docs ? [DOCS_JOB] : [])],
+    });
+  }
 }
 
 /** Keep documentation publication behind every configured package registry. */
 export function refreshReleaseDocsDependencies(project: DBXToolsJavaScriptProject): void {
   const workflow = releaseWorkflows.get(project);
   if (workflow) {
-    refreshDocsRegistryDependencies(workflow);
+    refreshReleaseOrdering(workflow);
   }
 }
 
-function publicationRegistryJobs(workflow: GithubWorkflow): string[] {
-  return Object.keys(workflow.jobs).filter(
-    (name) => name === "publish-node" || name.startsWith("publish-pypi-"),
-  );
-}
-
 /** Keep one public availability barrier behind every configured registry publisher. */
 export function refreshPublicationVerification(project: DBXToolsJavaScriptProject): void {
   const workflow = releaseWorkflows.get(project);
@@ -160,10 +181,7 @@ export function refreshPublicationVerification(project: DBXToolsJavaScriptProjec
     ...(hasNpm ? ["needs['build-release'].outputs.npm == 'true'"] : []),
     ...(hasPypi ? ["needs['build-release'].outputs.pypi == 'true'"] : []),
   ].join(" || ");
-  const prerequisites = registryJobs.map((name) => {
-    const output = name === "publish-node" ? "npm" : "pypi";
-    return `needs['build-release'].outputs.${output} != 'true' || needs['${name}'].result == 'success'`;
-  });
+  const prerequisites = publisherPrerequisites(registryJobs);
   const job: Job = {
     if: releaseCondition([
       "needs['build-release'].result == 'success'",
@@ -240,7 +258,7 @@ export function refreshPublicationVerification(project: DBXToolsJavaScriptProjec
   } else {
     workflow.addJob(PUBLICATION_VERIFIER_JOB, job);
   }
-  refreshDocsRegistryDependencies(workflow);
+  refreshReleaseOrdering(workflow);
 }
 
 function releaseBuildJob(
@@ -276,7 +294,7 @@ function releaseBuildJob(
           fetchDepth: 0,
         },
       }),
-      ...project.renderWorkflowSetup({ mutable: true }),
+      ...project.renderWorkflowSetup({ mutable: false }),
       {
         name: "Verify release context",
         id: "release",
@@ -398,7 +416,7 @@ function nodePublishJob(): Job {
 }
 
 function addDocsJobs(workflow: GithubWorkflow): void {
-  workflow.addJob("deploy-docs", {
+  workflow.addJob(DOCS_JOB, {
     if: releaseCondition([
       "needs['build-release'].result == 'success'",
       "needs['build-release'].outputs.docs == 'true'",
@@ -419,7 +437,7 @@ function addDocsJobs(workflow: GithubWorkflow): void {
       },
     ],
   });
-  refreshDocsRegistryDependencies(workflow);
+  refreshReleaseOrdering(workflow);
 }
 
 /** Owns the single release workflow and local release preparation tasks. */

package/tasks/bun-lockfile.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env -S bun
+/**
+ * Keep `bun.lock` free of private npm registry URLs.
+ *
+ * Detects the active npm registry and, when it is not public npm, rewrites
+ * every tarball URL under it. Options also read `PROJEN_BUN_LOCKFILE_*`
+ * environment variables and `.env`.
+ */
+import { relative } from "node:path";
+import { log } from "@dbx-tools/shared-core";
+import { runTaskMain, taskCommand, taskOptions, taskRoot } from "./cli.ts";
+import { TaskRootOptionSchema } from "./options.ts";
+import { BunLockfileOptionsSchema, normalizeBunLockfileAt } from "../src/bun-lockfile.ts";
+
+const logger = log.logger("projen:bun-lockfile");
+
+const TaskSchema = BunLockfileOptionsSchema.extend({ root: TaskRootOptionSchema });
+
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const { root, ...options } = await taskOptions(
+    taskCommand(import.meta.url, "Keep bun.lock free of private npm registry URLs", TaskSchema),
+    TaskSchema,
+    args,
+  );
+  const result = normalizeBunLockfileAt(taskRoot(root), options);
+  if (!result.exists || !result.changed) return;
+  const file = relative(process.cwd(), result.path) || result.path;
+  if (options.check) {
+    throw new Error(
+      `${file} contains ${result.rewritten} private registry tarball URLs; run \`bun run bun-lockfile\``,
+    );
+  }
+  logger.info(`rewrote ${result.rewritten} private registry tarball URLs`, { file });
+}
+
+await runTaskMain(import.meta, main);