create-ailk 0.1.0

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

@@ -0,0 +1,73 @@
+/**
+ * delete_page — Paid-tier MCP tool for removing a content page.
+ *
+ * D14a Stage 1 Unit C — wires McpServer delete_page to ContentAdapter.deletePage.
+ * Mandatory optimistic locking: caller supplies `ifMatch`; stale or missing
+ * tokens yield canonical conflict bodies.
+ *
+ * Success body is `{ ok: true }` per the Stage 0 catalog `deletePageOutputSchema`.
+ */
+
+import { join } from "node:path";
+
+import {
+  SCHEMA_ORG_TYPES,
+  SLUG_PATTERN,
+  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 DeletePageInputSchema = z.object({
+  type: z.enum(SCHEMA_ORG_TYPES),
+  // Defence-in-depth slug allowlist matches create_page / update_page;
+  // the adapter also enforces the pattern, but a fail-fast validation_failed
+  // here keeps the tool's surface contract consistent (issue #398).
+  slug: z.string().regex(SLUG_PATTERN),
+  ifMatch: z.string().min(1),
+});
+
+interface DeletePageSuccess {
+  ok: true;
+}
+
+export type DeletePageResult = DeletePageSuccess | ErrorBody;
+
+export interface DeletePageInput {
+  type: string;
+  slug: string;
+  ifMatch: string;
+}
+
+export async function ailkDeletePage(
+  input: DeletePageInput,
+  adapter?: ContentAdapter,
+): Promise<DeletePageResult> {
+  const guard = await requirePaidTier();
+  if (guard) return guard;
+
+  const parsed = DeletePageInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return validationError("Invalid input for delete_page.", {
+      issues: parsed.error.issues,
+    });
+  }
+
+  const { type, slug, ifMatch } = parsed.data;
+  const resolved =
+    adapter ??
+    createMdxAdapter({ contentRoot: join(process.cwd(), "content") });
+
+  try {
+    await resolved.deletePage(type, slug, { ifMatch });
+    return { ok: true };
+  } catch (err) {
+    const mapped = mapAdapterError(err, { type, slug });
+    if (mapped) return mapped;
+    throw err;
+  }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * get_business_hours — returns business hours from LocalBusiness structured data.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Resolves a page by slug (default: "home") and extracts LocalBusiness schema.
+ * Returns null when the page is not found or has no openingHoursSpecification.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07).
+ *
+ * Input:  { slug?: string, locale?: string }
+ * Output: Array<{ dayOfWeek, opens, closes, validFrom?, validThrough? }> | null
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter } from "@working-theory/content-adapters";
+import {
+  getBusinessHoursInputSchema,
+  getBusinessHoursOutputSchema,
+  type GetBusinessHoursInput,
+  type GetBusinessHoursOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getBusinessHoursInputSchema, getBusinessHoursOutputSchema };
+export type { GetBusinessHoursInput, GetBusinessHoursOutput };
+
+const DEFAULT_SLUG = "home";
+
+/**
+ * get_business_hours handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetBusinessHours(
+  input: GetBusinessHoursInput,
+  contentRoot?: string,
+): Promise<GetBusinessHoursOutput> {
+  getBusinessHoursInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  const slug = input.slug ?? DEFAULT_SLUG;
+  const data = await adapter.extractStructuredData("LocalBusiness", slug, locale);
+  if (!data) return null;
+
+  const hours = data.openingHoursSpecification;
+  if (!Array.isArray(hours) || hours.length === 0) return null;
+
+  return getBusinessHoursOutputSchema.parse(
+    (hours as Record<string, unknown>[]).map((h) => ({
+      dayOfWeek: h["dayOfWeek"] as string,
+      opens: h["opens"] as string,
+      closes: h["closes"] as string,
+      validFrom: h["validFrom"] as string | undefined,
+      validThrough: h["validThrough"] as string | undefined,
+    })),
+  );
+}

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

@@ -0,0 +1,69 @@
+/**
+ * get_faq — returns FAQ question/answer pairs from FAQPage structured data.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Resolves a page by slug (default: "faq") and extracts FAQPage schema.
+ * Returns null when the page is not found or has no mainEntity questions.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07).
+ *
+ * Input:  { slug?: string, locale?: string }
+ * Output: { questions: Array<{ question, answer }> } | null
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter } from "@working-theory/content-adapters";
+import {
+  getFaqInputSchema,
+  getFaqOutputSchema,
+  type GetFaqInput,
+  type GetFaqOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getFaqInputSchema, getFaqOutputSchema };
+export type { GetFaqInput, GetFaqOutput };
+
+const DEFAULT_SLUG = "faq";
+
+/**
+ * get_faq handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetFaq(
+  input: GetFaqInput,
+  contentRoot?: string,
+): Promise<GetFaqOutput> {
+  getFaqInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  const slug = input.slug ?? DEFAULT_SLUG;
+  const data = await adapter.extractStructuredData("FAQPage", slug, locale);
+  if (!data) return null;
+
+  const entities = data.mainEntity;
+  if (!Array.isArray(entities) || entities.length === 0) return null;
+
+  const questions = (entities as Record<string, unknown>[]).map((item) => ({
+    question: (item["name"] as string) ?? "",
+    answer:
+      typeof item["acceptedAnswer"] === "object" &&
+      item["acceptedAnswer"] !== null
+        ? (((item["acceptedAnswer"] as Record<string, unknown>)[
+            "text"
+          ] as string) ?? "")
+        : ((item["acceptedAnswer"] as string) ?? ""),
+  }));
+
+  return getFaqOutputSchema.parse({ questions });
+}

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

@@ -0,0 +1,85 @@
+/**
+ * get_locations — returns all Place locations from structured data site-wide.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Lists all pages of type "Place" and extracts Place schema from each.
+ * Returns an empty array when no Place pages exist.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07). Page enumeration is locale-scoped.
+ *
+ * Input:  { locale?: string }
+ * Output: { locations: Array<{ name, address, geo?, telephone? }> }
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter, SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import {
+  getLocationsInputSchema,
+  getLocationsOutputSchema,
+  type GetLocationsInput,
+  type GetLocationsOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getLocationsInputSchema, getLocationsOutputSchema };
+export type { GetLocationsInput, GetLocationsOutput };
+
+/**
+ * get_locations handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetLocations(
+  input: GetLocationsInput,
+  contentRoot?: string,
+): Promise<GetLocationsOutput> {
+  getLocationsInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  // Place is not a page-level SchemaOrgType, so we iterate all types to find
+  // pages whose schema field has Place structured data.
+  const allPages = await Promise.all(
+    SCHEMA_ORG_TYPES.map((type) => adapter.listPages(type, locale)),
+  );
+
+  // Deduplicate slugs before extracting — a slug can appear in multiple types.
+  const slugsSeen = new Set<string>();
+  const uniquePages = allPages.flat().filter((page) => {
+    if (slugsSeen.has(page.slug)) return false;
+    slugsSeen.add(page.slug);
+    return true;
+  });
+
+  // Parallelize extraction — each call is an independent fs read.
+  const extracted = await Promise.all(
+    uniquePages.map(async (page) => ({
+      page,
+      data: await adapter.extractStructuredData("Place", page.slug, locale),
+    })),
+  );
+
+  const locations: GetLocationsOutput["locations"] = [];
+  for (const { page, data } of extracted) {
+    if (!data) continue;
+    const place = data as Record<string, unknown>;
+    const address = place["address"] as Record<string, unknown> | undefined;
+    if (!address) continue;
+    locations.push({
+      name: page.title,
+      address,
+      geo: place["geo"] as Record<string, unknown> | undefined,
+      telephone: place["telephone"] as string | undefined,
+    });
+  }
+
+  return getLocationsOutputSchema.parse({ locations });
+}

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

@@ -0,0 +1,66 @@
+/**
+ * get_offerings — returns Services and/or Products as a unified offerings array.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Lists pages of type "Service" and/or "Product" and shapes them into a
+ * unified offerings array. Optionally filtered by type.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07). Lists are locale-scoped.
+ *
+ * Input:  { type?: 'service' | 'product', locale?: string }
+ * Output: { offerings: Array<{ name, description, category?, image? }> }
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter, type SchemaOrgType } from "@working-theory/content-adapters";
+import {
+  getOfferingsInputSchema,
+  getOfferingsOutputSchema,
+  type GetOfferingsInput,
+  type GetOfferingsOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getOfferingsInputSchema, getOfferingsOutputSchema };
+export type { GetOfferingsInput, GetOfferingsOutput };
+
+/**
+ * get_offerings handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetOfferings(
+  input: GetOfferingsInput,
+  contentRoot?: string,
+): Promise<GetOfferingsOutput> {
+  getOfferingsInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  const typesToFetch: SchemaOrgType[] = [];
+  if (!input.type || input.type === "service") typesToFetch.push("Service");
+  if (!input.type || input.type === "product") typesToFetch.push("Product");
+
+  const perType = await Promise.all(
+    typesToFetch.map((type) => adapter.listPages(type, locale)),
+  );
+
+  const offerings: GetOfferingsOutput["offerings"] = perType
+    .flat()
+    .map((page) => ({
+      name: page.title,
+      description: page.description,
+      category: page.schema?.["category"] as string | undefined,
+      image: page.image,
+    }));
+
+  return getOfferingsOutputSchema.parse({ offerings });
+}

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

@@ -0,0 +1,74 @@
+/**
+ * get_pricing — returns pricing tiers from Offer structured data.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Resolves a page by slug (default: "pricing") and extracts Offer schema.
+ * Returns null when the page is not found or has no offer data.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07).
+ *
+ * Input:  { slug?: string, locale?: string }
+ * Output: { tiers: Array<{ name, price, priceCurrency, description? }> } | null
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter } from "@working-theory/content-adapters";
+import {
+  getPricingInputSchema,
+  getPricingOutputSchema,
+  type GetPricingInput,
+  type GetPricingOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getPricingInputSchema, getPricingOutputSchema };
+export type { GetPricingInput, GetPricingOutput };
+
+const DEFAULT_SLUG = "pricing";
+
+/**
+ * get_pricing handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetPricing(
+  input: GetPricingInput,
+  contentRoot?: string,
+): Promise<GetPricingOutput> {
+  getPricingInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  const slug = input.slug ?? DEFAULT_SLUG;
+  const data = await adapter.extractStructuredData("Product", slug, locale);
+  if (!data) return null;
+
+  const schema = data as Record<string, unknown>;
+
+  // Support both a top-level `offers` array and a single offer object.
+  const offersRaw = schema["offers"];
+  const offersArr: Record<string, unknown>[] = Array.isArray(offersRaw)
+    ? (offersRaw as Record<string, unknown>[])
+    : offersRaw && typeof offersRaw === "object"
+      ? [offersRaw as Record<string, unknown>]
+      : [];
+
+  if (offersArr.length === 0) return null;
+
+  const tiers = offersArr.map((offer) => ({
+    name: (offer["name"] as string) ?? "",
+    price: (offer["price"] as string | number) ?? "",
+    priceCurrency: (offer["priceCurrency"] as string) ?? "USD",
+    description: offer["description"] as string | undefined,
+  }));
+
+  return getPricingOutputSchema.parse({ tiers });
+}

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

@@ -0,0 +1,84 @@
+/**
+ * get_site_info — returns structured site identity from the HomePage.
+ *
+ * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Resolves the HomePage by slug (default: "home") and extracts the `schema`
+ * frontmatter field. Returns null when the page is not found or has no schema.
+ *
+ * Phase 3 S3: optional `locale` parameter (BCP-47). Validated against the
+ * project's allowlist; invalid or unknown values silently fall back to the
+ * default locale (AC-i18n-07).
+ *
+ * Input:  { slug?: string, locale?: string }
+ * Output: { name, description, contact?, brandColors?, socialHandles? } | null
+ * Session/scope: none — read-only public content.
+ */
+
+import { join } from "node:path";
+
+import { createMdxAdapter } from "@working-theory/content-adapters";
+import {
+  getSiteInfoInputSchema,
+  getSiteInfoOutputSchema,
+  type GetSiteInfoInput,
+  type GetSiteInfoOutput,
+} from "@working-theory/validation";
+
+import { resolveLocale } from "../lib/resolve-locale.js";
+
+export { getSiteInfoInputSchema, getSiteInfoOutputSchema };
+export type { GetSiteInfoInput, GetSiteInfoOutput };
+
+const DEFAULT_SLUG = "home";
+
+/**
+ * get_site_info handler.
+ *
+ * Accepts an optional `contentRoot` override for testing. When omitted,
+ * resolves the content root relative to cwd (supports ESM runtime).
+ */
+export async function ailkGetSiteInfo(
+  input: GetSiteInfoInput,
+  contentRoot?: string,
+): Promise<GetSiteInfoOutput> {
+  getSiteInfoInputSchema.parse(input);
+
+  const root = contentRoot ?? join(process.cwd(), "content");
+  const locale = resolveLocale(input.locale);
+  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+
+  const slug = input.slug ?? DEFAULT_SLUG;
+  const data = await adapter.extractStructuredData("HomePage", slug, locale);
+  if (!data) return null;
+
+  const schema = data as Record<string, unknown>;
+
+  const contactRaw = schema["contactPoint"] as
+    | Record<string, unknown>
+    | undefined;
+  const contact =
+    contactRaw !== undefined
+      ? {
+          email: contactRaw["email"] as string | undefined,
+          phone: contactRaw["telephone"] as string | undefined,
+        }
+      : undefined;
+
+  const colorsRaw = schema["brandColors"];
+  const brandColors = Array.isArray(colorsRaw)
+    ? (colorsRaw as string[])
+    : undefined;
+
+  const socialsRaw = schema["sameAs"];
+  const socialHandles = Array.isArray(socialsRaw)
+    ? (socialsRaw as string[])
+    : undefined;
+
+  return getSiteInfoOutputSchema.parse({
+    name: (schema["name"] as string) ?? "",
+    description: (schema["description"] as string) ?? "",
+    contact,
+    brandColors,
+    socialHandles,
+  });
+}

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

@@ -0,0 +1,125 @@
+/**
+ * MCP tool registry — re-exports every tool module.
+ *
+ * Add new tool modules here as they land in Phase 3+.
+ */
+
+export {
+  purchaseInputSchema,
+  purchaseOutputSchema,
+  ailkPurchase,
+  type PurchaseInput,
+  type PurchaseOutput,
+} from "./purchase.js";
+
+export {
+  listPagesInputSchema,
+  listPagesOutputSchema,
+  ailkListPages,
+  type ListPagesInput,
+  type ListPagesOutput,
+} from "./list_pages.js";
+
+export {
+  readContentInputSchema,
+  readContentOutputSchema,
+  ailkReadContent,
+  type ReadContentInput,
+  type ReadContentOutput,
+} from "./read_content.js";
+
+export {
+  searchContentInputSchema,
+  searchContentOutputSchema,
+  ailkSearchContent,
+  type SearchContentInput,
+  type SearchContentOutput,
+} from "./search_content.js";
+
+export {
+  getSiteInfoInputSchema,
+  getSiteInfoOutputSchema,
+  ailkGetSiteInfo,
+  type GetSiteInfoInput,
+  type GetSiteInfoOutput,
+} from "./get_site_info.js";
+
+export {
+  getBusinessHoursInputSchema,
+  getBusinessHoursOutputSchema,
+  ailkGetBusinessHours,
+  type GetBusinessHoursInput,
+  type GetBusinessHoursOutput,
+} from "./get_business_hours.js";
+
+export {
+  getLocationsInputSchema,
+  getLocationsOutputSchema,
+  ailkGetLocations,
+  type GetLocationsInput,
+  type GetLocationsOutput,
+} from "./get_locations.js";
+
+export {
+  getOfferingsInputSchema,
+  getOfferingsOutputSchema,
+  ailkGetOfferings,
+  type GetOfferingsInput,
+  type GetOfferingsOutput,
+} from "./get_offerings.js";
+
+export {
+  getPricingInputSchema,
+  getPricingOutputSchema,
+  ailkGetPricing,
+  type GetPricingInput,
+  type GetPricingOutput,
+} from "./get_pricing.js";
+
+export {
+  getFaqInputSchema,
+  getFaqOutputSchema,
+  ailkGetFaq,
+  type GetFaqInput,
+  type GetFaqOutput,
+} from "./get_faq.js";
+
+export {
+  auditInputSchema,
+  auditOutputSchema,
+  ailkAudit,
+  type AuditInput,
+  type AuditOutput,
+} from "./audit.js";
+
+export {
+  submitLeadInputSchema,
+  submitLeadOutputSchema,
+  ailkCaptureLead,
+  type SubmitLeadInput,
+  type SubmitLeadOutput,
+} from "./capture_lead.js";
+
+export {
+  subscribeNewsletterInputSchema,
+  subscribeNewsletterOutputSchema,
+  ailkSubscribeNewsletter,
+  type SubscribeNewsletterInput,
+  type SubscribeNewsletterOutput,
+} from "./subscribe_newsletter.js";
+
+export {
+  requestCallbackInputSchema,
+  requestCallbackOutputSchema,
+  ailkRequestCallback,
+  type RequestCallbackInput,
+  type RequestCallbackOutput,
+} from "./request_callback.js";
+
+export {
+  scaffoldInputSchema,
+  scaffoldOutputSchema,
+  ailkScaffold,
+  type ScaffoldInput,
+  type ScaffoldOutput,
+} from "./scaffold.js";