create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,58 @@
+// oss: false
+/**
+ * create_booking — book one open slot for an attendee (#4416).
+ *
+ * The MCP twin of `POST /v1/schedule/book` (API↔MCP parity, root CLAUDE.md).
+ * Validates input via Zod, forwards through `@working-theory/api-client`, and
+ * shapes the response into the MCP output schema. No business logic and no
+ * credential — the scheduling key lives in apps/api.
+ *
+ * MCP-only anonymous write, the posture `subscribe_newsletter` and
+ * `request_callback` already established: an agent booking on a prospect's
+ * behalf has no session. Listed in `MCP_ONLY_TOOLS` in
+ * apps/mcp/__tests__/parity.test.ts.
+ *
+ * `slot_unavailable` is the interesting failure and is surfaced verbatim: a
+ * caller that races another booker should re-read availability and retry with
+ * a different slot, exactly as the `booker` section's UI does.
+ *
+ * Input:  { calLink, start, attendee: { name, email, timeZone?, notes? } }
+ * Output: { ok: true, data: { bookingId, start, end, meetingUrl? } }
+ *       | { ok: false, error: { kind } }
+ * Session/scope: none — anonymous, identity-blind (apps/mcp/CLAUDE.md).
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  createBookingInputSchema,
+  createBookingOutputSchema,
+  type CreateBookingInput,
+  type CreateBookingOutput,
+} from "@working-theory/validation";
+
+import { schedulingKindFromStatus } from "./list_availability.js";
+
+export { createBookingInputSchema, createBookingOutputSchema };
+export type { CreateBookingInput, CreateBookingOutput };
+
+export async function ailkCreateBooking(
+  input: CreateBookingInput,
+): Promise<CreateBookingOutput> {
+  const parsed = createBookingInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: parsed.error.issues[0]?.message ?? "Invalid input.",
+      },
+    };
+  }
+
+  const res = await apiClient.schedule.book(parsed.data);
+  if (!res.ok) {
+    return { ok: false, error: { kind: schedulingKindFromStatus(res.status) } };
+  }
+
+  return createBookingOutputSchema.parse({ ok: true, data: res.body });
+}

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

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * create_page — Paid-tier MCP tool for authoring a new content page.
  *

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

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * delete_page — Paid-tier MCP tool for removing a content page.
  *

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

@@ -0,0 +1,55 @@
+// oss: false
+/**
+ * get_event_meta — read one or more events' derived meta, no slots (#4633).
+ *
+ * The MCP twin of `GET /v1/schedule/event-meta` (API↔MCP parity, root
+ * CLAUDE.md). Exists for the same reason the route does: rendering an event's
+ * facts (title, duration, description, price) must not cost an availability
+ * window per event. Validates input via Zod, forwards through
+ * `@working-theory/api-client`, and shapes the response into the MCP output
+ * schema. No business logic and no credential — the scheduling key lives in
+ * apps/api.
+ *
+ * MCP-only — no web Server Action twin, same posture as `list_availability`:
+ * a tile-rendering page is an RSC calling the HTTP route via api-client, not
+ * a form. Listed in `MCP_ONLY_TOOLS` in apps/mcp/__tests__/parity.test.ts.
+ *
+ * Input:  { calLinks } — comma-separated `"<owner>/<event-slug>"` links
+ * Output: { ok: true, data: { events } } | { ok: false, error: { kind } }
+ * Session/scope: none — anonymous, identity-blind (apps/mcp/CLAUDE.md).
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  getEventMetaInputSchema,
+  getEventMetaOutputSchema,
+  type GetEventMetaInput,
+  type GetEventMetaOutput,
+} from "@working-theory/validation";
+
+import { schedulingKindFromStatus } from "./list_availability.js";
+
+export { getEventMetaInputSchema, getEventMetaOutputSchema };
+export type { GetEventMetaInput, GetEventMetaOutput };
+
+export async function ailkGetEventMeta(
+  input: GetEventMetaInput,
+): Promise<GetEventMetaOutput> {
+  const parsed = getEventMetaInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: parsed.error.issues[0]?.message ?? "Invalid input.",
+      },
+    };
+  }
+
+  const res = await apiClient.schedule.eventMeta(parsed.data);
+  if (!res.ok) {
+    return { ok: false, error: { kind: schedulingKindFromStatus(res.status) } };
+  }
+
+  return getEventMetaOutputSchema.parse({ ok: true, data: res.body });
+}

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

@@ -0,0 +1,61 @@
+/**
+ * get_flow — serve a validated flow config (#3956 D7).
+ *
+ * Validates input via Zod, forwards to GET /v1/flows/:slug via
+ * @working-theory/api-client, and shapes the response into the MCP output
+ * schema. No business logic — orchestration lives in apps/api (flow-engine.ts).
+ *
+ * Both routes are agent-callable (a chat agent can serve and walk a flow) —
+ * the input/output schemas are the SAME `@working-theory/validation` schemas
+ * the HTTP route itself validates against (D7 — no simplified MCP-only
+ * shape, unlike capture_lead's decoupled input). The `getFlowOutputSchema`
+ * export covers the success shape; the error branch below is composed
+ * locally (mcp-tool-catalog.ts can only import from `@working-theory/validation`,
+ * not from this file, so the catalog's outputShape stays the plain success
+ * schema — the same best-effort-documentation shape `read_content`'s
+ * `.nullable()` output already carries for its own not-found branch).
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  flowSlugSchema,
+  getFlowOutputSchema,
+  type FlowConfig,
+} from "@working-theory/validation";
+import { z } from "zod";
+
+export const getFlowInputSchema = z.object({
+  slug: flowSlugSchema,
+});
+
+export { getFlowOutputSchema };
+
+export type GetFlowInput = z.infer<typeof getFlowInputSchema>;
+
+export type AilkGetFlowOutput =
+  | { ok: true; data: FlowConfig }
+  | {
+      ok: false;
+      error:
+        | { kind: "invalid_input"; issues: unknown[] }
+        | { kind: "api_error"; status: number };
+    };
+
+export async function ailkGetFlow(
+  input: GetFlowInput,
+): Promise<AilkGetFlowOutput> {
+  const parsed = getFlowInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: { kind: "invalid_input", issues: parsed.error.issues },
+    };
+  }
+
+  const res = await apiClient.flows.get(parsed.data.slug);
+  if (!res.ok) {
+    return { ok: false, error: { kind: "api_error", status: res.status } };
+  }
+
+  return { ok: true, data: res.body };
+}

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

@@ -123,3 +123,28 @@ export {
   type ScaffoldInput,
   type ScaffoldOutput,
 } from "./scaffold.js";
+
+export {
+  getFlowInputSchema,
+  getFlowOutputSchema,
+  ailkGetFlow,
+  type GetFlowInput,
+  type AilkGetFlowOutput,
+} from "./get_flow.js";
+
+export {
+  submitFlowStepInputSchemaForTool,
+  submitFlowStepOutputSchema,
+  ailkSubmitFlowStep,
+  type SubmitFlowStepInput,
+  type AilkSubmitFlowStepOutput,
+} from "./submit_flow_step.js";
+
+// The scheduling tools (list_availability, get_event_meta, create_booking) are
+// deliberately NOT re-exported here, and neither are the content-write tools
+// (create_page, update_page, delete_page). Both groups are module-conditional
+// slice files (#5182): a re-export from this barrel is a static path into a
+// file the OSS strip removes, which reds the public tree's type-check. They are
+// reached only through `createMcpServer`'s per-module loader in ../server.ts.
+// The rule this barrel now follows: it re-exports exactly the tools no module
+// gate can remove.

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

@@ -0,0 +1,67 @@
+// oss: false
+/**
+ * list_availability — read open booking slots for an event (#4416).
+ *
+ * The MCP twin of `GET /v1/schedule/availability` (API↔MCP parity, root
+ * CLAUDE.md). Validates input via Zod, forwards through
+ * `@working-theory/api-client`, and shapes the response into the MCP output
+ * schema. No business logic and no credential: the scheduling key lives in
+ * apps/api, so an agent gets the same answer a browser does without ever
+ * being near it.
+ *
+ * MCP-only — there is no web Server Action twin. The `booker` section is a
+ * client island that calls the HTTP route directly (the ContactForm /
+ * StepFlow pattern), so this tool exists to give agents the same read, not to
+ * back a web form. Listed in `MCP_ONLY_TOOLS` in apps/mcp/__tests__/parity.test.ts.
+ *
+ * Input:  { calLink, from, to, timeZone? }
+ * Output: { ok: true, data: { event, slots } } | { ok: false, error: { kind } }
+ * Session/scope: none — anonymous, identity-blind (apps/mcp/CLAUDE.md).
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  listAvailabilityInputSchema,
+  listAvailabilityOutputSchema,
+  type ListAvailabilityInput,
+  type ListAvailabilityOutput,
+  type SchedulingErrorKind,
+} from "@working-theory/validation";
+
+export { listAvailabilityInputSchema, listAvailabilityOutputSchema };
+export type { ListAvailabilityInput, ListAvailabilityOutput };
+
+/**
+ * Map the route's HTTP status back to the shared error vocabulary, so an
+ * agent reads the SAME `kind` the route emitted rather than a bare number.
+ * Parity is on the code, not just the endpoint (apps/api/CLAUDE.md).
+ */
+export function schedulingKindFromStatus(status: number): SchedulingErrorKind {
+  if (status === 400) return "invalid_input";
+  if (status === 404) return "event_not_found";
+  if (status === 409) return "slot_unavailable";
+  if (status === 503) return "not_configured";
+  return "provider_error";
+}
+
+export async function ailkListAvailability(
+  input: ListAvailabilityInput,
+): Promise<ListAvailabilityOutput> {
+  const parsed = listAvailabilityInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: parsed.error.issues[0]?.message ?? "Invalid input.",
+      },
+    };
+  }
+
+  const res = await apiClient.schedule.availability(parsed.data);
+  if (!res.ok) {
+    return { ok: false, error: { kind: schedulingKindFromStatus(res.status) } };
+  }
+
+  return listAvailabilityOutputSchema.parse({ ok: true, data: res.body });
+}

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

@@ -69,6 +69,9 @@ export async function ailkPurchase(
     ...(input.quantity !== undefined && { quantity: input.quantity }),
     successUrl,
     cancelUrl,
+    ...(input.allowPromotionCodes !== undefined && {
+      allowPromotionCodes: input.allowPromotionCodes,
+    }),
   });
 
   if (!result.ok) {

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

@@ -0,0 +1,83 @@
+/**
+ * submit_flow_step — submit one step's answers (#3956 D7).
+ *
+ * Validates input via Zod, forwards to POST /v1/flows/:slug/steps via
+ * @working-theory/api-client, and shapes the response into the MCP output
+ * schema. No business logic — orchestration lives in apps/api (flow-engine.ts).
+ *
+ * The input shape composes `submitFlowStepInputSchema.shape` (D1's exact
+ * field validators — sessionId/stepKey/values/locale) with the `slug` the
+ * flat MCP input needs in place of the route's URL path segment. Same D7
+ * "reuse the route's own schemas" contract as get_flow — the catalog's
+ * outputShape stays the plain success schema for the same layering reason
+ * documented there.
+ */
+
+import { apiClient } from "@working-theory/api-client";
+import {
+  flowSlugSchema,
+  submitFlowStepInputSchema,
+  submitFlowStepOutputSchema,
+  type AeoScoreResult,
+} from "@working-theory/validation";
+import { z } from "zod";
+
+export const submitFlowStepInputSchemaForTool = z
+  .object({
+    slug: flowSlugSchema,
+    ...submitFlowStepInputSchema.shape,
+  })
+  .strict();
+
+export { submitFlowStepOutputSchema };
+
+export type SubmitFlowStepInput = z.infer<
+  typeof submitFlowStepInputSchemaForTool
+>;
+
+export type AilkSubmitFlowStepOutput =
+  | {
+      ok: true;
+      data: {
+        sessionId: string;
+        landed: string;
+        nextStepKey: string | null;
+        completed: boolean;
+        leadId?: string;
+        /** Server-derived segment (#3959 D6) — present from the segmentation-step response onward. */
+        segment?: string;
+        /** D9 (#4663) — present on the aeo_score step's own response AND on the completion response when the flow declares one. */
+        aeoScore?: AeoScoreResult;
+      };
+    }
+  | {
+      ok: false;
+      error:
+        | { kind: "invalid_input"; issues: unknown[] }
+        | { kind: "api_error"; status: number };
+    };
+
+export async function ailkSubmitFlowStep(
+  input: SubmitFlowStepInput,
+): Promise<AilkSubmitFlowStepOutput> {
+  const parsed = submitFlowStepInputSchemaForTool.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: { kind: "invalid_input", issues: parsed.error.issues },
+    };
+  }
+
+  const { slug, sessionId, stepKey, values, locale } = parsed.data;
+  const res = await apiClient.flows.submitStep(slug, {
+    ...(sessionId !== undefined && { sessionId }),
+    stepKey,
+    values,
+    ...(locale !== undefined && { locale }),
+  });
+  if (!res.ok) {
+    return { ok: false, error: { kind: "api_error", status: res.status } };
+  }
+
+  return { ok: true, data: res.body };
+}

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

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * update_page — Paid-tier MCP tool for revising an existing content page.
  *

package/templates/apps/mcp/tsconfig.json

@@ -7,13 +7,5 @@
     "types": ["node"]
   },
   "include": ["src"],
-  "exclude": ["node_modules", "dist"],
-  "references": [
-    { "path": "../../packages/aeo" },
-    { "path": "../../packages/api-client" },
-    { "path": "../../packages/content-adapters" },
-    { "path": "../../packages/metadata" },
-    { "path": "../../packages/schema" },
-    { "path": "../../packages/validation" }
-  ]
+  "exclude": ["node_modules", "dist"]
 }

package/templates/apps/web/.env.example

@@ -15,6 +15,19 @@ CONTENT_BACKEND=mdx
 # Override the on-disk content root. Defaults to <repo-root>/content.
 # AILK_CONTENT_ROOT=
 
+# =============================================================================
+# apps/api base URL (browser-side lead-capture forms) — #3965
+# =============================================================================
+# apps/web and apps/api are separate origins in every deployment shape that
+# doesn't front them with a rewrite/proxy. A browser-side block (e.g.
+# NewsletterFormInline, packages/ui/src/blocks/NewsletterFormInline.tsx)
+# posting a root-relative action (e.g. /v1/leads/subscribe) resolves it
+# against apps/web's OWN origin -- not apps/api's -- unless this is set.
+# Same convention as apps/workspace/lib/client-api.ts's identically-named var.
+# Should be apps/api's origin with NO trailing slash (a single trailing
+# slash is stripped before joining, but keep this clean regardless).
+# NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
+
 # =============================================================================
 # Better Auth (apps/web)
 # =============================================================================
@@ -45,3 +58,34 @@ CONTENT_BACKEND=mdx
 # Better Stack heartbeat URL — when set, pingHeartbeat() POSTs on cron/startup.
 # Unset means the heartbeat util is a no-op (apps/web/lib/observability/better-stack.ts).
 # BETTER_STACK_HEARTBEAT_URL=
+
+# =============================================================================
+# Scheduling — the scheduling module's booking page (#4633)
+# =============================================================================
+# Which event `/schedule` books, as "<owner>/<event-slug>" — the path of the
+# provider's own public booking page. Read server-side in
+# app/[locale]/schedule/page.tsx and handed to the `booker` section, which
+# sends it back to apps/api's /v1/schedule/* routes to name the event.
+#
+# Unset is a supported state: `/schedule` 404s, exactly as if the scheduling
+# module were not installed.
+#
+# NOT a credential, and deliberately NOT a NEXT_PUBLIC_ variable — the API key
+# it pairs with (CAL_API_KEY) lives in apps/api and this app never reads it, so
+# keeping the whole scheduling config surface server-read is what makes that
+# boundary checkable rather than merely intended.
+# SCHEDULING_CAL_LINK=owner/event-slug
+#
+# SPLIT-ORIGIN DEPLOYS NEED A CSP EXTENSION. The booker calls this site's
+# /v1/schedule/* routes from the browser, resolved through
+# NEXT_PUBLIC_AILK_API_URL. Set that variable and the calls become
+# cross-origin, but the baseline CSP in security-headers.config.ts is
+# `connect-src 'self' https://api.stripe.com` — so the browser blocks them and
+# the booker shows its generic unavailable state with no explanation. Pass the
+# API origin through the customer extension `buildHeaders` accepts:
+#
+#   buildHeaders({ csp: { "connect-src": ["'self'", "<your apps/api origin>"] } })
+#
+# Deploying apps/web and apps/api on one origin (leaving
+# NEXT_PUBLIC_AILK_API_URL unset) needs no extension — the calls stay
+# same-origin and 'self' already covers them.

package/templates/apps/web/CLAUDE.md

@@ -64,6 +64,34 @@ Don't ship a page after one render. The expected per-page loop:
    - Fix mismatches. Be specific in self-review: "heading is 32px, reference shows 24px", not "looks off."
    - Repeat until no visible differences and no responsive issues at any of the four breakpoints.
 
+## Conversational intake (contact page)
+
+The contact page (`apps/web/app/[locale]/contact/`) consumes
+`ConversationalIntake` — a chat-style intake block + deterministic engine
+from `@working-theory/ui`, unmodified. The block/engine contract (six-behavior
+mapping, `NextTurn`/`IntakeScript` shapes, the v1/v2 seam) is documented in
+`packages/ui/src/blocks/conversational-intake/README.md`; read that first.
+
+This app's specific wiring: `ConversationalIntakeWrapper.tsx` hosts the
+block and owns submission + fallback; `intake-script.ts` supplies the script
+via `buildContactIntakeScript(copy)`, whose question ids (`name` / `message`
+/ `email`) double as the field-mapping contract into `submitLeadInputSchema`;
+`intake-analytics.ts` fires the `"intake-turn-abandonment"` event once per
+turn (turn index + status only, never answer text) from the block's
+`getThinkingDelayMs` override seam. Completion submits through the existing
+`captureLeadAction`; Skip or a failed submit falls back to the existing
+`<ContactForm/>`, prefilled with whatever was already captured — a lead is
+never silently lost.
+
+**Note:** the contact page currently mounts the wrapper alongside
+`renderPage`'s output (`page.tsx`), not as a page-level swap. A downstream
+Positionary consumer pattern that DID swap the whole page was corrected
+under #4577 (decision D71 — the intake belongs behind the hero CTA's
+lightbox gate; landed in PR #4583 via `packages/ui/src/sections/FormLightbox.tsx`
+and `HeroIntakeContext.tsx`, spec `docs/specs/4577-intake-lightbox-correction-spec.md`).
+Don't take a whole-page mount as the pattern to replicate; the lightbox-gate
+seam is the canonical embedding shape.
+
 ## AEO & performance
 
 - Static rendering is the default. Don't introduce client rendering without a reason.