create-ailk 0.23.0 → 0.25.1

package/templates/apps/mcp/src/lib/audit-single-page.ts

@@ -1,308 +0,0 @@
-/**
- * audit-single-page — URL-or-slug → AuditInput adapter.
- *
- * Builds an `AuditInput` for a single page identified by slug or URL.
- * The resulting value is ready to pass directly to `runAudit`.
- *
- * Security constraint — same-origin only:
- *   URL inputs are checked against `AILK_BASE_URL` (or `NEXT_PUBLIC_BASE_URL`
- *   as fallback). Cross-domain URLs are rejected synchronously before any I/O.
- *   No `fetch()` is called anywhere in this file.
- *
- * Sitewide identity (#6597): the content root's `_site.mdx` (or its parent's)
- * is loaded, and the page's JSON-LD is stored as the flat node array
- * `composeGraph` produces — the page's primary first, then the identity nodes
- * the web render path emits — with the audit's identity mode following the
- * site's kind. The same composition the `ailk-audit` CLI uses.
- *
- * Input:  { slug, type? } | { url }  (exactly one branch; not both, not neither)
- * Output: AuditInput ready for runAudit
- * Session/scope: none — read-only filesystem access via content adapter.
- */
-
-import {
-  READINESS_SCAN_TYPES,
-  chassisSectionIds,
-  type AuditInput,
-  type ReadinessPageFacts,
-} from "@working-theory/aeo";
-import {
-  identityModeForSite,
-  loadSitewideIdentity,
-} from "@working-theory/aeo/cli/build-input";
-import {
-  type ContentAdapter,
-  type ContentPage,
-  type SchemaOrgType,
-} from "@working-theory/content-adapters";
-import {
-  buildJsonLd,
-  composeGraph,
-  graphNodes,
-  pageTypeRegistry,
-} from "@working-theory/schema";
-
-import {
-  getMcpContentAdapter,
-  mcpContentRoot,
-} from "./content-adapter.js";
-import { resolveLocale } from "./resolve-locale.js";
-import { readStripeTaxSignal } from "./stripe-tax-signal.js";
-
-export interface SlugInput {
-  slug: string;
-  type?: SchemaOrgType;
-  /**
-   * BCP-47 locale tag (Phase 3 S3). Optional; falls back to the project's
-   * default locale when omitted or invalid (AC-i18n-07).
-   */
-  locale?: string;
-}
-
-export interface UrlInput {
-  url: string;
-  /**
-   * BCP-47 locale tag (Phase 3 S3). Optional; falls back to the project's
-   * default locale when omitted or invalid (AC-i18n-07).
-   */
-  locale?: string;
-}
-
-export type SinglePageInput = SlugInput | UrlInput;
-
-const DEFAULT_IDENTITY_MODE = "organization" as const;
-
-function getBaseUrl(): string {
-  return process.env.AILK_BASE_URL ?? process.env.NEXT_PUBLIC_BASE_URL ?? "";
-}
-
-/**
- * Validates that a URL is on the AILK installation's own domain.
- *
- * Uses `URL` to parse and extract `hostname` — this correctly handles
- * credential-stuffed bypass attempts like `https://attacker@own-domain/`
- * (hostname is `attacker`, not `own-domain`) and IPv6 addresses.
- * Case-folding: URL spec normalises hostname to lowercase before comparison.
- *
- * Throws with an agent-readable error referencing `ailk audit` CLI when
- * the URL is cross-domain. The rejection is purely string-based — no I/O.
- */
-function assertSameOrigin(raw: string): void {
-  const baseUrl = getBaseUrl();
-
-  let parsed: URL;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    throw new Error(`Invalid URL: "${raw}"`);
-  }
-
-  if (!baseUrl) {
-    // No base URL configured — we cannot validate; reject to be safe.
-    throw new Error(
-      "AILK_BASE_URL (or NEXT_PUBLIC_BASE_URL) is not set. " +
-        "Cannot validate same-origin for URL input. " +
-        "Use slug input, or set AILK_BASE_URL. " +
-        "For cross-domain audits use `ailk audit` CLI.",
-    );
-  }
-
-  let base: URL;
-  try {
-    base = new URL(baseUrl);
-  } catch {
-    throw new Error(`AILK_BASE_URL is not a valid URL: "${baseUrl}"`);
-  }
-
-  // URL spec lowercases hostname; compare after normalisation.
-  if (parsed.hostname !== base.hostname) {
-    throw new Error(
-      `URL "${raw}" is out of scope for audit — ` +
-        `hostname "${parsed.hostname}" does not match installation domain "${base.hostname}". ` +
-        "For cross-domain or multi-site audits use `ailk audit` CLI.",
-    );
-  }
-}
-
-/**
- * Extracts `{ type, slug }` from a same-origin URL path.
- *
- * Expects the path to follow the convention `/<SchemaOrgType>/<slug>`.
- * Strips query strings and fragments before parsing.
- */
-function extractTypeSlugFromUrl(raw: string): {
-  type: SchemaOrgType;
-  slug: string;
-} {
-  const parsed = new URL(raw);
-  // pathname is already stripped of query/fragment by the URL object
-  const segments = parsed.pathname.split("/").filter(Boolean);
-  if (segments.length < 2) {
-    throw new Error(
-      `Cannot extract type/slug from URL path "${parsed.pathname}". ` +
-        "Expected format: /<SchemaOrgType>/<slug>",
-    );
-  }
-  const type = segments[0] as SchemaOrgType;
-  const slug = segments[1] as string;
-  return { type, slug };
-}
-
-/**
- * The site-level view the readiness rules grade (#5949 FR9/D5).
- *
- * Three adapter calls, bounded and type-closed: the collection-style pair for
- * `Product` / `Service`, the landing-style read for `PurchasePolicyPage`
- * (#6646). Independent of site size and of which page was audited (NFR4). The
- * three are independent of each other, so they run concurrently (#6012).
- *
- * Fail-open-to-pass, stated: under an unresolved adapter every list is `[]`,
- * `sitePages` is empty, and all three rules pass — a site with no known priced
- * page owes no purchase policy, which is the correct verdict for "the audit could
- * not see the site". A type the adapter legitimately has no pages of resolves
- * this way too, silently — it is not an error.
- *
- * A GENUINE adapter failure (the call throws) is a different condition from
- * that silent "no pages of this type" case, and collapsing the two loses the
- * distinction: never a throw that would take down an audit of an unrelated
- * page, but the failure is surfaced rather than vanishing indistinguishably
- * into the same vacuous pass (#6012, from the #6010 review).
- *
- * Logged via `console.error`, NOT `console.debug`/`console.log` — on the
- * default stdio MCP transport (`apps/mcp/src/index.ts`), stdout IS the
- * JSON-RPC framing channel, and `console.debug`/`console.log` both write
- * there (they are the same stream in Node). `console.error` (stderr) is the
- * convention this file's own bootstrap already uses for exactly this reason
- * (`index.ts:43,63`) — writing anywhere else would corrupt the protocol
- * stream for a mere adapter hiccup on one readiness-scan type.
- */
-async function scanSitePages(
-  adapter: ContentAdapter,
-  locale: string,
-): Promise<ReadinessPageFacts[]> {
-  const perType = await Promise.all(
-    READINESS_SCAN_TYPES.map(async (type) => {
-      const isDetail = type === "Product" || type === "Service";
-      try {
-        const pages = isDetail
-          ? await adapter.listDetail(type, locale)
-          : await adapter.listPages(type, locale);
-        return { type, pages };
-      } catch (err) {
-        console.error(
-          `[aeo] readiness scan: adapter threw listing type "${type}" — ` +
-            "treating as no pages for it",
-          err,
-        );
-        return { type, pages: [] as ContentPage[] };
-      }
-    }),
-  );
-
-  const facts: ReadinessPageFacts[] = [];
-  for (const { type, pages } of perType) {
-    for (const page of pages) {
-      // The purchase policy's section anchors (#6646) — which policies it carries.
-      const sectionIds = chassisSectionIds(page.sections);
-      facts.push({
-        slug: page.slug,
-        type,
-        ...(page.price !== undefined && { price: page.price }),
-        ...(page.stripe?.taxCode !== undefined && {
-          taxCode: page.stripe.taxCode,
-        }),
-        ...(sectionIds !== undefined && { chassisSectionIds: sectionIds }),
-      });
-    }
-  }
-  return facts;
-}
-
-/**
- * Builds an `AuditInput` for a single page.
- *
- * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves it through `mcpContentRoot()` (#8070 D3).
- *
- * `projectRoot` is the matching seam for the project.yaml the Stripe-Tax signal
- * is read from (#5949 D9); it defaults to the process cwd.
- */
-export async function buildSinglePageAuditInput(
-  input: SinglePageInput,
-  contentRoot?: string,
-  projectRoot?: string,
-): Promise<AuditInput> {
-  // Validate: exactly one of slug or url, not both, not neither.
-  const hasSlug = "slug" in input;
-  const hasUrl = "url" in input;
-
-  if (hasSlug && hasUrl) {
-    throw new Error(
-      "slug and url are mutually exclusive — provide one, not both.",
-    );
-  }
-  if (!hasSlug && !hasUrl) {
-    throw new Error("Either slug or url is required.");
-  }
-
-  const root = contentRoot ?? mcpContentRoot();
-  const locale = resolveLocale(input.locale);
-  const adapter = getMcpContentAdapter({ contentRoot: root, locale });
-
-  let type: SchemaOrgType;
-  let slug: string;
-
-  if (hasUrl) {
-    assertSameOrigin((input as UrlInput).url);
-    const extracted = extractTypeSlugFromUrl((input as UrlInput).url);
-    type = extracted.type;
-    slug = extracted.slug;
-  } else {
-    const slugInput = input as SlugInput;
-    slug = slugInput.slug;
-    type = slugInput.type ?? "HomePage";
-  }
-
-  const page = await adapter.getPageBySlug(type, slug, locale);
-  if (!page) {
-    throw new Error(
-      `Page not found: type="${type}" slug="${slug}". ` +
-        "Check that the page exists in the content directory.",
-    );
-  }
-
-  const site = loadSitewideIdentity(root, locale);
-
-  const pageKey = `${type}/${slug}`;
-  const jsonLdByPage: Record<string, unknown> = {};
-  try {
-    // Cast to ContentPageInput — structurally compatible but exactOptionalPropertyTypes
-    // differs between @working-theory/content-adapters ContentPage and @working-theory/schema ContentPageInput.
-    // This is the same pattern used in packages/aeo/src/cli/build-input.ts.
-    const primary = buildJsonLd(page as Parameters<typeof buildJsonLd>[0]);
-    jsonLdByPage[pageKey] =
-      site === undefined
-        ? primary
-        : graphNodes(
-            composeGraph({ primary, site, isHomePage: type === "HomePage" }),
-          );
-  } catch {
-    // Omit key on build failure — downstream rule reports "no JSON-LD".
-    // This mirrors packages/aeo/src/cli/build-input.ts behavior.
-  }
-
-  const stripeTaxEnabled = readStripeTaxSignal(projectRoot ?? process.cwd());
-
-  return {
-    pages: [{ slug, type, locale }],
-    locale,
-    identityMode:
-      site !== undefined ? identityModeForSite(site) : DEFAULT_IDENTITY_MODE,
-    registry: pageTypeRegistry,
-    jsonLdByPage,
-    readiness: {
-      sitePages: await scanSitePages(adapter, locale),
-      ...(stripeTaxEnabled !== undefined && { stripeTaxEnabled }),
-    },
-  };
-}

package/templates/apps/mcp/src/lib/commerce-claim.ts

@@ -1,263 +0,0 @@
-/**
- * The deployment's licence claims, resolved at boot and re-read every
- * `MCP_CLAIM_REFRESH_MS` (#7156 spec D1), read synchronously thereafter: the
- * `commerce` add-on claim (#5971 spec D2) and,
- * from the same single `checkLicense()` read, the set of licence features the
- * deployment holds (#7136 spec D3) — which gates the five `feature`-tagged
- * catalog tools under `MCP_FEATURE_GATE_MODE`. The claim is the deployment's
- * own: no tool argument, request header or session feeds it.
- *
- * Why memoised: `createMcpServer()` and `listRegisteredTools()`
- * (`apps/mcp/src/server.ts`) are synchronous and must stay that way —
- * `checkLicense()` is not. `lib/public-workspace.ts` (#5876) already solved
- * this exact shape for the content adapter, and this file follows it
- * verbatim rather than inventing a second idiom: `apps/mcp/src/index.ts`
- * awaits the initialiser once, before either transport branch, and every
- * reader takes the memoised value.
- *
- * Why TWO states where `apps/api/src/lib/require-commerce-claim.ts` has
- * three: that file's `undetermined` arm exists for exactly one caller — the
- * Stripe webhook receiver, which must hold an event with a retryable 503
- * rather than drop a charge that already moved. `start_purchase` is the twin
- * of the checkout LAUNCHER, not the webhook, and the launcher answers the
- * module-disabled response on both non-serving states because a checkout that
- * cannot be started loses nothing. So `undetermined` collapses into
- * `unclaimed` at the boundary, and this gate needs neither the stored-JWT read
- * nor the env-presence read the API twin carries.
- *
- * Fail closed (NFR-3): the initial state is `"unclaimed"` with no feature
- * held, and every path that cannot POSITIVELY establish the claim — an
- * unresolved boot, a thrown `checkLicense()`, a revoked licence, an expired
- * or unreadable one — leaves it that way.
- *
- * `apps/*` may not import `apps/*`, so the small duplication of the API-side
- * gate is the same shape `apps/mcp/src/config/modules.ts` already documents
- * for `isModuleEnabled`.
- */
-
-import { checkLicense, type ProFeature } from "@working-theory/license";
-import type { McpCatalogOptions } from "@working-theory/metadata";
-
-/** The licence `features[]` claim that turns the commerce add-on on — the
- * same literal `apps/api/src/lib/require-commerce-claim.ts` reads. */
-const COMMERCE_FEATURE = "commerce";
-
-/** Two states: the claim is positively held, or it is not. */
-export type McpCommerceClaim = "claimed" | "unclaimed";
-
-let claim: McpCommerceClaim = "unclaimed";
-
-const NO_FEATURES: ReadonlySet<ProFeature> = new Set();
-
-let heldFeatures: ReadonlySet<ProFeature> = NO_FEATURES;
-
-let featureGateOverride: McpCatalogOptions["featureGate"];
-
-export interface InitMcpCommerceClaimOptions {
-  /** Injection seam for tests — when supplied, used in place of the real
-   * `checkLicense()` so no suite reaches a licence server (NFR-6). */
-  checkLicense?: typeof checkLicense;
-}
-
-/** One resolved read: the commerce claim and the held feature set it
- * implies, from a single `checkLicense()` call. Never throws — the mapping
- * both {@link initMcpCommerceClaim} and {@link startMcpClaimRefresh}'s loop
- * share (#7156 spec D1): a revoked or unreadable licence resolves to the
- * fail-closed `"unclaimed"` with no feature, rather than propagating. */
-async function readMcpClaims(
-  options: InitMcpCommerceClaimOptions,
-): Promise<{ claim: McpCommerceClaim; features: ReadonlySet<ProFeature> }> {
-  const read = options.checkLicense ?? checkLicense;
-  try {
-    const result = await read();
-    // Revoked paid licences keep verifying until JWT exp (up to 24h after the
-    // server reports `revoked`), so a revoked licence holds no feature. See
-    // packages/license/src/types.ts § LicenseResult, ADR 0014.
-    const features =
-      result.revoked !== true ? new Set(result.features) : NO_FEATURES;
-    const resolvedClaim: McpCommerceClaim = features.has(COMMERCE_FEATURE)
-      ? "claimed"
-      : "unclaimed";
-    return { claim: resolvedClaim, features };
-  } catch {
-    return { claim: "unclaimed", features: NO_FEATURES };
-  }
-}
-
-/**
- * Resolves the deployment's commerce claim and held licence features from
- * ONE `checkLicense()` call, and memoises both for {@link mcpCommerceClaim}'s
- * and {@link mcpHeldFeatures}'s synchronous reads. Safe to call more than
- * once (each call re-resolves and re-memoises); production calls it once at
- * bootstrap, and {@link startMcpClaimRefresh} re-reads through the same
- * mapping thereafter.
- *
- * Never throws: a licence read that fails resolves to the fail-closed
- * `"unclaimed"` rather than propagating.
- */
-export async function initMcpCommerceClaim(
-  options: InitMcpCommerceClaimOptions = {},
-): Promise<McpCommerceClaim> {
-  const result = await readMcpClaims(options);
-  claim = result.claim;
-  heldFeatures = result.features;
-  return claim;
-}
-
-/** How often the running server re-reads the deployment's licence claim
- * (#7156). The server re-reads on this bound, so it agrees with the manifest
- * route's origin response within it; the route answers
- * `cache-control: public, max-age=86400`, so a downstream cache may serve an
- * older manifest for up to 24 hours. A code constant, not an env var.
- *
- * The call-time half of the refuse-flip gate is `isServedNow()` in
- * `server.ts` (#7315): it re-applies this memo at every claim-tagged call, so
- * a session opened before a re-read still refuses within this bound. */
-export const MCP_CLAIM_REFRESH_MS = 5 * 60 * 1000;
-
-/** How many consecutive re-read intervals may find the previous read still
- * unfinished before the memo falls back to no claim (#7315 L1). With
- * `MCP_CLAIM_REFRESH_MS` at 5 minutes, a claim is served at most 20 minutes
- * after the last read that finished. A code constant, not an env var. */
-export const MCP_CLAIM_MAX_MISSED_REREADS = 3;
-
-/** The running re-read loop's timer, if one is active — module-global so
- * {@link resetMcpCommerceClaim} can stop it. */
-let refreshTimer: ReturnType<typeof setInterval> | undefined;
-
-/** Bumped by every {@link startMcpClaimRefresh} and {@link
- * resetMcpCommerceClaim} call. Each loop's closure captures its own
- * generation at start; a tick whose generation has gone stale (a later
- * start, or a reset) discards its result instead of writing it. */
-let refreshGeneration = 0;
-
-/** Stops the running re-read loop, if any, and bumps the generation so any
- * read already in flight from it is discarded on settling. */
-function stopMcpClaimRefresh(): void {
-  if (refreshTimer !== undefined) {
-    clearInterval(refreshTimer);
-    refreshTimer = undefined;
-  }
-  refreshGeneration++;
-}
-
-/**
- * Starts the bounded re-read: every `MCP_CLAIM_REFRESH_MS`, one licence read,
- * skipped while the previous one is still pending. At most one loop per
- * process — a second call replaces the first. The timer is unref'd, so it
- * never holds a process open. Never throws.
- *
- * A tick that finds the previous read still unfinished increments a `missed`
- * count and returns, as before, UNLESS that count has reached
- * {@link MCP_CLAIM_MAX_MISSED_REREADS}: at the ceiling the memo falls back to
- * no claim and a fresh read starts on the same tick (#7315 L1). Each read
- * captures its own sequence number; a read writes the memo, and clears the
- * in-flight flag, only while it is still the most recently started read — so
- * a read the ceiling abandons can never write a stale result once a fresh
- * read has replaced it.
- */
-export function startMcpClaimRefresh(
-  options: InitMcpCommerceClaimOptions = {},
-): void {
-  stopMcpClaimRefresh();
-  const generation = refreshGeneration;
-  let inFlight = false;
-  let missed = 0;
-  let readSeq = 0;
-
-  function startRead(): void {
-    inFlight = true;
-    missed = 0;
-    const seq = ++readSeq;
-    void readMcpClaims(options)
-      .then((result) => {
-        if (generation === refreshGeneration && seq === readSeq) {
-          claim = result.claim;
-          heldFeatures = result.features;
-        }
-      })
-      .finally(() => {
-        if (seq === readSeq) {
-          inFlight = false;
-        }
-      });
-  }
-
-  const timer = setInterval(() => {
-    if (generation !== refreshGeneration) return;
-    if (!inFlight) {
-      startRead();
-      return;
-    }
-    if (++missed < MCP_CLAIM_MAX_MISSED_REREADS) return;
-    claim = "unclaimed";
-    heldFeatures = NO_FEATURES;
-    startRead();
-  }, MCP_CLAIM_REFRESH_MS);
-  timer.unref();
-  refreshTimer = timer;
-}
-
-/** Test-only writers are inert outside a test run (#7156 L2): each throws,
- * before touching any state, unless NODE_ENV is "test" — which Jest sets. */
-function assertTestOnly(name: string): void {
-  if (process.env["NODE_ENV"] !== "test") {
-    throw new Error(`${name} is test-only and cannot run outside a test`);
-  }
-}
-
-/** The memoised claim, read synchronously by both gates in `server.ts` and
- * by `tools/purchase.ts`'s call-time re-check. */
-export function mcpCommerceClaim(): McpCommerceClaim {
-  return claim;
-}
-
-/** Test-only injector — sets the memoised claim directly, bypassing the
- * licence read entirely. The seam every claim-state matrix in
- * `apps/mcp/__tests__` drives both halves through. */
-export function __setMcpCommerceClaimForTest(next: McpCommerceClaim): void {
-  assertTestOnly("__setMcpCommerceClaimForTest");
-  claim = next;
-}
-
-/** The memoised licence features this deployment holds (#7136), read
- * synchronously by `server.ts`'s catalog options and boot warning. */
-export function mcpHeldFeatures(): ReadonlySet<ProFeature> {
-  return heldFeatures;
-}
-
-/** Test-only injector — sets the memoised feature set directly, bypassing
- * the licence read entirely. */
-export function __setMcpHeldFeaturesForTest(
-  features: readonly ProFeature[],
-): void {
-  assertTestOnly("__setMcpHeldFeaturesForTest");
-  heldFeatures = new Set(features);
-}
-
-/** The test-set gate mode, or `undefined` — meaning `MCP_FEATURE_GATE_MODE`
- * decides. Production never sets it. */
-export function mcpFeatureGateOverride(): McpCatalogOptions["featureGate"] {
-  return featureGateOverride;
-}
-
-/** Test-only injector — overrides `MCP_FEATURE_GATE_MODE` for this module's
- * readers, so a suite can drive refuse mode without flipping the constant. */
-export function __setMcpFeatureGateForTest(
-  mode: McpCatalogOptions["featureGate"],
-): void {
-  assertTestOnly("__setMcpFeatureGateForTest");
-  featureGateOverride = mode;
-}
-
-/** Test-only reset — returns to the module's initial, fail-closed state: no
- * commerce claim, no feature held, no gate-mode override — and stops the
- * re-read loop (#7156 D1), so a suite's `afterEach(resetMcpCommerceClaim)`
- * cannot leak one. */
-export function resetMcpCommerceClaim(): void {
-  assertTestOnly("resetMcpCommerceClaim");
-  stopMcpClaimRefresh();
-  claim = "unclaimed";
-  heldFeatures = NO_FEATURES;
-  featureGateOverride = undefined;
-}