@dbx-tools/projen 0.9.154 → 0.9.157

package/src/project-js.ts

@@ -6,17 +6,30 @@
  * {@link DBXToolsNodeProject} (monorepo root) and {@link DBXToolsTypeScriptProject}
  * (a package, or a standalone compiling root) both implement {@link DBXToolsJavaScriptProject}.
  */
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import * as projectUtils from "@dbx-tools/core/project-utils";
-import { ignore, match } from "@dbx-tools/path";
-import { object, stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
+import { repositoryUrl } from "@dbx-tools/core";
+import { ignore, findFilesSync, toPathMatcher } from "@dbx-tools/path";
+import {
+  type OneOrMany,
+  isRecord,
+  sequence,
+  toSlug,
+  tokenize,
+  trimToNull,
+  dedent,
+} from "@dbx-tools/shared-core";
 import { type IConstruct } from "constructs";
 import { Component, LogLevel, Project, type Task, TextFile, javascript, typescript } from "projen";
 import { JobPermission, type JobStep } from "projen/lib/github/workflows-model";
 import type { ReleaseProjectOptions } from "projen/lib/release";
-import { AppKitWorkspace, type AppKitWorkspaceMode } from "./appkit-workspace.ts";
-import { generateBarrels, isGeneratedBarrel } from "./barrels.ts";
+import {
+  AppKitWorkspace,
+  isAppKitApplication,
+  type AppKitBundleOptions,
+  type AppKitWorkspaceMode,
+} from "./appkit-workspace.ts";
+import { folderBarrelFile, generateBarrels } from "./barrels.ts";
 
 import { BUN_APP_OVERRIDES, RootBunfigFile } from "./bun-app.ts";
 import { BUN_VERSION, BUN_VERSION_CHECK_SCRIPT, MINIMUM_BUN_VERSION } from "./bun-workflow.ts";
@@ -27,7 +40,7 @@ import { resolvePkgRoot } from "./engine-root.ts";
 import * as mixin from "./mixin.ts";
 import {
   DEFAULT_PACKAGE_ROOTS,
-  type DiscoveredPackage,
+  DiscoveredPackage,
   projectName,
   readPackageManifest,
   scanPackages,
@@ -113,10 +126,10 @@ export class PackageIdentifier {
    */
   static of(...names: OneOrMany<string>): PackageIdentifier {
     const segments = names.flatMap((part) => part.split("/")).filter(Boolean);
-    const scope = segments.length ? stringUtils.toSlug(segments[0]!) : "";
+    const scope = segments.length ? toSlug(segments[0]!) : "";
     const nameParts = [
       scope,
-      ...segments.slice(1).flatMap((segment) => [...stringUtils.tokenize(segment)]),
+      ...segments.slice(1).flatMap((segment) => [...tokenize(segment)]),
     ].filter(Boolean);
     if (!nameParts.length) throw new Error(`Invalid name: ${names.join(", ")}`);
     if (nameParts.length === 1) return new PackageIdentifier(undefined, nameParts[0]!);
@@ -144,11 +157,11 @@ function repositoryOptions(
   const existingRepositoryUrl =
     typeof existingRepository === "string"
       ? existingRepository
-      : object.isRecord(existingRepository)
-        ? stringUtils.trimToNull(existingRepository.url)
+      : isRecord(existingRepository)
+        ? trimToNull(existingRepository.url)
         : undefined;
   const repository =
-    options.repository ?? projectUtils.repositoryUrl(workspaceRoot, "npm") ?? existingRepositoryUrl;
+    options.repository ?? repositoryUrl(workspaceRoot, "npm") ?? existingRepositoryUrl;
   const projectRoot = options.parent
     ? resolve(options.parent.outdir, options.outdir ?? ".")
     : resolve(options.outdir ?? process.cwd());
@@ -239,7 +252,7 @@ function dependencyName(spec: string): string {
 /** Add an optional peer and make it available while developing the package. */
 export function addOptionalPeer(pkg: javascript.NodeProject, spec: string): void {
   const name = dependencyName(spec);
-  const current = object.isRecord(pkg.package.manifest.peerDependenciesMeta)
+  const current = isRecord(pkg.package.manifest.peerDependenciesMeta)
     ? pkg.package.manifest.peerDependenciesMeta
     : {};
   pkg.addPeerDeps(spec);
@@ -256,8 +269,8 @@ export function projectRepositoryUrl(project: javascript.NodeProject): string |
   const configured =
     typeof repository === "string"
       ? repository
-      : object.isRecord(repository)
-        ? (stringUtils.trimToNull(repository.url) ?? undefined)
+      : isRecord(repository)
+        ? (trimToNull(repository.url) ?? undefined)
         : undefined;
   return configured?.replace(/^git\+/, "").replace(/\.git$/, "");
 }
@@ -285,47 +298,45 @@ export function projectReleaseBranch(project: DBXToolsJavaScriptProject): string
  */
 export function addPackageFiles(pkg: javascript.NodeProject, ...entries: string[]): void {
   const current = (pkg.package.manifest.files ?? []) as string[];
-  pkg.package.addField("files", [...object.sequence(current, entries).distinct()]);
+  pkg.package.addField("files", [...sequence(current, entries).distinct()]);
 }
 
-/**
- * The automatic subpath map for a package's public top-level TypeScript and CSS
- * files plus directory entrypoints, skipping `_`-prefixed private modules and
- * declaration files.
- *
- * This widens no API surface: the root `index.ts` barrel already re-exports every
- * non-`_` module, so those names are public through `.` either way - the subpaths
- * just add a narrower import path. Deriving the map is what lets a tag carry the
- * whole export layout, instead of each package hand-listing its own modules.
- * The wildcard resolves generated nested barrels at every depth while exact
- * exports continue to win for hand-authored entrypoints and assets.
- */
-export function srcModuleExports(pkg: javascript.NodeProject): Record<string, string> {
+/** Generate folder-only TypeScript subpaths plus public CSS asset subpaths. */
+export function srcFolderExports(
+  pkg: javascript.NodeProject,
+  additionalModules: readonly string[] = [],
+): Record<string, string> {
   const srcDir = join(pkg.outdir, "src");
   if (!existsSync(srcDir)) return {};
 
+  const discovered = [...findFilesSync("**/*", { cwd: srcDir })].map(toPosix);
+  const modules = new Set([
+    ...discovered.filter(
+      (file) =>
+        /\.(?:ts|tsx)$/.test(file) &&
+        !file.endsWith(".d.ts") &&
+        !/(^|\/)_/.test(file) &&
+        !/\.(?:test|spec)\./.test(file) &&
+        !/(^|\/)index\.(?:ts|tsx)$/.test(file),
+    ),
+    ...additionalModules
+      .map((file) => toPosix(file).replace(/^src\//, ""))
+      .filter((file) => /\.(?:ts|tsx)$/.test(file) && !/(^|\/)_/.test(file)),
+  ]);
+  const directories = new Set<string>();
+  for (const module of modules) {
+    const directory = dirname(module);
+    if (directory !== ".") directories.add(directory);
+  }
+
   const exports: Record<string, string> = {};
-  for (const entry of readdirSync(srcDir, { withFileTypes: true }).sort((left, right) =>
-    left.name.localeCompare(right.name),
-  )) {
-    if (entry.name.startsWith("_")) continue;
-    if (entry.isFile() && /\.(?:ts|tsx)$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
-      exports[`./${entry.name.replace(/\.tsx?$/, "")}`] = `./src/${entry.name}`;
-      continue;
-    }
-    if (entry.isFile() && entry.name.endsWith(".css")) {
-      exports[`./${entry.name}`] = `./src/${entry.name}`;
-      continue;
-    }
-    if (!entry.isDirectory()) continue;
-    const index = ["index.ts", "index.tsx"].find((file) =>
-      existsSync(join(srcDir, entry.name, file)),
-    );
-    if (index && !isGeneratedBarrel(join(srcDir, entry.name, index))) {
-      exports[`./${entry.name}`] = `./src/${entry.name}/${index}`;
-    }
+  for (const directory of [...directories].sort((left, right) => left.localeCompare(right))) {
+    exports[`./${directory}`] = `./${folderBarrelFile(directory)}`;
   }
-  return { ...exports, "./*": "./src/*/index.ts" };
+  for (const file of discovered.filter((file) => file.endsWith(".css") && !/(^|\/)_/.test(file))) {
+    exports[`./${file}`] = `./src/${file}`;
+  }
+  return exports;
 }
 
 /**
@@ -377,8 +388,6 @@ const PRETTIER_SETTINGS: javascript.PrettierSettings = {
   endOfLine: javascript.EndOfLine.LF,
 };
 
-export { PROJEN_VERSION } from "./projen-version.ts";
-
 /** SPDX license shared by generated JavaScript and Python packages. */
 export const LICENSE = "Apache-2.0";
 
@@ -520,10 +529,8 @@ const DEV_DEPS_ROOT: string[] = [
 
 function configureRootBunRuntime(project: DBXToolsJavaScriptProject): void {
   new TextFile(project, BUN_VERSION_CHECK_SCRIPT, {
-    lines: stringUtils
-      .dedent(
-        // ============================================================================
-        /*ts*/ `
+    lines: dedent(// ============================================================================
+    /*ts*/ `
           /** Minimum Bun version accepted by this workspace. */
           const MINIMUM_VERSION = ${JSON.stringify(MINIMUM_BUN_VERSION)};
 
@@ -550,10 +557,8 @@ function configureRootBunRuntime(project: DBXToolsJavaScriptProject): void {
               \`Bun \${MINIMUM_VERSION} or newer is required; running \${Bun.version}. Use "bun run bun" to select the workspace-local Bun binary.\`,
             );
           }
-        `,
-        // ============================================================================
-      )
-      .split("\n"),
+        `).split("\n"),
+    // ============================================================================
   });
   const check = `bun ${BUN_VERSION_CHECK_SCRIPT}`;
   project.package.installTask.prependExec(check);
@@ -638,6 +643,13 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
      * `auto`; `true` also validates the required package roles and entry files.
      */
     readonly appkit?: AppKitWorkspaceMode;
+    /**
+     * One Bun/AppKit application root. Defaults to `packages/app` when that
+     * directory exists. Set false to disable application-root discovery.
+     */
+    readonly appRoot?: string | false;
+    /** Minimal generated bundle settings, or false for an application-owned bundle. */
+    readonly appBundle?: false | AppKitBundleOptions;
     /**
      * Extra repo-root paths that trigger a full re-synth during `sync --watch`
      * (alongside `.projenrc.ts`). Repo-relative, e.g. `".example.projenrc.ts"`.
@@ -877,22 +889,22 @@ export class DBXToolsTypeScriptProject
     // instead of failing, so authoring a React component would otherwise need
     // per-package tsconfig config to be compiled at all.
     this.tsconfig?.addInclude("src/**/*.tsx");
+    this.tsconfig?.addInclude("index.*.ts");
     this.dbxToolsConfig = new DBXToolsConfig(this, options);
     // Source-first entry: point the package at its package-ROOT `index.ts` barrel
     // so packages resolve each other's `@scope/pkg` imports to source.
     this.package.addField("type", "module");
     this.package.addField("exports", {
       ".": "./index.ts",
-      ...srcModuleExports(this),
+      ...srcFolderExports(this),
       "./package.json": "./package.json",
     });
     this.package.addVersion(readWorkspaceVersion(this.root.outdir));
-    addPackageFiles(this, "index.ts", "src");
-    if (existsSync(join(this.outdir, "exports.ts"))) addPackageFiles(this, "exports.ts");
+    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. The native no-tests option is portable
     // across Windows and Unix and lets packages without tests remain a no-op.
-    this.testTask.exec("bun test test --pass-with-no-tests");
+    this.testTask.exec(`bun test ${this.testdir} --pass-with-no-tests`);
     initProject(this, options);
   }
 
@@ -945,19 +957,11 @@ class GeneratedSource extends Component {
       }
       if (modules.length === 0) continue;
       const current = (subproject.package.manifest.exports ?? {}) as Record<string, unknown>;
-      const sourceExports = Object.fromEntries(
-        modules.map((module) => [`./${module.slice("src/".length, -".ts".length)}`, `./${module}`]),
-      );
-      const nestedExport = current["./*"];
+      const { "./package.json": packageJson, ...withoutPackageJson } = current;
       subproject.package.addField("exports", {
-        ...Object.fromEntries(
-          Object.entries(current).filter(
-            ([subpath]) => subpath !== "./*" && subpath !== "./package.json",
-          ),
-        ),
-        ...sourceExports,
-        ...(nestedExport ? { "./*": nestedExport } : {}),
-        ...(current["./package.json"] ? { "./package.json": current["./package.json"] } : {}),
+        ...withoutPackageJson,
+        ...srcFolderExports(subproject, modules),
+        ...(packageJson ? { "./package.json": packageJson } : {}),
       });
     }
   }
@@ -1058,6 +1062,62 @@ class EslintIgnoreCodegen extends Component {
   }
 }
 
+/** Require package implementation files to import their own modules relatively. */
+class EslintWorkspaceImports extends Component {
+  private readonly configured = new Set<string>();
+
+  public override preSynthesize(): void {
+    const eslint = javascript.Eslint.of(this.project);
+    if (!eslint) return;
+    const root = this.project as DBXToolsNodeProject | DBXToolsTypeScriptProject;
+    const rootAbs = resolve(root.outdir);
+    const configure = (directory: string, packageName: string): void => {
+      const rel = toPosix(relative(rootAbs, directory));
+      const key = `${rel}:${packageName}`;
+      if (this.configured.has(key)) return;
+      this.configured.add(key);
+      eslint.addOverride({
+        files: [`${rel ? `${rel}/` : ""}**/*.{ts,tsx}`],
+        rules: {
+          "no-restricted-imports": [
+            "error",
+            {
+              patterns: [
+                {
+                  group: [packageName, `${packageName}/**`],
+                  message: "Use relative imports within this package.",
+                },
+              ],
+            },
+          ],
+        },
+      });
+    };
+
+    const members = root.node
+      .findAll()
+      .filter(
+        (candidate): candidate is DBXToolsNodeProject | DBXToolsTypeScriptProject =>
+          candidate !== root &&
+          (candidate instanceof DBXToolsNodeProject ||
+            candidate instanceof DBXToolsTypeScriptProject),
+      );
+    for (const member of members) {
+      configure(member.outdir, member.package.packageName);
+    }
+    if (members.length === 0 && root.extraWorkspaceMembers.length === 0) {
+      configure(root.outdir, root.package.packageName);
+    }
+    for (const member of root.extraWorkspaceMembers) {
+      const directory = resolve(rootAbs, member);
+      const packageName = readPackageManifest(directory)?.name;
+      if (typeof packageName === "string" && packageName.trim()) {
+        configure(directory, packageName);
+      }
+    }
+  }
+}
+
 /**
  * Keep generated package barrels and codegen modules out of root formatting.
  *
@@ -1074,15 +1134,14 @@ class PrettierIgnoreGenerated extends Component {
     for (const sub of this.project.subprojects) {
       if (!(sub instanceof DBXToolsTypeScriptProject)) continue;
       const rel = toPosix(relative(rootAbs, sub.outdir));
-      prettier.addIgnorePattern(`${rel}/index.ts`);
-      prettier.addIgnorePattern(`${rel}/src/**/index.ts`);
+      prettier.addIgnorePattern(`${rel}/index*.ts`);
       for (const module of codegenModulePaths(sub.dbxToolsConfig.codegenInputs)) {
         prettier.addIgnorePattern(`${rel}/${module}`);
       }
     }
     const extraMembers = (this.project as DBXToolsNodeProject).extraWorkspaceMembers ?? [];
     for (const member of extraMembers) {
-      prettier.addIgnorePattern(`${member}/index.ts`);
+      prettier.addIgnorePattern(`${member}/index*.ts`);
     }
   }
 }
@@ -1094,7 +1153,7 @@ const DEFAULT_OMIT_RELATIVE_PREFIX = ["node"];
 function resolveOmitRelativePrefix(option: OneOrMany<string> | undefined): string[] {
   const raw = option === undefined ? DEFAULT_OMIT_RELATIVE_PREFIX : option;
   const list = Array.isArray(raw) ? raw : [raw];
-  return list.map((segment) => stringUtils.toSlug(segment)).filter(Boolean);
+  return list.map((segment) => toSlug(segment)).filter(Boolean);
 }
 
 /**
@@ -1104,7 +1163,7 @@ function resolveOmitRelativePrefix(option: OneOrMany<string> | undefined): strin
  */
 function packageNameFor(scope: string, relPath: string, omitPrefixes: string[]): string {
   const segments = relPath.split("/").filter(Boolean);
-  if (segments.length > 1 && omitPrefixes.includes(stringUtils.toSlug(segments[0]!))) {
+  if (segments.length > 1 && omitPrefixes.includes(toSlug(segments[0]!))) {
     segments.shift();
   }
   return PackageIdentifier.of(scope, segments.join("/")).packageName;
@@ -1145,14 +1204,14 @@ function engineSelfDependency(project: javascript.NodeProject): string | undefin
   const enginePkgJson = join(resolvePkgRoot(), "package.json");
   if (!toPosix(enginePkgJson).includes("/node_modules/")) return undefined;
   const engine = readPackageManifest(dirname(enginePkgJson));
-  const name = stringUtils.trimToNull(engine?.name);
+  const name = trimToNull(engine?.name);
   if (!name) return undefined;
-  const version = stringUtils.trimToNull(engine?.version);
+  const version = trimToNull(engine?.version);
 
   // No existing consumer manifest (or no entry) falls through to a computed pin.
   const consumer = readPackageManifest(resolve(project.outdir));
   const dependencyOf = (field: unknown): string | undefined =>
-    object.isRecord(field) ? (stringUtils.trimToNull(field[name]) ?? undefined) : undefined;
+    isRecord(field) ? (trimToNull(field[name]) ?? undefined) : undefined;
   const existing = dependencyOf(consumer?.devDependencies) ?? dependencyOf(consumer?.dependencies);
   if (existing) return `${name}@${existing}`;
   return `${name}@^${version}`;
@@ -1174,7 +1233,7 @@ function tagPathMatches(key: string, p: DiscoveredPackage): boolean {
     return true;
   }
   // Otherwise treat the key as a glob against the same targets.
-  const isMatch = match.toPathMatcher(key);
+  const isMatch = toPathMatcher(key);
   return isMatch(p.relPath) || isMatch(p.memberPath) || p.tagCandidates.some((c) => isMatch(c));
 }
 
@@ -1278,6 +1337,12 @@ function initProject(
   const roots =
     options.packageRoots ??
     (existsSync(resolve(project.outdir, "packages/js")) ? ["packages/js"] : DEFAULT_PACKAGE_ROOTS);
+  const rootAbs = resolve(project.outdir);
+  const configuredAppRoot =
+    options.appRoot === false
+      ? undefined
+      : (options.appRoot ??
+        (existsSync(resolve(rootAbs, "packages/app")) ? "packages/app" : undefined));
   project.dbxToolsConfig.packageRoots = [...roots];
   if (options.syncResynthPaths?.length) {
     project.dbxToolsConfig.syncResynthPaths = [...options.syncResynthPaths];
@@ -1317,11 +1382,11 @@ function initProject(
     ".npmrc",
   );
   for (const root of roots) {
-    project.annotateGenerated(`/${root}/**/index.ts`);
+    project.annotateGenerated(`/${root}/**/index*.ts`);
     project.annotateGenerated(`/${root}/**/src/generated/**`);
   }
   for (const member of project.extraWorkspaceMembers) {
-    project.annotateGenerated(`/${member}/index.ts`);
+    project.annotateGenerated(`/${member}/index*.ts`);
   }
 
   // ESLint lives ONLY on the root and lints every package. `projectService` resolves
@@ -1350,11 +1415,15 @@ function initProject(
   // Generated read-only outputs (barrels, app scripts, and codegen). ESLint
   // --fix cannot rewrite files owned by the barrel generator, codegen, or projen.
   for (const root of roots) {
-    eslint.addIgnorePattern(`${root}/**/index.ts`);
+    eslint.addIgnorePattern(`${root}/**/index*.ts`);
   }
   eslint.addIgnorePattern("**/src/generated/**");
   for (const member of project.extraWorkspaceMembers) {
-    eslint.addIgnorePattern(`${member}/index.ts`);
+    eslint.addIgnorePattern(`${member}/index*.ts`);
+  }
+  if (configuredAppRoot) {
+    eslint.addIgnorePattern(`${configuredAppRoot}/index*.ts`);
+    eslint.addIgnorePattern(`${configuredAppRoot}/client/vite.config.ts`);
   }
   // The generated bun app scripts + unmanaged overrides live at the package root,
   // outside any `src/**` tsconfig include, so the type-aware parser cannot resolve
@@ -1367,6 +1436,7 @@ function initProject(
   // Codegen inputs may be added by mixins after construction; ignore their
   // generated modules once typed package configuration is final.
   new EslintIgnoreCodegen(project);
+  new EslintWorkspaceImports(project);
   eslint.addRules({
     "import/no-relative-packages": "error",
     // Monorepo tooling legitimately uses devDeps (typescript, tsx, projen) in src.
@@ -1396,6 +1466,9 @@ function initProject(
       "tsconfig.json",
       ...roots.map((r) => `${r}/**/tsconfig.json`),
       ...project.extraWorkspaceMembers.map((member) => `${member}/tsconfig.json`),
+      ...(configuredAppRoot
+        ? [`${configuredAppRoot}/tsconfig.client.json`, `${configuredAppRoot}/tsconfig.server.json`]
+        : []),
     ];
   }
 
@@ -1410,7 +1483,6 @@ function initProject(
   };
 
   // Already-attached subprojects, keyed by repo-relative member path.
-  const rootAbs = resolve(project.outdir);
   const existing = new Map<string, DBXToolsJavaScriptProject>();
   for (const sub of project.subprojects) {
     if (sub instanceof DBXToolsNodeProject || sub instanceof DBXToolsTypeScriptProject) {
@@ -1418,12 +1490,52 @@ function initProject(
     }
   }
 
+  let application: DBXToolsTypeScriptProject | undefined;
+  let applicationPath: string | undefined;
+  if (configuredAppRoot) {
+    const appPath = toPosix(relative(rootAbs, resolve(rootAbs, configuredAppRoot)));
+    if (!appPath || appPath.startsWith("../")) {
+      throw new Error(`appRoot must resolve beneath the workspace root: ${configuredAppRoot}`);
+    }
+    applicationPath = appPath;
+    const segments = appPath.split("/").filter(Boolean);
+    const discovered = new DiscoveredPackage(rootAbs, segments[0]!, segments.slice(1));
+    const found = existing.get(appPath);
+    if (found) {
+      if (!(found instanceof DBXToolsTypeScriptProject)) {
+        throw new Error(`appRoot must be a TypeScript project: ${appPath}`);
+      }
+      application = found;
+    } else {
+      const defaults = {
+        name: packageNameFor(project.scope, discovered.relPath, omitPrefixes),
+        ...options.packageDefaults,
+        publishable: false,
+      } satisfies DiscoveredTypeScriptPackageOptions;
+      const packageOptions = options.resolvePackageOptions?.(discovered, defaults) ?? defaults;
+      application = new DBXToolsTypeScriptProject({
+        parent: project,
+        outdir: appPath,
+        ...packageOptions,
+        publishable: false,
+        tags: [],
+      });
+      existing.set(appPath, application);
+    }
+  }
+
   // Discover + append a child per src-bearing folder. A root encapsulating an
   // already-attached project doesn't re-create it, it just unions the tags in. The
   // agnostic floor is set in the child's constructor; per-tag deps/tsconfig come from
   // the PACKAGE_TAG_MIXINS applied across the subtree below.
   for (const p of scanPackages(rootAbs, roots)) {
-    const tags = [...object.sequence(p.tagCandidates, resolveTags(p, tagPaths)).distinct()];
+    if (
+      applicationPath &&
+      (p.memberPath === applicationPath || p.memberPath.startsWith(`${applicationPath}/`))
+    ) {
+      continue;
+    }
+    const tags = [...sequence(p.tagCandidates, resolveTags(p, tagPaths)).distinct()];
     const found = existing.get(p.memberPath);
     if (found) {
       found.dbxToolsConfig.tags.push(...tags);
@@ -1444,7 +1556,7 @@ function initProject(
   }
 
   // The root project may itself carry tags (via a `""`/`"."` tag-path key).
-  const rootTags = [...object.sequence(tagPaths[""], tagPaths["."]).distinct()];
+  const rootTags = [...sequence(tagPaths[""], tagPaths["."]).distinct()];
   if (rootTags.length) project.dbxToolsConfig.tags.push(...rootTags);
 
   // Apply per-tag mixins across the whole subtree now that every child exists
@@ -1455,19 +1567,13 @@ function initProject(
   }
   const appkitMode = options.appkit ?? "auto";
   if (appkitMode !== false) {
-    const projects = [project, ...project.subprojects].filter(
-      (candidate): candidate is DBXToolsNodeProject | DBXToolsTypeScriptProject =>
-        candidate instanceof DBXToolsNodeProject || candidate instanceof DBXToolsTypeScriptProject,
-    );
-    const apps = projects.filter((candidate) => candidate.dbxToolsConfig.tags.includes("app"));
-    const servers = projects.filter((candidate) =>
-      candidate.dbxToolsConfig.tags.includes("server"),
-    );
-    const enabled = appkitMode === true || (apps.length > 0 && servers.length > 0);
-    if (enabled) {
+    if (appkitMode === true && !application) {
+      throw new Error("appkit: true requires an application root");
+    }
+    if (application && (appkitMode === true || isAppKitApplication(application))) {
       new AppKitWorkspace(project, {
-        apps,
-        servers,
+        application,
+        bundle: options.appBundle,
         validate: appkitMode === true,
       });
     }

package/src/project-predicate.ts

@@ -3,14 +3,8 @@
  * package identity, tags, and repository path.
  */
 import { relative } from "node:path";
-import { match, PathMatchInput, PathMatchPredicate } from "@dbx-tools/path";
-import {
-  object,
-  predicate,
-  Sequence,
-  type OneOrMany,
-  type Predicate,
-} from "@dbx-tools/shared-core";
+import { PathMatchInput, PathMatchPredicate, toPathMatcher } from "@dbx-tools/path";
+import { Sequence, type OneOrMany, type Predicate, sequence, create } from "@dbx-tools/shared-core";
 import { IConstruct } from "constructs";
 import { Project } from "projen";
 import { toPosix } from "./packages.ts";
@@ -28,7 +22,7 @@ import type { DBXToolsProject } from "./project.ts";
  * silently reject that construct before the install problem can be diagnosed.
  */
 export function isProject(): Predicate<IConstruct, Project> {
-  return predicate.create((c: IConstruct): c is Project => Project.isProject(c));
+  return create((c: IConstruct): c is Project => Project.isProject(c));
 }
 
 /** Guard: the construct implements the language-agnostic {@link DBXToolsProject} contract. */
@@ -53,9 +47,8 @@ export function isDBXToolsJavaScriptProject(): Predicate<IConstruct, DBXToolsJav
  * the resulting predicate.
  */
 function projectMatchers(...inputs: OneOrMany<PathMatchInput>): Sequence<PathMatchPredicate> {
-  return object
-    .sequence(inputs)
-    .map((input) => match.toPathMatcher(input))
+  return sequence(inputs)
+    .map((input) => toPathMatcher(input))
     .cache();
 }
 

package/src/project-py.ts

@@ -1,8 +1,8 @@
 /** Reusable uv workspace generation for Python packages hosted in a projen tree. */
 import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
-import * as projectUtils from "@dbx-tools/core/project-utils";
-import { stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
+import { projectUtils } from "@dbx-tools/core";
+import { type OneOrMany, toSlug, dedent } from "@dbx-tools/shared-core";
 import { Component, License, TextFile, type Project, github, javascript, python } from "projen";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { header, PYTHON_GENERATED_PACKAGE } from "./generated.ts";
@@ -350,8 +350,8 @@ export class DBXToolsPythonWorkspace extends Component {
   constructor(project: javascript.NodeProject, options: DBXToolsPythonWorkspaceOptions) {
     super(project);
     const scope = isDBXToolsJavaScriptProject()(project)
-      ? stringUtils.toSlug(project.scope)
-      : stringUtils.toSlug(project.name).replace(/-root$/, "");
+      ? toSlug(project.scope)
+      : toSlug(project.name).replace(/-root$/, "");
     const repositoryUrl =
       options.repository?.url ??
       projectRepositoryUrl(project) ??
@@ -379,7 +379,7 @@ export class DBXToolsPythonWorkspace extends Component {
         directory,
         description: `${scope} ${directory} Python package.`,
         ...pkg,
-        name: pkg?.name ?? `${scope}-${stringUtils.toSlug(directory)}`,
+        name: pkg?.name ?? `${scope}-${toSlug(directory)}`,
         module: pkg?.module ?? pythonModuleName(scope, directory),
       };
     });
@@ -802,7 +802,7 @@ export class DBXToolsPythonWorkspace extends Component {
       marker: true,
       readonly: true,
       // prettier-ignore
-      lines: stringUtils.dedent(
+      lines: dedent(
         // ============================================================================
         /*js*/`
           #!/usr/bin/env bun