@dbx-tools/projen 0.1.1 → 0.3.43

package/src/release.ts

@@ -0,0 +1,236 @@
+/**
+ * Release wiring: registers the `bump` task on a project (compute next version +
+ * commit + tag + push), parameterized by the project's git tag prefix, and - when
+ * the project has a GitHub component - authors the tag-driven npm publish
+ * workflow that the pushed tag triggers.
+ */
+import { Component } from "projen";
+import { GithubWorkflow } from "projen/lib/github";
+import { JobPermission } from "projen/lib/github/workflows-model";
+import { applyTasks, taskScript, type DBXToolsNodeProject } from "./project";
+
+/**
+ * A standalone project that lives in a repo SUBDIRECTORY but is NOT a member of
+ * this pnpm workspace (e.g. the `@dbx-tools/projen` engine in `projen/`), yet
+ * still needs a release workflow. GitHub Actions only runs workflows from the
+ * REPO-ROOT `.github/`, so the workflow for such a project is authored here,
+ * alongside the root's own `release` workflow, under a distinct name + tag
+ * prefix so the two never collide. Tag-driven and pack-based: push
+ * `<tagPrefix>1.2.3` and the single package in `directory` is published at 1.2.3
+ * via `npm pack` + `npm publish`.
+ *
+ * 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> && pnpm 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.
+ */
+export interface StandaloneRelease {
+  /** Workflow name (and `.github/workflows/<name>.yml` file). E.g. `projen-release`. */
+  readonly name: string;
+  /** Repo-relative directory of the standalone project. E.g. `projen`. */
+  readonly directory: string;
+  /**
+   * Git tag prefix that triggers this release, disjoint from the root's `v*`
+   * (e.g. `projen-v`). The pushed tag IS the published version.
+   */
+  readonly tagPrefix: string;
+}
+
+/** Options for {@link DBXToolsRelease}. */
+export interface DBXToolsReleaseOptions {
+  /**
+   * Git tag prefix for this project's releases (e.g. `v` or `projen-v`). The
+   * `bump` task reads/writes `<prefix><version>` tags, keeping sibling projects
+   * in the same repo on disjoint tag namespaces. Defaults to `v`.
+   */
+  readonly tagPrefix?: string;
+  /**
+   * Standalone in-repo projects (NOT workspace members) that each get their own
+   * tag-driven release workflow authored alongside the root's - see
+   * {@link StandaloneRelease}. Authored only when the project has a GitHub
+   * component. Defaults to none.
+   */
+  readonly standaloneReleases?: readonly StandaloneRelease[];
+}
+
+/**
+ * Adds a `bump` task: compute the next release version (from the higher of the
+ * latest `<prefix>*` git tag and the local `package.json`), then commit, tag,
+ * and push it - pushing the tag is what triggers the release workflow. Each step
+ * is toggleable (`--no-version` / `--no-commit` / `--no-tag` / `--no-push` /
+ * `--no-publish`); see `tasks/bump.ts`.
+ *
+ * When the project has a GitHub component (`github: true`), also authors the
+ * `release` workflow: on a pushed `<prefix>*` tag it sets that version on every
+ * publishable package and runs `pnpm -r publish` (which skips
+ * `private` packages and honors each package's `publishConfig`).
+ *
+ * Provenance is opt-in. Each package's generated `publishConfig` omits
+ * `provenance`, so LOCAL publishes (e.g. to a verdaccio) never try to attest -
+ * npm has no CI OIDC provider off-CI and would fail with `provider: null`. This
+ * CI workflow turns it on with `npm_config_provenance=true`, backed by the
+ * `id-token: write` permission that lets npm mint the OIDC token.
+ *
+ * Registry AUTH is still `NPM_TOKEN`, deliberately. OIDC here mints the
+ * provenance attestation only; full npm trusted publishing would additionally
+ * replace the token, but it has to be registered per package on npmjs.com
+ * against an exact repo + workflow filename, and this repo publishes 26 of
+ * them. That is a considered deferral, not an oversight - do not "fix" it by
+ * dropping the token without doing the registrations first, or every publish
+ * fails.
+ */
+export class DBXToolsRelease extends Component {
+  private readonly tagPrefix: string;
+  private readonly standaloneReleases: readonly StandaloneRelease[];
+
+  constructor(project: DBXToolsNodeProject, options: DBXToolsReleaseOptions = {}) {
+    super(project);
+    this.tagPrefix = options.tagPrefix ?? "v";
+    this.standaloneReleases = options.standaloneReleases ?? [];
+  }
+
+  public override preSynthesize(): void {
+    const project = this.project as DBXToolsNodeProject;
+    // Release the standalone projects in the SAME run, at the same version. They
+    // are not workspace members, so nothing else would ever bring them along.
+    const siblingArgs = this.standaloneReleases
+      .map(({ directory, tagPrefix }) => ` --sibling ${directory}:${tagPrefix}`)
+      .join("");
+    applyTasks(project, {
+      bump: {
+        exec: taskScript(project, "bump.ts", `--prefix ${this.tagPrefix}${siblingArgs}`),
+        receiveArgs: true,
+        description: "Bump the release version (default patch), then commit, tag, and push it",
+      },
+    });
+
+    // Author the tag-driven publish workflows only when GitHub is enabled - they
+    // live in `.github/`, which requires projen's GitHub component.
+    if (project.github) {
+      this.authorReleaseWorkflow(project);
+      for (const standalone of this.standaloneReleases) {
+        this.authorStandaloneReleaseWorkflow(project, standalone);
+      }
+    }
+  }
+
+  /**
+   * Emit the `release` GitHub workflow: push `<prefix>1.2.3` and every
+   * publishable package is published to npm at 1.2.3. Setting the
+   * version on every package first makes the pushed tag the published version
+   * (no bump math).
+   */
+  private authorReleaseWorkflow(project: DBXToolsNodeProject): void {
+    const workflow = new GithubWorkflow(project.github!, "release", {
+      // Serialize publishes so two tags landing together cannot race to the
+      // registry, but never cancel a run already in flight: a half-published
+      // release is worse than a queued one.
+      limitConcurrency: true,
+      concurrencyOptions: { group: "release", cancelInProgress: false },
+    });
+    // Read-only floor for any job that does not declare its own permissions;
+    // the publish job below overrides it with the `id-token` it needs.
+    workflow.file?.addOverride("permissions", { contents: "read" });
+    workflow.on({ push: { tags: [`${this.tagPrefix}*`] } });
+    workflow.addJob("publish", {
+      runsOn: ["ubuntu-latest"],
+      // `id-token: write` lets npm mint the OIDC token for provenance attestation.
+      permissions: { contents: JobPermission.READ, idToken: JobPermission.WRITE },
+      timeoutMinutes: 30,
+      env: { CI: "true" },
+      steps: [
+        { name: "Checkout", uses: "actions/checkout@v6", with: { "fetch-depth": 0 } },
+        { name: "Setup pnpm", uses: "pnpm/action-setup@v5", with: { version: "10.33.0" } },
+        {
+          name: "Setup Node.js",
+          uses: "actions/setup-node@v6",
+          with: { "node-version": "lts/*", "registry-url": "https://registry.npmjs.org" },
+        },
+        // NOT frozen. The lockfile is gitignored by policy (it can carry a
+        // private-registry fingerprint), so CI often has none or a stale one -
+        // and `--frozen-lockfile` turns that into a hard release failure rather
+        // than resolving. A blocked publish is worse here than a resolved one.
+        { name: "Install", run: "pnpm install --no-frozen-lockfile" },
+        // The pushed tag is the version: `<prefix>1.2.3` -> `1.2.3`. Set it on
+        // every package (manifests are projen-readonly, so unlock them first).
+        {
+          name: "Set version from tag",
+          run: [
+            `VERSION="\${GITHUB_REF_NAME#${this.tagPrefix}}"`,
+            "chmod -R u+w . || true",
+            'pnpm -r exec npm version "$VERSION" --no-git-tag-version --allow-same-version',
+          ].join("\n"),
+        },
+        {
+          name: "Publish to npm",
+          // `pnpm -r publish` publishes every non-private package,
+          // rewriting `workspace:*` deps to the published version. Provenance is
+          // opt-in (omitted from each package's `publishConfig` so local
+          // publishes work); CI turns it on here via `npm_config_provenance`.
+          run: "pnpm -r publish --no-git-checks --access public",
+          env: {
+            NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}",
+            npm_config_provenance: "true",
+          },
+        },
+      ],
+    });
+  }
+
+  /**
+   * Emit a {@link StandaloneRelease}'s workflow: push `<prefix>1.2.3` and the
+   * single package in `directory` (a non-workspace-member project) is published
+   * at 1.2.3 via `npm pack` + `npm publish`. Its `package.json` is
+   * projen-generated read-only, so it is unlocked before `npm version` rewrites
+   * it. No bump math - the pushed tag IS the published version.
+   */
+  private authorStandaloneReleaseWorkflow(
+    project: DBXToolsNodeProject,
+    { name, directory, tagPrefix }: StandaloneRelease,
+  ): void {
+    const workflow = new GithubWorkflow(project.github!, name, {
+      limitConcurrency: true,
+      concurrencyOptions: { group: name, cancelInProgress: false },
+    });
+    workflow.file?.addOverride("permissions", { contents: "read" });
+    workflow.on({ push: { tags: [`${tagPrefix}*`] } });
+    workflow.addJob("publish", {
+      runsOn: ["ubuntu-latest"],
+      // `id-token: write` lets npm mint the OIDC token for provenance attestation.
+      permissions: { contents: JobPermission.READ, idToken: JobPermission.WRITE },
+      timeoutMinutes: 30,
+      defaults: { run: { workingDirectory: directory } },
+      env: { CI: "true" },
+      steps: [
+        { name: "Checkout", uses: "actions/checkout@v6", with: { "fetch-depth": 0 } },
+        { name: "Setup pnpm", uses: "pnpm/action-setup@v5", with: { version: "10.33.0" } },
+        {
+          name: "Setup Node.js",
+          uses: "actions/setup-node@v6",
+          with: { "node-version": "lts/*", "registry-url": "https://registry.npmjs.org" },
+        },
+        // NOT frozen. The lockfile is gitignored by policy (it can carry a
+        // private-registry fingerprint), so CI often has none or a stale one -
+        // and `--frozen-lockfile` turns that into a hard release failure rather
+        // than resolving. A blocked publish is worse here than a resolved one.
+        { name: "Install", run: "pnpm install --no-frozen-lockfile" },
+        // The pushed tag is the version: `<prefix>1.2.3` -> `1.2.3`. package.json
+        // is projen-generated read-only, so unlock it before `npm version` writes.
+        {
+          name: "Set version from tag",
+          run: [
+            "chmod u+w package.json",
+            `npm version "\${GITHUB_REF_NAME#${tagPrefix}}" --no-git-tag-version --allow-same-version`,
+          ].join("\n"),
+        },
+        { name: "Pack", run: "pnpm pack --pack-destination dist/js" },
+        {
+          name: "Publish to npm",
+          run: "npm publish dist/js/*.tgz --access public",
+          env: { NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}" },
+        },
+      ],
+    });
+  }
+}

package/src/scaffold.ts

@@ -0,0 +1,34 @@
+/**
+ * Runs a projen re-synth, for the `sync` task and its watchers.
+ */
+import { join } from "node:path";
+import { exec } from "@dbx-tools/core";
+import { repoRoot } from "./packages";
+
+/**
+ * Re-run projen synth by executing `.projenrc.ts` with `node --import tsx` (no
+ * projen network re-exec).
+ *
+ * `post: true` runs the full flow - projen's post-synth `pnpm install` AND the
+ * post-synth barrels component - which is what the one-shot `sync` task
+ * wants. The default (`post: false`) sets `PROJEN_DISABLE_POST`, skipping both so
+ * the watch loop stays fast; there the caller rebuilds barrels explicitly.
+ *
+ * Deliberately never forces `CI: "true"` here: besides pnpm's own no-TTY prompt,
+ * `CI` also makes pnpm choose a `--frozen-lockfile` install for a MULTI-package
+ * workspace's subprojects, which is the wrong tradeoff for routine re-synths (a
+ * newly added/edited package's lockfile entry is expected to be behind). A caller
+ * that needs the no-TTY prompt answered non-interactively (the `dbx-tools` CLI, when
+ * bootstrapping an empty folder) runs with `post: false` and does its own install
+ * afterward instead.
+ */
+export function runSynth(options: { post?: boolean } = {}): void {
+  const env = { ...process.env };
+  if (options.post) delete env.PROJEN_DISABLE_POST;
+  else env.PROJEN_DISABLE_POST = "true";
+  exec.spawnSync(process.execPath, ["--import", "tsx", join(repoRoot, ".projenrc.ts")], {
+    cwd: repoRoot,
+    env,
+    check: true,
+  });
+}

package/src/tags.ts

@@ -0,0 +1,172 @@
+/**
+ * Tags, expressed as MIXINS (`constructs` `IMixin`).
+ *
+ * A tag names a target environment (React/Vite, Node, agnostic, ...) - modeled on
+ * `databricks apps init` (AppKit): `ui`, `server`, `shared`. Any `src`-bearing folder
+ * under a package root is discovered automatically; path-derived tag
+ * candidates plus `packageTagPaths` decide which mixins apply. ("Scope" is
+ * reserved for the npm `@scope/` in package names.)
+ *
+ * Mixin factories live in {@link ./mixin}; package predicates live in {@link ./project}
+ * ({@link projectPredicate.hasTag}).
+ * The per-tag table is {@link PACKAGE_TAG_MIXINS}. Apply with the constructs-native `project.with(...)`
+ * across the subtree; the root applies built-in tag mixins during construction and
+ * callers add their own afterward.
+ */
+import type { IMixin as ConstructsMixin } from "constructs";
+import { DependencyType, javascript } from "projen";
+import { addCliBinLaunchers } from "./cli-bin";
+import { create } from "./mixin";
+import {
+  addPackageFiles,
+  applyCompilerOptions,
+  applyExports,
+  applyIncludes,
+  applyTasks,
+  srcModuleExports,
+} from "./project";
+import * as projectPredicate from "./project-predicate";
+import { ViteConfigFile } from "./vite";
+
+/** Node compiler options: ES2022 lib + node types, deliberately no DOM. */
+const NODE_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {
+  target: "ES2022",
+  lib: ["ES2022"],
+  types: ["node"],
+};
+
+/** The DOM-capable lib list shared by the browser tags (`ui`, `openapi`). */
+const DOM_LIB = ["ES2022", "DOM", "DOM.Iterable"];
+
+/**
+ * The agnostic floor every package gets at construction: ES2022 stdlib plus the
+ * web-platform globals available in every JS runtime (browser, workers, Node 18+)
+ * via the `WebWorker` lib - `AbortController`/`AbortSignal`, `URL`, `crypto`, the
+ * timer functions, `fetch`, `TextEncoder`, etc. Deliberately NO `DOM` lib (no
+ * `document`/`window`) and no node types, so agnostic code stays isomorphic. Also
+ * the whole config the `shared` tag applies.
+ */
+export const AGNOSTIC_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {
+  target: "ES2022",
+  lib: ["ES2022", "WebWorker"],
+  types: [],
+};
+
+/**
+ * The tag table, as mixins. Each entry configures every package carrying
+ * that tag (deps + tsconfig + tasks) when applied via `project.with(...)`. The keys
+ * are the known tag names; a package carrying a given tag receives its mixin when
+ * that tag appears in `dbxToolsConfig.tags`. Select which apply with the `defaultTagMixins` option (`false` = none,
+ * or a subset list; unselected packages fall back to {@link AGNOSTIC_COMPILER_OPTIONS}).
+ */
+export const PACKAGE_TAG_MIXINS = {
+  // `ui`: a React COMPONENT LIBRARY (source-first, consumed by apps) - modeled
+  // on `@databricks/appkit-ui`. React + DOM lib + JSX, and the default `tsc`
+  // compile (typecheck). No vite app build / index.html: a full browser app is an
+  // `app`-tagged package (see below) that layers vite on top.
+  ui: create(projectPredicate.hasTag("ui"), (p) => {
+    p.addDeps("react@catalog:", "react-dom@catalog:");
+    p.addDevDeps("@types/react@catalog:", "@types/react-dom@catalog:");
+    applyCompilerOptions(p, {
+      target: "ES2022",
+      lib: [...DOM_LIB],
+      jsx: javascript.TypeScriptJsxMode.REACT_JSX,
+    });
+    // A component library's standard subpath surface: `./react` (components),
+    // `./styles.css` (Tailwind entry), and `./package.json`. A package that
+    // ships more (e.g. ui-appkit's `./vite` preset) overrides this in its own
+    // mixin; an `app`-tagged package replaces it with a `.` root (see below).
+    applyExports(p, {
+      "./react": "./src/react/index.ts",
+      "./styles.css": "./src/styles.css",
+      "./package.json": "./package.json",
+    });
+  }),
+  // `app`: a full browser app built + served by Vite (needs an `index.html`
+  // entry). Self-contained React app: React + DOM lib + JSX + the vite toolchain
+  // and app tasks (`dev`/`build`/`preview`). `build` resets the compile task, so
+  // `compile` bundles with vite rather than `tsc`.
+  app: create(projectPredicate.hasTag("app"), (p) => {
+    p.addDeps("react@catalog:", "react-dom@catalog:");
+    p.addDevDeps(
+      "vite@catalog:",
+      "@vitejs/plugin-react@catalog:",
+      "@types/react@catalog:",
+      "@types/react-dom@catalog:",
+    );
+    applyCompilerOptions(p, {
+      target: "ES2022",
+      lib: [...DOM_LIB],
+      jsx: javascript.TypeScriptJsxMode.REACT_JSX,
+      types: ["vite/client"],
+    });
+    applyTasks(p, {
+      dev: { exec: "vite" },
+      build: { exec: "vite build" },
+      preview: { exec: "vite preview" },
+    });
+    new ViteConfigFile(p);
+    // An app has a single root entry, not a component library's subpaths - so it
+    // replaces the `ui` tag's `./react`/`./styles.css` surface with a `.` root.
+    applyExports(p, {
+      ".": "./index.ts",
+      "./package.json": "./package.json",
+    });
+  }),
+  cli: create(projectPredicate.hasTag("cli"), (p) => {
+    // tsx is a RUNTIME dep, not a dev one: a CLI's bin is a `.ts` entry that needs
+    // the tsx loader registered before it can run, and an installed consumer
+    // (`npm i -g`) has no other source for it. Drop the baseline devDep so it isn't
+    // declared in both blocks. The generated `.mjs` launchers are what actually
+    // reach it - see {@link addCliBinLaunchers}.
+    p.deps.removeDependency("tsx", DependencyType.BUILD);
+    p.addDeps("commander@catalog:", "@clack/prompts@catalog:", "tsx@catalog:");
+    p.addDevDeps("@types/node@catalog:");
+    addCliBinLaunchers(p);
+    // A CLI compiles code OUTSIDE `src/` - its root `index.ts` barrel and the
+    // `bin/` entries - which the src-only tag default doesn't reach, so the
+    // tsconfig is rooted at the package instead.
+    applyCompilerOptions(p, { ...NODE_COMPILER_OPTIONS, rootDir: "." });
+    applyIncludes(p, "index.ts", "bin/**/*.ts");
+    // A CLI's standard surface: the `.` root entry, a `./<module>` subpath per
+    // top-level `src` module, and `./package.json`. Derived rather than declared
+    // so no CLI has to hand-list its own modules.
+    applyExports(p, {
+      ".": "./index.ts",
+      ...srcModuleExports(p),
+      "./package.json": "./package.json",
+    });
+    // A CLI is the one shape whose entry point lives outside `src`, so its
+    // launchers have to be added to the tarball allowlist explicitly.
+    addPackageFiles(p, "bin");
+  }),
+  server: create(projectPredicate.hasTag("server"), (p) => {
+    // A Node/Express service. tsoa's decorators (@Route/@Get/...) also drive
+    // the `openapi` task (spec + client); experimentalDecorators lets them
+    // type-check. `dev`/`start` run the app's `src/server.ts` with tsx.
+    p.addDeps("express@catalog:", "tsoa@catalog:");
+    p.addDevDeps("@types/node@catalog:", "@types/express@catalog:");
+    applyCompilerOptions(p, {
+      ...NODE_COMPILER_OPTIONS,
+      experimentalDecorators: true,
+    });
+    applyTasks(p, {
+      dev: { exec: "tsx watch src/server.ts" },
+      start: { exec: "tsx src/server.ts" },
+    });
+  }),
+  node: create(projectPredicate.hasTag("node"), (p) => {
+    p.addDevDeps("@types/node@catalog:");
+    applyCompilerOptions(p, NODE_COMPILER_OPTIONS);
+  }),
+  shared: create(projectPredicate.hasTag("shared"), (p) => {
+    applyCompilerOptions(p, AGNOSTIC_COMPILER_OPTIONS);
+  }),
+  openapi: create(projectPredicate.hasTag("openapi"), (p) => {
+    p.addDeps("openapi-fetch@catalog:");
+    applyCompilerOptions(p, { target: "ES2022", lib: [...DOM_LIB], types: [] });
+  }),
+} satisfies Record<string, ConstructsMixin>;
+
+/** A known tag name (a key of {@link PACKAGE_TAG_MIXINS}). */
+export type PackageTag = keyof typeof PACKAGE_TAG_MIXINS;

package/src/tsconfig.ts

@@ -0,0 +1,60 @@
+/**
+ * Root `tsconfig.base.json` and `tsconfig.json` for the projenrc program.
+ */
+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
+ * `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
+ * a sane ESM config. `lib` is set narrowly in the root `tsconfig.json`.
+ */
+const BASE_COMPILER_OPTIONS: javascript.TypeScriptCompilerOptions = {
+  target: "ESNext",
+  module: "ESNext",
+  moduleResolution: javascript.TypeScriptModuleResolution.BUNDLER,
+  moduleDetection: javascript.TypeScriptModuleDetection.FORCE,
+  allowJs: true,
+  esModuleInterop: true,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  allowImportingTsExtensions: true,
+  noEmit: true,
+  strict: true,
+  skipLibCheck: true,
+  forceConsistentCasingInFileNames: true,
+  noUncheckedIndexedAccess: true,
+  noImplicitOverride: true,
+  noFallthroughCasesInSwitch: true,
+};
+
+/**
+ * Emits `tsconfig.base.json` and `tsconfig.json` for the monorepo root program.
+ * Packages type-check against their own projen-generated tsconfigs via `compile`.
+ */
+export class DBXToolsRootTsconfig extends Component {
+  constructor(scope: Project) {
+    super(scope);
+
+    new JsonFile(scope, "tsconfig.base.json", {
+      marker: true,
+      readonly: true,
+      obj: { compilerOptions: BASE_COMPILER_OPTIONS },
+    });
+
+    new JsonFile(scope, "tsconfig.json", {
+      marker: true,
+      readonly: true,
+      obj: {
+        extends: "./tsconfig.base.json",
+        compilerOptions: {
+          lib: ["ESNext"],
+          types: ["node"],
+        } satisfies javascript.TypeScriptCompilerOptions,
+        include: [".projenrc.ts"],
+        exclude: ["node_modules", "**/dist", "**/node_modules"],
+      },
+    });
+  }
+}

package/src/vite.ts

@@ -0,0 +1,91 @@
+/**
+ * `vite.config.ts` as a first-class projen file component.
+ *
+ * {@link ViteConfigFile} extends projen's `TextFile` and emits a generated,
+ * read-only Vite config: the React plugin plus a runtime OVERRIDE chain. At Vite
+ * startup the generated config looks for each unmanaged override module sitting
+ * beside it (default {@link DEFAULT_VITE_OVERRIDES}: `vite.config.override.js`) and, when present, merges that module's default export
+ * over the generated config with Vite's `mergeConfig` - in listed order, so later
+ * files win and absent ones are skipped. A package thus tweaks Vite WITHOUT editing
+ * the projen-owned file.
+ *
+ * The override modules are `.js` because Vite loads them via a plain dynamic
+ * `import()` at config time. Being a package-ROOT file (not under `src/`), the
+ * generated `vite.config.ts` is excluded from the package's `tsconfig` `include`, so
+ * its `node:*` usage never trips the `ui` package's `compile` under the DOM-only
+ * tsconfig; Vite transpiles it with esbuild and runs it in Node at config time.
+ */
+import { type Project, TextFile } from "projen";
+
+/**
+ * Default unmanaged override modules, merged over the generated config in order
+ * (later wins, absent files skipped): a package's `vite.config.override.js`.
+ */
+const DEFAULT_VITE_OVERRIDES = ["vite.config.override.js"];
+
+/** Render the generated `vite.config.ts` source with the override chain inlined. */
+function renderViteConfig(overridePaths: string[]): string {
+  const overrides = overridePaths.map((path) => `  ${JSON.stringify(path)},`).join("\n");
+  return String.raw`
+import { existsSync } from "node:fs";
+import react from "@vitejs/plugin-react";
+import {
+  defineConfig,
+  mergeConfig,
+  type ConfigEnv,
+  type UserConfig,
+  type UserConfigExport,
+} from "vite";
+
+// Unmanaged override modules (relative to this file), merged over the generated
+// config in order - later wins, absent files are skipped.
+const OVERRIDE_FILES = [
+${overrides}
+];
+
+async function resolveConfig(
+  config: UserConfigExport,
+  env: ConfigEnv,
+): Promise<UserConfig> {
+  if (typeof config === "function") {
+    return await config(env);
+  }
+  return await config;
+}
+
+export default defineConfig(async (configEnv: ConfigEnv) => {
+  let config: UserConfig = {
+    plugins: [react()],
+  };
+
+  for (const file of OVERRIDE_FILES) {
+    const overrideUrl = new URL(file, import.meta.url);
+    if (!existsSync(overrideUrl)) {
+      continue;
+    }
+    const overrideModule = await import(overrideUrl.href);
+    const override = await resolveConfig(
+      overrideModule.default as UserConfigExport,
+      configEnv,
+    );
+    config = mergeConfig(config, override);
+  }
+
+  return config;
+});
+`.trimStart();
+}
+
+/**
+ * A projen-owned, read-only `vite.config.ts` (React + the runtime override merge
+ * chain described in the module docstring).
+ */
+export class ViteConfigFile extends TextFile {
+  constructor(project: Project) {
+    super(project, "vite.config.ts", {
+      marker: true,
+      readonly: true,
+      lines: renderViteConfig(DEFAULT_VITE_OVERRIDES).split("\n"),
+    });
+  }
+}

package/src/vscode.ts

@@ -0,0 +1,69 @@
+/**
+ * Root `.vscode/*` files: settings, extension recommendations, and tasks.
+ *
+ * Prettier is projen's built-in component (not emitted here). The auto-run watcher
+ * is delivered by `.vscode/tasks.json` (`runOn: folderOpen`) - projen has no native
+ * tasks.json component, so a `JsonFile` is the idiomatic emitter.
+ */
+import { Component, JsonFile, type Project, vscode } from "projen";
+
+/**
+ * Configures root `.vscode/settings.json`, `extensions.json`, and `tasks.json`.
+ * Only a tree ROOT constructs this component (see {@link DBXToolsNodeProject}).
+ */
+export class DBXToolsVsCode extends Component {
+  /** projen's built-in VsCode component (settings + extension recommendations). */
+  readonly vsCode: vscode.VsCode;
+
+  constructor(scope: Project) {
+    super(scope);
+
+    this.vsCode = new vscode.VsCode(scope);
+    this.vsCode.settings.addSettings({
+      "typescript.tsdk": "node_modules/typescript/lib",
+      "typescript.preferences.importModuleSpecifier": "non-relative",
+      "javascript.preferences.importModuleSpecifier": "non-relative",
+      "editor.formatOnSave": true,
+      "editor.defaultFormatter": "esbenp.prettier-vscode",
+      "files.watcherExclude": {
+        "**/node_modules/**": true,
+        "**/dist/**": true,
+      },
+    });
+    this.vsCode.extensions.addRecommendations("esbenp.prettier-vscode");
+    this.vsCode.settings.file.readonly = true;
+    this.vsCode.extensions.file.readonly = true;
+
+    new JsonFile(scope, ".vscode/tasks.json", {
+      marker: false,
+      readonly: true,
+      obj: {
+        version: "2.0.0",
+        tasks: [
+          {
+            label: "sync",
+            detail:
+              "projen sync --watch - projenrc (.projenrc.ts + syncResynthPaths re-synth) + barrels + openapi watchers",
+            type: "shell",
+            command: "pnpm exec projen sync --watch",
+            isBackground: true,
+            problemMatcher: [],
+            runOptions: { runOn: "folderOpen" },
+            presentation: {
+              reveal: "always",
+              panel: "dedicated",
+              group: "projen",
+            },
+          },
+          {
+            label: "synth",
+            detail: "projen - synthesize all generated config",
+            type: "shell",
+            command: "pnpm exec projen",
+            problemMatcher: [],
+          },
+        ],
+      },
+    });
+  }
+}