create-ailk 0.23.0 → 0.25.1

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

@@ -1,142 +0,0 @@
-/**
- * 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
- * `bootMcp()` (`apps/mcp/src/boot.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. Absent, every tool and
- * `audit-single-page` take {@link mcpContentRoot} (#8070 D3).
- */
-
-import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
-
-import {
-  resolveContentAdapter,
-  resolvedAdapterKind,
-  type ContentAdapter,
-  type MdxContentAdapter,
-} from "@working-theory/content-adapters";
-
-import {
-  emptyContentAdapter,
-  readOnlyContentAdapter,
-} from "./empty-content-adapter.js";
-import { publicWorkspace } from "./topology.generated.js";
-
-export interface McpContentAdapterOptions {
-  /** Filesystem content root. Defaults to {@link mcpContentRoot}. */
-  contentRoot?: string;
-  /** Locale already resolved against the project allowlist (`resolveLocale()`). */
-  locale?: string;
-}
-
-/**
- * The MCP server's content root — the ONE place apps/mcp derives it (#8070 D3).
- *
- * In order: `AILK_CONTENT_ROOT` when set and non-empty (absolute, or resolved
- * against the working directory); else `<cwd>/content` when it exists (the
- * server started from the repo root); else `<cwd>/../../content` when it
- * exists (the server started from `apps/mcp` — a Vercel project whose root
- * directory is `apps/mcp`); else `<cwd>/content`, the prior default, so a
- * missing root keeps serving the same empty result it always did.
- *
- * Read on every call, never cached: it is two `existsSync` probes, and a
- * cached value would pin the first working directory a test or a host used.
- */
-export function mcpContentRoot(): string {
-  const cwd = process.cwd();
-  const override = process.env["AILK_CONTENT_ROOT"]?.trim();
-  if (override) return resolve(cwd, override);
-
-  const local = join(cwd, "content");
-  if (existsSync(local)) return local;
-
-  const repo = join(cwd, "..", "..", "content");
-  if (existsSync(repo)) return repo;
-
-  return local;
-}
-
-/**
- * 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 ?? mcpContentRoot();
-  const defaultLocale = options.locale;
-
-  if (resolvedAdapterKind() !== "database") {
-    return resolveContentAdapter({ contentRoot, defaultLocale });
-  }
-
-  const workspace = publicWorkspace();
-  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

@@ -1,139 +0,0 @@
-/**
- * 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/errors.ts

@@ -1,61 +0,0 @@
-/**
- * Canonical error shape for apps/mcp content-write tools (D14a Stage 0).
- *
- * Mirrors the apps/api shape (`apps/api/src/lib/errors.ts`) intentionally —
- * REST and MCP surfaces must produce isomorphic error bodies (per brief
- * Layer 1 AC). The only structural difference is that MCP returns the body as
- * the tool result itself; HTTP carries it alongside a status code.
- *
- * Codes are the same closed set used by apps/api so an agent calling either
- * surface gets the same machine-readable shape.
- */
-
-export type ErrorCode =
-  | "validation_failed"
-  | "not_found"
-  | "conflict"
-  | "payment_required"
-  | "unauthorized";
-
-export interface ErrorBody {
-  error: ErrorCode;
-  message: string;
-  details?: Record<string, unknown>;
-}
-
-function makeBody(
-  code: ErrorCode,
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorBody {
-  if (details === undefined) {
-    return { error: code, message };
-  }
-  return { error: code, message, details };
-}
-
-export function validationError(
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorBody {
-  return makeBody("validation_failed", message, details);
-}
-
-export function unauthorizedError(message: string): ErrorBody {
-  return makeBody("unauthorized", message);
-}
-
-export function paymentRequiredError(message: string): ErrorBody {
-  return makeBody("payment_required", message);
-}
-
-export function notFoundError(message: string): ErrorBody {
-  return makeBody("not_found", message);
-}
-
-export function conflictError(
-  message: string,
-  details?: Record<string, unknown>,
-): ErrorBody {
-  return makeBody("conflict", message, details);
-}

package/templates/apps/mcp/src/lib/license-key-store.ts

@@ -1,45 +0,0 @@
-/**
- * Registers the durable home of a renewed licence key (#6677 DD-6).
- *
- * `@working-theory/license` renews the deployment's key before it lapses and
- * keeps the renewed key in a `LicenseKeyStore`. Its default store is a file,
- * which a redeploy wipes. With a database configured, this registers the
- * store backed by ONE deployment-wide `SiteSetting` row,
- * `(DEFAULT_WORKSPACE_ID, "license.renewed_key")`, shared with apps/api and
- * apps/web — so the key apps/api renewed is the key this server resolves.
- *
- * `index.ts` awaits this BEFORE `initMcpCommerceClaim()`, which memoises the
- * claim at boot. Both imports are dynamic and reached only when
- * `DATABASE_URL` is set, so an MDX-only deployment never constructs a Prisma
- * client (the `prisma.ts` header's rule).
- */
-
-/**
- * Register the SiteSetting-backed store when `DATABASE_URL` is set. An
- * explicitly set `AILK_LICENSE_STORAGE_PATH` is the operator choosing the
- * file store, and is honoured. Never throws: a failure logs and leaves the
- * file store in place.
- */
-export async function registerLicenseKeyStore(): Promise<void> {
-  if (!process.env["DATABASE_URL"] || process.env["AILK_LICENSE_STORAGE_PATH"]) return;
-  try {
-    const [{ getMcpPrismaClient }, { DEFAULT_WORKSPACE_ID }, license] =
-      await Promise.all([
-        import("./prisma.js"),
-        import("@working-theory/database/tenancy"),
-        import("@working-theory/license"),
-      ]);
-    const prisma = getMcpPrismaClient();
-    license.setLicenseKeyStore(
-      license.createSiteSettingLicenseKeyStore(
-        prisma.siteSetting,
-        DEFAULT_WORKSPACE_ID,
-      ),
-    );
-  } catch (err) {
-    console.error(
-      "[mcp] could not register the SiteSetting licence-key store — the file store stays in place:",
-      err instanceof Error ? err.name : "non-Error thrown",
-    );
-  }
-}

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

@@ -1,171 +0,0 @@
-/**
- * readLocales — read and validate the `product.locales` field from project.yaml.
- *
- * Mirrors `apps/web/lib/locales.ts` and `apps/api/src/lib/locales.ts`.
- * Duplicated because architecture.yaml does not permit cross-app imports
- * (apps/mcp may not import apps/web or apps/api), and a shared package for
- * filesystem helpers would extend the architectural surface beyond the scope
- * of this spec.
- *
- * Validation rules:
- * - `locales` field absent → defaults to `["en"]` (backward-compat with OSS
- *   forks that pre-date the field)
- * - `locales` present → must be a non-empty array of BCP-47 locale tags
- *   matching `/^[a-z]{2}(-[A-Z]{2})?$/` (MVP subset)
- * - `product.default_locale` must be included in the `locales` list; parse
- *   error if not
- * - `locales: []` → parse error (empty array is invalid)
- *
- * Used by content read tools to validate the `locale` parameter against the
- * configured allowlist before passing to the adapter (defense-in-depth per
- * AC-i18n-07).
- */
-
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { parse } from "yaml";
-
-/** BCP-47 MVP subset: `xx` or `xx-XX` (language + optional region). */
-const BCP47_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
-
-/**
- * Reads, validates, and returns the sorted locale list from project.yaml.
- *
- * @param cwd - Directory to search from. Defaults to `process.cwd()`.
- * @returns Sorted `string[]` of enabled locale tags.
- * @throws Error with a descriptive message (file + cause) when validation fails.
- */
-export function readLocales(cwd = process.cwd()): string[] {
-  const filePath = resolveProjectYamlPath(cwd);
-
-  let raw: string;
-  try {
-    raw = readFileSync(filePath, "utf8");
-  } catch (err) {
-    const e = new Error(
-      `[locales] Cannot read ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    (e as { cause?: unknown }).cause = err;
-    throw e;
-  }
-
-  let doc: unknown;
-  try {
-    doc = parse(raw);
-  } catch (err) {
-    const e = new Error(
-      `[locales] YAML parse error in ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    (e as { cause?: unknown }).cause = err;
-    throw e;
-  }
-
-  if (!doc || typeof doc !== "object") {
-    throw new Error(
-      `[locales] ${filePath}: expected a YAML mapping at the top level`,
-    );
-  }
-
-  const top = doc as Record<string, unknown>;
-  const product = top["product"];
-
-  const p =
-    product && typeof product === "object"
-      ? (product as Record<string, unknown>)
-      : {};
-
-  const defaultLocale =
-    typeof p["default_locale"] === "string" ? p["default_locale"] : "en";
-
-  const rawLocales = p["locales"];
-
-  if (rawLocales === undefined || rawLocales === null) {
-    return ["en"];
-  }
-
-  if (!Array.isArray(rawLocales)) {
-    throw new Error(
-      `[locales] ${filePath}: product.locales must be an array, got ${typeof rawLocales}`,
-    );
-  }
-
-  if (rawLocales.length === 0) {
-    throw new Error(
-      `[locales] ${filePath}: product.locales must be a non-empty array (got empty array)`,
-    );
-  }
-
-  for (const entry of rawLocales) {
-    if (typeof entry !== "string") {
-      throw new Error(
-        `[locales] ${filePath}: product.locales entries must be strings, got ${typeof entry}`,
-      );
-    }
-    if (!BCP47_RE.test(entry)) {
-      throw new Error(
-        `[locales] ${filePath}: product.locales entry "${entry}" is not a valid BCP-47 locale tag (expected format: xx or xx-XX)`,
-      );
-    }
-  }
-
-  const locales = rawLocales as string[];
-
-  if (!locales.includes(defaultLocale)) {
-    throw new Error(
-      `[locales] ${filePath}: product.default_locale "${defaultLocale}" is not in product.locales [${locales.join(", ")}]`,
-    );
-  }
-
-  return [...locales].sort();
-}
-
-/**
- * Read the project's default locale from project.yaml. Returns `"en"` when
- * project.yaml is absent or `product.default_locale` is unset — same default
- * as the adapter.
- */
-export function readDefaultLocale(cwd = process.cwd()): string {
-  const filePath = resolveProjectYamlPath(cwd);
-
-  let raw: string;
-  try {
-    raw = readFileSync(filePath, "utf8");
-  } catch {
-    return "en";
-  }
-
-  let doc: unknown;
-  try {
-    doc = parse(raw);
-  } catch {
-    return "en";
-  }
-
-  if (!doc || typeof doc !== "object") return "en";
-  const product = (doc as Record<string, unknown>)["product"];
-  if (!product || typeof product !== "object") return "en";
-  const defaultLocale = (product as Record<string, unknown>)["default_locale"];
-  return typeof defaultLocale === "string" ? defaultLocale : "en";
-}
-
-/**
- * Probe likely locations for project.yaml. Apps run from their own dirs in
- * dev/build (`apps/mcp/`) but from repo root in some test setups.
- */
-function resolveProjectYamlPath(cwd: string): string {
-  const candidates = [
-    join(cwd, "project.yaml"),
-    join(cwd, "..", "project.yaml"),
-    join(cwd, "..", "..", "project.yaml"),
-  ];
-  for (const candidate of candidates) {
-    try {
-      readFileSync(candidate, "utf8");
-      return candidate;
-    } catch {
-      // continue
-    }
-  }
-  return candidates[0] ?? join(cwd, "project.yaml");
-}

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

@@ -1,39 +0,0 @@
-/**
- * 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;
-}