create-ailk 0.5.0 → 0.6.0

package/templates/apps/mcp/src/lib/audit-single-page.ts

@@ -16,11 +16,21 @@
 
 import { join } from "node:path";
 
-import { type AuditInput } from "@working-theory/aeo";
-import { createMdxAdapter, type SchemaOrgType } from "@working-theory/content-adapters";
+import {
+  READINESS_SCAN_TYPES,
+  type AuditInput,
+  type ReadinessPageFacts,
+} from "@working-theory/aeo";
+import {
+  type ContentAdapter,
+  type ContentPage,
+  type SchemaOrgType,
+} from "@working-theory/content-adapters";
 import { buildJsonLd, pageTypeRegistry } from "@working-theory/schema";
 
+import { getMcpContentAdapter } from "./content-adapter.js";
 import { resolveLocale } from "./resolve-locale.js";
+import { readStripeTaxSignal } from "./stripe-tax-signal.js";
 
 export interface SlugInput {
   slug: string;
@@ -121,15 +131,86 @@ function extractTypeSlugFromUrl(raw: string): {
   return { type, slug };
 }
 
+/**
+ * The site-level view the readiness rules grade (#5949 FR9/D5).
+ *
+ * Five adapter calls, bounded and type-closed: the collection-style pair for
+ * `Product` / `Service`, the landing-style pair for the three policy types.
+ * Independent of site size and of which page was audited (NFR4). The five
+ * are independent of each other, so they run concurrently (#6012).
+ *
+ * Fail-open-to-pass, stated: under an unresolved adapter every list is `[]`,
+ * `sitePages` is empty, and all three rules pass — a site with no known priced
+ * page owes no policy page, which is the correct verdict for "the audit could
+ * not see the site". A type the adapter legitimately has no pages of resolves
+ * this way too, silently — it is not an error.
+ *
+ * A GENUINE adapter failure (the call throws) is a different condition from
+ * that silent "no pages of this type" case, and collapsing the two loses the
+ * distinction: never a throw that would take down an audit of an unrelated
+ * page, but the failure is surfaced rather than vanishing indistinguishably
+ * into the same vacuous pass (#6012, from the #6010 review).
+ *
+ * Logged via `console.error`, NOT `console.debug`/`console.log` — on the
+ * default stdio MCP transport (`apps/mcp/src/index.ts`), stdout IS the
+ * JSON-RPC framing channel, and `console.debug`/`console.log` both write
+ * there (they are the same stream in Node). `console.error` (stderr) is the
+ * convention this file's own bootstrap already uses for exactly this reason
+ * (`index.ts:43,63`) — writing anywhere else would corrupt the protocol
+ * stream for a mere adapter hiccup on one readiness-scan type.
+ */
+async function scanSitePages(
+  adapter: ContentAdapter,
+  locale: string,
+): Promise<ReadinessPageFacts[]> {
+  const perType = await Promise.all(
+    READINESS_SCAN_TYPES.map(async (type) => {
+      const isDetail = type === "Product" || type === "Service";
+      try {
+        const pages = isDetail
+          ? await adapter.listDetail(type, locale)
+          : await adapter.listPages(type, locale);
+        return { type, pages };
+      } catch (err) {
+        console.error(
+          `[aeo] readiness scan: adapter threw listing type "${type}" — ` +
+            "treating as no pages for it",
+          err,
+        );
+        return { type, pages: [] as ContentPage[] };
+      }
+    }),
+  );
+
+  const facts: ReadinessPageFacts[] = [];
+  for (const { type, pages } of perType) {
+    for (const page of pages) {
+      facts.push({
+        slug: page.slug,
+        type,
+        ...(page.price !== undefined && { price: page.price }),
+        ...(page.stripe?.taxCode !== undefined && {
+          taxCode: page.stripe.taxCode,
+        }),
+      });
+    }
+  }
+  return facts;
+}
+
 /**
  * Builds an `AuditInput` for a single page.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
  * resolves the content root relative to cwd (supports ESM runtime).
+ *
+ * `projectRoot` is the matching seam for the project.yaml the Stripe-Tax signal
+ * is read from (#5949 D9); it likewise defaults to the process cwd.
  */
 export async function buildSinglePageAuditInput(
   input: SinglePageInput,
   contentRoot?: string,
+  projectRoot?: string,
 ): Promise<AuditInput> {
   // Validate: exactly one of slug or url, not both, not neither.
   const hasSlug = "slug" in input;
@@ -146,7 +227,7 @@ export async function buildSinglePageAuditInput(
 
   const root = contentRoot ?? join(process.cwd(), "content");
   const locale = resolveLocale(input.locale);
-  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+  const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 
   let type: SchemaOrgType;
   let slug: string;
@@ -184,11 +265,17 @@ export async function buildSinglePageAuditInput(
     // This mirrors packages/aeo/src/cli/build-input.ts behavior.
   }
 
+  const stripeTaxEnabled = readStripeTaxSignal(projectRoot ?? process.cwd());
+
   return {
     pages: [{ slug, type, locale }],
     locale,
     identityMode: DEFAULT_IDENTITY_MODE,
     registry: pageTypeRegistry,
     jsonLdByPage,
+    readiness: {
+      sitePages: await scanSitePages(adapter, locale),
+      ...(stripeTaxEnabled !== undefined && { stripeTaxEnabled }),
+    },
   };
 }

package/templates/apps/mcp/src/lib/commerce-claim.ts

@@ -0,0 +1,94 @@
+/**
+ * The deployment's `commerce` add-on claim, resolved ONCE at boot and read
+ * synchronously thereafter (#5971 spec D2).
+ *
+ * Why memoised: `createMcpServer()` and `listRegisteredTools()`
+ * (`apps/mcp/src/server.ts`) are synchronous and must stay that way —
+ * `checkLicense()` is not. `lib/public-workspace.ts` (#5876) already solved
+ * this exact shape for the content adapter, and this file follows it
+ * verbatim rather than inventing a second idiom: `apps/mcp/src/index.ts`
+ * awaits the initialiser once, before either transport branch, and every
+ * reader takes the memoised value.
+ *
+ * Why TWO states where `apps/api/src/lib/require-commerce-claim.ts` has
+ * three: that file's `undetermined` arm exists for exactly one caller — the
+ * Stripe webhook receiver, which must hold an event with a retryable 503
+ * rather than drop a charge that already moved. `start_purchase` is the twin
+ * of the checkout LAUNCHER, not the webhook, and the launcher answers the
+ * module-disabled response on both non-serving states because a checkout that
+ * cannot be started loses nothing. So `undetermined` collapses into
+ * `unclaimed` at the boundary, and this gate needs neither the stored-JWT read
+ * nor the env-presence read the API twin carries.
+ *
+ * Fail closed (NFR-3): the initial state is `"unclaimed"`, and every path that
+ * cannot POSITIVELY establish the claim — an unresolved boot, a thrown
+ * `checkLicense()`, a revoked licence, an expired or unreadable one — leaves
+ * it that way.
+ *
+ * `apps/*` may not import `apps/*`, so the small duplication of the API-side
+ * gate is the same shape `apps/mcp/src/config/modules.ts` already documents
+ * for `isModuleEnabled`.
+ */
+
+import { checkLicense } from "@working-theory/license";
+
+/** The licence `features[]` claim that turns the commerce add-on on — the
+ * same literal `apps/api/src/lib/require-commerce-claim.ts` reads. */
+const COMMERCE_FEATURE = "commerce";
+
+/** Two states: the claim is positively held, or it is not. */
+export type McpCommerceClaim = "claimed" | "unclaimed";
+
+let claim: McpCommerceClaim = "unclaimed";
+
+export interface InitMcpCommerceClaimOptions {
+  /** Injection seam for tests — when supplied, used in place of the real
+   * `checkLicense()` so no suite reaches a licence server (NFR-6). */
+  checkLicense?: typeof checkLicense;
+}
+
+/**
+ * Resolves the deployment's commerce claim, once, and memoises it for
+ * {@link mcpCommerceClaim}'s synchronous read. Safe to call more than once
+ * (each call re-resolves and re-memoises); production calls it exactly once,
+ * at bootstrap (`index.ts`).
+ *
+ * Never throws: a licence read that fails resolves to the fail-closed
+ * `"unclaimed"` rather than propagating.
+ */
+export async function initMcpCommerceClaim(
+  options: InitMcpCommerceClaimOptions = {},
+): Promise<McpCommerceClaim> {
+  const read = options.checkLicense ?? checkLicense;
+  try {
+    const result = await read();
+    // Revoked paid licences keep verifying until JWT exp (up to 24h after the
+    // server reports `revoked`) — the same window `lib/require-paid-tier.ts`
+    // closes. See packages/license/src/types.ts § LicenseResult, ADR 0014.
+    claim =
+      result.revoked !== true && result.features.includes(COMMERCE_FEATURE)
+        ? "claimed"
+        : "unclaimed";
+  } catch {
+    claim = "unclaimed";
+  }
+  return claim;
+}
+
+/** The memoised claim, read synchronously by both gates in `server.ts` and
+ * by `tools/purchase.ts`'s call-time re-check. */
+export function mcpCommerceClaim(): McpCommerceClaim {
+  return claim;
+}
+
+/** Test-only injector — sets the memoised claim directly, bypassing the
+ * licence read entirely. The seam every claim-state matrix in
+ * `apps/mcp/__tests__` drives both halves through. */
+export function __setMcpCommerceClaimForTest(next: McpCommerceClaim): void {
+  claim = next;
+}
+
+/** Test-only reset — returns to the module's initial, fail-closed state. */
+export function resetMcpCommerceClaim(): void {
+  claim = "unclaimed";
+}

package/templates/apps/mcp/src/lib/content-adapter.ts

@@ -0,0 +1,113 @@
+/**
+ * The one content-adapter seam for apps/mcp (#5805).
+ *
+ * Adapter selection is NOT decided here — it is `resolveContentAdapter()`'s job
+ * (#5804, roadmap D3: one resolver, one env var). This module supplies the MCP
+ * server's own inputs (content root, resolved locale) and nothing else, so the
+ * twelve content tools and `audit-single-page` no longer each build their own
+ * MDX adapter against their own root. Mirrors
+ * `apps/api/src/lib/content-adapter.ts`, which adopted the resolver in #5827.
+ *
+ * `CONTENT_ADAPTER` selects: `mdx` (default) | `projection` | `database`.
+ * `CONTENT_BACKEND` is read for one more release by the resolver's shim.
+ *
+ * `CONTENT_ADAPTER=database` (#5876 spec D2/D4/D5/D6/D13). The `mdx` and
+ * `projection` paths below are byte-identical to before this issue — no
+ * `workspaceId`, no `await import()`, no workspace read (D6, NFR-1/NFR-2). On
+ * `database`, this seam reads `mcpPublicWorkspace()` — the resolution
+ * `apps/mcp/src/index.ts` already awaited once at bootstrap
+ * (`public-workspace.ts`, D4) — and forwards `workspaceId` + `prisma` to the
+ * resolver on a resolved deployment; every other arm (unresolved, or a tool
+ * invoked before bootstrap resolved) returns the fail-closed
+ * `emptyContentAdapter()` (D5), never a client-supplied workspace, never a
+ * throw. On BOTH arms the returned adapter is READ-ONLY under `database`:
+ * `createPage`/`updatePage`/`deletePage`/`getPageVersion` throw the named
+ * write error (D13) — this seam also serves `apps/mcp/src/tools/create_page.ts`
+ * et al. when they exist, so the boundary is held here, not per tool.
+ *
+ * The `contentRoot` argument is the test-override seam every tool already
+ * exposes as its optional second parameter — tests inject a fixture root
+ * through it, and that keeps working unchanged.
+ */
+
+import { join } from "node:path";
+
+import {
+  resolveContentAdapter,
+  resolvedAdapterKind,
+  type ContentAdapter,
+  type MdxContentAdapter,
+} from "@working-theory/content-adapters";
+
+import {
+  emptyContentAdapter,
+  readOnlyContentAdapter,
+} from "./empty-content-adapter.js";
+import { mcpPublicWorkspace } from "./public-workspace.js";
+
+export interface McpContentAdapterOptions {
+  /** Filesystem content root. Defaults to `<cwd>/content` — the tools' prior default. */
+  contentRoot?: string;
+  /** Locale already resolved against the project allowlist (`resolveLocale()`). */
+  locale?: string;
+}
+
+/**
+ * Returns the `ContentAdapter` the environment selects, rooted at the caller's
+ * content root. The resolver memoises per distinct option set, so this is safe
+ * to call on every tool invocation.
+ */
+export function getMcpContentAdapter(
+  options: McpContentAdapterOptions = {},
+): ContentAdapter {
+  const contentRoot = options.contentRoot ?? join(process.cwd(), "content");
+  const defaultLocale = options.locale;
+
+  if (resolvedAdapterKind() !== "database") {
+    return resolveContentAdapter({ contentRoot, defaultLocale });
+  }
+
+  const workspace = mcpPublicWorkspace();
+  if (workspace.kind !== "resolved") {
+    return emptyContentAdapter();
+  }
+
+  const adapter = resolveContentAdapter({
+    workspaceId: workspace.workspaceId,
+    prisma: workspace.prisma,
+    contentRoot,
+    defaultLocale,
+  });
+  // Under CONTENT_ADAPTER=database, resolveContentAdapter() always builds a
+  // DatabaseContentAdapter (packages/content-adapters/src/database/adapter.ts),
+  // which always exposes getPageSource — the read-only wrapper needs the
+  // MdxContentAdapter shape to pass the six reads + getPageSource through
+  // untouched and gate only the four write methods (D13).
+  return readOnlyContentAdapter(adapter as MdxContentAdapter);
+}
+
+/**
+ * The same resolution, narrowed to the MDX adapter's richer surface.
+ *
+ * `read_content` returns a page's raw MDX body, which only
+ * `MdxContentAdapter.getPageSource()` provides — the base `ContentAdapter`
+ * contract returns frontmatter only. Rather than cast, this asserts the
+ * capability on the adapter the resolver actually built, so a server pointed
+ * at a non-MDX `CONTENT_ADAPTER` gets a named error instead of a
+ * `getPageSource is not a function` TypeError. On the default `mdx` path the
+ * check always passes and behaviour is unchanged. Under `database`, both the
+ * fail-closed empty adapter and the read-only-wrapped database adapter also
+ * provide `getPageSource`, so the check passes there too (D5).
+ */
+export function getMcpMdxContentAdapter(
+  options: McpContentAdapterOptions = {},
+): MdxContentAdapter {
+  const adapter = getMcpContentAdapter(options);
+  if (typeof (adapter as MdxContentAdapter).getPageSource !== "function") {
+    throw new Error(
+      "This tool needs the MDX adapter's getPageSource(): the adapter selected by " +
+        "CONTENT_ADAPTER does not provide a raw MDX body. Use CONTENT_ADAPTER=mdx (the default).",
+    );
+  }
+  return adapter as MdxContentAdapter;
+}

package/templates/apps/mcp/src/lib/empty-content-adapter.ts

@@ -0,0 +1,139 @@
+/**
+ * The fail-closed EMPTY adapter (#5876 spec D5) — a null object that holds
+ * no client and issues no query. `getMcpContentAdapter()` (`content-adapter.ts`)
+ * returns it whenever the environment selects `CONTENT_ADAPTER=database` and
+ * the deployment's workspace resolution (`public-workspace.ts`) did not land
+ * at `{ kind: "resolved" }`.
+ *
+ * All eleven `MdxContentAdapter` methods are specified, not left to throw a
+ * generic TypeError: the six reads plus `getPageSource` return their own
+ * not-found/empty shape, and the four write methods throw the SAME named
+ * error `readOnlyContentAdapter()` (below) throws on the RESOLVED arm
+ * (#5876 spec D13) — the seam is read-only under `CONTENT_ADAPTER=database`
+ * on both arms, not only this fail-closed one.
+ *
+ * Three properties follow for free from this shape, over the rejected
+ * alternatives (throwing the resolver's own "workspaceId required" error, or
+ * returning `null` from the seam and guarding per tool):
+ *
+ *   1. Every content tool's own not-found/empty mapping fires with NO tool
+ *      edit — `read_content` and `get_*` already treat `null` as not-found;
+ *      `list_pages` and `search_content` already treat `[]` as empty.
+ *   2. "Before any content lookup" (NFR-5) is structural, not asserted —
+ *      there is nothing here to look anything up in.
+ *   3. `getMcpMdxContentAdapter()`'s `typeof getPageSource === "function"`
+ *      capability check (`content-adapter.ts`) passes, so `read_content`
+ *      never sees THAT named throw on the fail-closed path.
+ */
+import type {
+  ContentPage,
+  ExtractionType,
+  MdxContentAdapter,
+  MdxPageSource,
+  SchemaOrgType,
+  SearchOptions,
+  SearchResult,
+  StructuredDataFor,
+} from "@working-theory/content-adapters";
+
+/**
+ * The one message every write method throws, on BOTH the empty adapter and
+ * the read-only wrapper of a resolved database adapter — the seam is
+ * read-only under `CONTENT_ADAPTER=database`, full stop (#5876 spec D13).
+ * The three write MCP tools this boundary was drawn against
+ * (`create_page`/`update_page`/`delete_page`) were retired ahead of this
+ * issue (#5853); this is the seam's own STOP boundary, held independent of
+ * which tools currently reach it.
+ */
+const WRITE_NOT_SUPPORTED_MESSAGE =
+  "This MCP server's CONTENT_ADAPTER=database seam is read-only: " +
+  "createPage/updatePage/deletePage/getPageVersion are not available here. " +
+  "Content writes go through apps/api's tenant-guarded workspace content routes.";
+
+function throwWriteNotSupported(): never {
+  throw new Error(WRITE_NOT_SUPPORTED_MESSAGE);
+}
+
+/**
+ * A null object satisfying `MdxContentAdapter`. Holds no client; every read
+ * method resolves synchronously to its empty shape with no I/O.
+ */
+export function emptyContentAdapter(): MdxContentAdapter {
+  const adapter: MdxContentAdapter = {
+    async getPageBySlug(
+      _type: SchemaOrgType,
+      _slug: string,
+      _locale?: string,
+    ): Promise<ContentPage | null> {
+      return null;
+    },
+    async listPages(
+      _type: SchemaOrgType,
+      _locale?: string,
+    ): Promise<ContentPage[]> {
+      return [];
+    },
+    async getDetailBySlug(
+      _type: SchemaOrgType,
+      _slug: string,
+      _locale?: string,
+    ): Promise<ContentPage | null> {
+      return null;
+    },
+    async listDetail(
+      _type: SchemaOrgType,
+      _locale?: string,
+    ): Promise<ContentPage[]> {
+      return [];
+    },
+    async searchPages(
+      _query: string,
+      _options?: SearchOptions,
+    ): Promise<SearchResult[]> {
+      return [];
+    },
+    async extractStructuredData<T extends ExtractionType>(
+      _type: T,
+      _slug: string,
+      _locale?: string,
+    ): Promise<StructuredDataFor<T> | null> {
+      return null;
+    },
+    async getPageSource(
+      _type: SchemaOrgType,
+      _slug: string,
+      _locale?: string,
+    ): Promise<MdxPageSource | null> {
+      return null;
+    },
+    createPage: throwWriteNotSupported,
+    updatePage: throwWriteNotSupported,
+    deletePage: throwWriteNotSupported,
+    getPageVersion: throwWriteNotSupported,
+  };
+  return adapter;
+}
+
+/**
+ * Wraps a RESOLVED database adapter so its four write methods throw the same
+ * read-only error the empty adapter throws — the seam is read-only under
+ * `CONTENT_ADAPTER=database` on both arms (#5876 spec D13). The six read
+ * methods and `getPageSource` pass through untouched.
+ */
+export function readOnlyContentAdapter(
+  adapter: MdxContentAdapter,
+): MdxContentAdapter {
+  return {
+    getPageBySlug: adapter.getPageBySlug.bind(adapter),
+    listPages: adapter.listPages.bind(adapter),
+    getDetailBySlug: adapter.getDetailBySlug.bind(adapter),
+    listDetail: adapter.listDetail.bind(adapter),
+    searchPages: adapter.searchPages.bind(adapter),
+    extractStructuredData: adapter.extractStructuredData.bind(adapter),
+    getPageSource: adapter.getPageSource.bind(adapter),
+    createPage: throwWriteNotSupported,
+    updatePage: throwWriteNotSupported,
+    deletePage: throwWriteNotSupported,
+    getPageVersion: throwWriteNotSupported,
+  };
+}

package/templates/apps/mcp/src/lib/prisma.ts

@@ -0,0 +1,39 @@
+/**
+ * Lazy Prisma client singleton for apps/mcp's `CONTENT_ADAPTER=database` path
+ * (#5876 spec D7).
+ *
+ * Deliberately NOT the eager, module-scope-construction shape of
+ * `apps/api/src/lib/prisma.ts` / `apps/web/lib/prisma-for-auth.ts`: this
+ * module is reached only from `initMcpPublicWorkspace()`'s `database` branch
+ * (`public-workspace.ts`), via `await import("./prisma.js")`, and only when
+ * the caller supplied no `prisma` of its own — the injection seam every test
+ * uses instead (FR-1). Constructing at MODULE scope — with a
+ * `connectionString` that is `undefined` on every MDX-only deployment (the
+ * 350 pre-existing apps/mcp tests set no `DATABASE_URL`) — would break the
+ * no-`DATABASE_URL` scaffold the instant this file was imported anywhere,
+ * even transitively. Construction happens on first CALL and is memoised
+ * after that, mirroring #5852's identical deferral of the apps/api client
+ * (`apps/api/src/services/public-site-resolver.ts` § D6).
+ */
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "@working-theory/database";
+
+let client: PrismaClient | undefined;
+
+/**
+ * The process-wide lazy Prisma client for the MCP server's database path.
+ * Constructs on first call; every subsequent call returns the same instance.
+ */
+export function getMcpPrismaClient(): PrismaClient {
+  if (client === undefined) {
+    const adapter = new PrismaPg({
+      connectionString: process.env.DATABASE_URL,
+    });
+    client = new PrismaClient({
+      adapter,
+      log:
+        process.env.NODE_ENV === "development" ? ["error", "warn"] : ["error"],
+    });
+  }
+  return client;
+}

package/templates/apps/mcp/src/lib/public-workspace.ts

@@ -0,0 +1,133 @@
+/**
+ * The MCP server's own workspace resolution (#5876 spec D2/D4/D6/D7) — which
+ * workspace `CONTENT_ADAPTER=database` content reads serve, resolved ONCE at
+ * bootstrap and read synchronously thereafter by `content-adapter.ts`.
+ *
+ * WHY RESOLUTION HAPPENS AT BOOTSTRAP, NOT PER CALL (D4). Workspace
+ * resolution is I/O (a `workspace.count()` + `findUnique()`), but
+ * `getMcpContentAdapter()` stays SYNCHRONOUS — every one of its thirteen
+ * call sites (nine read tools, `audit-single-page.ts`, and the three write
+ * tools) calls it without `await`. Making it async would force `await` at
+ * every one of those sites, a needless cross-cutting edit to a hard-floor
+ * surface (`apps/mcp/src/tools/**`). So `apps/mcp/src/index.ts` awaits
+ * `initMcpPublicWorkspace()` once, before either transport branch, and the
+ * result is memoised here for `mcpPublicWorkspace()`'s synchronous read.
+ *
+ * A tool invoked before `initMcpPublicWorkspace()` has resolved sees the
+ * module's initial `{ kind: "not-required" }` state — which the seam reads
+ * exactly like an unresolved deployment under `database` mode (the empty
+ * adapter, never content). That is the accepted, safe-direction cost D4
+ * names, and it's what keeps the 350 pre-existing tests — which never call
+ * `init` — on the byte-identical MDX path.
+ *
+ * NO-OP UNLESS THE ENVIRONMENT SELECTS `database` (D6). On `mdx` and
+ * `projection`, `initMcpPublicWorkspace()`'s first statement is the same
+ * `resolvedAdapterKind()` test the seam itself uses, and it returns before
+ * any `await import()` — no database round-trip, no `DATABASE_URL` read, on
+ * every MDX-only deployment.
+ *
+ * THE ONE-WORKSPACE PREDICATE IS SHARED, NOT REIMPLEMENTED (D2). This module
+ * issues no direct tenant-model query of its own — it delegates to
+ * `@working-theory/database/tenancy`'s `resolveDefaultWorkspaceRow`, the same
+ * predicate `apps/api/src/services/default-tenant.ts` re-points at. One
+ * predicate, reached from two apps, never two predicates (NFR-7).
+ *
+ * THE LAZY CLIENT (D7). The `prisma` injection option is the seam AC-1/AC-2
+ * are scored through: when the caller supplies one, `./prisma.js` (the
+ * module that constructs a real `PrismaClient`) is never imported — which is
+ * what keeps every test in this repo's ordinary Jest run off a real
+ * database connection (NFR-6).
+ */
+import {
+  resolvedAdapterKind,
+  type ArtifactPrismaClient,
+} from "@working-theory/content-adapters";
+import {
+  resolveDefaultWorkspaceRow,
+  type WorkspacePredicateClient,
+} from "@working-theory/database/tenancy";
+
+/**
+ * The three answers the MCP server's own workspace resolution can reach.
+ * `reason` exists for the caller's own logging only — no MCP tool emits it
+ * to the (anonymous, unauthenticated) caller (NFR-4, mirroring
+ * `apps/api/src/services/public-site-resolver.ts`'s identical
+ * `PublicSiteResolution`). Unlike that HTTP twin, there is no `host-unmatched`
+ * arm here: an MCP stdio session carries no HTTP request and no host to
+ * mismatch against (§2.3 — a host→workspace branch is explicitly out of
+ * scope, #3635's to add).
+ */
+export type McpWorkspaceResolution =
+  | { kind: "not-required" }
+  | { kind: "resolved"; workspaceId: string; prisma: ArtifactPrismaClient }
+  | { kind: "unresolved"; reason: "ambiguous" };
+
+export interface InitMcpPublicWorkspaceOptions {
+  /**
+   * Injection seam for tests (D7, D11) — when supplied, `initMcpPublicWorkspace()`
+   * uses it and never loads `./prisma.js`. Typed as the narrow surface THIS
+   * function itself calls (`workspace.count`/`findUnique`); the real
+   * `PrismaClient` (or a caller-injected structural equivalent) is
+   * structurally wider and also satisfies `ArtifactPrismaClient`, which is
+   * what the seam later forwards to `resolveContentAdapter()`.
+   */
+  prisma?: WorkspacePredicateClient;
+}
+
+let resolution: McpWorkspaceResolution = { kind: "not-required" };
+
+/**
+ * Resolves the MCP server's workspace, once. Memoises the result for
+ * `mcpPublicWorkspace()`'s synchronous read. Safe to call more than once
+ * (each call re-resolves and re-memoises) — production calls it exactly once,
+ * at bootstrap (`index.ts`).
+ */
+export async function initMcpPublicWorkspace(
+  options: InitMcpPublicWorkspaceOptions = {},
+): Promise<McpWorkspaceResolution> {
+  if (resolvedAdapterKind() !== "database") {
+    resolution = { kind: "not-required" };
+    return resolution;
+  }
+
+  // Deferred — see this file's header (D7) and #5852's identical deferral of
+  // apps/api's own client (`services/public-site-resolver.ts`).
+  const prisma =
+    options.prisma ?? (await import("./prisma.js")).getMcpPrismaClient();
+  const workspace = await resolveDefaultWorkspaceRow(prisma);
+  resolution =
+    workspace === null
+      ? { kind: "unresolved", reason: "ambiguous" }
+      : {
+          kind: "resolved",
+          workspaceId: workspace.id,
+          prisma: prisma as unknown as ArtifactPrismaClient,
+        };
+  return resolution;
+}
+
+/**
+ * The memoised resolution, read synchronously. `content-adapter.ts`'s
+ * `database` branch is the one caller in production; every arm other than
+ * `{ kind: "resolved" }` maps to the fail-closed empty adapter.
+ */
+export function mcpPublicWorkspace(): McpWorkspaceResolution {
+  return resolution;
+}
+
+/** Test-only injector — sets the memoised resolution directly, bypassing the
+ * tenancy predicate entirely. This is the seam `read_content.test.ts`,
+ * `list_pages.test.ts` and `fail-closed-tools.test.ts` use: they care about
+ * the CONTENT tools' behaviour under a given resolution, not about exercising
+ * the resolution logic itself (that's `public-workspace.test.ts`'s job, via
+ * the real `initMcpPublicWorkspace({ prisma: <stub> })`). */
+export function __setMcpPublicWorkspaceForTest(
+  next: McpWorkspaceResolution,
+): void {
+  resolution = next;
+}
+
+/** Test-only reset — returns to the module's initial, pre-bootstrap state. */
+export function resetMcpPublicWorkspace(): void {
+  resolution = { kind: "not-required" };
+}