create-stitchkit 0.3.2 → 0.4.0

package/template/scripts/runtime-smoke.ts

@@ -3,10 +3,10 @@ import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
 import { runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
-import { assertPublicWebSurface } from './web-surface-smoke';
+import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
 
 const toolingEnv = loadToolingEnv();
-const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
 
 async function json(path: string): Promise<unknown> {
   const response = await fetch(`${apiOrigin}${path}`);
@@ -28,6 +28,9 @@ if (!Object.keys(openApi.paths).includes('/api/system/status')) {
 }
 
 await runSurfaceConformance({ apiOrigin });
-await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN);
 
-console.log('Runtime HTTP, typed client, OpenAPI, MCP and public web smoke passed');
+console.log(
+  'Runtime HTTP, typed client, OpenAPI, MCP, public web and placement-free artifact smoke passed',
+);

package/template/scripts/serve-mode.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+/**
+ * The web role refuses a mode it does not understand.
+ *
+ * `argv[2] === 'development' ? 'dev' : 'start'` meant a typo, an empty string
+ * and a missing argument all became production in silence — the one decision
+ * that changes whether the role serves a build or compiles on demand. Run as a
+ * real process, because the failure has to happen before Next is spawned.
+ */
+const serve = join(import.meta.dir, '../packages/frontend/scripts/serve.ts');
+
+async function refusal(argv: string[]): Promise<{ code: number; stderr: string }> {
+  const child = Bun.spawn(['bun', serve, ...argv], {
+    cwd: join(import.meta.dir, '../packages/frontend'),
+    env: { ...Bun.env, WEB_PORT: '3210', BIND_HOST: '127.0.0.1' },
+    stdout: 'ignore',
+    stderr: 'pipe',
+  });
+  const [stderr, code] = await Promise.all([new Response(child.stderr).text(), child.exited]);
+  return { code, stderr };
+}
+
+test('a misspelled mode is refused, not treated as production', async () => {
+  const { code, stderr } = await refusal(['produciton']);
+  expect(code).not.toBe(0);
+  expect(stderr).toContain('Run mode must be "development" or "production"');
+  expect(stderr).toContain('produciton');
+}, 30_000);
+
+test('a missing mode is refused', async () => {
+  const { code, stderr } = await refusal([]);
+  expect(code).not.toBe(0);
+  expect(stderr).toContain('received nothing');
+}, 30_000);

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/tooling-env.ts

@@ -5,9 +5,12 @@ 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(),
 });
 

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

@@ -26,3 +26,73 @@ export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
     throw new Error(`GET ${SITEMAP_PATH} omitted the localized theme-system URL`);
   }
 }
+
+/**
+ * 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): Promise<void> {
+  const addresses = [
+    { host: 'alpha.example', proto: 'https' },
+    { host: 'beta.example:8443', proto: 'http' },
+  ];
+
+  for (const { host, proto } of addresses) {
+    const expected = `${proto}://${host}`;
+    const headers = { 'x-forwarded-host': host, 'x-forwarded-proto': proto };
+
+    const sitemap = await fetch(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 fetch(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 fetch(publicUrl(webOrigin, SITEMAP_PATH), {
+    headers: { 'x-forwarded-host': 'attacker.example', '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.
+  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 },
+    });
+    // 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);