create-ailk 0.1.0

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

@@ -0,0 +1,171 @@
+/**
+ * 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/require-paid-tier.ts

@@ -0,0 +1,44 @@
+/**
+ * Paid-tier license guard for apps/mcp content-write tools (D14a Stage 0).
+ *
+ * Calls `checkLicense()` from @working-theory/license and returns a canonical
+ * `payment_required` error body for free tier; returns `null` to signal the
+ * caller may proceed.
+ *
+ * Usage in a tool handler:
+ *
+ *   const guard = await requirePaidTier();
+ *   if (guard) return guard;  // free tier — return canonical error body
+ *   // paid tier — proceed
+ *
+ * Pattern intentionally returns the error body directly (vs. throwing) — MCP
+ * tools surface errors as their result body, not via thrown exceptions.
+ */
+
+import { checkLicense } from "@working-theory/license";
+
+import { paymentRequiredError, type ErrorBody } from "./errors.js";
+
+const FREE_TIER_MESSAGE =
+  "This tool requires a paid license. Visit https://ailaunchkit.ai to upgrade.";
+
+export async function requirePaidTier(): Promise<ErrorBody | null> {
+  let result;
+  try {
+    result = await checkLicense();
+  } catch {
+    // Per ADR 0014 — local-verify license; an exception is a bug, not a
+    // network failure. Treat as free for safe-by-default gating.
+    return paymentRequiredError(FREE_TIER_MESSAGE);
+  }
+
+  // Revoked paid licenses keep verifying until JWT exp (up to 24h after the
+  // server reports `revoked`). Closing the gate when `revoked === true`
+  // shrinks that window to "next request" without waiting for exp. See
+  // packages/license/src/types.ts § LicenseResult and ADR 0014.
+  if (result.revoked === true || result.tier === "free") {
+    return paymentRequiredError(FREE_TIER_MESSAGE);
+  }
+
+  return null;
+}

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

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

package/templates/apps/mcp/src/server.ts

@@ -0,0 +1,139 @@
+/**
+ * MCP server factory.
+ *
+ * Creates and configures the McpServer instance with all registered tools.
+ * The server is returned unconnected — callers attach a transport (stdio in
+ * production, in-memory in tests).
+ *
+ * Tool names + descriptions + input shapes come from the canonical catalog
+ * exported by `@working-theory/metadata` (issue #209). The catalog is the single source
+ * of truth shared with `apps/web /.well-known/mcp` for agent discovery.
+ * Handlers continue to live in `apps/mcp/src/tools/*` — this module wires
+ * each catalog entry to its handler.
+ */
+
+import { getMcpToolRegistrations, OSS_DISABLED_TOOLS } from "@working-theory/metadata";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import { ailkAudit } from "./tools/audit.js";
+import { ailkCaptureLead } from "./tools/capture_lead.js";
+import { ailkCreatePage } from "./tools/create_page.js";
+import { ailkDeletePage } from "./tools/delete_page.js";
+import { ailkGetBusinessHours } from "./tools/get_business_hours.js";
+import { ailkGetFaq } from "./tools/get_faq.js";
+import { ailkGetLocations } from "./tools/get_locations.js";
+import { ailkGetOfferings } from "./tools/get_offerings.js";
+import { ailkGetPricing } from "./tools/get_pricing.js";
+import { ailkGetSiteInfo } from "./tools/get_site_info.js";
+import { ailkListPages } from "./tools/list_pages.js";
+import { ailkPurchase } from "./tools/purchase.js";
+import { ailkReadContent } from "./tools/read_content.js";
+import { ailkRequestCallback } from "./tools/request_callback.js";
+import { ailkScaffold } from "./tools/scaffold.js";
+import { ailkSearchContent } from "./tools/search_content.js";
+import { ailkSubscribeNewsletter } from "./tools/subscribe_newsletter.js";
+import { ailkUpdatePage } from "./tools/update_page.js";
+
+/**
+ * Tool-name → handler map. Each handler accepts the parsed input the SDK
+ * passes through after Zod validation against the catalog input shape.
+ *
+ * Cast via `never` is safe: each handler validates its input via its own
+ * Zod parse before doing real work (see apps/mcp/src/tools/*.ts).
+ */
+const HANDLERS: Record<string, (input: unknown) => Promise<unknown>> = {
+  start_purchase: (input) => ailkPurchase(input as never),
+  list_pages: (input) => ailkListPages(input as never),
+  read_content: (input) => ailkReadContent(input as never),
+  search_content: (input) => ailkSearchContent(input as never),
+  get_site_info: (input) => ailkGetSiteInfo(input as never),
+  get_business_hours: (input) => ailkGetBusinessHours(input as never),
+  get_locations: (input) => ailkGetLocations(input as never),
+  get_offerings: (input) => ailkGetOfferings(input as never),
+  get_pricing: (input) => ailkGetPricing(input as never),
+  get_faq: (input) => ailkGetFaq(input as never),
+  audit: (input) => {
+    const { slug, type, url } = input as {
+      slug?: string;
+      type?: string;
+      url?: string;
+    };
+    const handlerInput = url !== undefined ? { url } : { slug: slug!, type };
+    return ailkAudit(handlerInput as never);
+  },
+  capture_lead: (input) => ailkCaptureLead(input as never),
+  subscribe_newsletter: (input) => ailkSubscribeNewsletter(input as never),
+  request_callback: (input) => ailkRequestCallback(input as never),
+  scaffold: (input) => ailkScaffold(input as never),
+  // D14a Stage 1 Unit C (#55): Paid-tier content write surface. Handlers
+  // self-gate via requirePaidTier and return canonical error bodies (no throw)
+  // for license / validation / conflict / not-found cases — see
+  // apps/mcp/src/lib/errors.ts. Catalog entries carry tier: "pro" so agents
+  // see the gating before invoking via list_tools.
+  create_page: (input) => ailkCreatePage(input as never),
+  update_page: (input) => ailkUpdatePage(input as never),
+  delete_page: (input) => ailkDeletePage(input as never),
+};
+
+/**
+ * Tool descriptor returned by {@link listRegisteredTools}. A minimal shape
+ * sufficient for callers that need to assert which tools are registered
+ * (e.g., the S15a regression test) without depending on the SDK's internal
+ * `_registeredTools` field.
+ */
+export interface RegisteredToolDescriptor {
+  name: string;
+  description: string;
+}
+
+/**
+ * Returns the list of tools that {@link createMcpServer} will register, after
+ * the OSS catalog filter ({@link OSS_DISABLED_TOOLS}) is applied. Pure — no
+ * server instance is constructed.
+ *
+ * Consumed by `apps/mcp/__tests__/purchase-disabled.test.ts` to assert that
+ * disabled tools are absent from the registered catalog. If a future change
+ * removes a name from `OSS_DISABLED_TOOLS` without satisfying the Phase 3
+ * re-enable criteria, that test fails RED.
+ */
+export function listRegisteredTools(): RegisteredToolDescriptor[] {
+  return getMcpToolRegistrations()
+    .filter((reg) => !OSS_DISABLED_TOOLS.has(reg.name))
+    .map((reg) => ({ name: reg.name, description: reg.description }));
+}
+
+/**
+ * Creates a configured McpServer with all AILK tools registered, less any
+ * tool name in {@link OSS_DISABLED_TOOLS}. The disabled filter is applied
+ * defensively here even though the upstream `getMcpToolRegistrations()`
+ * already excludes them — a belt-and-braces guard so a future regression in
+ * the metadata package can't accidentally re-register a disabled tool.
+ *
+ * Re-enable criteria for each disabled tool live at
+ * `docs/internal/roadmaps/phase-3-readiness.md`. S15a (issue #610) is the
+ * source of this filter.
+ */
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "ailk",
+    version: "0.1.0",
+  });
+
+  for (const reg of getMcpToolRegistrations()) {
+    if (OSS_DISABLED_TOOLS.has(reg.name)) {
+      continue;
+    }
+    const handler = HANDLERS[reg.name];
+    if (!handler) {
+      throw new Error(`MCP catalog drift: no handler for tool '${reg.name}'`);
+    }
+    server.tool(reg.name, reg.description, reg.inputShape, async (input) => {
+      const result = await handler(input);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+      };
+    });
+  }
+
+  return server;
+}

package/templates/apps/mcp/src/tools/audit.ts

@@ -0,0 +1,103 @@
+/**
+ * audit — runs the AEO Layer 1 scoring engine against a single page.
+ *
+ * Pure read: imports runAudit from @working-theory/aeo (ADR 0011). No auth required.
+ * The adapter (audit-single-page) resolves URL or slug to a filesystem read;
+ * no fetch() is called anywhere in this file or the adapter.
+ *
+ * Input:  { slug, type? } | { url }
+ *   slug branch — lowercase [a-z0-9-]+ slug; type optional (defaults BlogPosting)
+ *   url branch  — absolute URL on the AILK installation's own domain only
+ *                 (same-origin check uses AILK_BASE_URL || NEXT_PUBLIC_BASE_URL)
+ *
+ * Output: { score, perRule, perPage, meta }
+ *   score    — 0–100 overall
+ *   perRule  — per-rule breakdown (id, name, weight, status, evidence?, advice?)
+ *   perPage  — per-page summary (slug, type, score)
+ *   meta     — { auditedAt, ruleSet, locale }
+ *
+ * Session/scope: none — read-only public content.
+ */
+
+import {
+  runAudit,
+  alwaysFails,
+  alwaysPasses,
+  entityMarkup,
+  faqHowtoIncentive,
+  jsonldValidity,
+  schemaCoverage,
+  type Rule,
+} from "@working-theory/aeo";
+import {
+  auditInputSchema,
+  auditOutputSchema,
+  type AuditInput,
+  type AuditOutput,
+} from "@working-theory/validation";
+
+import {
+  buildSinglePageAuditInput,
+  type SinglePageInput,
+} from "../lib/audit-single-page.js";
+
+export { auditInputSchema, auditOutputSchema };
+export type { AuditInput, AuditOutput };
+
+/**
+ * Canonical rule set — mirrors packages/aeo/src/cli/index.ts RULES array.
+ * Imported from @working-theory/aeo public API; must not be re-implemented here.
+ */
+const RULES: Rule[] = [
+  alwaysPasses,
+  alwaysFails,
+  schemaCoverage,
+  jsonldValidity,
+  faqHowtoIncentive,
+  entityMarkup,
+];
+
+/**
+ * audit handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkAudit(
+  input: AuditInput,
+  contentRoot?: string,
+): Promise<AuditOutput> {
+  auditInputSchema.parse(input);
+
+  // Cast: AuditInput's Zod-inferred optional fields include `undefined` in
+  // their union, but SinglePageInput uses exactOptionalPropertyTypes where `?`
+  // means "absent." The auditInputSchema.parse above guarantees validity.
+  const auditInput = await buildSinglePageAuditInput(
+    input as unknown as SinglePageInput,
+    contentRoot,
+  );
+  const report = runAudit(auditInput, RULES);
+
+  const result: AuditOutput = {
+    score: report.score,
+    perRule: report.perRule.map((r) => ({
+      ruleId: r.id,
+      name: r.id, // rule description not on PerRuleResult; use id as name
+      weight: r.weight,
+      status: r.pass ? "pass" : "fail",
+      ...(r.evidence !== undefined && { evidence: r.evidence }),
+    })),
+    perPage: report.perPage.map((p) => ({
+      slug: p.slug,
+      type: p.type,
+      score: p.score,
+    })),
+    meta: {
+      auditedAt: report.meta.auditedAt,
+      ruleSet: `${report.meta.schemaVersion}/${report.meta.registryVersion}`,
+      locale: auditInput.locale,
+    },
+  };
+
+  return auditOutputSchema.parse(result);
+}

package/templates/apps/mcp/src/tools/capture_lead.ts

@@ -0,0 +1,52 @@
+/**
+ * capture_lead — capture a contact-form lead.
+ *
+ * Validates input via Zod, forwards to POST /api/leads/submit via
+ * @working-theory/api-client, and shapes the response into the MCP output schema.
+ * No business logic — orchestration lives in apps/api B6.
+ *
+ * Paired with captureLeadAction Server Action per ADR 0013.
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  submitLeadInputSchema,
+  submitLeadOutputSchema,
+  type SubmitLeadInput,
+  type SubmitLeadOutput,
+} from "@working-theory/validation";
+
+export { submitLeadInputSchema, submitLeadOutputSchema };
+export type { SubmitLeadInput, SubmitLeadOutput };
+
+export async function ailkCaptureLead(
+  input: SubmitLeadInput,
+): Promise<SubmitLeadOutput> {
+  const parsed = submitLeadInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: { kind: "invalid_input", issues: parsed.error.issues },
+    };
+  }
+
+  const { name, email, message, phone } = parsed.data;
+  const siteId = process.env.AILK_SITE_ID ?? "default";
+  const body = {
+    siteId,
+    source: "mcp",
+    email,
+    payload: {
+      name,
+      ...(message !== undefined && { message }),
+      ...(phone !== undefined && { phone }),
+    },
+  };
+
+  const res = await apiClient.leads.submit(body);
+  if (!res.ok) {
+    return { ok: false, error: { kind: "api_error", status: res.status } };
+  }
+
+  return { ok: true, id: res.body.id, persisted: res.body.persisted };
+}

package/templates/apps/mcp/src/tools/create_page.ts

@@ -0,0 +1,95 @@
+/**
+ * create_page — Paid-tier MCP tool for authoring a new content page.
+ *
+ * D14a Stage 1 Unit C — wires the McpServer create_page handler to the
+ * ContentAdapter.createPage method (Stage 1 Unit A implements the MDX
+ * adapter; tests inject a fake adapter).
+ *
+ * Surface contract: validates input via FrontmatterSchema.extend({ body }),
+ * runs the Paid-tier license guard, calls adapter.createPage, and maps adapter
+ * errors to canonical MCP error bodies (see apps/mcp/src/lib/errors.ts).
+ *
+ * Input shape mirrors the Stage 0 catalog entry in
+ * packages/metadata/src/mcp-tool-catalog.ts. Catalog parses a permissive
+ * outer shape (`page: record`); this handler parses strictly via
+ * FrontmatterSchema so bad frontmatter surfaces as a validation_failed body.
+ */
+
+import { join } from "node:path";
+
+import {
+  FrontmatterSchema,
+  createMdxAdapter,
+  mapAdapterError,
+  type ContentAdapter,
+} from "@working-theory/content-adapters";
+import { z } from "zod";
+
+import { validationError, type ErrorBody } from "../lib/errors.js";
+import { requirePaidTier } from "../lib/require-paid-tier.js";
+
+const CreatePageInputSchema = FrontmatterSchema.extend({
+  body: z.string().min(1),
+});
+
+interface CreatePageSuccess {
+  page: Record<string, unknown>;
+  version: string;
+}
+
+export type CreatePageResult = CreatePageSuccess | ErrorBody;
+
+export interface CreatePageInput {
+  type: string;
+  slug: string;
+  page: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * ailkCreatePage handler.
+ *
+ * Optional `adapter` injection mirrors the Q3 resolution in the resource plan
+ * (tests construct adapters directly with isolated content roots). When
+ * omitted, falls back to the default MDX adapter rooted at process.cwd()/content.
+ */
+export async function ailkCreatePage(
+  input: CreatePageInput,
+  adapter?: ContentAdapter,
+): Promise<CreatePageResult> {
+  const guard = await requirePaidTier();
+  if (guard) return guard;
+
+  const parsed = CreatePageInputSchema.safeParse({
+    ...input.page,
+    type: input.type,
+    slug: input.slug,
+    body: input.body,
+  });
+
+  if (!parsed.success) {
+    return validationError("Invalid frontmatter or body for create_page.", {
+      issues: parsed.error.issues,
+    });
+  }
+
+  const resolved =
+    adapter ??
+    createMdxAdapter({ contentRoot: join(process.cwd(), "content") });
+
+  try {
+    const result = await resolved.createPage(
+      parsed.data.type,
+      parsed.data.slug,
+      parsed.data,
+    );
+    return { page: result.page, version: result.version };
+  } catch (err) {
+    const mapped = mapAdapterError(err, {
+      type: parsed.data.type,
+      slug: parsed.data.slug,
+    });
+    if (mapped) return mapped;
+    throw err;
+  }
+}