create-stitchkit 0.3.3 → 0.4.1

package/template/scripts/client-boundary.test.ts

@@ -0,0 +1,117 @@
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import {
+  type ClientBoundaryScan,
+  clientEntries,
+  findDeclarationLeaks,
+  specifiers,
+} from './client-boundary';
+
+const root = resolve(import.meta.dir, '..');
+const project: ClientBoundaryScan = {
+  root,
+  frontendSrc: join(root, 'packages/frontend/src'),
+  declaration: join(root, 'packages/config/src/declaration.ts'),
+};
+
+describe('the declaration stays out of the browser', () => {
+  test('the fixture actually has client components to walk', () => {
+    expect(clientEntries(project).length).toBeGreaterThan(0);
+  });
+
+  test('no client graph reaches the project declaration', () => {
+    expect(
+      findDeclarationLeaks(project).map((chain) =>
+        chain.map((file) => relative(root, file)).join(' → '),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('the scanner fails however the import is written', () => {
+  // A check that only recognises the one spelling the leak had the first time
+  // is a check that passes while the leak is back. These fixtures write it the
+  // two other ways it can come back.
+  const created: string[] = [];
+  afterAll(() => {
+    for (const path of created) rmSync(path, { recursive: true, force: true });
+  });
+
+  function fixture(files: Record<string, string>): ClientBoundaryScan {
+    const base = mkdtempSync(join(tmpdir(), 'client-boundary-'));
+    created.push(base);
+    const write = (relativePath: string, content: string): void => {
+      const path = join(base, relativePath);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    };
+    write(
+      'packages/config/package.json',
+      JSON.stringify({
+        name: '@app/config',
+        exports: { './declaration': './src/declaration.ts' },
+      }),
+    );
+    write('packages/config/src/declaration.ts', 'export const appDeclaration = {};\n');
+    for (const [path, content] of Object.entries(files)) write(path, content);
+    return {
+      root: base,
+      frontendSrc: join(base, 'packages/frontend/src'),
+      declaration: join(base, 'packages/config/src/declaration.ts'),
+    };
+  }
+
+  test('a barrel that re-exports the declaration is a leak', () => {
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { appDeclaration } from './lib';\nexport const value = appDeclaration;\n",
+      'packages/frontend/src/lib/index.ts': "export * from '@app/config/declaration';\n",
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a relative path into the config package is a leak', () => {
+    // No `@app/` prefix anywhere in the file, so a check on the specifier
+    // string sees nothing at all.
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { appDeclaration } from '../../config/src/declaration';\nexport const value = appDeclaration;\n",
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a double-quoted import is a leak too', () => {
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        '\'use client\';\nimport { appDeclaration } from "@app/config/declaration";\nexport const value = appDeclaration;\n',
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a client graph that reaches nothing forbidden is clean', () => {
+    // The control: without it every assertion above would also pass with a
+    // scanner that reports a leak for anything.
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { name } from './lib';\nexport const value = name;\n",
+      'packages/frontend/src/lib/index.ts': "export const name = 'x';\n",
+    });
+    expect(findDeclarationLeaks(scan)).toEqual([]);
+  });
+
+  test('both quote styles and side-effect imports are read', () => {
+    expect(
+      specifiers(
+        [
+          "import a from 'single';",
+          'import b from "double";',
+          "import 'side-effect';",
+          'const c = await import("dynamic");',
+          "export { d } from 'reexport';",
+        ].join('\n'),
+      ),
+    ).toEqual(['single', 'double', 'reexport', 'side-effect', 'dynamic']);
+  });
+});

package/template/scripts/client-boundary.ts

@@ -0,0 +1,148 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * What a `'use client'` graph is allowed to reach.
+ *
+ * The project declaration is not application data — it is what the repository
+ * says about how it is built and run: role commands, working directories,
+ * artifact and migration paths, and the name of every environment variable a
+ * deployment supplies. One `import` from a module a client component happens to
+ * use puts all of it, plus the Zod schema that parses it, into the browser
+ * bundle. That is the exact mistake `app-identity.generated.ts` exists to
+ * prevent, made from the other side — and it shipped, because nothing checked
+ * the graph, only the file that imports directly.
+ *
+ * The check is a resolved FILE, not a spelling. Matching the string
+ * `@app/config/declaration` catches the one way the leak was written the first
+ * time and misses the two ways it comes back: a barrel that re-exports it, and
+ * a relative path into the config package. Both end at the same file, so that
+ * is what this follows.
+ */
+export interface ClientBoundaryScan {
+  /** Repository root — where `packages/<name>` lives. */
+  root: string;
+  /** The client graph's entry directory. */
+  frontendSrc: string;
+  /** The module no client graph may reach. */
+  declaration: string;
+}
+
+export function sourceFiles(directory: string): string[] {
+  const found: string[] = [];
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry === 'node_modules' || entry === 'generated') continue;
+      found.push(...sourceFiles(path));
+    } else if (/\.tsx?$/.test(entry)) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/**
+ * Every module specifier in a source file, in either quote style.
+ *
+ * Formatting is enforced elsewhere, which is exactly why this must not depend
+ * on it: a check that only reads the house style stops being a check the day
+ * someone pastes a line from somewhere else.
+ */
+export function specifiers(source: string): string[] {
+  const quoted = `'([^']+)'|"([^"]+)"`;
+  return [
+    // `import … from 'x'` and `export … from 'x'`.
+    ...[...source.matchAll(new RegExp(String.raw`from\s+(?:${quoted})`, 'g'))],
+    // `import 'x'` and `import('x')`. Written out because a side-effect import
+    // has no `from` — and a module pulled in for its side effects is in the
+    // bundle exactly as much as one whose value is used.
+    ...[...source.matchAll(new RegExp(String.raw`import\s*\(?\s*(?:${quoted})`, 'g'))],
+  ].flatMap((match) => {
+    const specifier = match[1] ?? match[2];
+    return specifier ? [specifier] : [];
+  });
+}
+
+function firstExistingFile(base: string): string | undefined {
+  for (const candidate of [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+  ]) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return undefined;
+}
+
+/** `@app/config/declaration` → the file its package's `exports` map names. */
+function resolveWorkspace(scan: ClientBoundaryScan, specifier: string): string | undefined {
+  const parts = specifier.split('/');
+  if (parts[0] !== '@app' || !parts[1]) return undefined;
+  const packageRoot = join(scan.root, 'packages', parts[1]);
+  const manifestPath = join(packageRoot, 'package.json');
+  if (!existsSync(manifestPath)) return undefined;
+  const subpath = parts.length > 2 ? `./${parts.slice(2).join('/')}` : '.';
+  const manifest: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const exportsField =
+    typeof manifest === 'object' && manifest !== null
+      ? Reflect.get(manifest, 'exports')
+      : undefined;
+  const target =
+    typeof exportsField === 'object' && exportsField !== null
+      ? Reflect.get(exportsField, subpath)
+      : undefined;
+  if (typeof target !== 'string') return undefined;
+  return firstExistingFile(resolve(packageRoot, target));
+}
+
+export function resolveSpecifier(
+  scan: ClientBoundaryScan,
+  from: string,
+  specifier: string,
+): string | undefined {
+  if (specifier.startsWith('@app/')) return resolveWorkspace(scan, specifier);
+  const base = specifier.startsWith('@/')
+    ? join(scan.frontendSrc, specifier.slice(2))
+    : specifier.startsWith('.')
+      ? resolve(dirname(from), specifier)
+      : undefined;
+  return base ? firstExistingFile(base) : undefined;
+}
+
+/** The import chain from a client entry to the declaration, if one exists. */
+export function pathToDeclaration(
+  scan: ClientBoundaryScan,
+  entry: string,
+): string[] | undefined {
+  const seen = new Set<string>();
+  const queue: Array<{ file: string; chain: string[] }> = [{ file: entry, chain: [entry] }];
+  while (queue.length > 0) {
+    const step = queue.shift();
+    if (!step || seen.has(step.file)) continue;
+    seen.add(step.file);
+    const source = readFileSync(step.file, 'utf8');
+    for (const specifier of specifiers(source)) {
+      const next = resolveSpecifier(scan, step.file, specifier);
+      if (next === scan.declaration) return [...step.chain, next];
+      if (next && !seen.has(next)) queue.push({ file: next, chain: [...step.chain, next] });
+    }
+  }
+  return undefined;
+}
+
+export function clientEntries(scan: ClientBoundaryScan): string[] {
+  return sourceFiles(scan.frontendSrc).filter((file) =>
+    /^\s*['"]use client['"]/m.test(readFileSync(file, 'utf8')),
+  );
+}
+
+/** Every client entry whose graph reaches the declaration, as a readable chain. */
+export function findDeclarationLeaks(scan: ClientBoundaryScan): string[][] {
+  return clientEntries(scan).flatMap((entry) => {
+    const chain = pathToDeclaration(scan, entry);
+    return chain ? [chain] : [];
+  });
+}

package/template/scripts/declaration.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'dotenv';
+import { appDeclaration } from '../packages/config/src/declaration';
+import {
+  assertSupervisionAllowsShutdown,
+  LOCAL_SUPERVISION,
+  renderAppIdentity,
+  renderEcosystem,
+  renderEnvVariables,
+  terminationBudgetMs,
+} from './declaration';
+import { ensureLocalEnvironment } from './local-env';
+
+const root = resolve(import.meta.dir, '..');
+const read = (name: string) => readFileSync(resolve(root, name), 'utf8');
+
+describe('the declaration is the source of what is derived from it', () => {
+  test('the checked-in supervision files are exactly what the generator renders', () => {
+    // Byte-for-byte: nothing in these files is authored, so a difference is
+    // always a hand edit or a stale file — never a formatting opinion.
+    expect(read('ecosystem.config.cjs')).toBe(renderEcosystem(appDeclaration, 'production'));
+    expect(read('ecosystem.dev.config.cjs')).toBe(
+      renderEcosystem(appDeclaration, 'development'),
+    );
+    expect(read('packages/config/src/app-identity.generated.ts')).toBe(renderAppIdentity());
+  });
+
+  test('env.variables in the declaration matches the one environment schema', () => {
+    // Content, not bytes: roles are authored in this file and the formatter
+    // owns its shape — only the derived block has to agree.
+    expect(appDeclaration.env.variables).toEqual(renderEnvVariables());
+  });
+
+  test('every declared variable appears once, with a shape a reader can act on', () => {
+    const derived = renderEnvVariables();
+    expect(new Set(derived.map((entry) => entry.name)).size).toBe(derived.length);
+    expect(derived).toContainEqual({ name: 'DATABASE_URL', shape: 'url', required: true });
+    // A variable with a default is NOT required — the schema decides, not this list.
+    expect(derived).toContainEqual({ name: 'BIND_HOST', shape: 'string', required: false });
+    // An enum names its members: "one of an unnamed set" is useless to the
+    // reader this list exists for.
+    expect(derived).toContainEqual({
+      name: 'LOG_FORMAT',
+      shape: 'enum',
+      required: false,
+      members: ['pretty', 'json'],
+    });
+  });
+});
+
+describe('supervision may not be shorter than the code needs', () => {
+  test('the budget is the whole shutdown, not just the drain', () => {
+    for (const role of appDeclaration.roles) {
+      // Drain, then the force that follows it, then cleanup. Comparing against
+      // the drain alone is what let 15s + 5s meet a 20s kill timeout exactly.
+      expect(terminationBudgetMs(role)).toBeGreaterThan(role.drainFloorMs);
+    }
+  });
+
+  test('the local policy allows every role its full shutdown', () => {
+    expect(() =>
+      assertSupervisionAllowsShutdown(appDeclaration, LOCAL_SUPERVISION.killTimeoutMs),
+    ).not.toThrow();
+  });
+
+  test('a timeout that only covers the drain is refused', () => {
+    const floor = Math.max(...appDeclaration.roles.map((role) => role.drainFloorMs));
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, floor)).toThrow(
+      /killed mid-shutdown/,
+    );
+  });
+
+  test('a timeout one millisecond under the budget is refused', () => {
+    const budget = Math.max(...appDeclaration.roles.map(terminationBudgetMs));
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, budget - 1)).toThrow();
+    expect(() => assertSupervisionAllowsShutdown(appDeclaration, budget)).not.toThrow();
+  });
+
+  test('rendering a supervision file cannot bypass the rule', () => {
+    const impatient = {
+      ...appDeclaration,
+      roles: appDeclaration.roles.map((role) => ({ ...role, drainFloorMs: 10 ** 9 })),
+    };
+    expect(() => renderEcosystem(impatient, 'production')).toThrow(/mid-shutdown/);
+  });
+});
+
+describe('no repository file carries a value of the place', () => {
+  // The real property, checked the same way the frontend build is checked: no
+  // value that differs between two deployments may appear in a repository file.
+  // A kill timeout may — supervision policy is the place's, and for the manual
+  // path this repository IS the place, which is why it is one visible constant.
+  ensureLocalEnvironment(root);
+  const environment = parse(read('.env'));
+  const placementValues = Object.values(environment).filter(
+    (value) => /^\d+$/.test(value) || value.includes('://') || /\d+\.\d+\.\d+\.\d+/.test(value),
+  );
+
+  test('the fixture actually contains ports and addresses to look for', () => {
+    expect(placementValues.length).toBeGreaterThan(2);
+  });
+
+  const repositoryFiles = [
+    'ecosystem.config.cjs',
+    'ecosystem.dev.config.cjs',
+    'project.json',
+    'packages/config/src/app-identity.generated.ts',
+  ];
+  for (const name of repositoryFiles) {
+    test(`${name} names no port and no address`, () => {
+      const rendered = read(name);
+      for (const value of placementValues) expect(rendered).not.toInclude(value);
+    });
+  }
+
+  for (const name of ['ecosystem.config.cjs', 'ecosystem.dev.config.cjs']) {
+    test(`${name} says it is generated`, () => {
+      expect(read(name)).toStartWith('// GENERATED FILE — do not edit.');
+    });
+  }
+});
+
+describe('a role starts its own process, never a launcher', () => {
+  // Measured, not assumed: under PM2 a `bun run <script>` command made the API
+  // role receive the stop signal twice — once from the supervisor, once
+  // forwarded by the launcher — and the second press forced the shutdown, which
+  // turned a declared 15s drain into 1.3ms. Direct exec: `Shutdown clean`.
+  // The schema refuses the shape; this checks what actually reaches PM2.
+  const modes: Array<'production' | 'development'> = ['production', 'development'];
+
+  for (const mode of modes) {
+    test(`the ${mode} supervision file execs the role directly`, () => {
+      const rendered = renderEcosystem(appDeclaration, mode)
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('//'))
+        .join('\n');
+      expect(rendered).not.toMatch(/args: \["run"/);
+      expect(rendered).not.toContain('--filter');
+      // And the deployment's environment is not overruled by a repository file.
+      expect(rendered).not.toContain('override');
+    });
+  }
+});
+
+describe('the drain floor has one home', () => {
+  test('the API role reads its grace period from the declaration', () => {
+    const source = read('packages/backend/src/index.ts');
+    // A literal here would be a second number able to disagree with the one a
+    // supervisor reads, which is exactly how a 30s floor met a 15s kill timeout.
+    expect(source).toContain('gracePeriodMs: apiRole.drainFloorMs');
+    expect(source).not.toMatch(/gracePeriodMs:\s*\d/);
+  });
+});
+
+describe('an argument survives the generator intact', () => {
+  test('a space and a quote reach the supervision file unmangled', () => {
+    // The reason commands are argv and the generator serialises rather than
+    // concatenates: `split(' ')` destroyed quoted arguments, and building
+    // `'${part}'` by hand emitted invalid JavaScript for an argument
+    // containing a quote.
+    const awkward = {
+      ...appDeclaration,
+      roles: appDeclaration.roles.map((role) => ({
+        ...role,
+        commands: {
+          ...role.commands,
+          production: { executable: 'bun', args: ['run me.ts', "it's fine"] },
+        },
+      })),
+    };
+
+    const rendered = renderEcosystem(awkward, 'production');
+    expect(rendered).toContain('["run me.ts","it\'s fine"]');
+
+    // And it is still valid JavaScript: the file is `require`d by PM2.
+    expect(
+      () =>
+        new Function(
+          `return (${rendered.slice(rendered.indexOf('args: [')).slice(6).split(']')[0]}])`,
+        ),
+    ).not.toThrow();
+  });
+});
+
+describe('the guidance a next agent reads names the keys that exist', () => {
+  // `AGENTS.md` is not documentation about the past — it is the instruction the
+  // next agent follows. It kept pointing at `env.required` for a whole release
+  // after the key became `env.variables`, which is worse than a stale comment:
+  // the agent goes looking for something that is not there.
+  const guidance = ['AGENTS.md', 'README.md'];
+
+  for (const file of guidance) {
+    test(`${file} names no key the declaration does not have`, () => {
+      const text = readFileSync(resolve(import.meta.dir, '..', file), 'utf8');
+      const referenced = [...text.matchAll(/`(env|build|release|roles|identity)\.(\w+)`/g)];
+      const unknown = referenced.filter(([, root, key]) => {
+        const branch: unknown = Reflect.get(appDeclaration, root ?? '');
+        if (typeof branch !== 'object' || branch === null) return true;
+        return !Object.hasOwn(branch, key ?? '');
+      });
+      expect(unknown.map(([match]) => match)).toEqual([]);
+    });
+  }
+});