@dbx-tools/projen 0.1.1 → 0.3.43

package/src/mixin.ts

@@ -0,0 +1,47 @@
+/**
+ * Mixin factory for `constructs` {@link ConstructsMixin}.
+ *
+ * Apply with `construct.with(...)` across the subtree. Package-targeting mixins
+ * compose the `projectPredicate.hasIdentifierName` / `hasTag` / `hasPath`
+ * builders from `./project-predicate`; `project.applyToProjects` is the
+ * ergonomic front-end that assembles those and applies the mixin for you.
+ */
+import type { Predicate } from "@dbx-tools/shared-core";
+import type { IConstruct, IMixin as ConstructsMixin } from "constructs";
+
+export type { ConstructsMixin };
+
+/**
+ * Builds a {@link ConstructsMixin} from `supports` and `applyTo` callbacks.
+ *
+ * When `supports` is a type guard (`construct is U`) or a {@link Predicate},
+ * `applyTo` receives the narrowed `U`.
+ */
+export function create<U extends IConstruct>(
+  supports: Predicate<IConstruct, U>,
+  applyTo: (construct: U) => void,
+): ConstructsMixin;
+
+export function create<U extends IConstruct>(
+  supports: (construct: IConstruct) => construct is U,
+  applyTo: (construct: U) => void,
+): ConstructsMixin;
+
+export function create(
+  supports: (construct: IConstruct) => boolean,
+  applyTo: (construct: IConstruct) => void,
+): ConstructsMixin;
+
+export function create(
+  supports: (construct: IConstruct) => boolean,
+  applyTo: (construct: IConstruct) => void,
+): ConstructsMixin {
+  return {
+    supports,
+    applyTo: (construct: IConstruct): void => {
+      if (supports(construct)) {
+        (applyTo as (construct: IConstruct) => void)(construct);
+      }
+    },
+  };
+}

package/src/module-exports.ts

@@ -0,0 +1,120 @@
+/**
+ * Static extraction of a module's own top-level named exports, via oxc-parser
+ * (a fast, TypeScript-aware parser). Used by the barrel generator to hoist
+ * names that are unique across a package to the top level of its barrel.
+ *
+ * Only a module's OWN declared names are returned - names it declares with
+ * `export const/function/class/enum/interface/type` or names it re-labels in a
+ * local `export { local as exported }`. Deliberately excluded:
+ *
+ *   - `export default` (no stable importable name);
+ *   - `export * from "..."` / `export * as ns from "..."` (opaque or already a
+ *     namespace);
+ *   - any `export { ... } from "..."` re-export with a `source` (the name is
+ *     owned by another module, so hoisting it here would double-count).
+ *
+ * Each name carries whether it is TYPE-only (`interface` / `type` alias /
+ * `export type { ... }`), so the barrel can emit `export type { ... }` for it -
+ * required under `isolatedModules`, where re-exporting a type through a value
+ * `export { ... }` is a hard error (TS1205).
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import type { parseSync as OxcParseSync } from "oxc-parser";
+
+const require = createRequire(import.meta.url);
+
+/** oxc's `parseSync`, loaded lazily so importing this module stays cheap. */
+let parseSyncFn: typeof OxcParseSync | undefined;
+function parseSync(filename: string, source: string): ReturnType<typeof OxcParseSync> {
+  parseSyncFn ??= (require("oxc-parser") as typeof import("oxc-parser")).parseSync;
+  return parseSyncFn(filename, source);
+}
+
+/** A parsed top-level statement, narrowed to the discriminant every caller reads. */
+export type ModuleStatement = { readonly type: string };
+
+/**
+ * `file`'s top-level statements, or `[]` when it cannot be read or parsed. The
+ * single parse entry point for the whole engine: the barrel generator reads the
+ * same oxc AST to decide whether a file exports anything at all and to read a
+ * hand-authored `exports.ts`, so there is exactly one TypeScript parser here.
+ */
+export function moduleStatements(file: string): readonly ModuleStatement[] {
+  let source: string;
+  try {
+    source = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  try {
+    return parseSync(file, source).program.body;
+  } catch {
+    return [];
+  }
+}
+
+/** One exported name plus whether it is type-only (needs `export type`). */
+export interface ModuleExport {
+  readonly name: string;
+  readonly isType: boolean;
+}
+
+/** Declaration node types that are inherently type-only. */
+const TYPE_DECLARATIONS = new Set(["TSInterfaceDeclaration", "TSTypeAliasDeclaration"]);
+
+/**
+ * Parse `file` and return its own top-level named exports (see the module
+ * docstring for what's included). Returns `[]` on a read/parse error - a
+ * module the parser chokes on simply contributes no hoisted names.
+ */
+export function moduleExports(file: string): ModuleExport[] {
+  const body = moduleStatements(file);
+
+  // Dedupe within the module: an overloaded `export function f(...)` declares
+  // `f` once per signature, but it's a single exported name. First occurrence
+  // wins (a value declaration and a same-named type would be unusual and are
+  // collapsed to whichever appears first).
+  const byName = new Map<string, ModuleExport>();
+  const push = (e: ModuleExport): void => {
+    if (!byName.has(e.name)) byName.set(e.name, e);
+  };
+  for (const stmt of body) {
+    if (stmt.type !== "ExportNamedDeclaration") continue;
+    // Narrow to the fields we read; oxc's union is wider than what we touch.
+    const node = stmt as {
+      exportKind?: "value" | "type";
+      source?: { value?: string } | null;
+      declaration?: {
+        type: string;
+        id?: { name?: string } | null;
+        declarations?: { id?: { type?: string; name?: string } | null }[];
+      } | null;
+      specifiers?: {
+        exported?: { name?: string; value?: string };
+        exportKind?: "value" | "type";
+      }[];
+    };
+    // `export { ... } from "..."` re-exports another module's names; skip.
+    if (node.source) continue;
+
+    const stmtIsType = node.exportKind === "type";
+    const decl = node.declaration;
+    if (decl) {
+      if (decl.id?.name) {
+        push({ name: decl.id.name, isType: stmtIsType || TYPE_DECLARATIONS.has(decl.type) });
+      }
+      for (const d of decl.declarations ?? []) {
+        if (d.id?.type === "Identifier" && d.id.name) {
+          push({ name: d.id.name, isType: stmtIsType });
+        }
+      }
+    }
+    for (const spec of node.specifiers ?? []) {
+      const name = spec.exported?.name ?? spec.exported?.value;
+      if (!name) continue;
+      push({ name, isType: stmtIsType || spec.exportKind === "type" });
+    }
+  }
+  return [...byName.values()];
+}

package/src/openapi.ts

@@ -0,0 +1,162 @@
+/**
+ * OpenAPI generator (tsoa-based).
+ *
+ * Scans `server`/`node` packages for modules that **import tsoa**
+ * (`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).
+ *   - `src/schema.ts`  - types generated from the spec (openapi-typescript).
+ *   - `src/client.ts`  - a typed `openapi-fetch` client, usable client-side.
+ *
+ * `generateSpec` then reads the actual controller decorators + TypeScript types from
+ * those files, so the API surface is annotated on the methods and nothing is
+ * hand-written twice. The generated client stack is openapi-typescript +
+ * openapi-fetch (openapi-ts.dev), the best-of-2026 choice since AppKit ships no
+ * OpenAPI client generator.
+ *
+ * `tsoa`, `typescript`, and `openapi-typescript` are loaded lazily (heavy, and only
+ * needed for `pnpm 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.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type * as ts from "typescript";
+import { find } from "@dbx-tools/path";
+import { lazyRequire } from "./_lazy-require";
+import { makeReadonly, makeWritable, stampGenerated } from "./generated";
+import { log } from "@dbx-tools/shared-core";
+import {
+  type RecordedPackage,
+  isModuleFile,
+  repoRoot,
+  toPosix,
+  recordedPackages,
+} from "./packages";
+
+const logger = log.logger("projen:openapi");
+
+/** The tag (and folder) the generated openapi client packages are written under. */
+const OPENAPI_TAG = "openapi";
+/** Heuristic: a module file whose source imports tsoa's runtime package. */
+const TSOA_IMPORT = /from\s+['"](?:tsoa|@tsoa\/runtime)['"]/;
+
+const CLIENT_SRC = `import createClient, { type ClientOptions } from "openapi-fetch";
+import type { paths } from "./schema";
+
+/** Create a typed OpenAPI client (openapi-fetch); safe to use in the browser. */
+export function createApiClient(options?: ClientOptions) {
+  return createClient<paths>(options);
+}
+`;
+
+/** True if any module file in `<pkg>/src` matches {@link TSOA_IMPORT}. */
+function hasTsoaControllers(pkg: Pick<RecordedPackage, "dir">): boolean {
+  const srcDir = join(pkg.dir, "src");
+  return [...find.findFiles("**/*", { cwd: srcDir })]
+    .filter(isModuleFile)
+    .some((f) => TSOA_IMPORT.test(readFileSync(join(srcDir, f), "utf8")));
+}
+
+/** `server`/`node` packages (never the generated `openapi` tag) with a tsoa import. */
+function controllerPackages(): RecordedPackage[] {
+  return recordedPackages().filter(
+    (p) => (p.tags.includes("server") || p.tags.includes("node")) && hasTsoaControllers(p),
+  );
+}
+
+/** True if the changed path is a source file that matches {@link TSOA_IMPORT}. */
+export function isTsoaController(path: string): boolean {
+  const posix = toPosix(path);
+  return (
+    !posix.includes(`/${OPENAPI_TAG}/`) &&
+    isModuleFile(path) &&
+    existsSync(path) &&
+    TSOA_IMPORT.test(readFileSync(path, "utf8"))
+  );
+}
+
+/**
+ * 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.
+ * A separate projen synth is still needed before new openapi folders become workspace
+ * members in `pnpm-workspace.yaml`.
+ */
+export async function generateOpenapi(): Promise<string[]> {
+  const pkgs = controllerPackages();
+  if (pkgs.length === 0) {
+    logger.info("no tsoa controllers found in any server/node package");
+    return [];
+  }
+
+  // Lazy, resilient loads: tsoa + typescript are CJS (require), openapi-typescript
+  // is ESM (dynamic import).
+  const require = createRequire(import.meta.url);
+  const { generateSpec } = lazyRequire<typeof import("tsoa")>(require, "tsoa", "openapi generation");
+  const tsRuntime = lazyRequire<typeof ts>(require, "typescript", "openapi generation");
+  const { default: openapiTS, astToString } = await import("openapi-typescript");
+
+  // Read tsoa's controllers with decorator support; skipLibCheck keeps third-party
+  // `.d.ts` out of the spec-generation compile.
+  const compilerOptions: ts.CompilerOptions = {
+    experimentalDecorators: true,
+    target: tsRuntime.ScriptTarget.ES2022,
+    module: tsRuntime.ModuleKind.ESNext,
+    moduleResolution: tsRuntime.ModuleResolutionKind.Bundler,
+    esModuleInterop: true,
+    skipLibCheck: true,
+  };
+
+  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.
+    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.
+    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,
+    );
+    makeReadonly(specPath);
+
+    // 2) src/schema.ts: types generated from the spec (openapi-typescript).
+    const spec = JSON.parse(readFileSync(specPath, "utf8"));
+    const schemaPath = join(srcDir, "schema.ts");
+    makeWritable(schemaPath);
+    writeFileSync(schemaPath, astToString(await openapiTS(spec)));
+    stampGenerated(schemaPath, {
+      tool: "projen openapi (tsoa + openapi-typescript)",
+      source: `the tsoa controllers in ${p.relPath}`,
+    });
+
+    // 3) src/client.ts: a typed openapi-fetch client over those types.
+    const clientPath = join(srcDir, "client.ts");
+    makeWritable(clientPath);
+    writeFileSync(clientPath, CLIENT_SRC);
+    stampGenerated(clientPath, {
+      tool: "projen openapi (openapi-fetch)",
+      source: "./schema",
+    });
+
+    written.push(outDir);
+    logger.success(`openapi/${leaf} (from ${p.relPath})`);
+  }
+  return written;
+}

package/src/packages.ts

@@ -0,0 +1,326 @@
+/**
+ * Package discovery + shared filesystem helpers.
+ *
+ * Terminology (Bit-style): a **tag** names a target environment
+ * (React/Vite, Node, agnostic, ...); a workspace **package** is a folder with a
+ * `src/` holding at least one module file (`.ts`/`.tsx`/`.js`/`.jsx`). "Scope" is
+ * reserved for the npm `@scope/` in package identifiers (e.g. `@dbx-tools/ui-app`).
+ *
+ * A package is discovered by scanning the {@link packageRoots} (default
+ * `["packages"]`). Its path *relative to the root* drives everything: the path
+ * segments join with `-` cumulatively into {@link DiscoveredPackage.tagCandidates}
+ * (e.g. `shared/path/coolDude/another` -> `[shared, shared-path, shared-path-cool-dude]`:
+ * each ancestor folder under the root, kebab-cased, excluding the leaf package
+ * folder), and those candidates are matched against `packageTagPaths` to decide which tag(s)
+ * apply. The match may yield NO tags - that is fine (the package still gets the
+ * agnostic default).
+ *
+ * Two discovery entry points. {@link scanPackages} walks the filesystem under the
+ * roots (synth time): it returns each package's path plus the tags implied by its
+ * path relative to the root, reading NO manifest. {@link recordedPackages} reads
+ * the recorded members from `pnpm-workspace.yaml` - the SOURCE OF TRUTH - and
+ * augments each with the `name` and `tags` read back from its own `package.json`
+ * (post-synth: barrels, watch, openapi), which is authoritative and so reflects any
+ * synth-time name override or resolved tag set.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { extname, relative, resolve, sep } from "node:path";
+import { project as coreProject } from "@dbx-tools/core";
+import { json, object, string } from "@dbx-tools/shared-core";
+import { find } from "@dbx-tools/path";
+import { parse } from "yaml";
+
+/**
+ * The repo root: the nearest package/projenrc root, falling back to the current
+ * working directory. Detection (npm prefix, git top-level, root markers) lives
+ * in `@dbx-tools/core`'s {@link coreProject.root}.
+ */
+export const repoRoot = coreProject.root() ?? process.cwd();
+
+/**
+ * Default package roots. Each is scanned for packages; override via the
+ * `packageRoots` option on a DBXTools project.
+ */
+export const DEFAULT_PACKAGE_ROOTS = ["packages"] as const;
+
+/**
+ * A project name: the root `package.json` name, else the git remote's repo
+ * name, else the root folder name. Delegates to `@dbx-tools/core`'s
+ * {@link coreProject.name}, which is also what a consuming repo's own tooling
+ * sees, so the engine and its host agree on the name.
+ */
+export function projectName(): string {
+  return coreProject.name(repoRoot);
+}
+
+const MODULE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+
+/** Glob for module files under any `src/`, built from {@link MODULE_EXTS} exts. */
+const SRC_MODULE_GLOB = `**/src/**/*.{${[...MODULE_EXTS].map((e) => e.slice(1)).join(",")}}`;
+
+export function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+/**
+ * Cumulative nesting tags from a package's path segments relative to its discovery
+ * root. Each segment is kebab-cased with {@link string.toSlug} (`coolDude` ->
+ * `cool-dude`). The leaf folder (the package name) is excluded when there are two
+ * or more segments; a lone segment tags itself.
+ */
+function nestingTagsFromSegments(segments: readonly string[]): string[] {
+  if (segments.length === 0) return [];
+  const prefix = segments.length === 1 ? segments : segments.slice(0, -1);
+  const out: string[] = [];
+  let acc = "";
+  for (const segment of prefix) {
+    const token = string.toSlug(segment);
+    if (!token) continue;
+    acc = acc ? `${acc}-${token}` : token;
+    out.push(acc);
+  }
+  return out;
+}
+
+/** Matches a barrel `index.<ext>` (as a basename or a posix path tail). */
+const BARREL_RE = /(^|\/)index\.(ts|tsx|js|jsx|mjs|cjs)$/;
+
+/** Basenames this toolchain generates (projen manifests/tsconfigs + vite config). */
+const GENERATED_BASENAMES = new Set([
+  "package.json",
+  "tsconfig.json",
+  "tsconfig.dev.json",
+  "vite.config.ts",
+]);
+
+/**
+ * True if the file matches the watcher's generated-file heuristic: projen manifest
+ * basenames, package-root barrels (`index.ts`), vite config, or declaration files.
+ * Other read-only toolchain output (e.g. openapi artifacts) is not covered here.
+ */
+export function isGeneratedFile(file: string): boolean {
+  const base = file.split(sep).pop() ?? "";
+  return GENERATED_BASENAMES.has(base) || BARREL_RE.test(base) || base.endsWith(".d.ts");
+}
+
+/** A re-exportable source module: ts/tsx/js/jsx/mjs/cjs, not a barrel/test/decl. */
+export function isModuleFile(file: string): boolean {
+  if (file.endsWith(".d.ts")) return false;
+  if (!MODULE_EXTS.has(extname(file))) return false;
+  // Accept both OS-native paths and posix (glob) inputs.
+  const base = toPosix(file).split("/").pop()!;
+  if (BARREL_RE.test(base)) return false;
+  if (/\.(test|spec)\./.test(base)) return false;
+  return true;
+}
+
+/**
+ * One discovered package: a `src`-bearing folder somewhere under a
+ * package root, identified by that root plus the segments of its path
+ * *relative to the root*. For `packages/ui/app` the root is `packages` and the
+ * segments are `["ui", "app"]`.
+ *
+ * The relative segments drive everything downstream: the npm name
+ * (`@<scope>/<segments joined by -`), the `memberPath`/`dir`, and the
+ * {@link tagCandidates} used to resolve which tag(s) apply.
+ */
+export class DiscoveredPackage {
+  constructor(
+    /** Absolute repo root. */
+    readonly projectRoot: string,
+    /** Repo-relative package root, e.g. `packages`. */
+    readonly root: string,
+    /** Path segments relative to `root`, e.g. `["ui", "app"]`. */
+    readonly relSegments: readonly string[],
+  ) {}
+
+  /** Posix path relative to the root, e.g. `ui/app`. */
+  get relPath(): string {
+    return this.relSegments.join("/");
+  }
+
+  /** Repo-relative posix member path: `packages/ui/app` (pnpm member + `outdir`). */
+  get memberPath(): string {
+    return [this.root, ...this.relSegments].join("/");
+  }
+
+  /** Absolute package directory. */
+  get dir(): string {
+    return resolve(this.projectRoot, this.root, ...this.relSegments);
+  }
+
+  /** The package folder name (last segment), e.g. `app`. */
+  get name(): string {
+    return this.relSegments[this.relSegments.length - 1] ?? this.root;
+  }
+
+  /**
+   * Tag candidates from nesting under the discovery root: cumulative kebab-case join
+   * of every ancestor folder, excluding the leaf package folder when depth >= 2
+   * (`shared/path/coolDude/another` -> `[shared, shared-path, shared-path-cool-dude]`).
+   * Matched against `packageTagPaths` to resolve applied mixin tags.
+   */
+  get tagCandidates(): string[] {
+    return nestingTagsFromSegments(this.relSegments);
+  }
+}
+
+/** Read the raw workspace member globs from `pnpm-workspace.yaml` (source of truth). */
+function readRecordedMembers(projectRoot: string = repoRoot): string[] {
+  const file = resolve(projectRoot, "pnpm-workspace.yaml");
+  if (!existsSync(file)) return [];
+  const doc = parse(readFileSync(file, "utf8")) as {
+    packages?: string[];
+  } | null;
+  return doc?.packages ?? [];
+}
+
+/** A member path `<root>/<...rel>` (>= 2 segments) as a {@link DiscoveredPackage}. */
+function packageOfMember(projectRoot: string, member: string): DiscoveredPackage | undefined {
+  const segs = toPosix(member).split("/").filter(Boolean);
+  if (segs.length < 2) return undefined;
+  return new DiscoveredPackage(projectRoot, segs[0]!, segs.slice(1));
+}
+
+/**
+ * Package dirs under `rootAbs`, found with a single `find.findFiles` scan from
+ * `@dbx-tools/path` for module files beneath any `src/`. A package is the
+ * folder that OWNS the `src/` - the segments before the FIRST `src/` - so a package's
+ * own subfolders never become nested packages (outermost wins). Barrels/tests/decls
+ * don't count (see {@link isModuleFile}), so a `src/` holding only an `index.ts`
+ * barrel is not a package. Depth is unbounded: `<root>/a/b/c/src` is discovered as
+ * `a/b/c`.
+ */
+function collectPackageDirs(rootAbs: string): string[] {
+  const owners = new Set<string>();
+  for (const file of find.findFiles(SRC_MODULE_GLOB, { cwd: rootAbs })) {
+    if (!isModuleFile(file)) continue;
+    const segs = toPosix(file).split("/");
+    const srcIdx = segs.indexOf("src");
+    if (srcIdx > 0) owners.add(segs.slice(0, srcIdx).join("/"));
+  }
+  const rels = [...owners];
+  // Outermost wins: drop any owner nested under another discovered owner.
+  return rels
+    .filter((d) => !rels.some((o) => o !== d && d.startsWith(`${o}/`)))
+    .map((rel) => resolve(rootAbs, rel));
+}
+
+/**
+ * Scan the filesystem for packages under `roots` (synth time): every `src`-bearing
+ * folder, at any depth, is one. Returns each as a {@link DiscoveredPackage} - its
+ * path plus the tags implied by its path relative to the root
+ * ({@link DiscoveredPackage.tagCandidates}); no `package.json` is read. Used by
+ * the root project's scan at synth, and by the watcher to compare disk against the
+ * recorded set. Sorted by member path.
+ */
+export function scanPackages(
+  projectRoot: string = repoRoot,
+  roots: readonly string[] = DEFAULT_PACKAGE_ROOTS,
+): DiscoveredPackage[] {
+  const out: DiscoveredPackage[] = [];
+  for (const root of roots) {
+    const rootAbs = resolve(projectRoot, root);
+    for (const pkgDir of collectPackageDirs(rootAbs)) {
+      const rel = toPosix(relative(rootAbs, pkgDir)).split("/").filter(Boolean);
+      out.push(new DiscoveredPackage(projectRoot, root, rel));
+    }
+  }
+  return out.sort((a, b) => a.memberPath.localeCompare(b.memberPath));
+}
+
+/**
+ * A recorded package: its path, plus the `name` and `tags` read back from
+ * its own `package.json` (both written at synth, and possibly overridden by a consumer
+ * `packageMixin` - e.g. a name override). `name`/`tags` fall back to the folder
+ * name / path candidates when the manifest is missing or carries none (a package
+ * added but not yet synthesized).
+ */
+export interface RecordedPackage {
+  /** Repo-relative posix member path, e.g. `packages/ui/app`. */
+  readonly path: string;
+  /** Repo-relative package root, e.g. `packages`. */
+  readonly root: string;
+  /** Posix path relative to the root, e.g. `ui/app`. */
+  readonly relPath: string;
+  /** Absolute package directory. */
+  readonly dir: string;
+  /** Resolved tags from `package.json` `dbxToolsConfig.tags`, else the path candidates. */
+  readonly tags: string[];
+}
+
+/**
+ * `<dir>/package.json` parsed as a record, or `undefined` when the file is
+ * absent or malformed. The single manifest reader for the engine - every
+ * caller that pokes at a `package.json` field goes through this so a missing or
+ * half-written manifest degrades the same way everywhere.
+ */
+export function readPackageManifest(dir: string): Record<string, unknown> | undefined {
+  const path = resolve(dir, "package.json");
+  if (!existsSync(path)) return undefined;
+  try {
+    return json.parseRecord(readFileSync(path, "utf8"));
+  } catch {
+    return undefined; // unreadable (permissions, race with a concurrent write)
+  }
+}
+
+/** A package's `dbxToolsConfig` object, or `undefined` when absent. */
+function readDbxToolsConfig(dir: string): Record<string, unknown> | undefined {
+  const config = readPackageManifest(dir)?.dbxToolsConfig;
+  return object.isRecord(config) ? config : undefined;
+}
+
+/** Read `<dir>/package.json`'s `dbxToolsConfig.tags` (`undefined` if absent). */
+function readManifestTags(dir: string): string[] | undefined {
+  const tags = readDbxToolsConfig(dir)?.tags;
+  return Array.isArray(tags) ? (tags as string[]) : undefined;
+}
+
+/**
+ * Extra repo-root paths that trigger a full re-synth during `sync --watch`, read from
+ * the root `package.json` `dbxToolsConfig.syncResynthPaths` (set via the
+ * {@link DBXToolsProjectOptions.syncResynthPaths} option at synth).
+ */
+export function syncResynthPaths(projectRoot: string = repoRoot): string[] {
+  const paths = readDbxToolsConfig(projectRoot)?.syncResynthPaths;
+  return Array.isArray(paths) ? string.parseList(paths.map((p) => String(p))) : [];
+}
+
+/**
+ * The recorded workspace members from `pnpm-workspace.yaml` (the source of truth),
+ * each augmented with the `tags` read back from its `package.json`. This is what
+ * every post-synth command (barrels, watch, openapi) uses: the manifest is
+ * authoritative, so it reflects the resolved tag set.
+ * Sorted by path.
+ */
+export function recordedPackages(projectRoot: string = repoRoot): RecordedPackage[] {
+  const out: RecordedPackage[] = [];
+  for (const member of readRecordedMembers(projectRoot)) {
+    const pkg = packageOfMember(projectRoot, member);
+    if (!pkg) continue;
+    out.push({
+      path: pkg.memberPath,
+      root: pkg.root,
+      relPath: pkg.relPath,
+      dir: pkg.dir,
+      tags: readManifestTags(pkg.dir) ?? pkg.tagCandidates,
+    });
+  }
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * The roots to scan for a live filesystem check: the distinct first segment of
+ * every recorded member, unioned with the defaults. Lets a command compare disk
+ * against the recorded truth without knowing the `packageRoots` the last
+ * synth was configured with.
+ */
+export function recordedRoots(projectRoot: string = repoRoot): string[] {
+  const roots = new Set<string>(DEFAULT_PACKAGE_ROOTS);
+  for (const member of readRecordedMembers(projectRoot)) {
+    const pkg = packageOfMember(projectRoot, member);
+    if (pkg) roots.add(pkg.root);
+  }
+  return [...roots];
+}