create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/lib/site.ts

@@ -1,254 +0,0 @@
-/**
- * @file site.ts
- * @description The current-site resolution helper (#3958 §3.2), extended by
- * #6155 (spec D2/D5/D6, ownership brief
- * `docs/internal/decisions/workspace-owns-data-surfaces-render.md`) with the
- * ALIAS -> WORKSPACE resolution the brief requires: `currentSiteId()`'s
- * env-var alias is resolved to a real `workspaces.id` ONCE at startup,
- * memoized, and ASSERTED — so a misconfigured deployment refuses to boot
- * instead of serving empty lists (AC-5).
- *
- * `currentSiteId()` is extracted verbatim from `routes/flows/index.ts`'s
- * private `currentSiteId()` so the flow-preset seed
- * (`services/flow-engine.ts` -> `bin/seed-presets.ts`) resolves the SAME
- * site id the `/v1/flows/*` routes resolve — a seed hard-coding `"default"`
- * would write presets the API cannot find whenever `AILK_SITE_ID` is set (a
- * silent, environment-dependent 404). Behavior is byte-identical to the
- * pre-extraction helper: same env var, same fallback, same call sites.
- * `currentSiteId()` stays SYNCHRONOUS and byte-identical (#6155 D5) — the
- * new resolution is async (it reads the database), and making
- * `currentSiteId()` async would edit every one of its dozen non-test call
- * sites across routes/services/bins, including the two route files NFR1
- * requires to stay byte-unchanged.
- *
- * The Checkout site stamp (#7868, spec D1/D2): `SITE_STAMP_KEY`,
- * `siteStamp()` and `isForeignSiteStamp()` are the one definition of the
- * `metadata.site` key every hub-created Checkout session carries and the
- * Stripe webhook reads. The stamp is `currentSiteId()`, so writer and reader
- * cannot disagree inside one deployment. A session is foreign only when its
- * stamp is a non-empty string other than `currentSiteId()`; an unstamped
- * session is the hub's own (roadmap D4).
- */
-import { resolvedAdapterKind } from "@working-theory/content-adapters";
-import {
-  DEFAULT_WORKSPACE_ID,
-  DEFAULT_WORKSPACE_SLUG,
-  resolveSentinelWorkspaceRow,
-} from "@working-theory/database/tenancy";
-import { logger } from "@working-theory/observability";
-
-import { prisma } from "./prisma.js";
-
-export function currentSiteId(): string {
-  return process.env.AILK_SITE_ID ?? "default";
-}
-
-/** The Checkout session metadata key naming the site a session belongs to (#7868 D1). */
-export const SITE_STAMP_KEY = "site";
-
-/**
- * The metadata a hub-created Checkout session carries (#7868 D1/D2):
- * `{ [SITE_STAMP_KEY]: currentSiteId() }`, read per call. Empty when the alias
- * is `""` (an `AILK_SITE_ID` set to the empty string), so Stripe is never sent
- * an empty value (SEC-7868-5) — and the webhook treats that deployment's
- * sessions as unstamped, exactly as today.
- */
-export function siteStamp(): Record<string, string> {
-  const site = currentSiteId();
-  return site === "" ? {} : { [SITE_STAMP_KEY]: site };
-}
-
-/**
- * True only when `metadata[SITE_STAMP_KEY]` is a non-empty string that is not
- * `currentSiteId()` — a session another site on the shared Stripe account
- * opened (#7868 D2). An absent, empty or non-string stamp is the hub's own
- * (roadmap D4: Payment Links, invoices, the portal and pre-stamp sessions
- * carry none). Exact, case-sensitive comparison, as the spokes' own check.
- */
-export function isForeignSiteStamp(
-  metadata: Record<string, string> | null | undefined,
-): boolean {
-  const stamp: unknown = metadata?.[SITE_STAMP_KEY];
-  return typeof stamp === "string" && stamp !== "" && stamp !== currentSiteId();
-}
-
-/**
- * The resolved workspace id, memoized after the first SUCCESSFUL resolution
- * ("resolves the alias once at startup", ownership brief § Layer 2 / #6155
- * D5). `null` is never cached — a failed resolution has already thrown from
- * `build()` (D6), so there is no negative-cache case to hold, and a later
- * retry (a test, a re-seeded database) is free to resolve on its next call.
- */
-let cachedWorkspaceId: string | null = null;
-
-/**
- * Resolves `currentSiteId()`'s alias to a real `workspaces.id`, per the
- * two-and-only-two rule (#6155 spec D2):
- *
- *  1. The literal alias `"default"` resolves to the seeded sentinel
- *     workspace — `DEFAULT_WORKSPACE_ID` — IFF that row exists and hangs
- *     off the sentinel Organization
- *     (`@working-theory/database/tenancy`'s `resolveSentinelWorkspaceRow`,
- *     which carries NO `workspace.count()` gate — unlike
- *     `resolveDefaultWorkspaceRow`, whose single-tenancy meaning this unit
- *     must NOT widen; see D2's "why a NEW resolver"). This is what lets a
- *     correctly-configured MULTI-workspace deployment that has not pinned
- *     `AILK_SITE_ID` still resolve — `resolveDefaultWorkspaceRow`'s count
- *     gate would refuse it.
- *  2. Any OTHER alias resolves ONLY by exact `workspaces.id` equality.
- *  3. Anything that resolves neither way is `null` — never a fallback,
- *     never a guess (`assertSiteAliasResolves` below is what turns a `null`
- *     into a startup refusal).
- *
- * Memoized (D5): the SECOND call issues zero Prisma queries once the first
- * has resolved successfully. `__resetSiteWorkspaceCacheForTests()` clears
- * the memo for test isolation.
- */
-export async function resolveSiteWorkspaceId(): Promise<string | null> {
-  if (cachedWorkspaceId !== null) {
-    return cachedWorkspaceId;
-  }
-
-  const resolved = await resolveWorkspaceIdForAlias(currentSiteId());
-  if (resolved !== null) {
-    cachedWorkspaceId = resolved;
-  }
-  return resolved;
-}
-
-/**
- * The two-and-only-two resolution rule (#6155 spec D2), extracted so a
- * write site holding an EXPLICIT `siteId` parameter (not necessarily
- * `currentSiteId()` — e.g. a `ProjectListing` resolved through its own
- * `SiteListingConfig.siteId`) can resolve it the same way
- * `resolveSiteWorkspaceId()` resolves the env alias, without going through
- * that function's `currentSiteId()`-only memo (#6254 spec D1a): the write
- * paths that still stamp a raw, unresolved alias resolve it first, through
- * this resolver, before it ever reaches a `workspace_id NOT NULL` /
- * `CHECK (workspace_id = site_id)` column.
- *
- *  1. The literal alias `"default"` resolves to the seeded sentinel
- *     workspace IFF that row exists (`resolveSentinelWorkspaceRow`).
- *  2. Any OTHER alias resolves ONLY by exact `workspaces.id` equality.
- *  3. Anything that resolves neither way is `null` — never a fallback,
- *     never a guess.
- *
- * Not memoized — callers passing a per-request `siteId` would otherwise
- * share a cache keyed on nothing. `resolveSiteWorkspaceId()` above keeps
- * its own single-value memo for the hot, env-alias-only path.
- */
-export async function resolveWorkspaceIdForAlias(
-  alias: string,
-): Promise<string | null> {
-  if (alias === DEFAULT_WORKSPACE_SLUG) {
-    const row = await resolveSentinelWorkspaceRow(prisma);
-    return row?.id ?? null;
-  }
-  const row = await prisma.workspace.findUnique({ where: { id: alias } });
-  return row ? alias : null;
-}
-
-/**
- * Asserts `currentSiteId()`'s alias resolves to a real workspace — the
- * misconfigured-deployment refusal AC-5 requires (D6). Awaited from
- * `build()` (`apps/api/src/server.ts`), beside the two startup assertions
- * already there; `apps/api/src/index.ts` already catches, logs and
- * `process.exit(1)`s on a `build()` throw, so this is a loud refusal to
- * start with no new exit-path code.
- *
- * THE CARVE-OUT (D6): when the alias genuinely CANNOT be checked — or NEED
- * not be — this logs a warning and returns rather than throwing: a
- * "database-less dev boot," never a misconfiguration. Three arms feed it, and
- * ALL THREE are presence checks made BEFORE any query is attempted — never a
- * catch around a query that already ran, which would just as readily swallow a
- * genuine connection failure as it would an absent delegate (code-review
- * finding, #6155):
- *
- *  0. **The content adapter is not `database`** (#6228) — the one arm that is
- *     "need not," not "cannot." The alias→workspace resolution exists so a
- *     database-backed content read has a workspace to read within; under
- *     `mdx` or `projection` NO read takes a `workspaceId` at all, so the
- *     assertion guards nothing and its only effect is to require a REACHABLE
- *     database of a deployment that never queries one. That is the #6228
- *     defect: `create-ailk`'s scaffold check sets a placeholder
- *     `DATABASE_URL` (presence is all `validateConfig()` wants, and Prisma
- *     connects lazily), so arm 1 does not fire, and the generated MDX site
- *     crashed at boot on `Can't reach database server`. Read through
- *     `resolvedAdapterKind()` — the ONE switch over `CONTENT_ADAPTER`
- *     (`packages/content-adapters/src/resolve.ts`) — rather than a second,
- *     drifting read of the env var here.
- *
- *  1. **No `DATABASE_URL` configured** — the literal `requireDb()` guard
- *     `apps/api/src/services/flow-engine.ts` uses for the flow services:
- *     presence, not reachability. (`apps/api/src/config/index.ts`'s own
- *     eager `validateConfig()` refuses a **production** `apps/api` boot with
- *     `DATABASE_URL` unset before `build()` is ever reached; outside
- *     production a real boot starts database-less (#6482), so this arm is
- *     reachable from a real dev boot as well as from any other caller of
- *     `build()`.)
- *  2. **`prisma.workspace.findUnique` is not even a function** — the case
- *     that surfaced this arm: `apps/api`'s shared/global prisma mocks
- *     (`lib/__mocks__/prisma-client.js`, the module-map-level double every
- *     test gets; the many hand-rolled hoisted factories in route/service
- *     suites that never touch tenancy) predate this unit and declare no
- *     `workspace` delegate at all — the FIRST real Prisma read `build()`
- *     itself has ever issued. Widening dozens of unrelated test files'
- *     prisma doubles to add a resolving `workspace.findUnique` has a far
- *     larger and harder-to-audit blast radius than making THIS one
- *     assertion resilient to "the check itself is unavailable." A resolution
- *     that could not even be ATTEMPTED is not a misconfiguration to fail
- *     loudly about — but a resolution that WAS attempted and threw (a real
- *     connection error, a permissions error, a bug in the resolver) is
- *     exactly the class D6/AC-5 exist to surface, so it is deliberately NOT
- *     caught here: it propagates out of `resolveSiteWorkspaceId()` and
- *     crashes the boot, the same as any other unhandled `build()` throw.
- *
- * A reachable database with no matching workspace is the failure case, and
- * it throws. A reachable database that ERRORS mid-query throws too — that is
- * NOT the carve-out, it is the misconfiguration AC-5 asks to fail loudly
- * about.
- */
-export async function assertSiteAliasResolves(): Promise<void> {
-  const adapterKind = resolvedAdapterKind();
-  if (adapterKind !== "database") {
-    logger.warn(
-      { alias: currentSiteId(), contentAdapter: adapterKind },
-      "[site] content adapter is not `database` — skipping the site-alias workspace assertion (no read takes a workspaceId on this boot)",
-    );
-    return;
-  }
-
-  if (!process.env.DATABASE_URL) {
-    logger.warn(
-      { alias: currentSiteId() },
-      "[site] DATABASE_URL not set — skipping the site-alias workspace assertion (database-less boot)",
-    );
-    return;
-  }
-
-  if (typeof prisma.workspace?.findUnique !== "function") {
-    logger.warn(
-      { alias: currentSiteId() },
-      "[site] prisma.workspace is unavailable — skipping the site-alias workspace assertion (the resolution could not be attempted)",
-    );
-    return;
-  }
-
-  const resolved = await resolveSiteWorkspaceId();
-  if (resolved !== null) {
-    return;
-  }
-
-  const alias = currentSiteId();
-  throw new Error(
-    `AILK_SITE_ID="${alias}" names no workspace. The site alias must be an ` +
-      'existing workspaces.id, or the literal "default" (the seeded ' +
-      `sentinel workspace ${DEFAULT_WORKSPACE_ID}). Run \`pnpm db:seed\`, or ` +
-      "set AILK_SITE_ID to a workspace this database holds.",
-  );
-}
-
-/** Test-only: clears the memoized resolution (#6155 D5). */
-export function __resetSiteWorkspaceCacheForTests(): void {
-  cachedWorkspaceId = null;
-}

package/templates/apps/api/src/lib/slice-load.ts

@@ -1,90 +0,0 @@
-/**
- * Slice-module load boundary (#5334 D4).
- *
- * Every paid-module SLICE in `apps/api` is reached through an indirect dynamic
- * `import()` — a specifier the call site never writes as a literal, because
- * `tsc` would then resolve it and the OSS strip would break (#5182 D1). #5304
- * moved those specifiers onto module-level constants, the one shape that is
- * simultaneously unresolvable to `tsc` and traceable to `@vercel/nft`, so the
- * files reach a Vercel deployment.
- *
- * WHAT THIS FILE IS FOR. That shape is correct for the deploy path the scaffold
- * ships, and it cannot be made to work under a BUNDLER. esbuild bundles a
- * dynamic `import()` iff its argument is a string literal at the call site —
- * exactly the predicate `tsc` resolves on, and exactly the one #5182 D1
- * requires be false. So in a bundled build the specifier survives verbatim and
- * Node resolves it against the BUNDLE OUTPUT directory rather than the source
- * module's: `"./list.js"`, written in `routes/project-listings/index.ts`,
- * becomes `dist/list.js` and does not exist. `build()` throws during
- * CONSTRUCTION, so every route 500s rather than one.
- *
- * The failure is otherwise silent on every channel: esbuild emits no warning
- * for the imports it declines to bundle, and a consuming frontend degrades to
- * an empty list and still answers 200. `salessmyth/samhenry` spent nine hours
- * on it. This boundary is what turns that into a one-line diagnosis — it does
- * not make bundling work, because nothing in this file could.
- *
- * WHY IT TAKES A THUNK AND NOT A SPECIFIER. `loadSlice("./list.js")` doing the
- * `import()` in here would be the obvious signature and would silently undo
- * #5304. `enumerateSliceSpecifiers()` treats a file as an "indirect file" only
- * if it carries a dynamic `import()` with a non-literal argument; move the call
- * out of the callers and they stop qualifying, their specifier constants stop
- * being candidates, and `check-slice-reachability.ts` passes vacuously over an
- * empty set. Worse, `@vercel/nft` constant-propagates `WORKSPACES_INDEX` into
- * `import(WORKSPACES_INDEX)` only because the constant and the call sit in one
- * module — hoist the call and there is nothing to propagate, so every slice
- * file goes untraced and #5304's outage returns with its own gate green.
- *
- * So the `import()` stays at the call site, in the caller's module, and this
- * function only awaits the thunk and interprets the failure.
- *
- * Gated by `scripts/check-bundled-build-diagnoses.ts`, which bundles `apps/api`
- * and asserts that the boot fails WITH this diagnostic rather than without one.
- */
-
-/**
- * Node reports an unresolvable ESM specifier as `ERR_MODULE_NOT_FOUND` and an
- * unresolvable CJS one as `MODULE_NOT_FOUND`. A bundle can produce either,
- * since a bundled graph mixes both.
- */
-const MODULE_NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
-
-function isModuleNotFound(error: unknown): boolean {
-  const code = (error as { code?: unknown } | null | undefined)?.code;
-  return typeof code === "string" && MODULE_NOT_FOUND_CODES.has(code);
-}
-
-/**
- * Await a slice module's loader thunk, turning an unresolvable module into a
- * diagnosis instead of a bare `ERR_MODULE_NOT_FOUND` on a path that never
- * existed.
- *
- * Anything that is not a module-resolution failure is rethrown UNTOUCHED — the
- * same object, not a wrapper. A slice that throws while evaluating is a real
- * bug in the slice and must keep its own stack and type.
- *
- * @param specifier the module specifier the thunk imports, for the message.
- *   Every call site already has it in scope, so nothing is enumerated here.
- * @param load the caller's own `() => import(CONST)` thunk. Must close over a
- *   constant in the CALLER's module — see the file header.
- */
-export async function loadSlice(
-  specifier: string,
-  load: () => Promise<unknown>,
-): Promise<unknown> {
-  try {
-    return await load();
-  } catch (error) {
-    if (!isModuleNotFound(error)) throw error;
-    throw new Error(
-      `AILK slice module '${specifier}' could not be resolved at runtime. ` +
-        `This throws during server construction, so every route fails, not one. Two causes produce it:\n` +
-        `  1. The module was compiled but not SHIPPED — the deploy-time file tracer did not emit it (#5304). ` +
-        `Check with \`pnpm slice-reachability:check\`.\n` +
-        `  2. This build was BUNDLED. apps/api does not support bundling (#5334): a bundler resolves this ` +
-        `specifier against the bundle's own output directory rather than its source module's, and esbuild ` +
-        `leaves it unbundled without a warning. See apps/api/CLAUDE.md § Deploy path.`,
-      { cause: error },
-    );
-  }
-}

package/templates/apps/api/src/lib/spoke-store.ts

@@ -1,180 +0,0 @@
-/**
- * The hub's spoke registry — its ONE data-access boundary (#7532, spec
- * docs/specs/7532-a-spoke-s-public-reads-spec.md D1, D2, D7).
- *
- * A spoke is a separately deployed site that calls this API server-to-server,
- * bound to exactly one workspace. It authenticates with a hub-minted key sent
- * in `x-ailk-spoke-key`. This file is the only one that names `prisma.spoke`.
- *
- * THE KEY IS NEVER STORED. The row keeps the lowercase hex SHA-256 of the
- * trimmed key (`credentialHash`) and its first 17 characters
- * (`credentialPrefix`: `ailk_spk_` plus 8 random ones) so an operator can
- * recognise a key in a list. A fast digest is enough: the key carries 256
- * bits of entropy, so a lookup by its unique digest leaks nothing usable.
- *
- * WHAT A KEY PROVES. It identifies a deployed SITE, not a person: every
- * anonymous visitor of that site, and every agent using its `apps/mcp`, acts
- * through it. It grants what the site's anonymous visitors can already do on
- * the hub — read that workspace's enabled meeting types and public content,
- * and write leads and bookings into it. One opt-in addition (#7876 D3): while
- * the hub's operator sets `AILK_SPOKE_FLOW_SEED`, a key may also write its
- * own workspace's flow definitions (`PUT /v1/flows/:slug/definition`),
- * limited to the blocks the site's own flow pages render — never emails,
- * deliverables, pricing, registers or listings.
- *
- * Three kinds of caller, kept apart:
- *   - the public resolver (`services/public-site-resolver.ts`) calls
- *     `hashSpokeKey`, `findSpokeByKeyHash` and `hasRegisteredSpoke` only;
- *   - the operator CLI (`bin/spokes.ts`) calls `registerSpoke`, `revokeSpoke`
- *     and `listSpokes` (and, through `lib/hub-sign-in-store.ts`'s
- *     `registerSignInClient`, `findSpokeById`). No route imports them;
- *   - the operator flow-copy service (`services/flow-copy.ts`, run only by
- *     `bin/flows-copy.ts`) calls `hasLiveSpokeForWorkspace` only (#7844 D7);
- *   - the hub sign-in service (`services/hub-sign-in.ts`) and the auth
- *     preHandler's hub-credential branch call `hashSpokeKey`,
- *     `findSpokeByKeyHash` and `findSpokeById` (#7894 D5, D6).
- *
- * Nothing here caches a row: a revocation takes effect on the next request
- * (NFR4). The resolver holds `hasRegisteredSpoke`'s answer itself (#7633 D3).
- */
-import { createHash, randomBytes } from "node:crypto";
-
-import { prisma } from "./prisma.js";
-
-/** Every spoke key starts with this, so a leaked one is recognisable. */
-export const SPOKE_KEY_PREFIX = "ailk_spk_";
-
-/** How much of the key the row keeps for recognition: the prefix + 8 characters. */
-const CREDENTIAL_PREFIX_LENGTH = SPOKE_KEY_PREFIX.length + 8;
-
-/** A new key: `ailk_spk_` + 32 random bytes in base64url (52 characters). */
-export function mintSpokeKey(): string {
-  return `${SPOKE_KEY_PREFIX}${randomBytes(32).toString("base64url")}`;
-}
-
-/** The stored digest of a key: lowercase hex SHA-256 of the TRIMMED value. */
-export function hashSpokeKey(key: string): string {
-  return createHash("sha256").update(key.trim()).digest("hex");
-}
-
-export interface SpokeLookupRow {
-  id: string;
-  workspaceId: string;
-  revokedAt: Date | null;
-}
-
-/** The one read the resolver makes: a `findUnique` by digest. */
-export async function findSpokeByKeyHash(
-  credentialHash: string,
-): Promise<SpokeLookupRow | null> {
-  return prisma.spoke.findUnique({
-    where: { credentialHash },
-    select: { id: true, workspaceId: true, revokedAt: true },
-  });
-}
-
-/**
- * The sign-in client's read of its own spoke (#7894 D3, D5): a spoke is
- * `Spoke.id`-bound to its `OAuthClient`, and the codes route — which has a
- * cookie session and no spoke key — checks the spoke is still unrevoked by id.
- */
-export async function findSpokeById(
-  id: string,
-): Promise<(SpokeLookupRow & { name: string }) | null> {
-  return prisma.spoke.findUnique({
-    where: { id },
-    select: { id: true, workspaceId: true, revokedAt: true, name: true },
-  });
-}
-
-/**
- * Whether this deployment is a hub: its registry holds at least one spoke,
- * revoked or not (#7633 D1). Reads every time; the resolver holds the
- * answer (D3).
- */
-export async function hasRegisteredSpoke(): Promise<boolean> {
-  const row = await prisma.spoke.findFirst({ select: { id: true } });
-  return Boolean(row);
-}
-
-/**
- * Whether at least one unrevoked spoke is bound to this workspace (#7844 D7):
- * the flow-copy tool's target check. Selects `id` only.
- */
-export async function hasLiveSpokeForWorkspace(
-  workspaceId: string,
-): Promise<boolean> {
-  const row = await prisma.spoke.findFirst({
-    where: { workspaceId, revokedAt: null },
-    select: { id: true },
-  });
-  return Boolean(row);
-}
-
-// ── Operator functions — `bin/spokes.ts` only ────────────────────────────────
-
-export interface SpokeListRow {
-  id: string;
-  name: string;
-  workspaceId: string;
-  credentialPrefix: string;
-  createdAt: Date;
-  revokedAt: Date | null;
-}
-
-const SPOKE_LIST_SELECT = {
-  id: true,
-  name: true,
-  workspaceId: true,
-  credentialPrefix: true,
-  createdAt: true,
-  revokedAt: true,
-} as const;
-
-export type RegisterSpokeResult =
-  | { ok: true; spoke: SpokeListRow; key: string }
-  | { ok: false; reason: "workspace-not-found" };
-
-/**
- * Register a spoke bound to one existing workspace. The returned `key` is the
- * only copy that will ever exist: the caller prints it once.
- */
-export async function registerSpoke(params: {
-  workspaceId: string;
-  name: string;
-}): Promise<RegisterSpokeResult> {
-  const workspace = await prisma.workspace.findUnique({
-    where: { id: params.workspaceId },
-    select: { id: true },
-  });
-  if (!workspace) return { ok: false, reason: "workspace-not-found" };
-
-  const key = mintSpokeKey();
-  const spoke = await prisma.spoke.create({
-    data: {
-      workspaceId: params.workspaceId,
-      name: params.name,
-      credentialHash: hashSpokeKey(key),
-      credentialPrefix: key.slice(0, CREDENTIAL_PREFIX_LENGTH),
-    },
-    select: SPOKE_LIST_SELECT,
-  });
-  return { ok: true, spoke, key };
-}
-
-/** Revoke one spoke. `false` when no unrevoked spoke has that id. */
-export async function revokeSpoke(id: string): Promise<boolean> {
-  const { count } = await prisma.spoke.updateMany({
-    where: { id, revokedAt: null },
-    data: { revokedAt: new Date() },
-  });
-  return count === 1;
-}
-
-/** Every spoke, newest first. Never selects the credential digest. */
-export async function listSpokes(): Promise<SpokeListRow[]> {
-  return prisma.spoke.findMany({
-    select: SPOKE_LIST_SELECT,
-    orderBy: { createdAt: "desc" },
-  });
-}