create-stitchkit 0.3.3 → 0.4.1

package/template/scripts/supervision-signal.test.ts

@@ -0,0 +1,94 @@
+import { expect, test } from 'bun:test';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Why the supervision files run each role from its OWN directory.
+ *
+ * A supervisor that reaches into a workspace from the root — `bun run --filter
+ * @app/backend start` — puts a launcher process between itself and the role.
+ * `SIGTERM` sent to that launcher does not arrive at the role: the launcher
+ * dies and the role is torn down without ever running its shutdown. Every
+ * drain, every `kill_timeout`, every grace period is then decoration.
+ *
+ * This test spawns both shapes and compares what the role actually receives, so
+ * the choice in `scripts/declaration.ts` is pinned by behaviour rather than by
+ * a comment that a later refactor can talk itself out of.
+ */
+async function roleReceivesSignal(from: 'role directory' | 'workspace root'): Promise<boolean> {
+  const root = await mkdtemp(join(tmpdir(), 'starter-signal-'));
+  try {
+    const rolePath = join(root, 'role');
+    await Bun.$`mkdir -p ${rolePath}`.quiet();
+    await writeFile(
+      join(rolePath, 'role.ts'),
+      [
+        "process.on('SIGTERM', () => { console.log('DRAINED'); process.exit(0); });",
+        "console.log('UP');",
+        'setInterval(() => {}, 1000);',
+      ].join('\n'),
+    );
+    await writeFile(
+      join(rolePath, 'package.json'),
+      JSON.stringify({ name: '@t/role', scripts: { start: 'bun role.ts' } }),
+    );
+    await writeFile(
+      join(root, 'package.json'),
+      JSON.stringify({ name: 'root', private: true, workspaces: ['role'] }),
+    );
+
+    // `detached` makes the child a process-group LEADER, which is what lets the
+    // negative-pid signal below reach the role behind the launcher. The
+    // NEGATIVE case is the point: there the role never sees the signal, so
+    // killing the launcher alone would leave it running for the life of the
+    // machine — this test used to leak one role per run.
+    const child =
+      from === 'role directory'
+        ? Bun.spawn(['bun', 'run', 'start'], {
+            cwd: rolePath,
+            detached: true,
+            stdout: 'pipe',
+            stderr: 'ignore',
+          })
+        : Bun.spawn(['bun', 'run', '--filter', '@t/role', 'start'], {
+            cwd: root,
+            detached: true,
+            stdout: 'pipe',
+            stderr: 'ignore',
+          });
+
+    const output = new Response(child.stdout).text();
+    await Bun.sleep(1500);
+    // The role first, exactly as a supervisor would; then the whole group, so
+    // nothing that ignored the request outlives the test.
+    child.kill('SIGTERM');
+    await child.exited;
+    const printed = await output;
+    try {
+      process.kill(-child.pid, 'SIGKILL');
+    } catch {
+      // The group is already gone, which is the outcome this wants.
+    }
+    // Without this the negative case passes when the spawn simply failed —
+    // proving nothing about signal delivery, which is the only thing it exists
+    // to prove.
+    if (!printed.includes('UP')) {
+      throw new Error(`The role never started when launched from the ${from}: ${printed}`);
+    }
+    return printed.includes('DRAINED');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+test('a role started in its own directory receives the shutdown signal', async () => {
+  expect(await roleReceivesSignal('role directory')).toBe(true);
+}, 20_000);
+
+test('a role started through a workspace filter never receives it', async () => {
+  // The reason `cwd` is per role in the generated supervision files. If this
+  // ever starts passing, the generator may be simplified — until then it may
+  // not.
+  expect(await roleReceivesSignal('workspace root')).toBe(false);
+}, 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,14 +1,30 @@
+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';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+// Tooling addresses are LEGITIMATELY bound to a place — they name the deployment a
+// check is dialling. They must not be named `NEXT_PUBLIC_*`, because that
+// prefix makes Next substitute the value into the build output.
 const ToolingEnvSchema = z.object({
-  NEXT_PUBLIC_API_URL: z.url(),
-  NEXT_PUBLIC_WEB_URL: z.url(),
+  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, '..')) {
@@ -20,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}`);
   }
@@ -26,3 +38,172 @@ export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
     throw new Error(`GET ${SITEMAP_PATH} omitted the localized theme-system URL`);
   }
 }
+
+/** 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.
+ *
+ * The single check that catches a regression back into a build-time address: if
+ * anything is baked in again — a `NEXT_PUBLIC_` variable, a prerendered
+ * `sitemap.xml` — the two answers below stop differing, because the build would
+ * be answering with the address it was built with instead of the one it was
+ * asked on.
+ */
+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 plan.addresses) {
+    const expected = `${proto}://${host}`;
+    const headers = { 'x-forwarded-host': host, 'x-forwarded-proto': proto };
+
+    const sitemap = await dial(publicUrl(webOrigin, SITEMAP_PATH), { headers });
+    if (sitemap.status !== 200) {
+      throw new Error(`GET ${SITEMAP_PATH} as ${expected} returned ${sitemap.status}`);
+    }
+    const body = await sitemap.text();
+    if (!body.includes(`${expected}/en`)) {
+      throw new Error(`GET ${SITEMAP_PATH} as ${expected} did not answer with that address`);
+    }
+    if (body.includes(new URL(webOrigin).host)) {
+      throw new Error(
+        `GET ${SITEMAP_PATH} as ${expected} leaked the address the build was made on — something is baked into the artifact`,
+      );
+    }
+
+    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`);
+    }
+  }
+
+  // Portable is not the same as forgeable. A host the deployment never claimed
+  // 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 dial(publicUrl(webOrigin, SITEMAP_PATH), {
+    headers: { 'x-forwarded-host': plan.forgedHost, 'x-forwarded-proto': 'https' },
+  });
+  if (forged.status < 400) {
+    throw new Error(
+      `GET ${SITEMAP_PATH} answered for an unclaimed host with ${forged.status} — the forwarded host is trusted without a policy`,
+    );
+  }
+
+  // Same rule, one layer down. A forwarded protocol outside `http | https` is a
+  // 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 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;
+    if (!acceptable) {
+      throw new Error(
+        `GET ${SITEMAP_PATH} with x-forwarded-proto "${proto}" returned ${answered.status} — an unknown protocol is normalised instead of refused`,
+      );
+    }
+  }
+}

package/template/app.config.json

@@ -1,9 +0,0 @@
-{
-  "slug": "stitchkit-starter",
-  "name": "Stitchkit Starter",
-  "version": "0.1.0",
-  "description": {
-    "en": "Stitchkit Starter is a production application built with Stitchkit.",
-    "ru": "Stitchkit Starter — production-приложение на Stitchkit."
-  }
-}

package/template/packages/config/src/identity.ts

@@ -1,18 +0,0 @@
-import { z } from 'zod';
-import source from '../../../app.config.json' with { type: 'json' };
-
-export const ApplicationIdentitySchema = z.object({
-  slug: z
-    .string()
-    .min(1)
-    .max(64)
-    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
-  name: z.string().trim().min(1).max(80),
-  version: z.string().regex(/^\d+\.\d+\.\d+$/),
-  description: z.object({
-    en: z.string().trim().min(1),
-    ru: z.string().trim().min(1),
-  }),
-});
-
-export const appIdentity = ApplicationIdentitySchema.parse(source);