create-ailk 0.24.0 → 0.26.0

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

@@ -1,140 +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 answer their empty
- *      `ItemList` over `[]` (#7167: the routes' own envelopes).
- *   2. "Before any content lookup" (NFR-5) is structural, not asserted —
- *      there is nothing here to look anything up in.
- *   3. `readContentDocument`'s `typeof getPageSource === "function"`
- *      capability check (`@working-theory/content-adapters`) 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;
-}

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

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

package/templates/apps/mcp/src/lib/resolve-locale.ts

@@ -1,30 +0,0 @@
-/**
- * resolveLocale — validate a caller-supplied locale against the project's
- * allowlist. Phase 3 S3.
- *
- * Returns the requested locale when it's present in `readLocales()`;
- * otherwise silently falls back to the project's default locale (AC-i18n-07).
- *
- * Failures reading `project.yaml` degrade to a default-locale-only allowlist
- * — mirrors the same defensive behavior in `apps/api/src/routes/content/*`.
- *
- * This boundary check is defense-in-depth on top of the adapter's BCP-47
- * regex; the adapter still applies its own check and fallback chain on
- * every read.
- */
-
-import { readDefaultLocale, readLocales } from "./locales.js";
-
-export function resolveLocale(requested: string | undefined): string {
-  const defaultLocale = readDefaultLocale();
-  if (requested === undefined) return defaultLocale;
-
-  let allow: string[];
-  try {
-    allow = readLocales();
-  } catch {
-    allow = [defaultLocale];
-  }
-
-  return allow.includes(requested) ? requested : defaultLocale;
-}