@dbx-tools/projen 0.6.75 → 0.6.76

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.76",
+    "@dbx-tools/path": "0.6.76",
+    "@dbx-tools/shared-core": "0.6.76",
     "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.76",
   "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}`,
     });
 

package/src/project.ts

@@ -203,8 +203,8 @@ export function applyTasks(pkg: javascript.NodeProject, tasks?: Record<string, T
  */
 export function applyExports(pkg: javascript.NodeProject, exports: Record<string, string>): void {
   pkg.package.addField("exports", exports);
-  // Keep the legacy entry points honest about the map that just replaced them.
-  // A subpath-only surface (the `ui` tag's `./react` + `./styles.css`) has no
+  // Keep the `main`/`types` entry points consistent with the map. A subpath-only
+  // surface (the `ui` tag's `./react` + `./styles.css`) has no
   // `.` export, so the constructor's `main`/`types` would keep advertising a
   // root entry that every exports-aware resolver ignores - the contradiction
   // publint reports as "exports is missing the root entrypoint".
@@ -673,8 +673,8 @@ export class DBXToolsTypeScriptProject
     // `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
     // directory auto-discovers `*.test.ts` recursively. But `bun test` EXITS 1
-    // when it matches no files (unlike the old `tsx --test 'glob'`, which was a
-    // no-op), so guard it: only invoke when a `*.test.ts` exists, else succeed.
+    // when it matches no files, so guard it: only invoke when a `*.test.ts`
+    // exists, else succeed.
     this.testTask.exec("bun test test", {
       condition: 'find test -name "*.test.ts" 2>/dev/null | grep -q .',
     });

package/src/release.ts

@@ -88,9 +88,9 @@ function publishSetupSteps(): JobStep[] {
  *
  * Declaring one also enlists it in the root's `bump`, which cuts BOTH tags at one
  * shared version. The separate tag namespace still lets it be released alone
- * (`cd <directory> && bun run bump`) for a consumer who wants only this package -
- * but a routine root bump no longer leaves it behind, which is how the engine
- * drifted to 0.1.24 while the packages reached 0.3.41.
+ * (`cd <directory> && bun run bump`) for a consumer who wants only this package.
+ * Enlisting it is what keeps a routine root bump from leaving it behind and letting
+ * its version drift away from the packages'.
  */
 export interface StandaloneRelease {
   /** Workflow name (and `.github/workflows/<name>.yml` file). E.g. `projen-release`. */

package/src/tags.ts

@@ -105,7 +105,7 @@ export const PACKAGE_TAG_MIXINS = {
       // generated `dev.ts`/`build.ts` use; no `vite/client`.
       types: ["bun"],
       // `@/` -> `src/` alias, resolved by both tsc and bun's bundler (bun reads
-      // tsconfig `paths`). Replaces the old Vite `resolve.alias` for `@`.
+      // tsconfig `paths`).
       baseUrl: ".",
       paths: { "@/*": ["./src/*"] },
     });

package/src/tsconfig.ts

@@ -5,9 +5,9 @@ import { Component, JsonFile, type Project, javascript } from "projen";
 
 /**
  * Compiler options for the ROOT program only (`.projenrc.ts` + the engine as
- * seen from the root). Each package now owns its own projen-generated
+ * seen from the root). Each package owns its own projen-generated
  * `tsconfig.json` (scope `lib`/`jsx`/`types` overlaid on projen's defaults), so
- * this base no longer feeds packages - it just gives the projenrc/editor program
+ * this base does not feed packages - it just gives the projenrc/editor program
  * a sane ESM config. `lib` is set narrowly in the root `tsconfig.json`.
  */
 const BASE_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {