create-ailk 0.1.0

package/templates/apps/mcp/__tests__/list_pages.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Tests for the list_pages MCP tool handler.
+ *
+ * Acceptance criteria verified here:
+ * - listPagesInputSchema validates correct inputs (optional type filter)
+ * - listPagesInputSchema rejects unknown type values
+ * - ailkListPages with a type arg returns pages for that type
+ * - ailkListPages with no type arg returns pages across all SCHEMA_ORG_TYPES
+ * - Output validates against listPagesOutputSchema
+ * - No console.* calls in handler (structural test)
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+import {
+  ailkListPages,
+  listPagesInputSchema,
+  listPagesOutputSchema,
+} from "../src/tools/list_pages.js";
+
+// Content root for real-filesystem tests — repo-relative
+const REPO_ROOT = resolve(__dirname, "../../..");
+const CONTENT_ROOT = join(REPO_ROOT, "content");
+
+describe("listPagesInputSchema", () => {
+  it("accepts empty input (type is optional)", () => {
+    const result = listPagesInputSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid SchemaOrgType", () => {
+    const result = listPagesInputSchema.safeParse({ type: "HomePage" });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts HomePage", () => {
+    const result = listPagesInputSchema.safeParse({ type: "HomePage" });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects an unknown type string", () => {
+    const result = listPagesInputSchema.safeParse({ type: "NotAType" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a numeric type", () => {
+    const result = listPagesInputSchema.safeParse({ type: 42 });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ailkListPages handler", () => {
+  it("returns pages array for a specific type", async () => {
+    const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
+
+    expect(Array.isArray(result.pages)).toBe(true);
+    // The real content/ tree has at least one HomePage
+    expect(result.pages.length).toBeGreaterThan(0);
+    for (const page of result.pages) {
+      expect(page.type).toBe("HomePage");
+      expect(typeof page.slug).toBe("string");
+      expect(typeof page.title).toBe("string");
+    }
+  });
+
+  it("returns empty pages array for a type with no content", async () => {
+    // FAQPage has no files in content/ by default
+    const result = await ailkListPages({ type: "FAQPage" }, CONTENT_ROOT);
+    expect(Array.isArray(result.pages)).toBe(true);
+  });
+
+  it("returns pages across all SCHEMA_ORG_TYPES when type is omitted", async () => {
+    const result = await ailkListPages({}, CONTENT_ROOT);
+    expect(Array.isArray(result.pages)).toBe(true);
+    // Should include at least one page (we know HomePage has content)
+    expect(result.pages.length).toBeGreaterThan(0);
+  });
+
+  it("output shape has required slug + type + title fields", async () => {
+    const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
+
+    for (const page of result.pages) {
+      expect(typeof page.slug).toBe("string");
+      expect(typeof page.type).toBe("string");
+      expect(typeof page.title).toBe("string");
+    }
+  });
+
+  it("output validates against listPagesOutputSchema", async () => {
+    const result = await ailkListPages({ type: "HomePage" }, CONTENT_ROOT);
+    const parsed = listPagesOutputSchema.safeParse(result);
+    expect(parsed.success).toBe(true);
+  });
+});
+
+describe("listPagesInputSchema — Zod boundary security", () => {
+  it("rejects input with path traversal characters in type", () => {
+    const result = listPagesInputSchema.safeParse({ type: "../etc/passwd" });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("architectural guard — no console calls", () => {
+  it("apps/mcp/src/tools/list_pages.ts does not call console.*", () => {
+    const src = readFileSync(
+      resolve(__dirname, "../src/tools/list_pages.ts"),
+      "utf-8",
+    );
+    expect(src).not.toMatch(/\bconsole\.(log|warn|error|info|debug)\b/);
+  });
+});

package/templates/apps/mcp/__tests__/locale.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for the locale parameter on content read MCP tools (Phase 3 S3).
+ *
+ * Acceptance criteria verified here:
+ * - read_content accepts an optional `locale` parameter
+ * - list_pages accepts an optional `locale` parameter
+ * - search_content accepts an optional `locale` parameter
+ * - Tool schemas accept BCP-47 tags and reject malformed values
+ * - Tool handlers return data when valid locale is passed (back-compat)
+ * - Invalid/unknown locales silently fall back to default (AC-i18n-07)
+ */
+
+import { resolve, join } from "node:path";
+
+import {
+  listPagesInputSchema,
+  readContentInputSchema,
+  searchContentInputSchema,
+} from "@working-theory/validation";
+
+import { ailkListPages } from "../src/tools/list_pages.js";
+import { ailkReadContent } from "../src/tools/read_content.js";
+import { ailkSearchContent } from "../src/tools/search_content.js";
+
+const REPO_ROOT = resolve(__dirname, "../../..");
+const CONTENT_ROOT = join(REPO_ROOT, "content");
+
+describe("locale parameter — input schemas", () => {
+  it("readContentInputSchema accepts a valid BCP-47 tag", () => {
+    const r = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+      locale: "en",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("readContentInputSchema accepts region-tagged BCP-47 (zh-CN)", () => {
+    const r = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+      locale: "zh-CN",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("readContentInputSchema rejects malformed locale (uppercase)", () => {
+    const r = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+      locale: "EN",
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("readContentInputSchema rejects path-traversal locale", () => {
+    const r = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+      locale: "../../etc/passwd",
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("readContentInputSchema accepts absent locale (optional)", () => {
+    const r = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("listPagesInputSchema accepts a valid locale", () => {
+    const r = listPagesInputSchema.safeParse({
+      type: "HomePage",
+      locale: "en",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("searchContentInputSchema accepts a valid locale", () => {
+    const r = searchContentInputSchema.safeParse({
+      query: "foo",
+      locale: "en",
+    });
+    expect(r.success).toBe(true);
+  });
+});
+
+describe("locale parameter — handler behavior (real adapter)", () => {
+  it("ailkReadContent returns the page when locale=en", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "home", locale: "en" },
+      CONTENT_ROOT,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.slug).toBe("home");
+  });
+
+  it("ailkReadContent silently falls back when locale=zz (unknown)", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "home", locale: "zz" },
+      CONTENT_ROOT,
+    );
+    // AC-i18n-07: silent fallback to default locale's content.
+    expect(result).not.toBeNull();
+    expect(result!.slug).toBe("home");
+  });
+
+  it("ailkListPages returns pages when locale=en", async () => {
+    const result = await ailkListPages(
+      { type: "HomePage", locale: "en" },
+      CONTENT_ROOT,
+    );
+    expect(Array.isArray(result.pages)).toBe(true);
+    expect(result.pages.length).toBeGreaterThan(0);
+  });
+
+  it("ailkListPages silently falls back when locale=zz", async () => {
+    const result = await ailkListPages(
+      { type: "HomePage", locale: "zz" },
+      CONTENT_ROOT,
+    );
+    // Falls back to default-locale list.
+    expect(Array.isArray(result.pages)).toBe(true);
+  });
+
+  it("ailkSearchContent returns results when locale=en", async () => {
+    const result = await ailkSearchContent(
+      { query: "AI", locale: "en" },
+      CONTENT_ROOT,
+    );
+    expect(Array.isArray(result.results)).toBe(true);
+  });
+});

package/templates/apps/mcp/__tests__/parity.test.ts

@@ -0,0 +1,205 @@
+/**
+ * MCP ↔ Server-Action parity test.
+ *
+ * Today: trivially passes (no Server Actions in apps/web, no MCP tools yet).
+ * Phase 3: every Server Action in apps/web has a matching MCP tool.
+ *
+ * Convention (locked in spec §3):
+ *   - Server Actions live at `apps/web/**\/*.actions.ts` and export a symbol
+ *     named `^[a-z][a-zA-Z0-9]*Action$` (e.g. `captureLeadAction`).
+ *   - MCP tools live at `apps/mcp/src/tools/<tool>.ts` and export a symbol
+ *     named `^ailk[A-Z][a-zA-Z0-9]*$` (e.g. `ailkCaptureLead`).
+ *   - Mapping: `<name>Action` ↔ `ailk<Name>` (PascalCase of the action prefix).
+ *
+ * The harness exposes `computeParityFailures(actions, tools)` as a pure helper
+ * so the populated/empty/divergent cases can be exercised without filesystem.
+ * The integration case enumerates the real filesystem and runs the same helper.
+ */
+
+import { readdirSync, statSync, readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const REPO_ROOT = resolve(__dirname, "../../..");
+const WEB_ROOT = join(REPO_ROOT, "apps/web");
+const MCP_TOOLS_ROOT = join(REPO_ROOT, "apps/mcp/src/tools");
+
+const ACTION_FILE_RE = /\.actions\.ts$/;
+const ACTION_EXPORT_RE =
+  /export\s+(?:async\s+)?(?:function|const)\s+([a-z][a-zA-Z0-9]*Action)\b/g;
+const TOOL_EXPORT_RE =
+  /export\s+(?:async\s+)?(?:function|const)\s+(ailk[A-Z][a-zA-Z0-9]*)\b/g;
+
+function walk(dir: string, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === "dist" || entry === ".next")
+      continue;
+    const p = join(dir, entry);
+    const s = statSync(p);
+    if (s.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+export function discoverServerActions(webRoot: string = WEB_ROOT): Set<string> {
+  const found = new Set<string>();
+  for (const file of walk(webRoot)) {
+    if (!ACTION_FILE_RE.test(file)) continue;
+    const content = readFileSync(file, "utf-8");
+    for (const m of content.matchAll(ACTION_EXPORT_RE)) {
+      found.add(m[1]);
+    }
+  }
+  return found;
+}
+
+export function discoverMcpTools(
+  toolsRoot: string = MCP_TOOLS_ROOT,
+): Set<string> {
+  const found = new Set<string>();
+  if (!existsSync(toolsRoot)) return found;
+  for (const file of walk(toolsRoot)) {
+    if (!file.endsWith(".ts")) continue;
+    const content = readFileSync(file, "utf-8");
+    for (const m of content.matchAll(TOOL_EXPORT_RE)) {
+      found.add(m[1]);
+    }
+  }
+  return found;
+}
+
+/**
+ * Map an action symbol (e.g. `captureLeadAction`) to its expected MCP tool
+ * symbol (`ailkCaptureLead`).
+ */
+export function actionToToolName(action: string): string {
+  // Strip trailing "Action" and capitalize first char.
+  const base = action.replace(/Action$/, "");
+  if (base.length === 0) return "ailk";
+  return `ailk${base[0].toUpperCase()}${base.slice(1)}`;
+}
+
+/**
+ * MCP-only tools — tools that have no Web Server Action equivalent because
+ * they are pure-read content tools. Adding a Server Action wrapper would be
+ * meaningless: these tools exist to serve agent consumers, not web UI flows.
+ *
+ * Each entry is the camelCase MCP handler name (e.g. ailkListPages).
+ * Extend this list in subsequent issues (I3–I5) as more read-only tools land.
+ *
+ * Note: this allow-list uses the symbol name convention (`ailk<PascalVerb>`),
+ * not the MCP tool name convention (`list_pages`). The parity harness operates
+ * on symbol names discovered via regex from tool source files.
+ */
+const MCP_ONLY_TOOLS = new Set([
+  "ailkListPages", // list_pages — pure read, no action equivalent (I2)
+  "ailkReadContent", // read_content — pure read, no action equivalent (I2)
+  "ailkSearchContent", // search_content — pure read, no action equivalent (I4)
+  "ailkGetSiteInfo", // get_site_info — pure read, no action equivalent (I4)
+  "ailkGetBusinessHours", // get_business_hours — pure read, no action equivalent (I4)
+  "ailkGetLocations", // get_locations — pure read, no action equivalent (I4)
+  "ailkGetOfferings", // get_offerings — pure read, no action equivalent (I4)
+  "ailkGetPricing", // get_pricing — pure read, no action equivalent (I4)
+  "ailkGetFaq", // get_faq — pure read, no action equivalent (I4)
+  "ailkAudit", // audit — AEO scoring tool, no web action equivalent (I5; ADR 0013)
+  "ailkSubscribeNewsletter", // subscribe_newsletter — anonymous write via MCP; no Server Action (B7)
+  "ailkRequestCallback", // request_callback — anonymous write via MCP; no Server Action (B7)
+  "ailkScaffold", // scaffold — agent-only scaffolder; no Server Action equivalent (#299)
+  "ailkCreatePage", // create_page — agent-first Pro content write; HTTP twin is apps/api, not a Server Action (D14a #55)
+  "ailkUpdatePage", // update_page — agent-first Pro content write; HTTP twin is apps/api, not a Server Action (D14a #55)
+  "ailkDeletePage", // delete_page — agent-first Pro content write; HTTP twin is apps/api, not a Server Action (D14a #55)
+]);
+
+/**
+ * Pure parity computation. Given the set of action symbols and the set of
+ * MCP tool symbols, return the missing-tool and orphan-tool sets.
+ *
+ * Tools in MCP_ONLY_TOOLS are excluded from orphan reporting — they are
+ * intentionally MCP-only and have no Server Action counterpart.
+ */
+export function computeParityFailures(
+  actions: Set<string>,
+  tools: Set<string>,
+): { missingTools: string[]; orphanTools: string[] } {
+  const expected = new Set<string>();
+  for (const a of actions) expected.add(actionToToolName(a));
+
+  const missingTools: string[] = [];
+  for (const e of expected) if (!tools.has(e)) missingTools.push(e);
+
+  const orphanTools: string[] = [];
+  for (const t of tools) {
+    if (!expected.has(t) && !MCP_ONLY_TOOLS.has(t)) orphanTools.push(t);
+  }
+
+  missingTools.sort();
+  orphanTools.sort();
+  return { missingTools, orphanTools };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("MCP ↔ Server-Action parity (helper)", () => {
+  it("trivially passes when both sides are empty", () => {
+    const r = computeParityFailures(new Set(), new Set());
+    expect(r.missingTools).toEqual([]);
+    expect(r.orphanTools).toEqual([]);
+  });
+
+  it("reports missing MCP tools when an action has no matching tool", () => {
+    const actions = new Set(["captureLeadAction"]);
+    const tools = new Set<string>();
+    const r = computeParityFailures(actions, tools);
+    expect(r.missingTools).toEqual(["ailkCaptureLead"]);
+    expect(r.orphanTools).toEqual([]);
+  });
+
+  it("reports orphan MCP tools when a tool has no matching action", () => {
+    const actions = new Set<string>();
+    const tools = new Set(["ailkPurchase"]);
+    const r = computeParityFailures(actions, tools);
+    expect(r.missingTools).toEqual([]);
+    expect(r.orphanTools).toEqual(["ailkPurchase"]);
+  });
+
+  it("passes when actions and tools are paired", () => {
+    const actions = new Set(["captureLeadAction", "purchaseAction"]);
+    const tools = new Set(["ailkCaptureLead", "ailkPurchase"]);
+    const r = computeParityFailures(actions, tools);
+    expect(r.missingTools).toEqual([]);
+    expect(r.orphanTools).toEqual([]);
+  });
+
+  it("maps action names to tool names by stripping Action and prefixing ailk", () => {
+    expect(actionToToolName("captureLeadAction")).toBe("ailkCaptureLead");
+    expect(actionToToolName("purchaseAction")).toBe("ailkPurchase");
+    expect(actionToToolName("auditAction")).toBe("ailkAudit");
+  });
+});
+
+describe("MCP ↔ Server-Action parity (filesystem)", () => {
+  it("D14a Stage 1 Unit C state: two Server Actions (purchaseAction + captureLeadAction), eighteen MCP tools, zero orphans", () => {
+    const actions = discoverServerActions();
+    const tools = discoverMcpTools();
+    const r = computeParityFailures(actions, tools);
+
+    // After D14a Stage 1 Unit C (#55): eighteen tools + two paired Server Actions.
+    // - ailkPurchase: paired with purchaseAction (apps/web/app/dev/purchase/).
+    // - ailkCaptureLead: paired with captureLeadAction (apps/web/app/contact/).
+    // - ailkListPages, ailkReadContent: MCP-only (pure read; I2)
+    // - ailkSearchContent, ailkGetSiteInfo, ailkGetBusinessHours,
+    //   ailkGetLocations, ailkGetOfferings, ailkGetPricing, ailkGetFaq:
+    //   MCP-only (pure read; I4; in MCP_ONLY_TOOLS allow-list).
+    // - ailkAudit: MCP-only (AEO scoring; I5; in MCP_ONLY_TOOLS allow-list).
+    // - ailkSubscribeNewsletter, ailkRequestCallback:
+    //   MCP-only anonymous-write tools (B7; in MCP_ONLY_TOOLS allow-list).
+    // - ailkScaffold: MCP-only agent scaffolder (#299; in MCP_ONLY_TOOLS).
+    // - ailkCreatePage, ailkUpdatePage, ailkDeletePage: MCP-only agent-first
+    //   Pro content writes; HTTP twin is apps/api, not Server Actions (D14a #55).
+    expect(actions.size).toBe(2);
+    expect(tools.size).toBe(18);
+    expect(r.missingTools).toEqual([]);
+    expect(r.orphanTools).toEqual([]);
+  });
+});

package/templates/apps/mcp/__tests__/purchase-disabled.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Tests for S15a — purchase tool disabled at OSS catalog.
+ *
+ * Issue #610 / spec
+ * `docs/internal/specs/ailk-pre-oss-security-phase-3-s15a-disable-purchase-spec.md`.
+ *
+ * Acceptance criterion verified here: `start_purchase` is NOT in the
+ * registered MCP tool catalog when the server is constructed by
+ * `createMcpServer()`. If a future PR re-registers the tool (by removing
+ * `'start_purchase'` from `OSS_DISABLED_TOOLS` in `apps/mcp/src/server.ts`),
+ * this test fails RED, forcing a deliberate review of the Phase 3
+ * re-enablement criteria in
+ * `docs/internal/roadmaps/phase-3-readiness.md`.
+ *
+ * `purchase.ts` source is preserved — only the registration is filtered.
+ */
+
+import { createMcpServer, listRegisteredTools } from "../src/server.js";
+
+describe("purchase tool — disabled at OSS catalog (S15a)", () => {
+  it("start_purchase is NOT in listRegisteredTools()", () => {
+    const tools = listRegisteredTools();
+    const names = tools.map((t) => t.name);
+    expect(names).not.toContain("start_purchase");
+  });
+
+  it("start_purchase is NOT in createMcpServer()._registeredTools", () => {
+    const server = createMcpServer();
+    // _registeredTools is a plain object (Record<string, ...>) in SDK v1.x.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirrors apps/mcp/__tests__/server.test.ts
+    const tools = (server as any)._registeredTools as Record<string, unknown>;
+    expect("start_purchase" in tools).toBe(false);
+  });
+});

package/templates/apps/mcp/__tests__/read_content.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for the read_content MCP tool handler.
+ *
+ * Acceptance criteria verified here:
+ * - readContentInputSchema validates correct inputs (type + slug)
+ * - readContentInputSchema rejects unknown type values and malformed slugs
+ * - ailkReadContent returns { slug, type, frontmatter, body } for a known slug
+ * - ailkReadContent returns null (not throws) for an unknown slug
+ * - Output validates against readContentOutputSchema
+ * - No console.* calls in handler (structural test)
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+import {
+  ailkReadContent,
+  readContentInputSchema,
+  readContentOutputSchema,
+} from "../src/tools/read_content.js";
+
+const REPO_ROOT = resolve(__dirname, "../../..");
+const CONTENT_ROOT = join(REPO_ROOT, "content");
+
+describe("readContentInputSchema", () => {
+  it("accepts a valid type + slug", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a HomePage slug", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "home",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects missing slug", () => {
+    const result = readContentInputSchema.safeParse({ type: "HomePage" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing type", () => {
+    const result = readContentInputSchema.safeParse({
+      slug: "launching-ailk",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an unknown type", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "NotAType",
+      slug: "some-slug",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty slug", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects slug with path traversal characters", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "../etc/passwd",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects slug with forward slashes", () => {
+    const result = readContentInputSchema.safeParse({
+      type: "HomePage",
+      slug: "some/path",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ailkReadContent handler", () => {
+  it("returns slug, type, frontmatter, body for a known HomePage", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "home" },
+      CONTENT_ROOT,
+    );
+
+    expect(result).not.toBeNull();
+    expect(result!.slug).toBe("home");
+    expect(result!.type).toBe("HomePage");
+    expect(typeof result!.frontmatter).toBe("object");
+    expect(typeof result!.body).toBe("string");
+  });
+
+  it("returns null (not throws) for an unknown slug", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "does-not-exist" },
+      CONTENT_ROOT,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null for a slug that exists in a different type", async () => {
+    // home.mdx exists under HomePage, not AboutPage
+    const result = await ailkReadContent(
+      { type: "AboutPage", slug: "home" },
+      CONTENT_ROOT,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("returns null for a valid type with no files when given an unknown slug", async () => {
+    const result = await ailkReadContent(
+      { type: "FAQPage", slug: "nonexistent" },
+      CONTENT_ROOT,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("output shape validates against readContentOutputSchema when non-null", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "home" },
+      CONTENT_ROOT,
+    );
+    const parsed = readContentOutputSchema.safeParse(result);
+    expect(parsed.success).toBe(true);
+  });
+
+  it("null validates against readContentOutputSchema", async () => {
+    const result = await ailkReadContent(
+      { type: "HomePage", slug: "does-not-exist" },
+      CONTENT_ROOT,
+    );
+    const parsed = readContentOutputSchema.safeParse(result);
+    expect(parsed.success).toBe(true);
+  });
+});
+
+describe("architectural guard — no console calls", () => {
+  it("apps/mcp/src/tools/read_content.ts does not call console.*", () => {
+    const src = readFileSync(
+      resolve(__dirname, "../src/tools/read_content.ts"),
+      "utf-8",
+    );
+    expect(src).not.toMatch(/\bconsole\.(log|warn|error|info|debug)\b/);
+  });
+});