@dbx-tools/projen 0.6.75 → 0.6.77

package/README.md

@@ -47,6 +47,44 @@ The engine treats generated barrels, tests, declaration files, and folders
 without exported source modules as implementation details. They do not create
 new package membership.
 
+## Add A Python uv Workspace
+
+`DBXToolsPythonWorkspace` attaches Python packaging to an existing projen root
+without turning Python packages into JavaScript workspace projects. It generates
+the root and member `pyproject.toml` files, standard `py:*` tasks, the VS Code
+interpreter setting, and an optional manual PyPI trusted-publishing workflow.
+
+```ts
+import { project, projectPy } from "@dbx-tools/projen";
+
+const root = new project.DBXToolsNodeProject({ name: "my-apps" });
+const repository = {
+  url: "https://github.com/example/my-apps.git",
+  ref: "main",
+  root: "python/packages",
+} as const;
+
+new projectPy.DBXToolsPythonWorkspace(root, {
+  repository,
+  packages: [
+    {
+      directory: "core",
+      name: "my-apps-core",
+      module: "my_apps.core",
+      description: "Shared Python helpers",
+    },
+  ],
+  interpreterPath: "${workspaceFolder}/python/.venv/bin/python",
+  release: true,
+});
+```
+
+Use `projectPy.pythonGitDependency(repository, name, directory)` for an internal
+dependency that must also resolve when a package is installed directly through a
+Git `#subdirectory=` URL. `root.vscode` is projen's existing VS Code component;
+dbx-tools reuses it rather than constructing a second `.vscode/settings.json`
+owner.
+
 ## Customize Packages With Mixins
 
 ```ts

package/index.ts

@@ -15,7 +15,9 @@ export * as openapi from "./src/openapi.ts";
 export * as packages from "./src/packages.ts";
 export * as pnpmWorkspace from "./src/pnpm-workspace.ts";
 export * as project from "./src/project.ts";
+export * as projectJs from "./src/project-js.ts";
 export * as projectPredicate from "./src/project-predicate.ts";
+export * as projectPy from "./src/project-py.ts";
 export * as publish from "./src/publish.ts";
 export * as release from "./src/release.ts";
 export * as scaffold from "./src/scaffold.ts";
@@ -23,15 +25,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 {
-  BUN_DEV_OVERRIDE,
-  BUN_BUILD_OVERRIDE,
-  BUN_APP_OVERRIDES,
-  RootBunfigFile,
-  BunfigFile,
-  BunDevServerFile,
-  BunBuildFile,
-} from "./src/bun-app.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";
 export { resolvePkgRoot } from "./src/engine-root.ts";
@@ -42,18 +36,11 @@ export { repoRoot, DEFAULT_PACKAGE_ROOTS, DiscoveredPackage } from "./src/packag
 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,
-  PROJEN_VERSION,
-  DBXToolsNodeProject,
-  DBXToolsTypeScriptProject,
-} from "./src/project.ts";
-export type {
-  DBXToolsProject,
-  DBXToolsProjectOptions,
-  DBXToolsTypeScriptProjectOptions,
-  ApplyToProjectsOptions,
-} from "./src/project.ts";
+export type { ApplyToProjectsOptions } from "./src/project.ts";
+export { PackageIdentifier, PROJEN_VERSION, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject } from "./src/project-js.ts";
+export type { DBXToolsProject, DBXToolsProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
+export { DBXToolsPythonWorkspace } from "./src/project-py.ts";
+export type { PythonRepositoryOptions, PythonPackageOptions, PythonReleaseOptions, DBXToolsPythonWorkspaceOptions } from "./src/project-py.ts";
 export { COMPILED_DIR, COMPILED_COMPILER_OPTIONS } from "./src/publish.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { StandaloneRelease, DBXToolsReleaseOptions } from "./src/release.ts";

package/package.json

@@ -26,9 +26,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "0.6.75",
-    "@dbx-tools/path": "0.6.75",
-    "@dbx-tools/shared-core": "0.6.75",
+    "@dbx-tools/core": "0.6.77",
+    "@dbx-tools/path": "0.6.77",
+    "@dbx-tools/shared-core": "0.6.77",
     "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.75",
+  "version": "0.6.77",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/bun-app.ts

@@ -1,8 +1,8 @@
 /**
  * Bun browser-app scaffolding as first-class projen file components.
  *
- * Replaces the old Vite toolchain (`vite.ts`). An `app`-tagged package gets three
- * generated, read-only files that stand in for `vite dev` / `vite build`:
+ * An `app`-tagged package gets three generated, read-only files that provide its
+ * whole dev/build toolchain:
  *
  * - {@link BunfigFile} - `bunfig.toml` wiring `bun-plugin-tailwind` into both the
  *   dev server (`[serve.static]`) and `Bun.build` (`[build]`) so Tailwind v4's
@@ -17,8 +17,7 @@
  * Each file supports an unmanaged OVERRIDE beside it (`bunfig.override.toml`,
  * `bun-dev.override.ts`, `bun-build.override.ts`): the dev/build scripts import
  * the override's default export and merge it over the generated options, so a
- * package tweaks its server/bundle WITHOUT editing the projen-owned file - the
- * same escape hatch the Vite generator offered via `vite.config.override.*`.
+ * package tweaks its server/bundle WITHOUT editing the projen-owned file.
  *
  * bun runs these `.ts` files directly. Being package-ROOT files (not under
  * `src/`), they are outside the package's `tsconfig` include, so their `Bun.*`
@@ -42,8 +41,7 @@ export const BUN_APP_OVERRIDES = ["bunfig.override.toml", BUN_DEV_OVERRIDE, BUN_
  * rejects passing a value built against one to an API typed by the other
  * ("separate declarations of a private property"). The hoisted linker de-dupes to
  * a single flat copy (npm-style), which is what keeps identity-based singletons
- * (AppKit `CacheManager`, Mastra classes, one React) coherent - the same coherence
- * the old cross-workspace `.pnpmfile.cjs` bridge used to guarantee.
+ * (AppKit `CacheManager`, Mastra classes, one React) coherent.
  */
 export class RootBunfigFile extends TextFile {
   constructor(project: Project) {

package/src/openapi.ts

@@ -5,7 +5,8 @@
  * (`from 'tsoa'` / `from '@tsoa/runtime'`) and, for each package that has them,
  * generates a read-only `<root>/openapi/<name>` package:
  *
- *   - `openapi.json`   - the OpenAPI 3 spec (tsoa `generateSpec`, from the types).
+ *   - `openapi.json`   - the OpenAPI 3 spec (tsoa `generateSpec`, then Speakeasy
+ *     optimization to extract duplicate inline schemas into components).
  *   - `src/schema.ts`  - types generated from the spec (openapi-typescript).
  *   - `src/client.ts`  - a typed `openapi-fetch` client, usable client-side.
  *
@@ -18,11 +19,23 @@
  * `tsoa`, `typescript`, and `openapi-typescript` are loaded lazily (heavy, and only
  * needed for `bun run openapi`), so importing this module stays cheap. `tsoa` and
  * `typescript` are not engine dependencies at all - both are resolved out of the
- * consuming workspace, which is where they already live.
+ * consuming workspace, which is where they already live. Speakeasy's `openapi`
+ * binary is installed lazily through `@dbx-tools/core`'s binary cache.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
+import { promisify } from "node:util";
+import { bin } from "@dbx-tools/core";
 import { find } from "@dbx-tools/path";
 import { log } from "@dbx-tools/shared-core";
 import type * as ts from "typescript";
@@ -42,6 +55,9 @@ const logger = log.logger("projen:openapi");
 const OPENAPI_TAG = "openapi";
 /** Heuristic: a module file whose source imports tsoa's runtime package. */
 const TSOA_IMPORT = /from\s+['"](?:tsoa|@tsoa\/runtime)['"]/;
+const SPEAKEASY_OPENAPI_VERSION = "1.24.0";
+const SPEAKEASY_OPENAPI_RELEASE_URL = `https://github.com/speakeasy-api/openapi/releases/download/v${SPEAKEASY_OPENAPI_VERSION}`;
+const execFileAsync = promisify(execFile);
 
 const CLIENT_SRC = `import createClient, { type ClientOptions } from "openapi-fetch";
 import type { paths } from "./schema";
@@ -78,6 +94,48 @@ export function isTsoaController(path: string): boolean {
   );
 }
 
+/** GitHub release asset name for Speakeasy's OpenAPI binary. */
+export function speakeasyOpenapiAssetName(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string {
+  const osName =
+    platform === "darwin"
+      ? "Darwin"
+      : platform === "linux"
+        ? "Linux"
+        : platform === "win32"
+          ? "Windows"
+          : undefined;
+  const archName = arch === "arm64" ? "arm64" : arch === "x64" ? "x86_64" : undefined;
+  if (!osName || !archName) {
+    throw new Error(`Speakeasy openapi has no supported release asset for ${platform}/${arch}`);
+  }
+  const extension = platform === "win32" ? "zip" : "tar.gz";
+  return `openapi_${osName}_${archName}.${extension}`;
+}
+
+async function speakeasyOpenapiPath(): Promise<string> {
+  const assetName = speakeasyOpenapiAssetName();
+  const context = await bin.ensure("openapi", `${SPEAKEASY_OPENAPI_RELEASE_URL}/${assetName}`, {
+    autoUnpackage: true,
+    minVersion: SPEAKEASY_OPENAPI_VERSION,
+    selector: ({ source }) =>
+      join(source, process.platform === "win32" ? "openapi.exe" : "openapi"),
+    versionParser: (output) => {
+      const version = bin.parseVersion(output);
+      return version === SPEAKEASY_OPENAPI_VERSION ? version : undefined;
+    },
+  });
+  return context.path;
+}
+
+/** Deduplicate inline schemas into `components.schemas` with Speakeasy. */
+export async function optimizeOpenapiSpec(specPath: string, executable?: string): Promise<void> {
+  const openapi = executable ?? (await speakeasyOpenapiPath());
+  await execFileAsync(openapi, ["spec", "optimize", specPath, "--write", "--non-interactive"]);
+}
+
 /**
  * Regenerate the `openapi` packages from every server/node package with a tsoa
  * import. Returns the package dirs it wrote so the caller can rebuild their barrels.
@@ -118,28 +176,37 @@ export async function generateOpenapi(): Promise<string[]> {
   const written: string[] = [];
   for (const p of pkgs) {
     // The generated package's folder is the source's leaf folder name (`api`), not
-    // its npm name - `p.name` is now the (possibly-overridden) manifest name.
+    // its npm name - `p.name` is the (possibly-overridden) manifest name.
     const leaf = p.relPath.split("/").pop() ?? p.relPath;
     const outDir = join(repoRoot, p.root, OPENAPI_TAG, leaf);
     const srcDir = join(outDir, "src");
     mkdirSync(srcDir, { recursive: true });
 
-    // 1) tsoa writes <outDir>/openapi.json from the controllers' decorators + types.
+    // 1) tsoa writes a temporary openapi.json, Speakeasy optimizes it there, then
+    // the complete spec moves into place so readers never observe an intermediate file.
     const specPath = join(outDir, "openapi.json");
-    makeWritable(specPath);
-    await generateSpec(
-      {
-        entryFile: "",
-        noImplicitAdditionalProperties: "throw-on-extras",
-        controllerPathGlobs: [join(p.dir, "src/**/*.ts")],
-        outputDirectory: outDir,
-        specFileBaseName: "openapi",
-        specVersion: 3,
-        name: `${p.relPath} API`,
-        version: "0.0.0",
-      },
-      compilerOptions,
-    );
+    const tempDir = mkdtempSync(join(outDir, ".openapi-"));
+    const tempSpecPath = join(tempDir, "openapi.json");
+    try {
+      await generateSpec(
+        {
+          entryFile: "",
+          noImplicitAdditionalProperties: "throw-on-extras",
+          controllerPathGlobs: [join(p.dir, "src/**/*.ts")],
+          outputDirectory: tempDir,
+          specFileBaseName: "openapi",
+          specVersion: 3,
+          name: `${p.relPath} API`,
+          version: "0.0.0",
+        },
+        compilerOptions,
+      );
+      await optimizeOpenapiSpec(tempSpecPath);
+      makeWritable(specPath);
+      renameSync(tempSpecPath, specPath);
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
     makeReadonly(specPath);
 
     // 2) src/schema.ts: types generated from the spec (openapi-typescript).
@@ -148,7 +215,7 @@ export async function generateOpenapi(): Promise<string[]> {
     makeWritable(schemaPath);
     writeFileSync(schemaPath, astToString(await openapiTS(spec)));
     stampGenerated(schemaPath, {
-      tool: "projen openapi (tsoa + openapi-typescript)",
+      tool: "projen openapi (tsoa + Speakeasy + openapi-typescript)",
       source: `the tsoa controllers in ${p.relPath}`,
     });