create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/src/mcp/tools.ts

@@ -0,0 +1,182 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// MCP tools, derived from the service registry (MASTER.md §11, §28.3).
+//
+// §28 is emphatic about why this is generated rather than authored: "New
+// feature merged → new MCP tool exists. No release lag at all." An instance
+// with a plugin installed an hour ago exposes that plugin's tools to an agent
+// now, with descriptions from the plugin's own schema — because there is no
+// second list anywhere that someone would have to remember to update.
+//
+// Two things are decided here that the HTTP API did not have to decide.
+//
+// **Which tools a caller sees.** The list is filtered by what the caller may
+// actually call. An agent shown eighty tools and permitted six will spend its
+// attempts discovering that by failing, and every failure is a request that
+// did something visible in an audit log for no reason. Capability discovery is
+// what MCP is for, so the list *is* the capability.
+//
+// **What is not a tool at all.** Credential services are excluded whatever the
+// caller's scopes say — see EXCLUDED_FAMILIES.
+import { listServices, permits, type Actor, type Service } from "@/core/service";
+import { toContractJsonSchema } from "@/core/contract/json-schema";
+
+/**
+ * Families that never become tools.
+ *
+ * Not a security control — scopes are that, and `apikeys.create` already
+ * refuses an agent outright. This is about what an agent should be *invited*
+ * to do. `auth.login` is a public service, so it would appear to an
+ * unauthenticated MCP client as a tool taking an email and a password, which
+ * is an invitation to guess at credentials rather than a capability of the
+ * business. An agent authenticates with the key it was given; managing
+ * credentials is the owner's work, done while signed in.
+ * Staff invitations are the same boundary: accepting one chooses a password,
+ * while creating or resending one issues a credential that can create an
+ * account. They stay available through the human UI and HTTP service surface,
+ * but an MCP client is never prompted to handle either side of that secret.
+ *
+ * Families that stay off MCP unless a service sets `mcpExclude: false`.
+ * Per-service `mcpExclude` is the C3.04 opt-out.
+ */
+const EXCLUDED_FAMILIES = new Set(["auth", "apikeys", "invitations"]);
+
+export function hiddenFromMcp(service: Service): boolean {
+  // Internal orchestration never becomes an agent capability. This check is
+  // first so `mcpExclude: false` cannot accidentally override the boundary.
+  if (service.def.permission === "system" || service.def.external === false) return true;
+  if (service.def.mcpExclude === true) return true;
+  if (service.def.mcpExclude === false) return false;
+  return EXCLUDED_FAMILIES.has(service.def.name.split(".")[0]!);
+}
+
+export interface McpTool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    /** C3.04: who this listing was computed for. */
+    actorKind: Actor["kind"];
+    /** C3.04: a person must confirm before the service will run. */
+    approval: "none" | "step_up" | "human";
+  };
+}
+
+/**
+ * `contacts.create` → `contacts_create`.
+ *
+ * MCP tool names are restricted to letters, digits, underscore and hyphen by
+ * most clients, and every service name in this codebase is `[a-z]` plus dots
+ * with no underscores of its own — asserted in the tests — so swapping the
+ * separator is unambiguous and reverses exactly.
+ */
+export function toolName(serviceName: string): string {
+  return serviceName.replace(/\./g, "_");
+}
+
+/** Verbs that destroy something a person would miss. */
+const DESTRUCTIVE = /^(delete|remove|revoke|purge|trash|merge)/;
+
+function describe(service: Service): string {
+  const { name, summary, permission, kind } = service.def;
+  const family = `${name.split(".")[0]!}.*`;
+  return [
+    summary,
+    "",
+    `Calls the \`${name}\` service. ${kind === "query" ? "Reads only." : "Changes data."}`,
+    permission === "public"
+      ? "Available to any caller."
+      : permission === "authenticated"
+        ? "Available only to a signed-in person."
+        : `Needs an API key scoped \`${name}\` or \`${family}\`.`,
+  ].join("\n");
+}
+
+/**
+ * A service's input as JSON Schema, for the tool's `inputSchema`.
+ *
+ * The same generation the OpenAPI document uses, and the same reason: it is
+ * the object the call will actually be validated against, so a tool cannot
+ * advertise a shape the service would reject.
+ */
+function inputSchema(service: Service): Record<string, unknown> {
+  // C3.04: dates and coercions must retain the HTTP/SDK wire shape. A local
+  // Zod conversion used to throw on dates and erase every field in the tool.
+  const schema = toContractJsonSchema(service.def.input, "input") as Record<string, unknown>;
+  // MCP requires an object schema at the top level. A service whose input is
+  // not an object (none are today) would otherwise produce a tool no client
+  // can call.
+  if (schema.type !== "object") return { type: "object", properties: {} };
+  return { properties: {}, ...schema };
+}
+
+/**
+ * Every tool this caller may use.
+ *
+ * `permits` is the same function the service itself will consult, so the list
+ * cannot promise something the call would refuse.
+ */
+export function toolsFor(actor: Actor): McpTool[] {
+  const tools: McpTool[] = [];
+  for (const service of listServices().values()) {
+    const { name, kind, permission, summary } = service.def;
+    if (hiddenFromMcp(service)) continue;
+    if (service.def.stepUp && actor.kind !== "user") continue;
+    if (service.def.agentCallable === false && actor.kind === "agent") continue;
+    if (!permits(actor, permission, name, kind)) continue;
+
+    const verb = name.split(".")[1] ?? "";
+    tools.push({
+      name: toolName(name),
+      title: summary,
+      description: describe(service),
+      inputSchema: inputSchema(service),
+      annotations: {
+        // Hints, not enforcement — the service is the enforcement. They let a
+        // client decide what to confirm with a person before running.
+        readOnlyHint: kind === "query",
+        destructiveHint: kind === "mutation" && DESTRUCTIVE.test(verb),
+        idempotentHint: kind === "query",
+        actorKind: actor.kind,
+        approval: service.def.stepUp
+          ? "step_up"
+          : service.def.agentCallable === false
+            ? "human"
+            : "none",
+      },
+    });
+  }
+  return tools.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** The service behind a tool name, if this caller may call it. */
+export function serviceForTool(
+  actor: Actor,
+  tool: string,
+): Service | undefined {
+  for (const service of listServices().values()) {
+    if (toolName(service.def.name) !== tool) continue;
+    if (hiddenFromMcp(service)) return undefined;
+    if (service.def.stepUp && actor.kind !== "user") return undefined;
+    if (service.def.agentCallable === false && actor.kind === "agent") {
+      return undefined;
+    }
+    // Resolved through the same permission check as the listing, so a tool
+    // that was never offered cannot be called by guessing its name.
+    if (
+      !permits(
+        actor,
+        service.def.permission,
+        service.def.name,
+        service.def.kind,
+      )
+    )
+      return undefined;
+    return service;
+  }
+  return undefined;
+}

package/dist/template/src/modules/ads/AdBeacon.tsx

@@ -0,0 +1,76 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+"use client";
+// MRC observation for a served fill (MASTER.md §4.16, C9.19).
+import { useEffect, useRef } from "react";
+import { VIEWABLE_MS, VIEWABLE_PIXEL_RATIO } from "./viewability";
+
+export function AdBeacon({
+  creativeId,
+  slotId,
+  children,
+}: {
+  creativeId: string;
+  slotId: string;
+  children: React.ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const impressed = useRef(false);
+  const viewable = useRef(false);
+  const hold = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || typeof IntersectionObserver === "undefined") return;
+
+    const send = (kind: "impression" | "viewable") => {
+      void fetch("/api/ads/view", {
+        method: "POST",
+        credentials: "same-origin",
+        keepalive: true,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          kind,
+          creativeId,
+          slotId,
+          path: window.location.pathname,
+        }),
+      });
+    };
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (!entry) return;
+        if (entry.isIntersecting && !impressed.current) {
+          impressed.current = true;
+          send("impression");
+        }
+        if (entry.intersectionRatio >= VIEWABLE_PIXEL_RATIO && !viewable.current) {
+          if (hold.current) return;
+          hold.current = setTimeout(() => {
+            hold.current = null;
+            if (viewable.current) return;
+            viewable.current = true;
+            send("viewable");
+          }, VIEWABLE_MS);
+        } else if (entry.intersectionRatio < VIEWABLE_PIXEL_RATIO && hold.current) {
+          clearTimeout(hold.current);
+          hold.current = null;
+        }
+      },
+      { threshold: [0, VIEWABLE_PIXEL_RATIO] },
+    );
+    observer.observe(node);
+    return () => {
+      observer.disconnect();
+      if (hold.current) clearTimeout(hold.current);
+    };
+  }, [creativeId, slotId]);
+
+  return (
+    <div ref={ref} data-ad-creative={creativeId} data-ad-slot={slotId}>
+      {children}
+    </div>
+  );
+}

package/dist/template/src/modules/ads/ThirdPartyConsent.tsx

@@ -0,0 +1,45 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Consent for somebody else's ad tag (MASTER.md §4.16, C9.20).
+//
+// Separate from analytics consent: C1.19 is explicit that creative code is a
+// different risk, and `fh_tc=granted` is the only value that opens the CSP.
+// Shown only inside a slot whose winning creative would have been third-party,
+// so a page with no such creative never asks.
+import type { Translate } from "@/core/i18n";
+
+export function ThirdPartyConsent({
+  returnTo,
+  t,
+}: {
+  returnTo: string;
+  t: Translate;
+}) {
+  return (
+    <div className="grid h-full w-full place-items-center gap-2 p-3 text-center">
+      <p className="text-xs text-ink-muted">{t("ads.consent.explanation")}</p>
+      <div className="flex flex-wrap justify-center gap-2">
+        <form action="/api/ads/third-party-consent" method="post">
+          <input type="hidden" name="decision" value="grant" />
+          <input type="hidden" name="returnTo" value={returnTo} />
+          <button
+            type="submit"
+            className="rounded-md bg-accent px-3 py-1.5 text-xs font-semibold text-on-accent"
+          >
+            {t("ads.consent.allow")}
+          </button>
+        </form>
+        <form action="/api/ads/third-party-consent" method="post">
+          <input type="hidden" name="decision" value="deny" />
+          <input type="hidden" name="returnTo" value={returnTo} />
+          <button
+            type="submit"
+            className="rounded-md border border-rule px-3 py-1.5 text-xs font-semibold text-ink"
+          >
+            {t("ads.consent.decline")}
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+}

package/dist/template/src/modules/ads/ads-txt.ts

@@ -0,0 +1,60 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Generated ads.txt / app-ads.txt (MASTER.md §4.16, C9.20).
+//
+// Programmatic demand requires the file; a hand-edited one goes stale. The
+// body is assembled from owner-managed rows so a line exists only because
+// somebody put it there, which is what "accurate" means — generating from
+// whatever creatives happen to be live would claim DIRECT for a network the
+// owner had already stopped using.
+
+export const TXT_RELATIONSHIPS = ["DIRECT", "RESELLER"] as const;
+export type TxtRelationship = (typeof TXT_RELATIONSHIPS)[number];
+
+export const TXT_SURFACES = ["web", "app", "both"] as const;
+export type TxtSurface = (typeof TXT_SURFACES)[number];
+
+export interface AdsTxtLine {
+  domain: string;
+  accountId: string;
+  relationship: TxtRelationship;
+  certificationAuthorityId: string | null;
+  surface: TxtSurface;
+}
+
+const DOMAIN =
+  /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/;
+
+/** An IAB advertising-system domain, lowercase, no scheme. */
+export function adsTxtDomain(value: string): string | null {
+  const host = value.trim().toLowerCase().replace(/\.$/, "");
+  if (!DOMAIN.test(host)) return null;
+  return host;
+}
+
+export function coversSurface(entry: TxtSurface, wanted: "web" | "app"): boolean {
+  return entry === "both" || entry === wanted;
+}
+
+/**
+ * The file a crawler fetches.
+ *
+ * Comment-only when there are no rows, so the route still answers and does
+ * not claim authorized sellers the owner never listed.
+ */
+export function renderAdsTxtFile(
+  entries: AdsTxtLine[],
+  ownerDomain: string | null,
+): string {
+  const lines: string[] = [];
+  if (ownerDomain) lines.push(`OWNERDOMAIN=${ownerDomain}`);
+  for (const entry of entries) {
+    const fields = [entry.domain, entry.accountId, entry.relationship];
+    if (entry.certificationAuthorityId) fields.push(entry.certificationAuthorityId);
+    lines.push(fields.join(", "));
+  }
+  if (lines.length === 0) {
+    return "# No authorized digital sellers are listed.\n";
+  }
+  return `${lines.join("\n")}\n`;
+}

package/dist/template/src/modules/ads/blocks.tsx

@@ -0,0 +1,246 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// The ad slot, on the page (MASTER.md §4.16, §32, C9.18).
+//
+// §4.16: an ad position is "placed on the page as a block (§32), so where an
+// ad appears is content structure like everything else." The block therefore
+// carries one thing — the slot's code — and everything else about the
+// placement (which sizes, at which breakpoint, whether unsold space falls back
+// to a house promotion) lives on the slot, where changing it is one row rather
+// than every page the slot is on.
+//
+// The block moved here from `cms/blocks/surfaces.tsx` in C9.18. Its C9.17
+// shape carried its own house image, its own href and its own four size
+// numbers, which was a second, private notion of an ad living inside the page
+// tree: unlabelled, uncounted, unreviewed, and invisible to the campaign
+// screen the owner sells from. §4.16 forbids exactly that — "sponsored
+// placements are labelled in the markup … and there is no configuration that
+// removes the label" — so a house promotion is now a campaign like any other,
+// and this renders whatever `ads.serve` says is running.
+//
+// ── Why the server answers for every breakpoint ───────────────────────────
+//
+// §4.16 wants "one placement [to serve] a leaderboard on a laptop and a 320×50
+// on a phone without the owner building two pages", and the platform refuses
+// to derive anything from a visitor's device (`analytics/visitor.ts` is
+// explicit about it). So `ads.serve` answers once per breakpoint the slot
+// declares, all the answers go into the HTML, and CSS shows the one that
+// belongs. Nothing is sniffed, nothing arrives late, and the space is right
+// before a byte of JavaScript runs — which is the Core Web Vitals promise §36
+// makes on core's behalf.
+//
+// Counting the impression of the copy that is actually visible is C9.19: an
+// element hidden by a media query is never 50% viewable for a second, so the
+// MRC definition already does the disambiguation for us.
+import { z } from "zod";
+import { defineBlock } from "@/modules/cms/blocks/types";
+import type { ResolvedImage } from "@/core/media/service";
+import { AdBeacon } from "./AdBeacon";
+import { ThirdPartyConsent } from "./ThirdPartyConsent";
+import { isThirdPartyKind, providerMarkup, stampNonce, type ProviderSpec } from "./tags";
+
+const ANONYMOUS = { kind: "anonymous" } as const;
+
+type Breakpoint = "desktop" | "tablet" | "mobile";
+
+interface ServedFill {
+  breakpoint: Breakpoint;
+  width: number;
+  height: number;
+  needsThirdPartyConsent: boolean;
+  creative: {
+    id: string;
+    kind: "image" | "native" | "html_tag" | "provider";
+    assetId: string | null;
+    altText: string | null;
+    headline: string | null;
+    body: string | null;
+    ctaLabel: string | null;
+    tagHtml: string | null;
+    provider: unknown;
+    href: string;
+    label: "sponsored" | "house";
+    lineItemId: string;
+    campaignId: string;
+    slotId: string;
+  } | null;
+}
+
+interface Served {
+  lazy: boolean;
+  fills: Array<ServedFill & { image: ResolvedImage | null }>;
+}
+
+/** Narrow to wide, which is the order the visibility rules are built in. */
+const ORDER: Breakpoint[] = ["mobile", "tablet", "desktop"];
+
+/** Tailwind's breakpoints, as the min-width each of ours starts at. */
+const PREFIX: Record<Breakpoint, string | null> = {
+  mobile: null,
+  tablet: "md",
+  desktop: "lg",
+};
+
+/**
+ * Show each answer over exactly the widths it was chosen for.
+ *
+ * Derived from the breakpoints the slot actually declares rather than
+ * hardcoded, because most slots declare two. A slot with a desktop and a
+ * mobile format and nothing in between must not go blank on a tablet: the
+ * mobile answer runs until the desktop one starts.
+ */
+function visibility(breakpoint: Breakpoint, declared: Breakpoint[]): string {
+  const present = ORDER.filter((each) => declared.includes(each));
+  const index = present.indexOf(breakpoint);
+  const from = PREFIX[breakpoint];
+  const next = present[index + 1];
+  const until = next ? PREFIX[next] : null;
+  return [from ? `hidden ${from}:block` : "block", until ? `${until}:hidden` : ""]
+    .filter(Boolean)
+    .join(" ");
+}
+
+export const adSlot = defineBlock({
+  type: "adSlot",
+  labelKey: "cms.block.adSlot",
+  contexts: ["page", "chrome"],
+  // One field, because everything else is a property of the slot. An owner
+  // who wants a different size here is describing a different position.
+  schema: z.object({ code: z.string().trim().min(1).max(40) }),
+  starter: () => ({ code: "header" }),
+  resolve: async (props, ctx): Promise<Served | null> => {
+    const { serve } = await import("./service");
+    const served = await serve.call(
+      {
+        code: props.code,
+        path: ctx.path,
+        locale: ctx.locale,
+        anonId: ctx.visitorId,
+        thirdPartyConsent: ctx.thirdPartyConsent,
+      },
+      ANONYMOUS,
+    );
+    if (!served) return null;
+
+    // Dynamically imported so the block does not drag core/media into every
+    // bundle that only needed a heading — the same reason the image block does.
+    const { resolveImage } = await import("@/core/media/service");
+    const fills = await Promise.all(
+      served.fills.map(async (fill) => ({
+        ...fill,
+        image: fill.creative?.assetId
+          ? await resolveImage.call({ id: fill.creative.assetId }, ANONYMOUS)
+          : null,
+      })),
+    );
+    return { lazy: served.lazy, fills };
+  },
+  render: ({ resolved, ctx }) => {
+    // Nothing sold and no house promotion: render nothing at all. The reason
+    // §4.16 reserves space is that "an ad that arrives late and pushes the
+    // article down is a Core Web Vitals failure" — and nothing arrives late
+    // here, because the answer is in the server's HTML. An empty grey box on
+    // every page of an unsold site would be a cost paid for no benefit.
+    // A slot waiting on third-party consent still reserves the hole.
+    const filled = (resolved?.fills ?? []).filter(
+      (fill) => fill.creative !== null || fill.needsThirdPartyConsent,
+    );
+    if (!resolved || filled.length === 0) return null;
+    const declared = filled.map((fill) => fill.breakpoint);
+
+    return (
+      <aside aria-label={ctx.t("ads.label.region")} className="grid justify-items-center">
+        {filled.map((fill) => {
+          const creative = fill.creative;
+          const box = {
+            className:
+              "grid place-items-center overflow-hidden rounded-md border border-rule bg-surface",
+            style: { width: fill.width, height: fill.height },
+          };
+          return (
+            <div key={fill.breakpoint} className={visibility(fill.breakpoint, declared)}>
+              {/* The label, unconditionally. §4.16: "there is no configuration
+                  that removes the label", so there is no prop here to remove
+                  it with and no branch that omits it. */}
+              <p className="text-xs uppercase tracking-wide text-ink-muted">
+                {ctx.t(`ads.label.${creative?.label ?? "sponsored"}`)}
+              </p>
+              {fill.needsThirdPartyConsent || !creative ? (
+                <div {...box}>
+                  <ThirdPartyConsent returnTo={ctx.path || "/"} t={ctx.t} />
+                </div>
+              ) : isThirdPartyKind(creative.kind) ? (
+                <AdBeacon creativeId={creative.id} slotId={creative.slotId}>
+                  <div
+                    {...box}
+                    dangerouslySetInnerHTML={{
+                      __html: thirdPartyHtml(creative, fill, ctx.cspNonce ?? ""),
+                    }}
+                  />
+                </AdBeacon>
+              ) : (
+                <AdBeacon creativeId={creative.id} slotId={creative.slotId}>
+                  <a
+                    href={creative.href}
+                    // `sponsored` is the declaration §4.16 asks for; `nofollow`
+                    // because a paid link must not pass ranking either way; and
+                    // `noopener` because the destination is somebody else's site.
+                    rel="sponsored nofollow noopener"
+                    className={box.className}
+                    style={box.style}
+                  >
+                    {creative.kind === "image" && fill.image ? (
+                      <picture>
+                        {fill.image.sources.map((source) => (
+                          <source key={source.format} srcSet={source.srcset} type={source.type} />
+                        ))}
+                        <img
+                          src={fill.image.src}
+                          alt={creative.altText ?? fill.image.altText ?? ""}
+                          width={fill.width}
+                          height={fill.height}
+                          loading={resolved.lazy ? "lazy" : "eager"}
+                          decoding="async"
+                          className="h-full w-full object-contain"
+                        />
+                      </picture>
+                    ) : (
+                      <span className="grid gap-1 px-3 py-2 text-center">
+                        <span className="text-sm font-semibold text-ink">{creative.headline}</span>
+                        {creative.body ? (
+                          <span className="text-xs text-ink-muted">{creative.body}</span>
+                        ) : null}
+                        {creative.ctaLabel ? (
+                          <span className="text-xs font-semibold text-accent">
+                            {creative.ctaLabel}
+                          </span>
+                        ) : null}
+                      </span>
+                    )}
+                  </a>
+                </AdBeacon>
+              )}
+            </div>
+          );
+        })}
+      </aside>
+    );
+  },
+});
+
+function thirdPartyHtml(
+  creative: NonNullable<ServedFill["creative"]>,
+  fill: { width: number; height: number },
+  nonce: string,
+): string {
+  if (creative.kind === "provider") {
+    const parsed = creative.provider as ProviderSpec | null;
+    if (parsed?.network && parsed.unitPath) {
+      const markup = providerMarkup(parsed, fill, `fh-gpt-${creative.id}`);
+      if (markup) return stampNonce(markup, nonce);
+    }
+  }
+  return stampNonce(creative.tagHtml ?? "", nonce);
+}
+
+export default [adSlot];