@dbx-tools/projen 0.6.90 → 0.6.92

package/README.md

@@ -293,6 +293,22 @@ invokes, so there is no second place to run the same thing:
 
 Do NOT run `projen default` (or `bunx projen`) from inside a member. Synth is a
 whole-tree operation driven by the ROOT `.projenrc.ts`, so a member-level run
-re-synths the entire workspace from the member's directory and rewrites the
-root `package.json` `version` back to `0.0.0`. Run `bun run sync` from the root
-instead.
+re-synths the entire workspace from the member's directory. Run `bun run sync`
+from the root instead.
+
+## Versioning
+
+The whole repo shares ONE version, stored in the root `VERSION` file (a plain
+`x.y.z` string; a fresh tree with no file defaults to `0.0.1`). Synth COPIES that
+value into every generated manifest - the root and `projen/` `package.json`, every
+JS member, every Python `pyproject.toml`, the generated openapi packages, and the
+example apps - so the packages, the engine, and the examples always match.
+`src/workspace-version.ts` owns reading and writing it. Synth only ever reads it;
+it never resets, upgrades, or downgrades a version on its own.
+
+`bun run bump` is the only command that changes the number: it fetches the remote
+tags once, takes the highest tag across `v*` and every sibling prefix as the base
+(falling back to the local `VERSION` file when the remote is unreachable or has no
+tag), increments by `--level`, writes `VERSION`, then synths so every manifest
+copies it. The remote is consulted only on `bump` and on one-time creation of a
+missing `VERSION` file - never on an ordinary synth.

package/index.ts

@@ -2,6 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 
+export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as clean from "./src/clean.ts";
@@ -25,6 +26,7 @@ export * as tags from "./src/tags.ts";
 export * as tsconfig from "./src/tsconfig.ts";
 export * as vscode from "./src/vscode.ts";
 export * as watch from "./src/watch.ts";
+export * as workspaceVersion from "./src/workspace-version.ts";
 export { BUN_DEV_OVERRIDE, BUN_BUILD_OVERRIDE, BUN_APP_OVERRIDES, RootBunfigFile, BunfigFile, BunDevServerFile, BunBuildFile } from "./src/bun-app.ts";
 export { DBXToolsConfig } from "./src/dbx-tools-config.ts";
 export type { DBXToolsConfigOptions } from "./src/dbx-tools-config.ts";
@@ -49,3 +51,5 @@ export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";
 export { DBXToolsVsCode } from "./src/vscode.ts";
 export type { IgnoreGroupOptions } from "./src/watch.ts";
+export { VERSION_FILE, DEFAULT_VERSION } from "./src/workspace-version.ts";
+export type { Semver } from "./src/workspace-version.ts";

package/package.json

@@ -26,9 +26,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "0.6.90",
-    "@dbx-tools/path": "0.6.90",
-    "@dbx-tools/shared-core": "0.6.90",
+    "@dbx-tools/core": "0.6.92",
+    "@dbx-tools/path": "0.6.92",
+    "@dbx-tools/shared-core": "0.6.92",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -47,7 +47,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.6.90",
+  "version": "0.6.92",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/barrels.ts

@@ -27,6 +27,10 @@
  * `export { ... }`. The module namespaces stay either way, so a namespaced call
  * site keeps working.
  *
+ * Every generated barrel also exports `PACKAGE_IDENTIFIER` from the package's own
+ * `package.json`. Runtime helpers can retain the package specifier without
+ * trying to recover it from an ESM namespace object or loader function.
+ *
  * Uniqueness is tallied over types and values TOGETHER: a name carried by two
  * modules is ambiguous whichever kind it is, and hoisting one module's value
  * beside another's same-named type would emit two conflicting re-exports. Such a
@@ -47,7 +51,7 @@
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { find } from "@dbx-tools/path";
-import { string } from "@dbx-tools/shared-core";
+import { json, string } from "@dbx-tools/shared-core";
 import isIdentifier from "is-identifier";
 import { header, isGenerated, makeReadonly, makeWritable, type HeaderOpts } from "./generated.ts";
 import { moduleExports, moduleStatements, type ModuleExport } from "./module-exports.ts";
@@ -101,6 +105,11 @@ const BARREL_HEADER: HeaderOpts = {
   source: "the exporting modules in ./src",
 };
 
+/** Generated package identity export, reserved against source-module hoisting. */
+const PACKAGE_IDENTIFIER_EXPORT = "PACKAGE_IDENTIFIER";
+const PACKAGE_IDENTIFIER_LINE = `export const ${PACKAGE_IDENTIFIER_EXPORT} = "";`;
+const PACKAGE_IDENTIFIER_LINE_RE = /^export const PACKAGE_IDENTIFIER = .*;$/m;
+
 /** `pnpm-workspace` -> `pnpmWorkspace`; `local-fs` -> `localFS` (`fs` -> `FS`). */
 function kebabToCamel(segment: string): string {
   const tokens = [...string.tokenizeWithOptions({ lowerCase: true, capitalize: true }, segment)];
@@ -262,6 +271,31 @@ function mergeCustomExports(content: string, pkgDir: string): string {
   return `${kept.join("\n").replace(/\n+$/, "")}\nexport * from "./exports.ts";\n`;
 }
 
+/** Read the authoritative npm package name emitted by the package project. */
+function packageIdentifier(pkgDir: string): string {
+  const manifestPath = join(pkgDir, "package.json");
+  const name = existsSync(manifestPath)
+    ? json.parseRecord(readFileSync(manifestPath, "utf8"))?.name
+    : undefined;
+  if (typeof name !== "string" || !name.trim()) {
+    throw new Error(`Cannot generate barrel without package.json name: ${manifestPath}`);
+  }
+  return name;
+}
+
+/** Normalize package identity so structural barrel comparisons need no manifest read. */
+function withoutPackageIdentifier(content: string): string {
+  return content.replace(PACKAGE_IDENTIFIER_LINE_RE, PACKAGE_IDENTIFIER_LINE);
+}
+
+/** Resolve and insert package identity only when a barrel is about to be written. */
+function withPackageIdentifier(content: string, pkgDir: string): string {
+  const line = `export const ${PACKAGE_IDENTIFIER_EXPORT} = ${JSON.stringify(
+    packageIdentifier(pkgDir),
+  )};`;
+  return content.replace(PACKAGE_IDENTIFIER_LINE_RE, () => line);
+}
+
 /**
  * Rebuild one package's root barrel. Returns 1 only if the barrel's contents
  * actually changed - a module was added, removed, renamed, or toggled its
@@ -317,30 +351,35 @@ function generateForPackage(pkgDir: string): number {
   // extension is written because `tsc` rewrites it on emit
   // (`rewriteRelativeImportExtensions`) - an extensionless specifier would be
   // copied through verbatim and Node's ESM resolver cannot probe for it.
-  let content = modulePaths
+  const namespaceExports = modulePaths
     .map((stem) => {
       const modulePath = `./src/${byModulePath.get(stem)!}`;
       return `export * as ${modulePathToNamespace(modulePath)} from "${modulePath}";`;
     })
     .join("\n");
+  let content = `${PACKAGE_IDENTIFIER_LINE}\n${namespaceExports}`;
   // Hoist package-unique named exports to the top level. Names a hand-authored
   // `exports.ts` declares are suppressed so that file stays authoritative.
   const customPath = join(pkgDir, CUSTOM_EXPORTS_FILE);
   const suppress = existsSync(customPath) ? customExportNames(customPath) : new Set<string>();
+  suppress.add(PACKAGE_IDENTIFIER_EXPORT);
   content = hoistUniqueExports(content, pkgDir, suppress);
   // A sibling `exports.ts` overrides/extends the generated barrel and wins on conflict.
   content = mergeCustomExports(content, pkgDir);
 
-  // The barrel only *changes* when its set of exporting modules does. If the
-  // stamped result matches what's already on disk, leave the file - and its
+  // The barrel only *changes* when its export structure does. Package identity is
+  // blanked on both sides of this comparison, so a no-op cycle never reads
+  // package.json merely to reconstruct a value the existing barrel already has.
+  // If the structural result matches what's on disk, leave the file - and its
   // read-only bit - completely untouched and report no change (0). This keeps the
   // watcher quiet on ordinary in-file edits (which leave the export * as … list
   // identical), and it is also what keeps a no-op cycle off the read-only bit
   // entirely: see {@link writeBarrel} for why unlocking a barrel we are not about
   // to rewrite is what produced spurious EACCES failures.
   content = `${content.replace(/\n+$/, "")}\n`;
-  const next = `${header(BARREL_HEADER)}\n${content}`;
-  if (before === next) return 0;
+  const template = `${header(BARREL_HEADER)}\n${content}`;
+  if (before !== undefined && withoutPackageIdentifier(before) === template) return 0;
+  const next = withPackageIdentifier(template, pkgDir);
 
   // Written whole (header included) rather than via `stampGenerated`, which would
   // re-read and rewrite the file to prepend the same header - a second write, and

package/src/openapi.ts

@@ -48,6 +48,7 @@ import {
   toPosix,
   recordedPackages,
 } from "./packages.ts";
+import { readWorkspaceVersion } from "./workspace-version.ts";
 
 const logger = log.logger("projen:openapi");
 
@@ -173,6 +174,7 @@ export async function generateOpenapi(): Promise<string[]> {
     skipLibCheck: true,
   };
 
+  const specVersion = readWorkspaceVersion(repoRoot);
   const written: string[] = [];
   for (const p of pkgs) {
     // The generated package's folder is the source's leaf folder name (`api`), not
@@ -197,7 +199,7 @@ export async function generateOpenapi(): Promise<string[]> {
           specFileBaseName: "openapi",
           specVersion: 3,
           name: `${p.relPath} API`,
-          version: "0.0.0",
+          version: specVersion,
         },
         compilerOptions,
       );

package/src/packages.ts

@@ -177,10 +177,11 @@ function readRecordedMembers(projectRoot: string = repoRoot): string[] {
   return doc?.packages ?? [];
 }
 
-/** A member path `<root>/<...rel>` (>= 2 segments) as a {@link DiscoveredPackage}. */
+/** A workspace member path as a {@link DiscoveredPackage}, including root-level members. */
 function packageOfMember(projectRoot: string, member: string): DiscoveredPackage | undefined {
   const segs = toPosix(member).split("/").filter(Boolean);
-  if (segs.length < 2) return undefined;
+  if (segs.length === 0) return undefined;
+  if (segs.length === 1) return new DiscoveredPackage(projectRoot, segs[0]!, []);
   return new DiscoveredPackage(projectRoot, segs[0]!, segs.slice(1));
 }
 

package/src/project-js.ts

@@ -36,12 +36,13 @@ import {
   toPosix,
 } from "./packages.ts";
 import { PnpmWorkspaceState, type DBXToolsPNPMWorkspaceOptions } from "./pnpm-workspace.ts";
+import type { DBXToolsProject, DBXToolsProjectOptions as CommonProjectOptions } from "./project.ts";
 import { applyCompiledPublish } from "./publish.ts";
 import { DBXToolsRelease, type StandaloneRelease } from "./release.ts";
 import { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS, type PackageTag } from "./tags.ts";
 import { DBXToolsRootTsconfig } from "./tsconfig.ts";
 import { DBXToolsVsCode } from "./vscode.ts";
-import type { DBXToolsProject, DBXToolsProjectOptions as CommonProjectOptions } from "./project.ts";
+import { readWorkspaceVersion } from "./workspace-version.ts";
 
 /**
  * The dbx-tools project surface, backed by projen's Node toolchain. A single
@@ -584,6 +585,9 @@ export class DBXToolsNodeProject
     // component, but the file is still required by the Databricks Apps platform
     // (its build phase installs with pnpm and reads catalog + `allowBuilds`).
     pnpmWorkspace.attachWorkspaceFile(this);
+    // Copy the single workspace version onto the root manifest. The `VERSION` file
+    // at the workspace root is the source of truth; synth only reads it.
+    this.package.addField("version", readWorkspaceVersion(this.outdir));
     this.scope = scope;
     this.extraWorkspaceMembers = options.extraWorkspaceMembers ?? [];
     this.rootInstallOnly = options.rootInstallOnly !== false;
@@ -678,6 +682,10 @@ export class DBXToolsTypeScriptProject
       ".": "./index.ts",
       "./package.json": "./package.json",
     });
+    // Every package carries the single workspace version, copied from the root
+    // `VERSION` file (the source of truth). `this.root` is the workspace root for a
+    // discovered member and this project itself for a standalone compiling root.
+    this.package.addField("version", readWorkspaceVersion(this.root.outdir));
     addPackageFiles(this, "index.ts", "src");
     // `bun test` intercepts `node:test` (the suites keep using node:test) and
     // runs it with bun's own fast runner. Args are FILTERS, not globs; a bare

package/src/project-predicate.ts

@@ -11,8 +11,8 @@ import { IConstruct } from "constructs";
 import { Project } from "projen";
 import { project } from "..";
 import { toPosix } from "./packages.ts";
-import type { DBXToolsProject } from "./project.ts";
 import type { DBXToolsJavaScriptProject } from "./project-js.ts";
+import type { DBXToolsProject } from "./project.ts";
 
 /**
  * Guard: the construct is a projen {@link Project} - the base every builder here

package/src/project-py.ts

@@ -4,6 +4,7 @@ import { Component, type Project, javascript, python, vscode } from "projen";
 import { GithubWorkflow } from "projen/lib/github";
 import { JobPermission } from "projen/lib/github/workflows-model";
 import type { DBXToolsProject, DBXToolsProjectOptions } from "./project.ts";
+import { readWorkspaceVersion } from "./workspace-version.ts";
 
 /** Git location used by direct `#subdirectory=` package dependencies. */
 export interface PythonRepositoryOptions {
@@ -19,6 +20,7 @@ export interface PythonPackageOptions extends DBXToolsProjectOptions {
   readonly module: string;
   readonly description: string;
   readonly dependencies?: readonly string[];
+  readonly scripts?: Readonly<Record<string, string>>;
 }
 
 /** Options for one projen-native Python workspace member. */
@@ -27,6 +29,8 @@ export interface DBXToolsPythonProjectOptions extends DBXToolsProjectOptions {
   readonly package: PythonPackageOptions;
   readonly repository: Required<PythonRepositoryOptions>;
   readonly requiresPython: string;
+  /** Workspace version copied onto this package's `pyproject.toml`. */
+  readonly version: string;
 }
 
 /** Python release workflow configuration. */
@@ -94,7 +98,7 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
       moduleName: pkg.module,
       authorName: "",
       authorEmail: "",
-      version: "0.0.0",
+      version: options.version,
       description: pkg.description,
       github: false,
       sample: false,
@@ -111,7 +115,7 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
       uvOptions: {
         project: {
           name: pkg.name,
-          version: "0.0.0",
+          version: options.version,
           description: pkg.description,
           readme: "README.md",
           requiresPython: options.requiresPython,
@@ -140,6 +144,9 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
     this.uv = this.packagingManager;
     this.uv.file.addDeletionOverride("project.authors");
     this.uv.file.addDeletionOverride("dependency-groups");
+    if (pkg.scripts) {
+      this.uv.file.addOverride("project.scripts", pkg.scripts);
+    }
     this.uv.file.readonly = true;
 
     for (const path of [".gitattributes", ".gitignore"]) {
@@ -159,6 +166,7 @@ export class DBXToolsPythonWorkspace extends Component {
   readonly packages: readonly DBXToolsPythonProject[];
   readonly repository: Required<PythonRepositoryOptions>;
   readonly requiresPython: string;
+  readonly version: string;
   readonly file: python.PyprojectTomlFile;
 
   constructor(project: javascript.NodeProject, options: DBXToolsPythonWorkspaceOptions) {
@@ -169,6 +177,9 @@ export class DBXToolsPythonWorkspace extends Component {
       root: options.repository.root ?? "packages/py",
     };
     this.requiresPython = options.requiresPython ?? ">=3.10";
+    // The single workspace version, copied from the root `VERSION` file so Python
+    // members carry the same number as their JS siblings.
+    this.version = readWorkspaceVersion(project.outdir);
     this.file = this.emitWorkspace(project, options);
     this.packages = options.packages.map(
       (pkg) =>
@@ -177,6 +188,7 @@ export class DBXToolsPythonWorkspace extends Component {
           package: pkg,
           repository: this.repository,
           requiresPython: this.requiresPython,
+          version: this.version,
         }),
     );
     for (const pkg of this.packages) {
@@ -216,7 +228,7 @@ export class DBXToolsPythonWorkspace extends Component {
     const file = new python.PyprojectTomlFile(project, {
       project: {
         name: options.workspaceName ?? `${string.toSlug(project.name)}-python-workspace`,
-        version: "0.0.0",
+        version: this.version,
         requiresPython: this.requiresPython,
         dependencies: [],
       },

package/src/project.ts

@@ -7,8 +7,8 @@ import { object, type OneOrMany } from "@dbx-tools/shared-core";
 import { type IConstruct } from "constructs";
 import { Project, type ProjectOptions } from "projen";
 import * as mixin from "./mixin.ts";
-import * as projectPredicate from "./project-predicate.ts";
 import type { DBXToolsJavaScriptProject } from "./project-js.ts";
+import * as projectPredicate from "./project-predicate.ts";
 
 export * from "./project-js.ts";
 export * from "./project-py.ts";

package/src/release.ts

@@ -269,9 +269,9 @@ export class DBXToolsRelease extends Component {
    *
    * `directory` (e.g. `projen/`) is a WORKSPACE MEMBER whose `@dbx-tools/*` deps
    * are `workspace:*`. `bun publish` resolves those to whatever version its
-   * SIBLINGS carry (via the lockfile), so before publishing we set the version on
-   * the package AND its in-scope siblings, then refresh the lockfile - otherwise
-   * the published engine would depend on the siblings' on-disk `0.0.0`. The
+   * SIBLINGS carry (via the lockfile), so before publishing we re-affirm the
+   * version on the package AND its in-scope siblings, then refresh the lockfile -
+   * otherwise a stale resolved version could reach the published engine. The
    * `Install` step already ran `bun install` from the repo root (the member
    * subdir walks up to it), so the workspace is linked. The manifests are
    * projen-readonly, hence the `chmod`. A manual `workflow_dispatch` run has no

package/src/workspace-version.ts

@@ -0,0 +1,155 @@
+/**
+ * Single source of truth for the workspace version.
+ *
+ * The repo-root `VERSION` file holds one plain `x.y.z` string that every
+ * generated manifest copies at synth: the root and `projen/` package.json, every
+ * JS member, every Python `pyproject.toml`, the generated openapi packages, and
+ * the example apps. Synth only READS this file (defaulting to {@link
+ * DEFAULT_VERSION} when it is absent on a fresh tree); it never rewrites it, so an
+ * ordinary `bunx projen` cannot move a package version up or down.
+ *
+ * Only two callers change the number: `bump` (which increments it) and the
+ * one-time bootstrap of a workspace that has no `VERSION` yet. Both resolve the
+ * base from the remote git tags first ({@link resolveRemoteVersion}) so a release
+ * cut elsewhere is respected, and fall back to the local file (or {@link
+ * DEFAULT_VERSION}) when the remote is unreachable or has no tags. The remote is
+ * consulted ONLY on those two paths, never on every synth/compile/commit.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { exec } from "@dbx-tools/core";
+
+/** Name of the repo-root file holding the workspace version. */
+export const VERSION_FILE = "VERSION";
+
+/** Version a fresh workspace starts at when no `VERSION` file and no remote tag exist. */
+export const DEFAULT_VERSION = "0.0.1";
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** A parsed `[major, minor, patch]` tuple. */
+export type Semver = [number, number, number];
+
+/** Parse `x.y.z` (ignoring any leading `v`/prefix), or `undefined` when it does not match. */
+export function parseSemver(raw: string): Semver | undefined {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+/** Ordering comparator: negative when `a < b`, positive when `a > b`, zero when equal. */
+export function compareSemver(a: Semver, b: Semver): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/** Absolute path to the `VERSION` file for a workspace root. */
+export function versionPath(root: string): string {
+  return join(root, VERSION_FILE);
+}
+
+/**
+ * Read the workspace version from `<root>/VERSION`. Returns {@link DEFAULT_VERSION}
+ * when the file is absent (a fresh consumer tree). A file that EXISTS but does not
+ * hold a valid `x.y.z` fails loudly rather than being silently "fixed" to a
+ * different number during synth.
+ */
+export function readWorkspaceVersion(root: string): string {
+  const path = versionPath(root);
+  if (!existsSync(path)) return DEFAULT_VERSION;
+  const raw = readFileSync(path, "utf8").trim();
+  if (!SEMVER.test(raw)) {
+    throw new Error(`${VERSION_FILE} must contain an x.y.z version, got ${JSON.stringify(raw)}`);
+  }
+  return raw;
+}
+
+/** Write the workspace version to `<root>/VERSION`. Only `bump` and bootstrap call this. */
+export function writeWorkspaceVersion(root: string, version: string): void {
+  if (!SEMVER.test(version)) {
+    throw new Error(`workspace version must be x.y.z, got ${JSON.stringify(version)}`);
+  }
+  writeFileSync(versionPath(root), `${version}\n`);
+}
+
+/** Run git in `cwd`, capturing stdout and swallowing failure (offline, no repo). */
+function gitCapture(cwd: string, args: string[]): string {
+  try {
+    const res = exec.spawnSync("git", args, {
+      cwd,
+      stdout: "capture",
+      stderr: "ignore",
+      stdin: "ignore",
+      check: false,
+    });
+    return res.stdout?.trim() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/** Highest tag matching `<prefix><semver>` in the local tag list, or `undefined`. */
+export function latestTagVersion(cwd: string, prefix: string): Semver | undefined {
+  const out = gitCapture(cwd, [
+    "-c",
+    "versionsort.suffix=-",
+    "tag",
+    "--sort=-version:refname",
+    "--list",
+    `${prefix}*`,
+  ]);
+  for (const tag of out.split("\n")) {
+    const v = parseSemver(tag.replace(prefix, ""));
+    if (v) return v;
+  }
+  return undefined;
+}
+
+/**
+ * Highest published version across every tag prefix, or `undefined` when the
+ * remote is unreachable or no matching tag exists. Fetches tags first (best
+ * effort) so a release made elsewhere is respected; a fetch failure just means
+ * the local tag list is used, and callers fall back to the `VERSION` file.
+ */
+export function resolveRemoteVersion(
+  cwd: string,
+  prefixes: readonly string[],
+  { fetch = true }: { fetch?: boolean } = {},
+): string | undefined {
+  if (fetch) gitCapture(cwd, ["fetch", "--tags", "--quiet"]);
+  let best: Semver | undefined;
+  for (const prefix of prefixes) {
+    const v = latestTagVersion(cwd, prefix);
+    if (v && (!best || compareSemver(v, best) > 0)) best = v;
+  }
+  return best ? best.join(".") : undefined;
+}
+
+/**
+ * The base version a `bump` increments from: the highest remote tag if any exists
+ * (a local file that is ahead does NOT win), else the local `VERSION` file, else
+ * {@link DEFAULT_VERSION}.
+ */
+export function resolveBaseVersion(
+  root: string,
+  prefixes: readonly string[],
+  options: { fetch?: boolean } = {},
+): { version: string; source: "remote" | "local" } {
+  const remote = resolveRemoteVersion(root, prefixes, options);
+  if (remote) return { version: remote, source: "remote" };
+  return { version: readWorkspaceVersion(root), source: "local" };
+}
+
+/**
+ * Create the `VERSION` file when it does not yet exist, seeding it from the remote
+ * tags (or {@link DEFAULT_VERSION} when the remote is unreachable / has no tag). An
+ * existing file is left untouched - only `bump` moves an established version, so
+ * bootstrap never upgrades or downgrades one. Returns the current version.
+ */
+export function ensureWorkspaceVersion(
+  root: string,
+  { prefixes = ["v"], fetch = true }: { prefixes?: readonly string[]; fetch?: boolean } = {},
+): string {
+  if (!existsSync(versionPath(root))) {
+    writeWorkspaceVersion(root, resolveRemoteVersion(root, prefixes, { fetch }) ?? DEFAULT_VERSION);
+  }
+  return readWorkspaceVersion(root);
+}

package/tasks/bump.ts

@@ -1,28 +1,30 @@
 #!/usr/bin/env -S bun
 /**
- * `projen bump` - synth, compute the next release version, then (by default)
- * commit, tag, and push it. Pushing the tag is what triggers the release
- * workflow.
+ * `projen bump` - compute the next release version, write it to the workspace
+ * `VERSION` file, synth so every manifest copies it, then (by default) commit,
+ * tag, and push. Pushing the tag is what triggers the release workflow.
  *
- * The next version is derived from the HIGHEST of:
- *   - the latest published git tag matching `<prefix><semver>` (fetched from
- *     the remote so a release made elsewhere is respected),
- *   - the same for every `--sibling` prefix, and
- *   - the local `package.json` version,
- * then incremented by `--level` (patch | minor | major; default patch).
+ * The base version is the HIGHEST published git tag across `<prefix>` and every
+ * `--sibling` prefix (fetched from the remote so a release cut elsewhere wins),
+ * falling back to the local `VERSION` file when the remote is unreachable or has
+ * no matching tag. A local file that is ahead does NOT override an existing
+ * remote tag. The base is then incremented by `--level` (patch | minor | major;
+ * default patch). The remote is consulted only here and on VERSION bootstrap,
+ * never on an ordinary synth.
  *
  * `--sibling <dir>:<tagPrefix>` (repeatable) releases an in-repo project that
  * publishes on its OWN tag namespace (e.g. `projen/`, tagged `projen-v*`) at the
- * SAME version as the root, in the same run: its manifest version is stamped, its
- * `<tagPrefix><version>` tag is cut and pushed (triggering its own workflow), and
- * it is included in the local-registry publish. Taking the base version from
- * every prefix at once is what keeps the two in lockstep: the engine sat at
- * 0.1.24 while the packages reached 0.3.41 precisely because each namespace only
- * ever looked at its own tags.
+ * SAME version as the root, in the same run: its `<tagPrefix><version>` tag is
+ * cut and pushed (triggering its own workflow), and it is included in the
+ * local-registry publish. Taking the base version from every prefix at once is
+ * what keeps the two in lockstep: the engine sat at 0.1.24 while the packages
+ * reached 0.3.41 precisely because each namespace only ever looked at its own
+ * tags. Both draw the fallback from the one root `VERSION` file, so the engine
+ * and the packages share a single source of truth.
  *
  * Flags (all default ON; negate with the `--no-` form, per commander):
- *   --synth   / --no-synth     run `projen` (synth) first so the tree is current
- *   --version / --no-version   write the bumped version into package.json
+ *   --synth   / --no-synth     synth after writing VERSION so manifests copy it
+ *   --version / --no-version   write the bumped version into `VERSION`
  *   --commit  / --no-commit    commit the release (staged with `git add -A`)
  *   --tag     / --no-tag       create the `<prefix><version>` git tag
  *   --push    / --no-push      push the CURRENT branch + tag to origin
@@ -34,7 +36,14 @@
  * verdaccio) right after the tag push. `--local-pypi <value>` does the same for
  * Python packages through a writable devpi index. Values for both:
  *   - `auto` (default): publish only when `npm config get registry` is a
- *     loopback host, or uv's default index is a loopback devpi `+simple` URL.
+ *     loopback host, or when ANY active Python index — the primary
+ *     `index-url` OR any `extra-index-url`, across uv and pip — is a loopback
+ *     devpi URL. Scanning the extras is what lets the corp proxy stay the
+ *     primary index while a local devpi added as an extra is the detected
+ *     publish target. The deploy endpoint for that index is taken from the
+ *     GLOBAL uv config — an explicit `publish-url` on the matching `[[index]]`
+ *     (or `UV_PUBLISH_URL`) — falling back to deriving it from the `+simple`
+ *     URL shape when no such setting exists.
  *   - `false`: never publish locally.
  *   - a URL: always publish to that registry.
  */
@@ -44,7 +53,15 @@ import { fileURLToPath } from "node:url";
 import { exec, project } from "@dbx-tools/core";
 import { log, net } from "@dbx-tools/shared-core";
 import { Command, Option } from "commander";
-import { activePythonIndex, resolveLocalPypi } from "./python-registry.ts";
+import { activePythonIndexes, resolveLocalPypi } from "./python-registry.ts";
+import {
+  type Semver,
+  compareSemver,
+  latestTagVersion,
+  parseSemver,
+  resolveBaseVersion,
+  writeWorkspaceVersion,
+} from "../src/workspace-version.ts";
 
 const logger = log.logger("projen:bump");
 const LEVELS = ["patch", "minor", "major"] as const;
@@ -70,17 +87,7 @@ function parseSibling(value: string, previous: Sibling[]): Sibling[] {
   return [...previous, { dir: value.slice(0, at), prefix: value.slice(at + 1) }];
 }
 
-/** Parse `x.y.z` (ignoring any leading `v`/prefix), returning a `[maj,min,pat]` tuple. */
-function parseSemver(raw: string): [number, number, number] | undefined {
-  const m = /(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
-}
-
-function compareSemver(a: [number, number, number], b: [number, number, number]): number {
-  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
-}
-
-function increment(v: [number, number, number], level: Level): [number, number, number] {
+function increment(v: Semver, level: Level): Semver {
   if (level === "major") return [v[0] + 1, 0, 0];
   if (level === "minor") return [v[0], v[1] + 1, 0];
   return [v[0], v[1], v[2] + 1];
@@ -97,29 +104,6 @@ function git(args: string[], capture = false): string {
   return res.stdout?.trim() ?? "";
 }
 
-/** Highest tag matching `<prefix><semver>`, or undefined. Call {@link fetchTags} first. */
-function latestTagVersion(prefix: string): [number, number, number] | undefined {
-  const out = git(
-    ["-c", "versionsort.suffix=-", "tag", "--sort=-version:refname", "--list", `${prefix}*`],
-    true,
-  );
-  for (const tag of out.split("\n")) {
-    const v = parseSemver(tag.replace(prefix, ""));
-    if (v) return v;
-  }
-  return undefined;
-}
-
-/** Pull remote tags once, so a release made elsewhere is respected. */
-function fetchTags(): void {
-  git(["fetch", "--tags", "--quiet"], true);
-}
-
-function readPackageVersion(pkgPath: string): [number, number, number] {
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
-  return parseSemver(pkg.version ?? "") ?? [0, 0, 0];
-}
-
 /**
  * Write ONLY the `version` field into a manifest projen owns (read-only, so
  * bracketed by a chmod that restores the mode). Used for the ROOT and the
@@ -190,7 +174,7 @@ program
   )
   .option(
     "--local-pypi <value>",
-    "publish Python packages locally: 'auto' (only a loopback devpi +simple index), 'false', or a devpi URL",
+    "publish Python packages locally: 'auto' (any active index-url or extra-index-url that is a loopback devpi +simple), 'false', or a devpi URL",
     "auto",
   )
   .option("--python-root <path>", "Python workspace package root", "packages/py")
@@ -217,50 +201,55 @@ program
         if (!existsSync(s.pkgPath)) throw new Error(`--sibling ${s.dir}: no package.json there`);
       }
 
-      // Synth first so the release commit captures an up-to-date tree (generated
-      // manifests, workspace file, tasks, ...) rather than a stale one.
-      if (opts.synth) {
-        logger.info("synthesizing (projen)");
-        exec.spawnSync("bun", [".projenrc.ts"], {
-          cwd: process.cwd(),
-          stdout: "inherit",
-          stderr: "inherit",
-          stdin: "ignore",
-          check: true,
-        });
-      }
+      // The `VERSION` file is the workspace source of truth and lives at the repo
+      // root, even when this task runs from a subdirectory (`cd projen && bun run
+      // bump`), so the engine and packages always share one number.
+      const root = project.root() ?? process.cwd();
 
-      // Base = highest of the local package version and the latest tag in EVERY
-      // namespace being released, so one shared version stays ahead of them all.
-      fetchTags();
+      // Base = the highest published tag across EVERY namespace being released
+      // (fetched from the remote so a release cut elsewhere wins), falling back to
+      // the local `VERSION` file when the remote is unreachable or has no tag. A
+      // local file that happens to be ahead does NOT override an existing remote.
       const prefixes = [opts.prefix, ...siblings.map((s) => s.prefix)];
-      const tagged = prefixes
-        .map((prefix) => ({ prefix, version: latestTagVersion(prefix) }))
-        .filter((t): t is { prefix: string; version: [number, number, number] } => !!t.version);
-      const base = tagged.reduce(
-        (highest, t) => (compareSemver(t.version, highest) > 0 ? t.version : highest),
-        readPackageVersion(pkgPath),
-      );
+      const baseInfo = resolveBaseVersion(root, prefixes);
+      const base = parseSemver(baseInfo.version) ?? [0, 0, 1];
       const next = increment(base, opts.level);
       const version = next.join(".");
       const tags = prefixes.map((prefix) => `${prefix}${version}`);
       logger.info(
         `bump ${base.join(".")} -> ${version} (${opts.level}); tags ${tags.join(", ")}` +
-          `${tagged.length ? "" : " [no remote tag]"}`,
+          `${baseInfo.source === "remote" ? "" : " [no remote tag; used local VERSION]"}`,
       );
-      for (const t of tagged) {
-        if (compareSemver(t.version, base) < 0) {
-          logger.info(`${t.prefix}* was behind at ${t.version.join(".")}, catching it up`);
+      // Note any tag namespace that trailed the base so a lockstep catch-up is visible.
+      for (const prefix of prefixes) {
+        const tagged = latestTagVersion(root, prefix);
+        if (tagged && compareSemver(tagged, base) < 0) {
+          logger.info(`${prefix}* was behind at ${tagged.join(".")}, catching it up`);
         }
       }
 
       const push = opts.push && opts.publish;
 
+      // Write the source of truth first, then synth so every generated manifest
+      // COPIES it - synth never invents, resets, or drifts a version on its own.
       if (opts.version) {
+        writeWorkspaceVersion(root, version);
+        // Keep the writable root/sibling manifests coherent even when synth is
+        // skipped (`--no-synth`); synth would otherwise set the same value.
         writeManifestVersion(pkgPath, version);
         for (const s of siblings) writeManifestVersion(s.pkgPath, version);
-        const also = siblings.length ? ` (and ${siblings.map((s) => s.dir).join(", ")})` : "";
-        logger.info(`wrote version ${version} to package.json${also}`);
+        logger.info(`wrote version ${version} to ${root}/VERSION`);
+      }
+
+      if (opts.synth) {
+        logger.info("synthesizing (projen)");
+        exec.spawnSync("bun", [".projenrc.ts"], {
+          cwd: process.cwd(),
+          stdout: "inherit",
+          stderr: "inherit",
+          stdin: "ignore",
+          check: true,
+        });
       }
 
       if (opts.commit) {
@@ -297,16 +286,15 @@ program
       }
       if (publishToLocalRegistry) {
         logger.info(`publishing ${version} to local registry ${localRegistry}`);
-        // Mirror the CI `release` workflow via the shared publish task: it sets
-        // the release version on every workspace member (`bun pm pkg set`; they
-        // keep `0.0.0` on disk, projen-owned, so it unlocks each briefly), then
-        // `bun publish`es each non-private one - and bun natively strips the
-        // `workspace:`/`catalog:` protocols in the packed tarball, resolving each
-        // to the version just set. `publish.ts` restores every manifest it touched
-        // at exit, so this leaves the worktree matching the release commit that was
-        // just pushed - the release version lives in the git tag, not on disk.
-        // Provenance is off for a local registry (no OIDC), so
-        // `NPM_CONFIG_PROVENANCE` is unset.
+        // Mirror the CI `release` workflow via the shared publish task: it
+        // re-affirms the release version on every workspace member (`bun pm pkg
+        // set`; the manifests already carry the shared `VERSION`, projen-owned, so
+        // it unlocks each briefly), then `bun publish`es each non-private one - and
+        // bun natively strips the `workspace:`/`catalog:` protocols in the packed
+        // tarball, resolving each to that version. `publish.ts` restores every
+        // manifest it touched at exit, so this leaves the worktree matching the
+        // release commit that was just pushed. Provenance is off for a local
+        // registry (no OIDC), so `NPM_CONFIG_PROVENANCE` is unset.
         // `publish.ts` is this task's SIBLING in the engine's `tasks/` dir; resolve
         // it off `import.meta.url` (works whether the engine is source-linked in-repo
         // or installed under node_modules) rather than a repo-relative `tasks/...`
@@ -322,16 +310,21 @@ program
         logger.success(`published ${version} to ${localRegistry}`);
       }
 
-      const activeIndex = activePythonIndex();
-      const localPypi = resolveLocalPypi(opts.localPypi, activeIndex);
+      // Scan EVERY active index (primary index-url + every extra-index-url,
+      // across uv and pip): auto-mode publishes to the first that is a loopback
+      // devpi +simple, so the corp proxy stays primary and a local devpi added
+      // as an extra index is the detected publish target.
+      const activeIndexes = activePythonIndexes();
+      const localPypi = resolveLocalPypi(opts.localPypi, activeIndexes);
       const pythonRoot = resolve(opts.pythonRoot);
       if (
         opts.localPypi.toLowerCase() === "auto" &&
-        activeIndex &&
-        net.isLoopbackHost(new URL(activeIndex)) &&
+        activeIndexes.some((index) => net.isLoopbackHost(index)) &&
         !localPypi
       ) {
-        logger.info(`skipped local Python publish: ${activeIndex} is not a devpi +simple index`);
+        logger.info(
+          `skipped local Python publish: no active index (${activeIndexes.join(", ")}) is a devpi +simple index`,
+        );
       }
       if (opts.version === false && localPypi) {
         logger.info("skipped local Python publish (--no-version left packages unstamped)");
@@ -360,16 +353,6 @@ program
         );
         logger.success(`published Python ${version} to ${localPypi.publishUrl}`);
       }
-
-      // Publishing can run package lifecycle hooks, including a standalone
-      // project's own projen synth, which rewrites its generated manifest back
-      // to 0.0.0. Re-assert the release version last so root and every sibling
-      // manifest finish the bump in lockstep.
-      if (opts.version) {
-        writeManifestVersion(pkgPath, version);
-        for (const s of siblings) writeManifestVersion(s.pkgPath, version);
-        logger.info(`synchronized release manifests at ${version}`);
-      }
     },
   );
 

package/tasks/publish-python.ts

@@ -22,11 +22,24 @@ interface PythonProjectFile {
   readonly source: string;
 }
 
+export interface StampPythonProjectsOptions {
+  readonly rewriteDependencies?: boolean;
+}
+
+export interface RestorePythonProjects {
+  (): void;
+  readonly paths: readonly string[];
+}
+
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-export function stampPythonProjects(root: string, version: string): () => void {
+export function stampPythonProjects(
+  root: string,
+  version: string,
+  options: StampPythonProjectsOptions = {},
+): RestorePythonProjects {
   const packageFiles = readdirSync(root, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .map((entry) => resolve(root, entry.name, "pyproject.toml"))
@@ -48,21 +61,25 @@ export function stampPythonProjects(root: string, version: string): () => void {
 
   try {
     for (const project of projects) {
-      let stamped = project.source.replace(/^version = "[^"]+"$/m, `version = "${version}"`);
-      if (stamped === project.source) {
+      const versionPattern = /^version = "[^"]+"$/m;
+      if (!versionPattern.test(project.source)) {
         throw new Error(`Expected one project version in ${project.path}`);
       }
-      for (const sibling of projects) {
-        stamped = stamped.replace(
-          new RegExp(
-            `${escapeRegExp(sibling.name)} @ git\\+[^" ]+#subdirectory=[^" ]+/${escapeRegExp(sibling.directory)}`,
-            "g",
-          ),
-          `${sibling.name}==${version}`,
-        );
+      let stamped = project.source.replace(versionPattern, `version = "${version}"`);
+      if (options.rewriteDependencies ?? true) {
+        for (const sibling of projects) {
+          stamped = stamped.replace(
+            new RegExp(
+              `${escapeRegExp(sibling.name)} @ git\\+[^" ]+#subdirectory=[^" ]+/${escapeRegExp(sibling.directory)}`,
+              "g",
+            ),
+            `${sibling.name}==${version}`,
+          );
+        }
       }
       chmodSync(project.path, project.mode | 0o200);
       writeFileSync(project.path, stamped);
+      chmodSync(project.path, project.mode);
     }
   } catch (error) {
     for (const project of projects) {
@@ -73,13 +90,17 @@ export function stampPythonProjects(root: string, version: string): () => void {
     throw error;
   }
 
-  return () => {
+  const restore = () => {
     for (const project of projects) {
       chmodSync(project.path, project.mode | 0o200);
       writeFileSync(project.path, project.source);
       chmodSync(project.path, project.mode);
     }
   };
+  Object.defineProperty(restore, "paths", {
+    value: projects.map((project) => project.path),
+  });
+  return restore as RestorePythonProjects;
 }
 
 export function publishPythonProjects(options: {
@@ -91,7 +112,7 @@ export function publishPythonProjects(options: {
 }): void {
   const root = resolve(options.root);
   const output = mkdtempSync(join(tmpdir(), "dbx-tools-python-publish-"));
-  const restore = stampPythonProjects(root, options.version);
+  const stamp = stampPythonProjects(root, options.version);
   try {
     exec.spawnSync("uv", ["build", "--all-packages", "--out-dir", output], {
       cwd: process.cwd(),
@@ -123,7 +144,7 @@ export function publishPythonProjects(options: {
       },
     );
   } finally {
-    restore();
+    stamp();
     rmSync(output, { recursive: true, force: true });
   }
 }

package/tasks/publish.ts

@@ -17,7 +17,8 @@
  *     packed manifest shows `"@scope/x": "<version>"` and the real catalog range,
  *     while the on-disk manifest keeps the protocols.) Setting each member's
  *     version first is the only prerequisite, so a sibling resolves the release
- *     version rather than the disk default of `0.0.0`;
+ *     version; the disk manifest already carries the workspace `VERSION`, and
+ *     this makes doubly sure it matches the value being published;
  *   - **`publishConfig` substitution** (compiled `lib/` entry points) is done
  *     HERE, by {@link applyPublishConfig}, NOT by bun: unlike pnpm/npm, `bun
  *     publish`/`bun pm pack` do NOT fold `publishConfig`'s `main`/`types`/`bin`/
@@ -42,10 +43,13 @@
  * since its whole job is to stamp the workspace for a `bun publish` that runs
  * afterwards from another directory.
  *
- * The disk manifests normally carry `version: 0.0.0` (projen owns them, read-only);
- * this unlocks each only long enough to set the version + publish, then RESTORES
- * every one it touched byte-for-byte (and re-locks the mode) on the way out - see
- * {@link restoreManifests}. The release version lives in the git tag, not on disk.
+ * The disk manifests carry the workspace `VERSION` (projen owns them, read-only);
+ * this unlocks each only long enough to fold in the `publishConfig` entry points
+ * (and re-affirm the version) + publish, then RESTORES every one it touched
+ * byte-for-byte (and re-locks the mode) on the way out - see
+ * {@link restoreManifests}. Restore returns each manifest to its committed
+ * content, which already equals the release version, so the worktree is never
+ * left regressed.
  */
 import { chmodSync, existsSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -215,8 +219,9 @@ const members = workspaceMembers(root)
   .filter((dir) => !excluded.has(resolve(root, dir).replace(`${resolve(root)}/`, "")));
 
 // Set the version on EVERY member first (native `bun pm pkg set`), so a sibling
-// published later has its `workspace:*` dep resolved to the release version - not
-// the disk default of 0.0.0 - by `bun publish`'s own protocol rewriting.
+// published later has its `workspace:*` dep resolved to the release version by
+// `bun publish`'s own protocol rewriting. The disk manifests already carry the
+// workspace `VERSION`; this re-affirms it against the value being published.
 logger.info(`setting ${version} across ${members.length} members`);
 for (const dir of members) {
   unlockManifest(join(dir, "package.json"));
@@ -227,7 +232,8 @@ for (const dir of members) {
 // just set. `bun publish`/`pm pack` reads the workspace version from the LOCKFILE,
 // not the live manifest, and a plain `bun install` (even `--force`) does NOT
 // re-resolve it after only a version-field change - deleting the lockfile first
-// does. Without this every `workspace:*` dep would publish as the stale `0.0.0`.
+// does. Without this a `workspace:*` dep could publish against a stale resolved
+// version instead of the one just set.
 const lockfile = join(root, "bun.lock");
 if (existsSync(lockfile)) rmSync(lockfile);
 logger.info("refreshing lockfile so workspace deps resolve to the release version");

package/tasks/python-registry.ts

@@ -22,7 +22,72 @@ export function parseUvDefaultIndex(source: string): string | undefined {
   return undefined;
 }
 
-/** Convert a devpi Simple API URL into its writable index URL. */
+/**
+ * Read EVERY index URL from uv's TOML config — the default (primary) index
+ * first, then any extra `[[index]]` entries in file order. uv's `[[index]]`
+ * table with `default = true` is the primary index; every other `[[index]]`
+ * is an extra index also consulted at resolve time, so a local devpi added as
+ * a non-default block is discoverable here.
+ */
+export function parseUvIndexes(source: string): string[] {
+  const blocks = source.split(/(?=^\[\[index\]\]\s*$)/m);
+  let primary: string | undefined;
+  const extras: string[] = [];
+  for (const block of blocks) {
+    if (!/^\[\[index\]\]\s*$/m.test(block)) continue;
+    const url = /^\s*url\s*=\s*["']([^"']+)["']\s*$/m.exec(block)?.[1];
+    if (!url) continue;
+    if (/^\s*default\s*=\s*true\s*$/m.test(block)) primary = url;
+    else extras.push(url);
+  }
+  return primary ? [primary, ...extras] : extras;
+}
+
+/**
+ * Read every `[[index]]` block's `url` -> `publish-url` mapping from uv's TOML
+ * config. uv lets an index declare an explicit upload endpoint via `publish-url`
+ * (the writable index URL, distinct from the `+simple` read URL); this is the
+ * global setting that names the local deploy target, so auto-detection prefers
+ * it over deriving the publish URL from the `+simple` URL shape.
+ */
+export function parseUvPublishUrls(source: string): Map<string, string> {
+  const map = new Map<string, string>();
+  const blocks = source.split(/(?=^\[\[index\]\]\s*$)/m);
+  for (const block of blocks) {
+    if (!/^\[\[index\]\]\s*$/m.test(block)) continue;
+    const url = /^\s*url\s*=\s*["']([^"']+)["']\s*$/m.exec(block)?.[1];
+    const publishUrl = /^\s*publish-url\s*=\s*["']([^"']+)["']\s*$/m.exec(block)?.[1];
+    if (url && publishUrl) map.set(url, publishUrl);
+  }
+  return map;
+}
+
+/**
+ * The explicit `publish-url` configured (in the global uv config or
+ * `UV_PUBLISH_URL`) for a given `+simple` index URL, or `undefined` when none is
+ * set. Lets auto-detection use the deploy endpoint the user declared globally
+ * rather than inferring it from the index URL.
+ */
+export function configuredPublishUrl(
+  indexUrl: string,
+  uvConfigPath: string = process.env.UV_CONFIG_FILE ?? resolve(homedir(), ".config/uv/uv.toml"),
+): string | undefined {
+  const fromEnv = process.env.UV_PUBLISH_URL?.trim();
+  if (fromEnv) return fromEnv;
+  if (!existsSync(uvConfigPath)) return undefined;
+  return parseUvPublishUrls(readFileSync(uvConfigPath, "utf8")).get(indexUrl);
+}
+
+/**
+ * Convert a devpi Simple API URL into a local publish target.
+ *
+ * The publish URL is taken from the GLOBAL uv config first — an explicit
+ * `publish-url` on the matching `[[index]]` (or `UV_PUBLISH_URL`), i.e. the
+ * deploy endpoint the user declared — and only DERIVED from the `+simple` URL
+ * shape when no such setting exists. Returns `undefined` for a non-loopback
+ * host or a URL that is neither a `+simple` index nor has a configured
+ * `publish-url`.
+ */
 export function devpiRegistry(index: string): LocalPythonRegistry | undefined {
   let url: URL;
   try {
@@ -32,6 +97,16 @@ export function devpiRegistry(index: string): LocalPythonRegistry | undefined {
   }
   if (!net.isLoopbackHost(url)) return undefined;
 
+  // A globally-configured publish-url wins: it names the deploy target directly,
+  // so we honor it even if the index URL isn't the conventional `+simple` shape.
+  const configured = configuredPublishUrl(url.href);
+  if (configured) {
+    return {
+      indexUrl: url.href,
+      publishUrl: configured.endsWith("/") ? configured : `${configured}/`,
+    };
+  }
+
   const path = url.pathname.replace(/\/+$/, "");
   if (!path.endsWith("/+simple")) return undefined;
   url.pathname = `${path.slice(0, -"/+simple".length)}/`;
@@ -43,38 +118,94 @@ export function devpiRegistry(index: string): LocalPythonRegistry | undefined {
   };
 }
 
-/** The active Python package index, preferring uv because Python builds use uv. */
-export function activePythonIndex(): string | undefined {
-  for (const value of [process.env.UV_DEFAULT_INDEX, process.env.UV_INDEX_URL]) {
-    if (value?.trim()) return value.trim();
-  }
-
-  const uvConfig = process.env.UV_CONFIG_FILE ?? resolve(homedir(), ".config/uv/uv.toml");
-  if (existsSync(uvConfig)) {
-    const index = parseUvDefaultIndex(readFileSync(uvConfig, "utf8"));
-    if (index) return index;
-  }
+/** Split a whitespace-separated index list (the pip/uv env-var form). */
+function splitIndexList(value: string | undefined): string[] {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed.split(/\s+/) : [];
+}
 
-  if (process.env.PIP_INDEX_URL?.trim()) return process.env.PIP_INDEX_URL.trim();
-  const pip = exec.spawnSync("python", ["-m", "pip", "config", "get", "global.index-url"], {
+/** Read a `pip config get <key>`, treating pip's literal "undefined" as unset. */
+function pipConfig(key: string): string | undefined {
+  const res = exec.spawnSync("python", ["-m", "pip", "config", "get", key], {
     cwd: process.cwd(),
     stdout: "capture",
     stderr: "ignore",
     stdin: "ignore",
     check: false,
   });
-  return pip.stdout?.trim() || undefined;
+  const out = res.stdout?.trim();
+  return out && out !== "undefined" ? out : undefined;
 }
 
-/** Resolve `auto`, `false`, or an explicit devpi index/publish URL. */
+/**
+ * Every Python package index in effect — the primary index FIRST, then extra
+ * indexes — deduplicated, across uv (preferred, because Python builds use uv)
+ * and pip. Both the primary `index-url` and every `extra-index-url` are read so
+ * a local devpi configured as an *extra* index (leaving the corp proxy as the
+ * primary) is still detected.
+ */
+export function activePythonIndexes(): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (value: string | undefined): void => {
+    const url = value?.trim();
+    if (url && !seen.has(url)) {
+      seen.add(url);
+      out.push(url);
+    }
+  };
+
+  // uv: env vars first (primary, then extras), then uv.toml's index blocks.
+  add(process.env.UV_DEFAULT_INDEX);
+  add(process.env.UV_INDEX_URL);
+  for (const url of splitIndexList(process.env.UV_INDEX)) add(url);
+  for (const url of splitIndexList(process.env.UV_EXTRA_INDEX_URL)) add(url);
+  const uvConfig = process.env.UV_CONFIG_FILE ?? resolve(homedir(), ".config/uv/uv.toml");
+  if (existsSync(uvConfig)) {
+    for (const url of parseUvIndexes(readFileSync(uvConfig, "utf8"))) add(url);
+  }
+
+  // pip: env vars (primary + extras), then `pip config` (index-url + extra-index-url).
+  add(process.env.PIP_INDEX_URL);
+  for (const url of splitIndexList(process.env.PIP_EXTRA_INDEX_URL)) add(url);
+  add(pipConfig("global.index-url"));
+  for (const url of splitIndexList(pipConfig("global.extra-index-url"))) add(url);
+
+  return out;
+}
+
+/** The primary (first) active Python index, or `undefined` when none is set. */
+export function activePythonIndex(): string | undefined {
+  return activePythonIndexes()[0];
+}
+
+/**
+ * Resolve `auto`, `false`, or an explicit devpi index/publish URL.
+ *
+ * - `false` (or empty): skip local publishing.
+ * - a URL: publish there (derive the writable index from a `+simple` URL, else
+ *   treat the value itself as the writable index).
+ * - `auto`: scan every active index — primary `index-url` AND every
+ *   `extra-index-url`, across uv and pip — and publish to the FIRST that is a
+ *   loopback devpi `+simple` index. This is what lets the corp proxy stay the
+ *   primary index while a local devpi added as an extra is the publish target.
+ *
+ * `indexes` accepts an array (the normal case) or a single string (kept for the
+ * existing single-index callers/tests); it defaults to {@link activePythonIndexes}.
+ */
 export function resolveLocalPypi(
   value: string,
-  activeIndex: string | undefined = activePythonIndex(),
+  indexes: readonly string[] | string | undefined = activePythonIndexes(),
 ): LocalPythonRegistry | undefined {
   const trimmed = value.trim();
   if (!trimmed || trimmed.toLowerCase() === "false") return undefined;
   if (trimmed.toLowerCase() === "auto") {
-    return activeIndex ? devpiRegistry(activeIndex) : undefined;
+    const list = typeof indexes === "string" ? [indexes] : (indexes ?? []);
+    for (const index of list) {
+      const registry = devpiRegistry(index);
+      if (registry) return registry;
+    }
+    return undefined;
   }
 
   const derived = devpiRegistry(trimmed);