create-stitchkit 0.4.0 → 0.4.2

package/template/scripts/shutdown-budget.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  type CleanupResult,
+  closeWithinBudget,
+  concludeShutdown,
+} from '../packages/backend/src/cleanup';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { CLEANUP_BUDGET_MS, FORCE_BUDGET_MS } from '../packages/config/src/shutdown';
+import { terminationBudgetMs } from './declaration';
+
+describe('the termination budget is an upper bound, not an estimate', () => {
+  test('the budget is exactly the three bounded parts', () => {
+    for (const role of appDeclaration.roles) {
+      expect(terminationBudgetMs(role)).toBe(
+        role.drainFloorMs + FORCE_BUDGET_MS + CLEANUP_BUDGET_MS,
+      );
+    }
+  });
+
+  test('a cleanup that finishes reports nothing unfinished', async () => {
+    const closed: string[] = [];
+    const result = await closeWithinBudget([
+      { name: 'MCP', close: async () => closed.push('MCP') },
+      { name: 'database', close: async () => closed.push('database') },
+    ]);
+    expect(closed).toEqual(['MCP', 'database']);
+    expect(result.unfinished).toEqual([]);
+  });
+
+  test('a close that hangs stops being waited for, and is named', async () => {
+    // The defect this exists for: the drain had a deadline, the closes after it
+    // had none, so a hung MCP session or database pool ran past the very kill
+    // timeout the budget had told the supervisor to allow — turning an orderly
+    // shutdown into the SIGKILL that runs no cleanup at all.
+    const result = await closeWithinBudget(
+      [{ name: 'MCP', close: () => new Promise<void>(() => undefined) }],
+      25,
+    );
+    expect(result.unfinished).toEqual(['MCP']);
+    expect(result.durationMs).toBeLessThan(CLEANUP_BUDGET_MS);
+  });
+
+  test('the steps share one budget rather than each getting a full one', async () => {
+    const result = await closeWithinBudget(
+      [
+        { name: 'MCP', close: () => new Promise<void>(() => undefined) },
+        { name: 'database', close: () => new Promise<void>(() => undefined) },
+      ],
+      25,
+    );
+    expect(result.unfinished).toEqual(['MCP', 'database']);
+    // Two steps, one budget: about one budget of wall clock, not two.
+    expect(result.durationMs).toBeLessThan(50);
+  });
+
+  test('a close that fails is a failure, and keeps its cause', async () => {
+    // It used to be swallowed into `undefined` with the note that the budget is
+    // about time. The budget is — but a close that throws is a shutdown that
+    // did not happen, and reporting it as a clean exit with the reason gone is
+    // how a broken shutdown looks exactly like a working one.
+    const result = await closeWithinBudget([
+      { name: 'database', close: () => Promise.reject(new Error('pool already gone')) },
+    ]);
+    expect(result.unfinished).toEqual([]);
+    expect(result.failed.map((failure) => failure.name)).toEqual(['database']);
+    expect(result.failed[0]?.cause).toBeInstanceOf(Error);
+  });
+
+  test('a cleanup that completed is a zero exit and no forced ending', () => {
+    let exited: number | undefined;
+    concludeShutdown({ unfinished: [], failed: [], durationMs: 3 }, true, (code) => {
+      exited = code;
+    });
+    expect(process.exitCode).toBe(0);
+    expect(exited).toBeUndefined();
+    process.exitCode = 0;
+  });
+
+  test('an unfinished step and a failed one both end the process non-zero', () => {
+    const endings: Array<[string, CleanupResult]> = [
+      ['unfinished', { unfinished: ['database'], failed: [], durationMs: 5 }],
+      [
+        'failed',
+        {
+          unfinished: [],
+          failed: [{ name: 'database', cause: new Error('pool already gone') }],
+          durationMs: 5,
+        },
+      ],
+    ];
+    for (const [label, result] of endings) {
+      let exited: number | undefined;
+      concludeShutdown(result, true, (code) => {
+        exited = code;
+      });
+      expect(`${label}:${exited}`).toBe(`${label}:1`);
+    }
+    process.exitCode = 0;
+  });
+
+  test('the role bounds its own cleanup rather than awaiting it bare', () => {
+    // One number, two readers — and the reader that matters is the role. An
+    // `await mcp.close()` here with nothing around it is the whole defect.
+    const source = readFileSync(
+      resolve(import.meta.dir, '../packages/backend/src/index.ts'),
+      'utf8',
+    );
+    expect(source).toContain('closeWithinBudget');
+    expect(source).not.toMatch(/await mcp\.close\(\);/);
+    expect(source).not.toMatch(/await prisma\.\$disconnect\(\);/);
+  });
+});
+
+describe('a spent budget ends the process itself', () => {
+  const fixture = resolve(import.meta.dir, 'shutdown-budget.fixture.ts');
+
+  async function runFixture(mode: string, budgetMs: number, waitMs: number) {
+    const child = Bun.spawn(['bun', fixture, String(budgetMs), mode], {
+      cwd: resolve(import.meta.dir, '..'),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const startedAt = Date.now();
+    const timeout = Bun.sleep(waitMs).then(() => 'timeout');
+    const finished = await Promise.race([child.exited, timeout]);
+    const elapsed = Date.now() - startedAt;
+    if (finished === 'timeout') {
+      child.kill('SIGKILL');
+      await child.exited;
+      return { exitCode: undefined, elapsed, stdout: '', stderr: '' };
+    }
+    const [stdout, stderr] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    return { exitCode: finished, elapsed, stdout, stderr };
+  }
+
+  test('a role whose close never finishes exits anyway, and says so', async () => {
+    const run = await runFixture('hang', 200, 8_000);
+    expect(run.exitCode).toBe(1);
+    expect(run.stderr).toContain('the cleanup budget is spent, exiting anyway');
+    // Well inside a supervisor's kill timeout, which is what the declared
+    // termination budget promises this stays inside.
+    expect(run.elapsed).toBeLessThan(5_000);
+  }, 20_000);
+
+  test('a role whose close throws exits non-zero, with the cause', async () => {
+    const run = await runFixture('throw', 200, 8_000);
+    expect(run.exitCode).toBe(1);
+    expect(run.stderr).toContain('Shutdown could not close database');
+    expect(run.stderr).toContain('pool already gone');
+  }, 20_000);
+
+  test('the held handle really does hold — without it the test proves nothing', async () => {
+    // Falsification. If this process ended on its own, the two assertions above
+    // would pass with `concludeShutdown` deleted, and the regression would be
+    // measuring the absence of work rather than the presence of an ending.
+    const run = await runFixture('clean', 200, 1_500);
+    expect(run.exitCode).toBeUndefined();
+  }, 20_000);
+});

package/template/scripts/surface-conformance.ts

@@ -46,7 +46,7 @@ interface SurfaceConformanceOptions {
 }
 
 async function readJson(url: string): Promise<unknown> {
-  const response = await fetch(url);
+  const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
   if (!response.ok) throw new Error(`GET ${url} returned ${response.status}`);
   return response.json();
 }
@@ -94,6 +94,13 @@ export async function discoverMcpTools(
   const transport = new StreamableHTTPClientTransport(new URL(`${apiOrigin}/mcp`));
   try {
     await client.connect(transport);
+    // Ask the server what it HAS before asking it to list it. A server exposing
+    // no MCP tool advertises no `tools` capability, and calling `listTools()`
+    // anyway makes the vendor client log a debug line — noise printed on every
+    // green run of a gate whose whole output is one line — to return the empty
+    // list the capability already stated. The absence is still observed here,
+    // and a manifest that claims an MCP tool still fails against it.
+    if (!client.getServerCapabilities()?.tools) return [];
     return (await client.listTools()).tools.map((tool) => tool.name);
   } finally {
     await client.close();

package/template/scripts/tooling-env.ts

@@ -1,6 +1,7 @@
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { config as dotenvConfig } from 'dotenv';
+import { config as dotenvConfig, parse as parseDotenv } from 'dotenv';
 import { z } from 'zod';
 import { ensureLocalEnvironment } from './local-env';
 
@@ -12,6 +13,18 @@ const ToolingEnvSchema = z.object({
   SMOKE_API_ORIGIN: z.url(),
   SMOKE_WEB_ORIGIN: z.url(),
   PLAYWRIGHT_BASE_URL: z.url().optional(),
+  // What the deployment says about the addresses it serves. A check that proves
+  // one artifact answers on many can only dial an address the deployment
+  // claims — every other one is refused, by design — so it has to read the
+  // claim rather than carry two fixture hosts of its own and require the
+  // deployment to have been told the same two names.
+  PUBLIC_WEB_ORIGIN: z.url().optional(),
+  PUBLIC_WEB_HOSTS: z.string().min(1).optional(),
+  // The acceptance gate's own database. Optional here because only that gate
+  // needs it and `runtime:smoke` must still run against a deployment someone
+  // else brought up; `resolveAcceptanceDatabase` is what makes it mandatory
+  // where it matters, with a refusal that names the line to add.
+  ACCEPTANCE_DATABASE_URL: z.url().optional(),
 });
 
 export function loadToolingEnv(root = path.resolve(scriptDirectory, '..')) {
@@ -23,6 +36,22 @@ export function loadToolingEnv(root = path.resolve(scriptDirectory, '..')) {
   return ToolingEnvSchema.parse(process.env);
 }
 
+/**
+ * The environment this deployment actually runs with: what the place injected,
+ * with `.env` filling the gaps.
+ *
+ * The same precedence the generated supervision file uses — a file in the
+ * repository never overrules the place — so a script reading it and a role
+ * started from it cannot disagree about which port a role is on.
+ */
+export function deploymentEnvironment(
+  root = path.resolve(scriptDirectory, '..'),
+): Record<string, string | undefined> {
+  const file = path.resolve(root, '.env');
+  const fromFile = existsSync(file) ? parseDotenv(readFileSync(file, 'utf8')) : {};
+  return { ...fromFile, ...process.env };
+}
+
 /** Process inheritance is isolated to this tooling environment boundary. */
 export function inheritToolingEnvironment(
   overrides: Record<string, string>,

package/template/scripts/web-surface-smoke.ts

@@ -1,12 +1,24 @@
 const OG_IMAGE_PATH = '/api/og/en/themes';
 const SITEMAP_PATH = '/sitemap.xml';
+const DIAL_TIMEOUT_MS = 30_000;
 
 function publicUrl(origin: string, path: string): URL {
   return new URL(path, new URL(origin).origin);
 }
 
+/**
+ * Every dial is bounded.
+ *
+ * A gate that hangs is worse than one that fails: it reports nothing, ever. An
+ * endpoint that accepts the connection and never answers used to stop the whole
+ * run with no output and no deadline.
+ */
+function dial(url: URL, init?: RequestInit): Promise<Response> {
+  return fetch(url, { ...init, signal: AbortSignal.timeout(DIAL_TIMEOUT_MS) });
+}
+
 export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
-  const image = await fetch(publicUrl(webOrigin, OG_IMAGE_PATH));
+  const image = await dial(publicUrl(webOrigin, OG_IMAGE_PATH));
   if (image.status !== 200) {
     throw new Error(`GET ${OG_IMAGE_PATH} returned ${image.status}`);
   }
@@ -18,7 +30,7 @@ export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
     throw new Error(`GET ${OG_IMAGE_PATH} returned an empty image`);
   }
 
-  const sitemap = await fetch(publicUrl(webOrigin, SITEMAP_PATH));
+  const sitemap = await dial(publicUrl(webOrigin, SITEMAP_PATH));
   if (sitemap.status !== 200) {
     throw new Error(`GET ${SITEMAP_PATH} returned ${sitemap.status}`);
   }
@@ -27,6 +39,97 @@ export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
   }
 }
 
+/** What the deployment has been told about the addresses it serves. */
+export interface PublicHostPolicy {
+  /** `PUBLIC_WEB_ORIGIN` — a single public address, stated outright. */
+  origin?: string | undefined;
+  /** `PUBLIC_WEB_HOSTS` — the comma-separated hosts this deployment claims. */
+  hosts?: string | undefined;
+}
+
+interface ForwardedAddress {
+  host: string;
+  proto: 'http' | 'https';
+}
+
+export type PortabilityPlan =
+  | {
+      kind: 'check';
+      addresses: readonly [ForwardedAddress, ForwardedAddress];
+      forgedHost: string;
+    }
+  | { kind: 'skip'; reason: string }
+  | { kind: 'refuse'; reason: string };
+
+function claimedHosts(hosts: string | undefined): string[] {
+  // Deduplicated, because the count is load-bearing: the check needs two
+  // DIFFERENT addresses to ask this deployment on, and one host written twice
+  // would pass as two and make it compare an address with itself.
+  return [
+    ...new Set(
+      (hosts ?? '')
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0),
+    ),
+  ];
+}
+
+/**
+ * Which addresses to ask this deployment on — ITS OWN, not the check's.
+ *
+ * The check can only dial an address the deployment claims: a forwarded host
+ * outside `PUBLIC_WEB_HOSTS` is refused on purpose, and rightly so. Naming two
+ * fixture hosts here therefore meant the deployment had to have been told about
+ * those exact two names by somebody else — which only the packed lane ever was.
+ * Everyone running the same command against their own deployment got a bare
+ * 500 from a policy working exactly as designed.
+ *
+ * So the deployment declares and the check reads, instead of two copies of the
+ * same fixture that must agree across two repositories.
+ */
+export function planPortabilityCheck(
+  webOrigin: string,
+  policy: PublicHostPolicy,
+): PortabilityPlan {
+  if (policy.origin) {
+    return {
+      kind: 'skip',
+      reason: `PUBLIC_WEB_ORIGIN pins this deployment to ${policy.origin}, so it answers with that one address whatever it is asked on. Portability by request is observable only where PUBLIC_WEB_HOSTS names the addresses instead.`,
+    };
+  }
+
+  const claimed = claimedHosts(policy.hosts);
+  const dialled = new URL(webOrigin).host.toLowerCase();
+  const others = claimed.filter((host) => host !== dialled);
+  const [first, second] = others;
+  if (!first || !second) {
+    const suggestion = [dialled, 'alpha.example', 'beta.example:8443'].join(',');
+    return {
+      kind: 'refuse',
+      reason: `This deployment claims ${claimed.length === 0 ? 'no host at all' : claimed.join(', ')}, which leaves ${others.length} address besides ${dialled} to ask it on. Proving that one artifact serves many needs at least two. Set PUBLIC_WEB_HOSTS=${suggestion} in .env, restart the web role (\`bun run dev\`), then rerun.`,
+    };
+  }
+
+  // The forged host must be one the deployment never claimed — otherwise the
+  // refusal it is supposed to provoke never happens and the check is vacuous.
+  let forgedHost = 'attacker.example';
+  for (let attempt = 1; claimed.includes(forgedHost); attempt += 1) {
+    forgedHost = `attacker-${attempt}.invalid`;
+  }
+
+  return {
+    kind: 'check',
+    // Both protocols on purpose: the answer has to follow the forwarded scheme,
+    // not a default the artifact was built with.
+    addresses: [
+      { host: first, proto: 'https' },
+      { host: second, proto: 'http' },
+    ],
+    forgedHost,
+  };
+}
+
 /**
  * One artifact, many external addresses.
  *
@@ -36,17 +139,24 @@ export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
  * be answering with the address it was built with instead of the one it was
  * asked on.
  */
-export async function assertArtifactIsPlacementFree(webOrigin: string): Promise<void> {
-  const addresses = [
-    { host: 'alpha.example', proto: 'https' },
-    { host: 'beta.example:8443', proto: 'http' },
-  ];
+export async function assertArtifactIsPlacementFree(
+  webOrigin: string,
+  policy: PublicHostPolicy,
+): Promise<void> {
+  const plan = planPortabilityCheck(webOrigin, policy);
+  if (plan.kind === 'refuse') throw new Error(plan.reason);
+  if (plan.kind === 'skip') {
+    // Named, not silent: a gate whose strongest check quietly did not run reads
+    // exactly like one that ran and passed.
+    console.log(`Placement-free check not run — ${plan.reason}`);
+    return;
+  }
 
-  for (const { host, proto } of addresses) {
+  for (const { host, proto } of plan.addresses) {
     const expected = `${proto}://${host}`;
     const headers = { 'x-forwarded-host': host, 'x-forwarded-proto': proto };
 
-    const sitemap = await fetch(publicUrl(webOrigin, SITEMAP_PATH), { headers });
+    const sitemap = await dial(publicUrl(webOrigin, SITEMAP_PATH), { headers });
     if (sitemap.status !== 200) {
       throw new Error(`GET ${SITEMAP_PATH} as ${expected} returned ${sitemap.status}`);
     }
@@ -60,7 +170,7 @@ export async function assertArtifactIsPlacementFree(webOrigin: string): Promise<
       );
     }
 
-    const robots = await fetch(publicUrl(webOrigin, '/robots.txt'), { headers });
+    const robots = await dial(publicUrl(webOrigin, '/robots.txt'), { headers });
     if (!(await robots.text()).includes(`Sitemap: ${expected}/sitemap.xml`)) {
       throw new Error(`GET /robots.txt as ${expected} did not answer with that address`);
     }
@@ -70,8 +180,8 @@ export async function assertArtifactIsPlacementFree(webOrigin: string): Promise<
   // must be refused, or the same mechanism that lets one artifact serve many
   // addresses lets a caller choose the canonical URL, the sitemap and the OG
   // metadata for everyone else.
-  const forged = await fetch(publicUrl(webOrigin, SITEMAP_PATH), {
-    headers: { 'x-forwarded-host': 'attacker.example', 'x-forwarded-proto': 'https' },
+  const forged = await dial(publicUrl(webOrigin, SITEMAP_PATH), {
+    headers: { 'x-forwarded-host': plan.forgedHost, 'x-forwarded-proto': 'https' },
   });
   if (forged.status < 400) {
     throw new Error(
@@ -83,9 +193,10 @@ export async function assertArtifactIsPlacementFree(webOrigin: string): Promise<
   // misconfigured proxy or a forgery, and both have to be visible: mapping
   // every unknown value to `http` produced a plausible canonical origin from
   // `ftp`, `javascript` and a truncated header alike.
+  const [claimedAddress] = plan.addresses;
   for (const proto of ['ftp', 'javascript', 'HTTPS://', '']) {
-    const answered = await fetch(publicUrl(webOrigin, SITEMAP_PATH), {
-      headers: { 'x-forwarded-host': 'alpha.example', 'x-forwarded-proto': proto },
+    const answered = await dial(publicUrl(webOrigin, SITEMAP_PATH), {
+      headers: { 'x-forwarded-host': claimedAddress.host, 'x-forwarded-proto': proto },
     });
     // An empty header carries no claim at all and is treated as absent.
     const acceptable = proto === '' ? answered.status === 200 : answered.status >= 400;