create-ailk 0.1.0

package/templates/apps/web/app/.well-known/ai-plugin.json/route.ts

@@ -0,0 +1,81 @@
+/**
+ * GET /.well-known/ai-plugin.json
+ *
+ * Returns the agent plugin manifest for AILK. The shape conforms to the
+ * AgentPluginManifestSchema defined in @working-theory/agent-contract.
+ *
+ * Fields with no source today default to 'none' / placeholder values and
+ * are documented here for Phase 2 enrichment:
+ *   - logo_url: no asset yet; omitted
+ *   - contact_email: no org email configured; omitted
+ *   - legal_info_url: no legal page yet; omitted
+ *   - api.url: no deployed OpenAPI spec yet; defaults to /openapi.json on same origin
+ *
+ * ─── Consumer re-validation expectation ─────────────────────────────────────
+ * This manifest is published over a public, cacheable HTTP route. Consumers
+ * (LLM agents, gateways, validators) MUST re-verify the manifest contents at
+ * fetch time — DO NOT trust a cached or out-of-band copy. In particular:
+ *
+ *   - `description_for_model`: an agent host should bound its length and
+ *     scan for prompt-injection patterns before passing it into a model
+ *     context window.
+ *   - `auth`: confirm the declared scheme matches the API's actual auth
+ *     enforcement at the OpenAPI endpoint.
+ *   - `api.url`: re-fetch the OpenAPI spec and validate the schema before
+ *     synthesizing tool definitions.
+ *
+ * See `docs/security/agent-manifest.md` for the full consumer guidance.
+ */
+
+import { resolveBaseUrl } from "../../../src/lib/routes";
+
+/** Soft cap to detect runaway `description_for_model` growth. */
+export const DESCRIPTION_FOR_MODEL_SOFT_CAP_CHARS = 8_000;
+
+const MANIFEST_DESCRIPTION_FOR_MODEL =
+  "AI Launch Kit (AILK) is an open-source template for shipping AI-native applications. Use it to explore the product catalog, purchase a license, or query documentation.";
+
+/**
+ * Validates that a manifest's `description_for_model` is within reasonable
+ * bounds. Logs a warning when oversized; returns a boolean for callers that
+ * want to short-circuit (we choose to still serve the manifest, since
+ * truncating silently would be worse than warning).
+ */
+export function validateDescriptionForModel(description: string): boolean {
+  if (description.length > DESCRIPTION_FOR_MODEL_SOFT_CAP_CHARS) {
+    console.warn(
+      `[ai-plugin.json] description_for_model exceeds soft cap (${description.length} > ${DESCRIPTION_FOR_MODEL_SOFT_CAP_CHARS} chars). Consumers may rate-limit or reject oversized manifests.`,
+    );
+    return false;
+  }
+  return true;
+}
+
+// Startup-time validation: fire once on module load so over-sized manifests
+// are flagged before the first request lands.
+validateDescriptionForModel(MANIFEST_DESCRIPTION_FOR_MODEL);
+
+export function GET(): Response {
+  const baseUrl = resolveBaseUrl();
+
+  const manifest = {
+    schema_version: "v1",
+    name_for_human: "AI Launch Kit",
+    name_for_model: "ai_launch_kit",
+    description_for_human:
+      "AX-first OSS template — ship software with API + MCP as canonical agent surfaces.",
+    description_for_model: MANIFEST_DESCRIPTION_FOR_MODEL,
+    auth: { type: "none" },
+    api: {
+      type: "openapi",
+      url: `${baseUrl}/openapi.json`,
+    },
+  };
+
+  return Response.json(manifest, {
+    status: 200,
+    headers: {
+      "cache-control": "public, max-age=86400",
+    },
+  });
+}

package/templates/apps/web/app/.well-known/mcp.json/build-manifest.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure builder for the /.well-known/mcp.json manifest.
+ *
+ * Extracted from the route handler so the manifest shape can be unit-tested
+ * without booting Next.js. Reads the canonical tool catalog from
+ * @working-theory/metadata; does no I/O of its own.
+ *
+ * Issue #209 (spec: docs/internal/specs/draft/ailk-mcp-mvp-pa-i6-discovery-route-spec.md).
+ * Issue #300 — moved to /.well-known/mcp.json; added name, description, transport,
+ * and outputSchema per MCP discovery spec.
+ * Issue #918 — added optional transports[] array to advertise HTTP transport
+ * endpoint when MCP_PUBLIC_HTTP_URL is configured.
+ */
+
+import { getMcpToolCatalog, type McpToolCatalogEntry } from "@working-theory/metadata";
+
+/**
+ * Inline transport descriptor shape — mirrors McpTransportDescriptor from
+ * @working-theory/agent-contract without creating a cross-boundary import from apps/web
+ * into packages/agent-contract (which is not on the architecture.yaml allowlist
+ * for apps/web). The canonical schema lives in agent-contract; this is a
+ * structural copy for the build-manifest module.
+ */
+type TransportDescriptor =
+  | { type: "stdio"; label?: string }
+  | { type: "http"; url: string; version?: string; label?: string };
+
+export interface McpManifest {
+  /** Manifest schema version. Bump on breaking shape changes only. */
+  schemaVersion: "1";
+  /** Human-readable server name. */
+  name: string;
+  /** Human-readable server description. */
+  description: string;
+  /** Absolute URL the agent connects to for the MCP protocol session. */
+  mcpEndpoint: string;
+  /** Tool catalog — names, descriptions, input schemas, and output schemas. */
+  tools: McpToolCatalogEntry[];
+  /**
+   * Primary transport for legacy MCP discovery clients (schemaVersion "1").
+   * New clients should use `transports[]`.
+   */
+  transport: {
+    type: "http";
+    version: string;
+  };
+  /**
+   * Available transport descriptors for this MCP server.
+   * Populated when the operator configures standalone transport endpoints.
+   * Agents SHOULD prefer this array over the singular `transport` field.
+   */
+  transports?: TransportDescriptor[];
+  /** AILK installation metadata (version etc.). */
+  ailk: {
+    version: string;
+  };
+}
+
+export interface BuildMcpManifestOptions {
+  /** Site base URL — used to derive the MCP endpoint. */
+  baseUrl: string;
+  /** AILK package version surfaced to discovering agents. */
+  ailkVersion: string;
+  /**
+   * Optional: absolute URL of the standalone MCP HTTP transport
+   * (i.e. the URL of apps/mcp when running in HTTP mode).
+   * When set, the manifest advertises this as an additional transport endpoint.
+   * Typically sourced from the MCP_PUBLIC_HTTP_URL env var in the web app.
+   */
+  mcpHttpUrl?: string;
+}
+
+/** Path the MCP server is mounted at, relative to baseUrl. */
+const MCP_ENDPOINT_PATH = "/api/mcp";
+
+/** MCP HTTP transport version this server implements. */
+const MCP_HTTP_VERSION = "2025-03-26";
+
+/**
+ * Builds the /.well-known/mcp.json manifest. Pure: same input → same output.
+ */
+export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
+  const transports: TransportDescriptor[] = [
+    { type: "stdio", label: "Local stdio (subprocess)" },
+  ];
+
+  if (opts.mcpHttpUrl) {
+    transports.push({
+      type: "http",
+      url: opts.mcpHttpUrl,
+      version: MCP_HTTP_VERSION,
+      label: "HTTP (Streamable HTTP transport)",
+    });
+  }
+
+  return {
+    schemaVersion: "1",
+    name: "AI Launch Kit",
+    description:
+      "AX-first OSS template — ship software with API + MCP as canonical agent surfaces.",
+    mcpEndpoint: `${opts.baseUrl}${MCP_ENDPOINT_PATH}`,
+    tools: getMcpToolCatalog(),
+    transport: {
+      type: "http",
+      version: MCP_HTTP_VERSION,
+    },
+    transports,
+    ailk: { version: opts.ailkVersion },
+  };
+}

package/templates/apps/web/app/.well-known/mcp.json/route.ts

@@ -0,0 +1,58 @@
+/**
+ * GET /.well-known/mcp.json
+ *
+ * Per-site MCP discovery manifest. Agents land on a customer site, hit this
+ * URL, and discover the MCP endpoint + tool catalog without out-of-band
+ * coordination. Issue #209 (initial), #300 (moved to correct URL + CORS).
+ *
+ * Pure assembly — no fetch(). The catalog is read in-process from
+ * @working-theory/metadata; the AILK version is read from this app's package.json.
+ *
+ * Mirrors /.well-known/ai-plugin.json conventions: Response.json with a
+ * conservative cache-control header.
+ *
+ * CORS: MCP discovery clients are cross-origin by design. The open GET is
+ * public — no credentials, no session-scoped data — so Access-Control-Allow-Origin: *
+ * is appropriate per the MCP discovery spec.
+ */
+
+import packageJson from "../../../package.json";
+import { resolveBaseUrl } from "../../../src/lib/routes";
+
+import { buildMcpManifest } from "./build-manifest";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+} as const;
+
+export function OPTIONS(): Response {
+  return new Response(null, {
+    status: 204,
+    headers: CORS_HEADERS,
+  });
+}
+
+export function GET(): Response {
+  // MCP_PUBLIC_HTTP_URL advertises the standalone HTTP transport endpoint
+  // (apps/mcp running in HTTP mode). When set, the manifest includes it
+  // as an additional transport descriptor for discovering agents.
+  const mcpHttpUrlEnv = process.env["MCP_PUBLIC_HTTP_URL"];
+
+  const manifest = buildMcpManifest({
+    baseUrl: resolveBaseUrl(),
+    ailkVersion: packageJson.version,
+    // Spread conditional to satisfy exactOptionalPropertyTypes: omit the key
+    // entirely when the env var is not set rather than passing undefined.
+    ...(mcpHttpUrlEnv ? { mcpHttpUrl: mcpHttpUrlEnv } : {}),
+  });
+
+  return Response.json(manifest, {
+    status: 200,
+    headers: {
+      "cache-control": "public, max-age=86400",
+      ...CORS_HEADERS,
+    },
+  });
+}

package/templates/apps/web/app/[locale]/__tests__/layout.test.tsx

@@ -0,0 +1,120 @@
+/**
+ * Tests for LocaleLayout — verifies the <html dir> attribute is set
+ * correctly based on the active locale.
+ *
+ * The layout is an async server component; jest renders it by awaiting
+ * the returned ReactElement promise. Heavy Next.js/next-intl deps are
+ * mocked so the test focuses on the dir attribute wiring only.
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+
+// ── Mock heavy/Next.js-specific dependencies ──────────────────────────
+jest.mock("next/navigation", () => ({
+  usePathname: jest.fn().mockReturnValue("/en/"),
+}));
+
+jest.mock("next/headers", () => ({
+  headers: jest.fn().mockResolvedValue({
+    get: jest.fn().mockReturnValue("/"),
+  }),
+}));
+
+jest.mock("next-intl/server", () => ({
+  getMessages: jest.fn().mockResolvedValue({}),
+  getTranslations: jest.fn().mockImplementation(({ namespace }: { namespace: string }) => {
+    if (namespace === "nav") {
+      const t = (key: string) => key;
+      return Promise.resolve(t);
+    }
+    const t = (key: string) => key;
+    return Promise.resolve(t);
+  }),
+}));
+
+jest.mock("next-intl", () => ({
+  NextIntlClientProvider: ({ children }: { children: React.ReactNode }) => (
+    <>{children}</>
+  ),
+}));
+
+jest.mock("@working-theory/web-i18n", () => ({
+  readLocales: jest.fn().mockReturnValue(["en"]),
+  buildHreflangAlternates: jest.fn().mockReturnValue({}),
+  getStealthRobots: jest.fn().mockReturnValue({}),
+}));
+
+jest.mock("@working-theory/analytics", () => ({
+  Telemetry: () => null,
+  VerificationMeta: () => null,
+}));
+
+// ── Import subject under test ──────────────────────────────────────────
+import LocaleLayout, { generateMetadata } from "../layout";
+
+async function renderLayout(locale: string): Promise<void> {
+  const element = LocaleLayout({
+    children: <span data-testid="child">content</span>,
+    params: Promise.resolve({ locale }),
+  });
+  const resolved = await element;
+  render(resolved);
+}
+
+describe("generateMetadata()", () => {
+  it("returns a title and description", async () => {
+    const metadata = await generateMetadata();
+    expect(metadata.title).toBe("AI Launch Kit");
+    expect(metadata.description).toMatch(/OSS/);
+  });
+
+  it("includes alternates.languages from buildHreflangAlternates", async () => {
+    const metadata = await generateMetadata();
+    expect(metadata.alternates).toBeDefined();
+    expect(metadata.alternates?.languages).toBeDefined();
+  });
+});
+
+describe("LocaleLayout — chrome smoke (#1451)", () => {
+  it("renders Nav with aria-label=Primary", async () => {
+    await renderLayout("en");
+    expect(document.querySelector("nav[aria-label='Primary']")).toBeInTheDocument();
+  });
+
+  it("renders Footer element", async () => {
+    await renderLayout("en");
+    expect(document.querySelector("footer")).toBeInTheDocument();
+  });
+
+  it("renders nav logo link pointing to locale home", async () => {
+    await renderLayout("en");
+    const logoLink = document.querySelector("[data-testid='brand-logo-link']");
+    expect(logoLink).toBeInTheDocument();
+    // as-needed dialect (#3450): bare for the default locale.
+    expect(logoLink?.getAttribute("href")).toBe("/");
+  });
+});
+
+describe("LocaleLayout — <html dir> attribute", () => {
+  // React 19 + jsdom: <html> is a singleton (document.documentElement);
+  // RTL merges the rendered <html> attributes onto the live document root.
+  it('renders dir="ltr" for locale "en"', async () => {
+    await renderLayout("en");
+    expect(document.documentElement.getAttribute("dir")).toBe("ltr");
+  });
+
+  it('renders dir="rtl" for locale "ar"', async () => {
+    await renderLayout("ar");
+    expect(document.documentElement.getAttribute("dir")).toBe("rtl");
+  });
+
+  it('preserves lang attribute for locale "en"', async () => {
+    await renderLayout("en");
+    expect(document.documentElement.getAttribute("lang")).toBe("en");
+  });
+
+  it('preserves lang attribute for locale "ar"', async () => {
+    await renderLayout("ar");
+    expect(document.documentElement.getAttribute("lang")).toBe("ar");
+  });
+});

package/templates/apps/web/app/[locale]/__tests__/page-renderer-migration.test.tsx

@@ -0,0 +1,202 @@
+/**
+ * HTML snapshot regression tests for the apps/web → @working-theory/page-renderer migration.
+ *
+ * Node version: captured against Node 22.x (same as CI).
+ * MDX seed content: DI-injected stub — no fs reads, deterministic across environments.
+ *
+ * Two-commit strategy (per spec §8 Open Questions):
+ *   Commit 1: this file added; snapshots captured against pre-migration routes (RED-passing).
+ *   Commit 2: routes migrated; same snapshots verify diff=0 (GREEN).
+ *
+ * Each of the four routes is tested in two states:
+ *   - empty: getMdxSource returns null → empty-state branch
+ *   - populated: getMdxSource returns a minimal MdxPageSource → full render
+ *
+ * Failure = snapshot diff > 0 bytes. DO NOT regenerate snapshots to pass.
+ * A non-zero diff indicates a behavior regression in the migration. Escalate.
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+import { stripJsonLd } from "@working-theory/page-renderer/testing";
+
+// ── @working-theory/ui mock ─────────────────────────────────────────────────────────────
+// SectionRenderer renders a predictable deterministic div so the snapshot is
+// stable across section-component implementations.
+jest.mock("@working-theory/ui", () => ({
+  SectionRenderer: ({ sections }: { sections: unknown[] }) =>
+    React.createElement("div", {
+      "data-testid": "section-renderer",
+      "data-section-count": String(sections.length),
+    }),
+}));
+
+// ── Import page components ─────────────────────────────────────────────────────
+import HomePage from "../page";
+import AboutPage from "../about/page";
+import FAQPage from "../faq/page";
+import LaunchServicePage from "../launch-service/page";
+
+// ── Shared stubs ───────────────────────────────────────────────────────────────
+
+function makeSource(
+  type: string,
+  slug: string,
+  title: string,
+  description: string,
+) {
+  return {
+    frontmatter: {
+      type: type as "HomePage",
+      slug,
+      title,
+      description,
+    },
+    body: "",
+  };
+}
+
+const getMdxSourceEmpty = jest.fn().mockResolvedValue(null);
+const getPageSectionsEmpty = jest.fn().mockResolvedValue([]);
+
+// ── HomePage ───────────────────────────────────────────────────────────────────
+
+describe("HomePage — snapshot regression", () => {
+  it("empty state renders deterministic HTML", async () => {
+    const element = await HomePage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourceEmpty,
+      getPageSections: getPageSectionsEmpty,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>AI Launch Kit</h1><p data-testid="home-description">AX-first OSS template for shipping software with API + MCP as canonical surfaces.</p></main>"`,
+    );
+  });
+
+  it("populated state renders deterministic HTML", async () => {
+    const source = makeSource(
+      "HomePage",
+      "home",
+      "AI Launch Kit",
+      "AX-first OSS template for shipping software with API + MCP as canonical surfaces.",
+    );
+    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
+    const getPageSectionsPopulated = jest.fn().mockResolvedValue([]);
+
+    const element = await HomePage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourcePopulated,
+      getPageSections: getPageSectionsPopulated,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>AI Launch Kit</h1><p data-testid="home-description">AX-first OSS template for shipping software with API + MCP as canonical surfaces.</p><div data-testid="section-renderer" data-section-count="0"></div></main>"`,
+    );
+  });
+});
+
+// ── AboutPage ──────────────────────────────────────────────────────────────────
+
+describe("AboutPage — snapshot regression", () => {
+  it("empty state renders deterministic HTML", async () => {
+    const element = await AboutPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourceEmpty,
+      getPageSections: getPageSectionsEmpty,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>About</h1><p data-testid="section-empty-state">About page content coming soon.</p></main>"`,
+    );
+  });
+
+  it("populated state renders deterministic HTML", async () => {
+    const source = makeSource("AboutPage", "about", "About Us", "Who we are.");
+    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
+    const getPageSectionsPopulated = jest.fn().mockResolvedValue([]);
+
+    const element = await AboutPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourcePopulated,
+      getPageSections: getPageSectionsPopulated,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>About Us</h1><p data-testid="about-description">Who we are.</p><div data-testid="section-renderer" data-section-count="0"></div></main>"`,
+    );
+  });
+});
+
+// ── FAQPage ────────────────────────────────────────────────────────────────────
+
+describe("FAQPage — snapshot regression", () => {
+  it("empty state renders deterministic HTML (with scaffold JSON-LD)", async () => {
+    const element = await FAQPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourceEmpty,
+      getPageSections: getPageSectionsEmpty,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>FAQ</h1><p data-testid="section-empty-state">Frequently asked questions content coming soon.</p></main>"`,
+    );
+  });
+
+  it("populated state renders deterministic HTML", async () => {
+    const source = makeSource(
+      "FAQPage",
+      "faq",
+      "FAQ",
+      "Frequently asked questions.",
+    );
+    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
+    const getPageSectionsPopulated = jest.fn().mockResolvedValue([]);
+
+    const element = await FAQPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourcePopulated,
+      getPageSections: getPageSectionsPopulated,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>FAQ</h1><p data-testid="faq-description">Frequently asked questions.</p><div data-testid="section-renderer" data-section-count="0"></div></main>"`,
+    );
+  });
+});
+
+// ── LaunchServicePage ──────────────────────────────────────────────────────────
+
+describe("LaunchServicePage — snapshot regression", () => {
+  it("empty state renders deterministic HTML", async () => {
+    const element = await LaunchServicePage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourceEmpty,
+      getPageSections: getPageSectionsEmpty,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>Launch Service</h1><p data-testid="section-empty-state">Launch Service page content coming soon.</p></main>"`,
+    );
+  });
+
+  it("populated state renders deterministic HTML", async () => {
+    const source = makeSource(
+      "Service",
+      "launch-service",
+      "Launch Service",
+      "Our launch service offering.",
+    );
+    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
+    const getPageSectionsPopulated = jest.fn().mockResolvedValue([]);
+
+    const element = await LaunchServicePage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourcePopulated,
+      getPageSections: getPageSectionsPopulated,
+    });
+    const { container } = render(element);
+    expect(stripJsonLd(container.innerHTML)).toMatchInlineSnapshot(
+      `"<main><h1>Launch Service</h1><p data-testid="launch-service-description">Our launch service offering.</p><div data-testid="section-renderer" data-section-count="0"></div></main>"`,
+    );
+  });
+});

package/templates/apps/web/app/[locale]/about/page.tsx

@@ -0,0 +1,31 @@
+// About page. Reads the AboutPage MDX frontmatter, renders sections via
+// SectionRenderer, and emits a JSON-LD <script>.
+import type {
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections} from "@working-theory/page-renderer";
+import {
+  renderPage
+} from "@working-theory/page-renderer";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+  getPageSections,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  return renderPage({
+    type: "AboutPage",
+    slug: "about",
+    locale,
+    translationsNamespace: "about",
+    ...(getMdxSource !== undefined && { getMdxSource }),
+    ...(getPageSections !== undefined && { getPageSections }),
+  });
+}