create-stitchkit 0.3.3 → 0.4.0

package/dist/cli.js

@@ -2,9 +2,207 @@
 // @bun
 
 // src/cli.ts
-import { basename as basename3, resolve as resolve2 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { basename as basename3, join as join2, resolve as resolve2 } from "path";
 var {spawn } = globalThis.Bun;
 
+// src/identity.ts
+import { basename } from "path";
+
+// ../core/src/declaration.ts
+import { z } from "zod";
+var PROJECT_DECLARATION_SCHEMA_VERSION = 1;
+var MACHINE_PATTERNS = [
+  [/:\/\//, "an absolute address"],
+  [/^\/\//, "a protocol-relative host"],
+  [/^[~]/, "a home-relative path"],
+  [/^[A-Za-z]:[\\/]/, "a Windows drive path"],
+  [/\\/, "a Windows path separator"],
+  [/(?:^|[\s=:])\d{1,3}(?:\.\d{1,3}){3}(?![\d.])/, "an IP address"],
+  [/(?:^|[\s=])[A-Za-z][\w.-]*:\d{2,5}(?![\w.])/, "a host and port"]
+];
+function namesAMachine(value) {
+  for (const [pattern, reason] of MACHINE_PATTERNS) {
+    if (pattern.test(value))
+      return reason;
+  }
+  return;
+}
+function refuseMachineNames(label) {
+  return (schema) => schema.refine((value) => namesAMachine(value) === undefined, {
+    error: (issue) => `${label} names a machine \u2014 ${namesAMachine(String(issue.input)) ?? "a value of the deployment"} is supplied by the deployment, not written in the code`
+  });
+}
+var ProjectSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and single hyphens (for example: talk-control)");
+var ProjectDescriptionSchema = z.record(refuseMachineNames("A locale tag")(z.string().min(1)), refuseMachineNames("A description")(z.string().trim().min(1))).refine((value) => Object.keys(value).length > 0, "Describe the project in at least one locale");
+var ProjectIdentitySchema = z.object({
+  slug: ProjectSlugSchema,
+  name: refuseMachineNames("A project name")(z.string().trim().min(1).max(80)),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Use a semantic version such as 0.1.0"),
+  description: ProjectDescriptionSchema
+}).strict();
+var RepositoryPathSchema = z.string().min(1).refine((value) => !value.startsWith("/"), "Use a path relative to the repository root").refine((value) => namesAMachine(value) === undefined, {
+  error: (issue) => `A path may not contain ${namesAMachine(String(issue.input)) ?? "a machine name"}`
+}).refine((value) => !value.split("/").includes(".."), "A path may not climb out of the repository");
+var BindingVariableSchema = z.string().regex(/^[A-Z][A-Z0-9_]*$/, "Name an environment variable, for example API_PORT");
+var ProjectListenerSchema = z.object({
+  portVariable: BindingVariableSchema,
+  bindVariable: BindingVariableSchema,
+  readinessPath: refuseMachineNames("A readiness path")(z.string().startsWith("/", "Readiness is a path, for example /health"))
+}).strict();
+var ProjectRunModeSchema = z.enum(["development", "production"]);
+var PROJECT_SCRIPT_LAUNCHERS = [
+  [/^(?:bun|npm|pnpm|yarn)$/, /^run$/],
+  [/^deno$/, /^task$/],
+  [/^(?:npx|bunx|pnpx)$/, null]
+];
+function launchesAScript(executable, firstArgument) {
+  for (const [runner, verb] of PROJECT_SCRIPT_LAUNCHERS) {
+    if (!runner.test(executable))
+      continue;
+    if (verb === null)
+      return true;
+    if (firstArgument !== undefined && verb.test(firstArgument))
+      return true;
+  }
+  return false;
+}
+var PORT_FLAG = /^(?:-p|-{1,2}(?:port|listen))$/i;
+var CommandPartSchema = refuseMachineNames("A command part")(z.string().min(1)).refine((value) => !value.startsWith("/"), "A command part may not be an absolute path \u2014 paths are relative to the source").refine((value) => !/^[^=\s]+=/.test(value), "A command part may not carry an inline value \u2014 write the flag and its value as separate arguments, so the value is checked like every other one");
+var CommandArgumentsSchema = z.array(CommandPartSchema).refine((args) => args.every((value, index) => !(/^\d{1,5}$/.test(value) && PORT_FLAG.test(args[index - 1] ?? ""))), "A number after a port flag is a port \u2014 name the variable that carries it and let the role read it");
+var ProjectCommandSchema = z.object({
+  executable: CommandPartSchema,
+  args: CommandArgumentsSchema
+}).strict();
+var ProjectRoleCommandSchema = ProjectCommandSchema.refine((value) => !launchesAScript(value.executable, value.args[0]), "Start the role process itself, not a script runner: a launcher between the supervisor and the role duplicates the shutdown signal and forces the drain").refine((value) => !value.args.includes("--filter"), "A workspace filter puts a launcher between the supervisor and the role, and the shutdown signal never reaches it");
+var ProjectRoleSchema = z.object({
+  name: ProjectSlugSchema,
+  workingDirectory: RepositoryPathSchema.optional(),
+  commands: z.record(ProjectRunModeSchema, ProjectRoleCommandSchema),
+  listener: ProjectListenerSchema.optional(),
+  drainFloorMs: z.number().int().nonnegative()
+}).strict();
+var ProjectBuildInputSchema = z.object({
+  name: ProjectSlugSchema,
+  path: RepositoryPathSchema,
+  digest: z.string().regex(/^sha256:[0-9a-f]{64}$/, 'Use a lowercase sha256 digest, as "sha256:<64 hex>"')
+}).strict();
+var ProjectBuildSchema = z.object({
+  command: ProjectCommandSchema,
+  artifacts: z.array(RepositoryPathSchema).min(1),
+  inputs: z.array(ProjectBuildInputSchema).optional()
+}).strict().refine((build) => {
+  const names = (build.inputs ?? []).map((input) => input.name);
+  return new Set(names).size === names.length;
+}, "Two build inputs share a name \u2014 a failure could then name either of them");
+var ProjectRequirementPhaseSchema = z.enum(["release", "start"]);
+var ProjectRequirementSchema = z.object({
+  name: ProjectSlugSchema,
+  phases: z.array(ProjectRequirementPhaseSchema).min(1)
+}).strict();
+var ProjectMigrationsSchema = z.object({
+  engine: refuseMachineNames("A migration engine name")(z.string().min(1).max(64)),
+  root: RepositoryPathSchema,
+  lockfile: RepositoryPathSchema
+}).strict();
+var ProjectReleaseSchema = z.object({ migrations: ProjectMigrationsSchema.optional() }).strict();
+var ProjectEnvShapeSchema = z.enum(["string", "integer", "boolean", "url", "enum"]);
+var ProjectEnvVariableSchema = z.object({
+  name: BindingVariableSchema,
+  shape: ProjectEnvShapeSchema,
+  required: z.boolean(),
+  members: z.array(refuseMachineNames("An enum member")(z.string().min(1))).min(1).optional()
+}).strict().refine((value) => value.shape === "enum" === (value.members !== undefined), "An enum variable lists its members; every other shape has none");
+var ProjectDeclarationSchema = z.object({
+  schemaVersion: z.literal(PROJECT_DECLARATION_SCHEMA_VERSION),
+  kind: z.enum(["library", "application"]),
+  identity: ProjectIdentitySchema,
+  roles: z.array(ProjectRoleSchema),
+  build: ProjectBuildSchema.optional(),
+  requires: z.array(ProjectRequirementSchema),
+  release: ProjectReleaseSchema,
+  env: z.object({ variables: z.array(ProjectEnvVariableSchema) }).strict()
+}).strict().refine((value) => value.kind === "application" ? value.roles.length > 0 : value.roles.length === 0, "An application declares at least one role; a library declares none").refine((value) => new Set(value.roles.map((role) => role.name)).size === value.roles.length, "Role names must be unique").refine((value) => new Set(value.requires.map((entry) => entry.name)).size === value.requires.length, "Name each requirement once and list its phases").refine((value) => value.requires.every((entry) => new Set(entry.phases).size === entry.phases.length), "List each phase of a requirement once").refine((value) => new Set(value.env.variables.map((entry) => entry.name)).size === value.env.variables.length, "Declare each environment variable once").refine((value) => listenerBindingProblem(value) === undefined, {
+  error: (issue) => listenerBindingProblem(issue.input) ?? "Listener bindings are inconsistent"
+});
+function isListenerBindingSubject(value) {
+  return typeof value === "object" && value !== null && "roles" in value && "env" in value;
+}
+function listenerBindingProblem(value) {
+  if (!isListenerBindingSubject(value))
+    return;
+  const shapes = new Map(value.env.variables.map((entry) => [entry.name, entry.shape]));
+  for (const role of value.roles) {
+    const listener = role.listener;
+    if (!listener)
+      continue;
+    if (listener.portVariable === listener.bindVariable) {
+      return `Role "${role.name}" points its port and its bind address at the same variable "${listener.portVariable}"`;
+    }
+    const expected = [
+      [listener.portVariable, "integer"],
+      [listener.bindVariable, "string"]
+    ];
+    for (const [name, shape] of expected) {
+      const declared = shapes.get(name);
+      if (declared === undefined) {
+        return `Role "${role.name}" listens on "${name}", which env.variables does not declare \u2014 a deployment reading this cannot know it has to supply it`;
+      }
+      if (declared !== shape) {
+        return `Role "${role.name}" listens on "${name}", declared as "${declared}" where a ${shape} is needed`;
+      }
+    }
+  }
+  return;
+}
+var VersionProbeSchema = z.object({ schemaVersion: z.unknown() }).loose();
+function parseProjectDeclaration(source) {
+  const probe = VersionProbeSchema.safeParse(source);
+  const declared = probe.success ? probe.data.schemaVersion : undefined;
+  if (declared !== undefined && declared !== PROJECT_DECLARATION_SCHEMA_VERSION) {
+    throw new Error(`Project declaration schema version ${JSON.stringify(declared)} is not supported \u2014 ` + `this build understands version ${PROJECT_DECLARATION_SCHEMA_VERSION}.`);
+  }
+  return ProjectDeclarationSchema.parse(source);
+}
+
+// src/identity.ts
+var APP_IDENTITY_PATH = "packages/config/src/app-identity.generated.ts";
+function renderAppIdentityModule(identity) {
+  return `// GENERATED FILE \u2014 do not edit.
+//
+// Rendered from \`project.json\` by \`scripts/declaration.ts\`.
+//
+// Identity ONLY, inlined rather than imported, because this is the part of the
+// declaration a browser may know. Importing the whole declaration from a client
+// component would put role commands, working directories, build artifact paths,
+// the migration lockfile and every environment variable name into the browser
+// bundle \u2014 the same mistake as publishing internal topology from a status
+// endpoint, made from the other side.
+
+export const appIdentity = ${JSON.stringify(identity, undefined, 2)};
+`;
+}
+function displayNameFromSlug(slug) {
+  return slug.split("-").map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
+}
+function createApplicationIdentity(destination, displayName) {
+  const slug = ProjectSlugSchema.parse(basename(destination));
+  const name = displayName?.trim() || displayNameFromSlug(slug);
+  return ProjectIdentitySchema.parse({
+    slug,
+    name,
+    version: "0.1.0",
+    description: {
+      en: `${name} is a production application built with Stitchkit.`,
+      ru: `${name} \u2014 production-\u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u043D\u0430 Stitchkit.`
+    }
+  });
+}
+function withIdentity(declaration, identity) {
+  const copied = parseProjectDeclaration(declaration);
+  return parseProjectDeclaration({ ...copied, identity });
+}
+
 // src/options.ts
 var HELP = `Create a production-shaped Stitchkit application.
 
@@ -62,38 +260,6 @@ import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { basename as basename2, dirname, extname, join, parse, relative, resolve, sep } from "path";
 import { z as z2 } from "zod";
-
-// src/identity.ts
-import { basename } from "path";
-import { z } from "zod";
-var ApplicationSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and single hyphens (for example: talk-control)");
-var ApplicationIdentitySchema = z.object({
-  slug: ApplicationSlugSchema,
-  name: z.string().trim().min(1).max(80),
-  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Use a semantic version such as 0.1.0"),
-  description: z.object({
-    en: z.string().trim().min(1),
-    ru: z.string().trim().min(1)
-  })
-});
-function displayNameFromSlug(slug) {
-  return slug.split("-").map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
-}
-function createApplicationIdentity(destination, displayName) {
-  const slug = ApplicationSlugSchema.parse(basename(destination));
-  const name = displayName?.trim() || displayNameFromSlug(slug);
-  return ApplicationIdentitySchema.parse({
-    slug,
-    name,
-    version: "0.1.0",
-    description: {
-      en: `${name} is a production application built with Stitchkit.`,
-      ru: `${name} \u2014 production-\u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u043D\u0430 Stitchkit.`
-    }
-  });
-}
-
-// src/scaffold.ts
 var TEXT_EXTENSIONS = new Set([
   ".cjs",
   ".css",
@@ -231,8 +397,13 @@ async function scaffoldProject(templateDirectory, destination, options = {}) {
     if (options.overlayDirectory) {
       await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(options.overlayDirectory));
     }
-    await writeFile(join(resolvedDestination, "app.config.json"), `${JSON.stringify(identity, undefined, 2)}
+    const declarationPath = join(resolvedDestination, "project.json");
+    const declaration = withIdentity(JSON.parse(await readFile(declarationPath, "utf8")), identity);
+    await writeFile(declarationPath, `${JSON.stringify(declaration, undefined, 2)}
 `);
+    const identityPath = join(resolvedDestination, APP_IDENTITY_PATH);
+    await mkdir(dirname(identityPath), { recursive: true });
+    await writeFile(identityPath, renderAppIdentityModule(declaration.identity));
     const manifestPath = join(resolvedDestination, "package.json");
     const manifest = RootManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
     await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: identity.slug }, undefined, 2)}
@@ -284,14 +455,10 @@ Created ${options.displayName ?? basename3(destination)}${mode}
     process.stdout.write(`  bun run dev
 
 `);
-    process.stdout.write(`Web: http://localhost:3210
-`);
-    process.stdout.write(`API: http://localhost:3211
-`);
-    process.stdout.write(`MCP: http://localhost:3211/mcp
-`);
-    process.stdout.write(`OpenAPI: http://localhost:3211/openapi.json
+    for (const line of await roleAddresses(destination)) {
+      process.stdout.write(`${line}
 `);
+    }
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -303,6 +470,31 @@ Created ${options.displayName ?? basename3(destination)}${mode}
 if (import.meta.main) {
   process.exitCode = await run(Bun.argv.slice(2));
 }
+async function roleAddresses(destination) {
+  try {
+    const declaration = parseProjectDeclaration(JSON.parse(await readFile2(join2(destination, "project.json"), "utf8")));
+    const environment = readEnvironmentExample(await readFile2(join2(destination, ".env.example"), "utf8"));
+    const host = environment.BIND_HOST ?? "127.0.0.1";
+    return declaration.roles.flatMap((role) => {
+      const port = role.listener && environment[role.listener.portVariable];
+      if (!role.listener || !port)
+        return [];
+      return [`${role.name}: http://${host}:${port}${role.listener.readinessPath}`];
+    });
+  } catch {
+    return [];
+  }
+}
+function readEnvironmentExample(source) {
+  const values = {};
+  for (const line of source.split(`
+`)) {
+    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line.trim());
+    if (match?.[1])
+      values[match[1]] = match[2] ?? "";
+  }
+  return values;
+}
 export {
   run
 };

package/examples/repository/_env.example.append

@@ -1,3 +1,24 @@
+# The web role reaches the API role internally, and forwards the browser's
+# same-origin `/api/…` calls to it. This one is required.
+INTERNAL_API_URL=http://127.0.0.1:3211
+
+# The realtime socket, and ONLY it. A WebSocket upgrade does not survive the
+# route handler that forwards `/api`, so two roles on two loopback ports must
+# name the socket's origin even though their HTTP is already same-origin.
+# Behind one routing layer that forwards `/socket.io`, leave this unset.
+PUBLIC_REALTIME_ORIGIN=http://127.0.0.1:3211
+
+# The browser origin the API role admits — for HTTP and for the realtime
+# handshake alike. Needed here because the socket above is cross-origin.
+CORS_ORIGIN=http://127.0.0.1:3210
+
+# THE CROSS-ORIGIN HTTP VARIANT — unset, and unnecessary for this example.
+# Set it only for a frontend that dials the API role itself instead of calling
+# its own `/api`: separate hostnames with nothing in front of them. Setting it
+# changes nothing on its own; switching is one import in
+# packages/frontend/src/lib/api/queries.ts. See lib/api/cross-origin.ts.
+# PUBLIC_API_ORIGIN=https://api.example
+
 GITHUB_REPOSITORY=max-listov/stitchkit
 GITHUB_CACHE_TTL_SECONDS=900
 # Optional. Defaults to the public GitHub API and supports GitHub Enterprise.

package/examples/repository/packages/backend/src/domain/repository/github-cache.ts

@@ -1,5 +1,5 @@
 import { env } from '@app/config';
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { RepositoryVisibility } from '@app/db';
 import type { RepositorySnapshot } from '@app/shared';
 import { z } from 'zod';
@@ -81,7 +81,7 @@ const snapshotStore: RepositorySnapshotStore = {
 function githubHeaders(): Headers {
   const headers = new Headers({
     Accept: 'application/vnd.github+json',
-    'User-Agent': appIdentity.slug,
+    'User-Agent': appDeclaration.identity.slug,
     'X-GitHub-Api-Version': '2026-03-10',
   });
   if (env.GITHUB_TOKEN) headers.set('Authorization', `Bearer ${env.GITHUB_TOKEN}`);

package/examples/repository/packages/backend/src/surface.ts

@@ -6,7 +6,7 @@ import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
   const socket = await createSocketIOServer({
-    cors: { origin: env.CORS_ORIGIN },
+    cors: { origin: env.CORS_ORIGIN ?? [] },
   });
   const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
   const repositoryService = createRepositoryService((snapshot) =>

package/examples/repository/packages/config/src/features.ts

@@ -1,6 +1,23 @@
 import { z } from 'zod';
 
 export const featureServerSchema = {
+  // The web role dereferences this on every proxied request and on every server
+  // render, so it TIGHTENS from optional to required. Declared optional, a
+  // deployment reading project.json would supply nothing and every request would
+  // throw — the declaration would be derived and still wrong, which is the one
+  // failure the derivation exists to prevent.
+  INTERNAL_API_URL: z.url(),
+  // Deliberately NOT tightened. The browser talks to its own origin by default
+  // (`frontend/src/lib/api/client.ts`), so a single-origin deployment supplies
+  // none of these. They are the price of a browser that leaves that origin, and
+  // only a deployment that has that case should be made to pay it.
+  //   PUBLIC_REALTIME_ORIGIN — where the socket connects, when no routing layer
+  //     forwards `/socket.io`. A WebSocket upgrade cannot be proxied by the
+  //     route handler that forwards `/api`, so this one is separate on purpose.
+  //   PUBLIC_API_ORIGIN — where the browser dials the API role over HTTP, for
+  //     the cross-origin variant. Inert until the import in `queries.ts` moves.
+  //   CORS_ORIGIN — the API role's allow-list, needed once the browser is
+  //     genuinely cross-origin for either of the two.
   GITHUB_API_URL: z.url().default('https://api.github.com'),
   GITHUB_REPOSITORY: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
   GITHUB_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(900),

package/examples/repository/packages/frontend/src/app/[locale]/page.tsx

@@ -1,10 +1,10 @@
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
 import { LocaleSchema } from '@/i18n/locales';
-import { createServerRepositoryApi } from '@/lib/api/client';
 import { useRepository } from '@/lib/api/queries';
+import { createServerRepositoryApi } from '@/lib/api/server-client';
 import { getQueryClient } from '@/lib/query-client';
 import { createPageMetadata } from '@/lib/seo/metadata';
 import { StarterPage } from './starter-page';
@@ -34,8 +34,8 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
   return (
     <HydrationBoundary state={dehydrate(queryClient)}>
       <StarterPage
-        applicationName={appIdentity.name}
-        applicationDescription={appIdentity.description[appLocale]}
+        applicationName={appDeclaration.identity.name}
+        applicationDescription={appDeclaration.identity.description[appLocale]}
         heroTitle={t('heroTitle')}
         catalogueLabel={t('ui')}
         locale={appLocale}

package/examples/repository/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -57,7 +57,7 @@ const architecture = [
   },
 ];
 
-export function StarterPage({
+export async function StarterPage({
   applicationName,
   applicationDescription,
   heroTitle,
@@ -71,7 +71,7 @@ export function StarterPage({
     name: SITE_NAME,
     applicationCategory: 'DeveloperApplication',
     operatingSystem: 'Web',
-    url: absoluteSiteUrl(`/${locale}`),
+    url: await absoluteSiteUrl(`/${locale}`),
     description: homeSeo.description,
   };
 

package/examples/repository/packages/frontend/src/app/api/[...path]/route.ts

@@ -0,0 +1,66 @@
+import { internalApiUrl } from '@/lib/api/place';
+
+/**
+ * The default shape: the browser talks to its OWN origin, and the web role
+ * forwards to the API role.
+ *
+ * This is what makes the example's client a plain module constant. A browser
+ * that dials the API role directly needs that role's public address, which is a
+ * property of the place — so the address has to arrive from the server at
+ * runtime, the client cannot exist until it does, and every call site pays for
+ * that with a lazy accessor. A same-origin request needs no address at all:
+ * `/api/…` is complete before any machine exists.
+ *
+ * What it costs: one extra hop through the web role, and no WebSocket — a
+ * route handler cannot proxy an upgrade. The realtime socket is therefore the
+ * one place this example still needs the API role's address, or a routing layer
+ * in front of both roles that serves them on one origin (see
+ * `lib/api/cross-origin.ts`).
+ */
+export const dynamic = 'force-dynamic';
+
+const FORWARDED_REQUEST_HEADERS = [
+  'accept',
+  'accept-language',
+  'content-type',
+  'authorization',
+];
+const FORWARDED_RESPONSE_HEADERS = ['content-type', 'cache-control', 'etag'];
+
+async function forward(request: Request): Promise<Response> {
+  const incoming = new URL(request.url);
+  // Rebuilt from the incoming pathname rather than from the matched segments,
+  // so an encoded segment reaches the API role exactly as it arrived.
+  const target = new URL(`${incoming.pathname}${incoming.search}`, internalApiUrl());
+
+  const headers = new Headers();
+  for (const name of FORWARDED_REQUEST_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+
+  // Buffered rather than streamed: forwarding a stream needs the non-standard
+  // `duplex` init that this project's types do not carry, and every payload
+  // this contract accepts is a small JSON document.
+  const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+  const response = await fetch(target, {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.arrayBuffer() : undefined,
+    // A redirect is the API role's answer, not something to resolve here.
+    redirect: 'manual',
+  });
+
+  const responseHeaders = new Headers();
+  for (const name of FORWARDED_RESPONSE_HEADERS) {
+    const value = response.headers.get(name);
+    if (value !== null) responseHeaders.set(name, value);
+  }
+  return new Response(response.body, { status: response.status, headers: responseHeaders });
+}
+
+export const GET = forward;
+export const POST = forward;
+export const PUT = forward;
+export const PATCH = forward;
+export const DELETE = forward;

package/examples/repository/packages/frontend/src/lib/api/client.ts

@@ -1,20 +1,25 @@
 import { repositoryContract } from '@app/shared';
 import { createClient, createHttpClient, createUrlBuilder } from 'stitchkit';
-import { env } from '@/env';
 
-function apiOrigin(): string {
-  return typeof window === 'undefined' ? env.INTERNAL_API_URL : env.NEXT_PUBLIC_API_URL;
-}
+/**
+ * The browser's API client — a module CONSTANT, because it needs no address.
+ *
+ * `/api` is complete when no machine exists: it names a path on whatever origin
+ * served the page. That is the whole reason this file has no factory, no lazy
+ * accessor and no parentheses at its call sites — see `queries.ts`. The web
+ * role forwards these requests to the API role (`app/api/[...path]/route.ts`).
+ *
+ * A browser that genuinely must reach a DIFFERENT origin cannot do this, and
+ * pays a real price for it. That variant lives in `cross-origin.ts`, named and
+ * explained, rather than in the default path everybody copies.
+ */
+const browserHttp = createHttpClient({ baseUrl: '/api', credentials: 'same-origin' });
+
+export const repositoryApi = createClient(repositoryContract, browserHttp);
+export const repositoryUrls = createUrlBuilder(repositoryContract, browserHttp);
 
+/** The server-side client needs an address, and reads it from the place. */
 export function createRepositoryApi(baseUrl: string) {
   const http = createHttpClient({ baseUrl: `${baseUrl}/api`, credentials: 'omit' });
   return createClient(repositoryContract, http);
 }
-
-const http = createHttpClient({ baseUrl: `${apiOrigin()}/api`, credentials: 'omit' });
-export const repositoryApi = createRepositoryApi(apiOrigin());
-export const repositoryUrls = createUrlBuilder(repositoryContract, http);
-
-export function createServerRepositoryApi() {
-  return createRepositoryApi(env.INTERNAL_API_URL);
-}

package/examples/repository/packages/frontend/src/lib/api/cross-origin.ts

@@ -0,0 +1,87 @@
+/**
+ * THE VARIANT: a browser that must reach the API role at a different origin.
+ *
+ * The default in this example is same-origin (`lib/api/client.ts`): the browser
+ * calls `/api/…` and the web role forwards. Two things can pull a deployment
+ * out of that, and they are separate, so they have separate variables:
+ *
+ * - **`PUBLIC_REALTIME_ORIGIN`** — the socket. A WebSocket upgrade does not
+ *   survive a proxying route handler, so a deployment running the two roles on
+ *   two ports with no routing layer in front of them must name the socket's
+ *   origin even though its HTTP is already same-origin. This one is read by the
+ *   default path, and unset means the page's own origin.
+ * - **`PUBLIC_API_ORIGIN`** — HTTP. Only for a frontend that genuinely dials
+ *   the API role itself: separate hostnames with nothing in front of them.
+ *   Setting it changes nothing on its own; switching is an import, below.
+ *
+ * Switching HTTP to this variant is one line in `queries.ts`:
+ *
+ * ```ts
+ * // before
+ * import { repositoryApi } from './client'
+ * fetcher: () => repositoryApi.read()
+ * // after
+ * import { repositoryApiCrossOrigin } from './cross-origin'
+ * fetcher: () => repositoryApiCrossOrigin().read()
+ * ```
+ *
+ * What that costs, in order:
+ *
+ * 1. **The address is a property of the place**, so it can never be compiled
+ *    in. The server reads it per request and hands it to the browser
+ *    (`providers/index.tsx` → `providers/client-providers.tsx`).
+ * 2. **Nothing can be built at import time.** The client has to be constructed
+ *    on FIRST USE — hence the parentheses, which the default path does not pay.
+ * 3. **Order matters.** Anything reading the origin must render inside
+ *    `<Providers>`; outside it, the value is not there yet.
+ * 4. **The API role needs `CORS_ORIGIN`**, for HTTP and for the realtime
+ *    handshake alike.
+ *
+ * None of that is wrong — it is the correct shape for the case. It is simply
+ * not the case most projects have, which is why it is not the body of the
+ * example.
+ */
+import { createRepositoryApi } from './client';
+
+export interface PublicOrigins {
+  /** Where the browser dials the API role over HTTP, if not this origin. */
+  readonly api: string | undefined;
+  /** Where the browser opens the realtime socket, if not this origin. */
+  readonly realtime: string | undefined;
+}
+
+let origins: PublicOrigins = { api: undefined, realtime: undefined };
+
+/** Supplied by the server, once, above every consumer. */
+export function setPublicOrigins(supplied: PublicOrigins): void {
+  origins = supplied;
+}
+
+/**
+ * The socket's origin, or `undefined` when this deployment serves both roles on
+ * one origin.
+ *
+ * `undefined` is an answer, not a missing value: the socket then connects to
+ * the page's own origin, where a routing layer forwards `/socket.io`.
+ */
+export function optionalRealtimeOrigin(): string | undefined {
+  return origins.realtime;
+}
+
+export function requirePublicApiOrigin(): string {
+  const { api } = origins;
+  if (!api) {
+    throw new Error(
+      'The public API origin has not been provided — set PUBLIC_API_ORIGIN and render this inside <Providers>, which supplies it from the server.',
+    );
+  }
+  return api;
+}
+
+let crossOriginApi: ReturnType<typeof createRepositoryApi> | undefined;
+
+/** Built on FIRST USE: the origin arrives at runtime, not at import. */
+export function repositoryApiCrossOrigin(): ReturnType<typeof createRepositoryApi> {
+  crossOriginApi ??= createRepositoryApi(requirePublicApiOrigin());
+  return crossOriginApi;
+}

package/examples/repository/packages/frontend/src/lib/api/place.ts

@@ -0,0 +1,26 @@
+import { env } from '@/env';
+
+/**
+ * The addresses this example reads from the place.
+ *
+ * `INTERNAL_API_URL` is REQUIRED — see `packages/config/src/features.ts` — and
+ * the declaration a deployment reads says so, because the web role dereferences
+ * it on every proxied request and on every server render.
+ *
+ * The two public ones are optional and independent, because the questions they
+ * answer are independent: HTTP can be forwarded by the web role, and a
+ * WebSocket upgrade cannot. A deployment behind one routing layer sets neither.
+ */
+export function internalApiUrl(): string {
+  return env.INTERNAL_API_URL;
+}
+
+/** Where the browser dials the API role over HTTP — the cross-origin variant. */
+export function publicApiOrigin(): string | undefined {
+  return env.PUBLIC_API_ORIGIN;
+}
+
+/** Where the browser opens the realtime socket, when it is not this origin. */
+export function publicRealtimeOrigin(): string | undefined {
+  return env.PUBLIC_REALTIME_ORIGIN;
+}

package/examples/repository/packages/frontend/src/lib/api/queries.ts

@@ -1,6 +1,9 @@
 import { createMutation, createQuery } from 'react-query-kit';
 import { repositoryApi } from './client';
 
+// No parentheses: the client is a module constant, because a same-origin path
+// needs no address. The cross-origin variant pays for its address with a lazy
+// accessor — see `cross-origin.ts`.
 export const useRepository = createQuery({
   queryKey: ['repository'],
   fetcher: () => repositoryApi.read(),