create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/plan-offerings.ts

@@ -0,0 +1,125 @@
+/**
+ * The workspace's offerings as plan keys (#8514 D9) — moved here unchanged
+ * from `routes/workspaces/plan.ts` by #8757 D4, so the magnet PATCH's
+ * save-time offering check and the lead route's submit-time re-check
+ * (`services/magnet-completion.ts`) read the same list `GET …/plan-offerings`
+ * serves.
+ *
+ * Two sources (#8934, spec
+ * docs/specs/8934-re-source-the-plan-offerings-spec.md D1–D4):
+ *
+ * - A connected workspace with the `commerce` claim lists its Offerings
+ *   shown set (`getWorkspaceShownSet`, read from the database and never from
+ *   Stripe — contract T7): one item per sellable Price, in the reader's
+ *   order, `key` the Price's full lookup key (G5), `name` the product name
+ *   and its billing word, `type` the product's group. The page list is not
+ *   consulted.
+ * - An unclaimed workspace, or one the reader answers `null` for (no
+ *   workspace, no connection, no selection), lists its OWN Service then
+ *   Product pages: `key` is the page slug's last segment when it is an
+ *   offering key (else the page is skipped), the first page per key wins, at
+ *   most 200; `name` is the page title. Off the database content adapter only
+ *   the default workspace has content (`workspaceContentAdapter`), so every
+ *   other workspace reads `[]`.
+ *
+ * Never throws: a failed read answers `{ failed }` with a fixed word or the
+ * error's class name only, so a caller can tell "none listed" from "could not
+ * tell" — a failure is never a pass. `LicenseUndetermined` (the licence could
+ * not be read, so the Offerings services may not be called — 8876 D10),
+ * `OfferingsSnapshotExpired` and `OfferingsSnapshotEmpty` (the rows say what
+ * is shown, but no current snapshot says which keys it sells).
+ *
+ * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
+ * entry, because the never-gate lead route reaches it.
+ */
+import {
+  PLAN_OFFERINGS_MAX,
+  planOfferingSchema,
+  type PlanOfferingItem,
+} from "@working-theory/validation";
+
+import { resolveCommerceClaim } from "../lib/require-commerce-claim.js";
+
+import { getWorkspaceShownSet } from "./offerings/index.js";
+import { workspaceContentAdapter } from "./public-site-resolver.js";
+
+/** `planOfferingItemSchema.name`'s bound, in UTF-16 units. */
+const NAME_MAX = 200;
+
+/** The workspace's offerings as plan keys (D3). */
+export async function listPlanOfferings(
+  workspaceId: string,
+): Promise<PlanOfferingItem[] | { failed: string }> {
+  try {
+    const claim = await resolveCommerceClaim();
+    if (claim === "undetermined") return { failed: "LicenseUndetermined" };
+    if (claim === "unclaimed") return await pageOfferings(workspaceId);
+    const shown = await getWorkspaceShownSet(workspaceId);
+    if (shown === null) return await pageOfferings(workspaceId);
+    if (shown.state === "expired") return { failed: "OfferingsSnapshotExpired" };
+    if (shown.state === "empty") return { failed: "OfferingsSnapshotEmpty" };
+    return collect(
+      shown.offerings.flatMap((offering) =>
+        offering.prices.map((price) => ({
+          key: price.lookupKey,
+          name: planOfferingName(offering.name, price.interval),
+          type: offering.ailkGroup,
+        })),
+      ),
+    );
+  } catch (error) {
+    // The error's class name only — never its message, which may name a slug.
+    return { failed: error instanceof Error ? error.name : typeof error };
+  }
+}
+
+/** The workspace's Service then Product pages as plan keys (D4, #8514 D9). */
+async function pageOfferings(workspaceId: string): Promise<PlanOfferingItem[]> {
+  const adapter = await workspaceContentAdapter(workspaceId);
+  if (!adapter) return [];
+  const [services, products] = await Promise.all([
+    adapter.listPages("Service"),
+    adapter.listPages("Product"),
+  ]);
+  const typed = [
+    ...services.map((page) => ({ page, type: "service" as const })),
+    ...products.map((page) => ({ page, type: "product" as const })),
+  ];
+  return collect(
+    typed.map(({ page, type }) => ({
+      key: page.slug.split("/").filter(Boolean).pop() ?? "",
+      name: page.title.trim().slice(0, NAME_MAX),
+      type,
+    })),
+  );
+}
+
+/** The guards both sources share: a valid key, a name, each key once, at most 200. */
+function collect(candidates: PlanOfferingItem[]): PlanOfferingItem[] {
+  const offerings: PlanOfferingItem[] = [];
+  const seen = new Set<string>();
+  for (const { key, name, type } of candidates) {
+    if (offerings.length >= PLAN_OFFERINGS_MAX) break;
+    if (!planOfferingSchema.safeParse(key).success || name === "" || seen.has(key)) continue;
+    seen.add(key);
+    offerings.push({ key, name, type });
+  }
+  return offerings;
+}
+
+/**
+ * `<product name> (<word>)`, the word from the Price's interval (D2). Whole
+ * code points are dropped from the end of the product name until the name
+ * fits `NAME_MAX` units, so a surrogate pair is never split; the word is
+ * always kept.
+ */
+function planOfferingName(productName: string, interval: "month" | "year" | null): string {
+  const word = interval === "month" ? "Monthly" : interval === "year" ? "Annual" : "One-time";
+  const suffix = ` (${word})`;
+  let name = "";
+  for (const point of productName) {
+    if (name.length + point.length + suffix.length > NAME_MAX) break;
+    name += point;
+  }
+  return name + suffix;
+}

package/templates/apps/api/src/services/public-site-resolver.ts

@@ -62,13 +62,16 @@
  * prefix — and never reaches the wire.
  *
  * THE FLOWS ROUTES' WORKSPACE (#7844 D1). `resolveCallerWorkspace` below is
- * the one function the five `/v1/flows` routes resolve their workspace with:
- * a spoke resolves to its own workspace (`viaSpoke: true`), a keyless call to
- * the `AILK_SITE_ID` alias exactly as before, and anything else to
- * `unresolved` with one of two reasons, `spoke-refused` or `alias-unresolved`.
- * The reasons are for `request.log` only; the routes answer both the same
- * way. It lives here rather than under `routes/flows/` because the two flows
- * route files sit in different module slices, and this file is base tree.
+ * the one function the five `/v1/flows` routes (and the open deliverable)
+ * resolve their workspace with: a spoke resolves to its own workspace
+ * (`viaSpoke: true`), a keyless call through branch 2's one-workspace
+ * predicate (#9145 — never the `AILK_SITE_ID` alias, so every anonymous
+ * route answers the same workspace for the same deployment), and anything
+ * else to `unresolved` with one of two reasons, `spoke-refused` or
+ * `ambiguous`. The reasons are for `request.log` only; the routes answer both
+ * the same way. It lives here rather than under `routes/flows/` because the
+ * two flows route files sit in different module slices, and this file is
+ * base tree.
  */
 import {
   resolvedAdapterKind,
@@ -246,14 +249,22 @@ export async function resolveCallerSite(
  * `request.log` only; the routes answer both reasons the same way.
  */
 export type CallerWorkspace =
-  | { kind: "resolved"; workspaceId: string; viaSpoke: boolean }
-  | { kind: "unresolved"; reason: "spoke-refused" | "alias-unresolved" };
+  | {
+      kind: "resolved";
+      workspaceId: string;
+      viaSpoke: boolean;
+      /** #8771 D3 — set exactly when `viaSpoke` is true: the registered spoke's id. */
+      spokeId?: string;
+    }
+  | { kind: "unresolved"; reason: "spoke-refused" | "ambiguous" };
 
 /**
  * Resolve the workspace a `/v1/flows` request serves. A spoke resolves to its
- * own workspace; a keyless call to the `AILK_SITE_ID` alias, exactly as the
- * flows routes did before #7844; a refused caller to nothing. There is no
- * fallback: a spoke never reaches the alias workspace (D5).
+ * own workspace; a keyless call through `resolveDefaultWorkspaceId`, the
+ * predicate `resolvePublicWorkspace` uses (#9145) — on any content adapter,
+ * since a flow is a database row whatever serves the pages; a refused caller
+ * to nothing. There is no fallback: a spoke never reaches the default
+ * workspace (D5).
  *
  * Calls `resolveCallerSite` with no options, so a failed hub-status read on a
  * keyless call rejects (#7844 C1).
@@ -270,13 +281,14 @@ export async function resolveCallerWorkspace(
       kind: "resolved",
       workspaceId: caller.workspaceId,
       viaSpoke: true,
+      spokeId: caller.spokeId,
     };
   }
   // Deferred, like every database import in this file.
-  const { resolveSiteWorkspaceId } = await import("../lib/site.js");
-  const workspaceId = await resolveSiteWorkspaceId();
+  const { resolveDefaultWorkspaceId } = await import("./default-tenant.js");
+  const workspaceId = await resolveDefaultWorkspaceId();
   return workspaceId === null
-    ? { kind: "unresolved", reason: "alias-unresolved" }
+    ? { kind: "unresolved", reason: "ambiguous" }
     : { kind: "resolved", workspaceId, viaSpoke: false };
 }
 

package/templates/apps/mcp/CLAUDE.md

@@ -77,32 +77,32 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback`
 **Maintenance (2):** `audit`, `create_project`
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
-**Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071)
+**Booking (4):** `list_availability`, `get_event_meta`, `list_meetings`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071). `list_meetings` (#8843 D5) twins `GET /v1/schedule/meetings`: it takes no argument and returns the site's Live meetings — slug, visibility, position and whether each can be booked, plus a bookable one's calLink, title, length, description and price; `private` means unlisted, not secret
 
-### Why the parity test counts 20 and a keyless server registers 19
+### Why the parity test counts 21 and a keyless server registers 20
 
-- **20 in the `TOOLS` array / parity test**: the `TOOLS` array in
-  `packages/metadata/src/mcp-tool-catalog.ts` defines 20 anonymous tools; the
-  parity test counts that full array. It also holds the fifteen signed-in
+- **21 in the `TOOLS` array / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 21 anonymous tools; the
+  parity test counts that full array. It also holds the eighteen signed-in
   workspace tools (#3591), which no anonymous view returns — see § The
   signed-in workspace surface below.
-- **19 registered on a KEYLESS deployment, 20 on a commerce-claimed one**
+- **20 registered on a KEYLESS deployment, 21 on a commerce-claimed one**
   (#5971): `createMcpServer` (`apps/mcp/src/server.ts`) registers
   `getMcpToolRegistrations()` minus `OSS_DISABLED_TOOLS` (now empty), minus
   module-gated tools whose module is off, minus any `addon`-tagged tool whose
   claim this deployment does not hold. `start_purchase` carries
   `addon: "commerce"`, so it is the one entry whose presence depends on the
-  licence — 19 without the claim, 20 with it.
-- **19 free anonymous tools**: since #5853 retired the three content-write
+  licence — 20 without the claim, 21 with it.
+- **20 free anonymous tools**: since #5853 retired the three content-write
   tools, every registered tool remains anonymous — call-time gating checks a
-  licence claim, never an identity. The five carrying `tier: "pro"`
+  licence claim, never an identity. The six carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
-  `create_booking`) are gated at REGISTRATION **and at call time** (#7315):
+  `list_meetings`, `create_booking`) are gated at REGISTRATION **and at call time** (#7315):
   each needs its module, and each catalog row names the licence `feature:`
   that entitles it. `start_purchase` is gated at call time by both this
   server-wide gate and its own Gate 2 in `tools/purchase.ts`.
   `MCP_FEATURE_GATE_MODE` (`packages/metadata`) decides what an unheld
-  feature does. In `"warn"` mode (this release) the five register on module
+  feature does. In `"warn"` mode (this release) the six register on module
   presence alone, and the boot (`bootMcp()`) logs one warning (stderr) per tool
   served without its feature. In `"refuse"` mode (the next release) they
   also need the deployment's licence to hold the feature, and
@@ -126,10 +126,14 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
 - **apps/mcp checks only the key's shape.** The key is attached as the SDK's `req.auth` for that
   request alone and reaches a tool as `extra.authInfo.token`. apps/api is the one place it is
   checked, and its tenant guard and the caller's clamped role decide every answer.
-- **Fifteen tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
+- **Eighteen tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
   and `modulesAnyOf` (the modules any one of which registers the tool — its twin route's gate):
   `get_agent_context`, the four message tools, the three submission tools, the three
-  application tools and (#8514) the two People notes tools, `get_person_notes` and
+  listing application tools (#9137: `list_listing_applications`, `get_listing_application`,
+  `decide_listing_application` — a `ProjectListing` row, never a job application, which is a Job
+  application magnet's submission; the pre-rename `list_inbox_applications`,
+  `get_inbox_application` and `decide_inbox_application` stay registered for one release as
+  deprecated aliases of the same handlers, each description opening `Deprecated: use …`) and (#8514) the two People notes tools, `get_person_notes` and
   `set_person_notes` — the team's private note on one client, which an agent reads and writes
   only with the `member-pieces-manage` grant; `set_person_notes` requires the `ifUpdatedAt` it
   read and is refused `notes_changed` when someone saved since — and (#8516) the two proposals
@@ -219,7 +223,11 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-14 — #8516: the signed-in workspace surface is fifteen tools — `list_proposals` and `create_proposal` (`tools/proposals.ts`) twin `GET`/`POST /v1/workspaces/:workspaceId/people/:personId/proposals` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-18 — #9137: the three listing application tools are `list_listing_applications`, `get_listing_application` and `decide_listing_application`, and their pre-rename names stay one release as deprecated aliases — the signed-in workspace surface is eighteen tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-18 — #8843 PR A: `list_meetings` twins `GET /v1/schedule/meetings` — Booking is four tools, the counts are 21 in TOOLS, 20 registered keyless and 21 commerce-claimed, and six tools carry `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/server.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-14 — #8516: the signed-in workspace surface is fifteen tools — `list_proposals` and `create_proposal` (`tools/proposals.ts`) twin `GET`/`POST /v1/workspaces/:workspaceId/people/:personId/proposals` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-13 — #8514: the signed-in workspace surface is thirteen tools — `get_person_notes` and `set_person_notes` (`tools/person_notes.ts`) twin `GET`/`PUT /v1/workspaces/:workspaceId/people/:personId/notes` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/mcp/__tests__/catalog-drift.test.ts

@@ -105,9 +105,14 @@ type GateMode = NonNullable<McpCatalogOptions["featureGate"]>;
 
 type McpFeature = NonNullable<McpToolCatalogEntry["feature"]>;
 
-/** The five licence-feature tools, by the feature that entitles them. */
+/** The six licence-feature tools, by the feature that entitles them. */
 const FEATURE_TOOLS: Record<McpFeature, readonly string[]> = {
-  scheduling: ["list_availability", "get_event_meta", "create_booking"],
+  scheduling: [
+    "list_availability",
+    "get_event_meta",
+    "list_meetings",
+    "create_booking",
+  ],
   "flows-deliverables": ["get_flow", "submit_flow_step"],
 };
 
@@ -318,14 +323,14 @@ describe.each([
       const bootNames = Object.keys(
         registeredToolsOf(createMcpServer()),
       ).sort();
-      // Both counts below are of the served catalog — the full catalog (20 at
+      // Both counts below are of the served catalog — the full catalog (21 at
       // boot, 14 after the re-read) minus this seam's UNSERVED_MCP_TOOLS (#8665).
       expect(bootNames).toEqual(
         servedCatalog(bootOptions)
           .map((t) => t.name)
           .sort(),
       );
-      expect(bootNames).toHaveLength(20 - UNSERVED_MCP_TOOLS.length);
+      expect(bootNames).toHaveLength(21 - UNSERVED_MCP_TOOLS.length);
 
       startMcpClaimRefresh({ checkLicense: resolving({ features: [] }) });
       await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);