create-stitchkit 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -12,6 +12,48 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-09-01
+
+Three findings from someone setting up a new application on the starter from
+scratch, as a consumer who had never seen it. All of them live between "the
+scaffold is green" and "my first feature renders".
+
+### Fixed
+
+- **The generated `.env` no longer looks ready when it is not.** `local-env.ts`
+  rendered the database name and left `USER:PASSWORD` literal, in a file a
+  generator had just written — and a generated file reads as finished.
+  `assertUsableEnvironment` now names the file, the line and the variable, and
+  covers `ACCEPTANCE_DATABASE_URL` as well as `DATABASE_URL`. It runs before the
+  supervisor check, so an unusable environment is reported instead of a pm2
+  error, and on every run rather than only the one that created the file.
+  Rendering still succeeds: a generator that refuses to generate would break
+  `--no-install` scaffolding.
+
+- **`CREATEDB` is named where `DATABASE_URL` is named.** `prisma migrate dev`
+  creates a shadow database, so a least-privilege role — the sensible default
+  on a shared server — fails `db:migrate` with `P3014`. Neither the README nor
+  `_env.example` mentioned it.
+
+- **`check:authored` no longer refuses `as const`.** The gate exists to catch a
+  cast that can *launder* a type; a const-assertion only narrows, introduces no
+  name and cannot widen. Five of the first fifteen findings on a real adoption
+  were this false positive. Findings now also name the sanctioned alternative
+  instead of only the sin.
+
+- **`ADDING_A_FEATURE.md` no longer points at files the scaffold lacks.** Steps
+  4 and 5 referenced `lib/api/client.ts` and a "shared realtime source" that a
+  generated project does not contain, phrased as "the same pattern used by the
+  application's other contracts" — of which there were none. Both steps now
+  create what they need, with the transport file given in full.
+
+### Added
+
+- **`check:guides`**, part of `check`: every repository path a guide names must
+  exist, unless the guide declares it with `(created in this step)`. The guide
+  had five such references and three of them were legitimate; only a gate tells
+  those apart reliably.
+
 ## [0.5.0] — 2026-09-01
 
 ### ⚠️ Breaking changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/README.md

@@ -29,6 +29,17 @@ Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
 bun run dev
 ```
 
+`.env` is generated on first run with the database name filled in and the
+credentials left as `USER:PASSWORD`. Replace them: `dev` refuses to start while
+the placeholder is there, naming the file and the line, rather than letting the
+driver fail on the first request.
+
+**The role that runs `bun run db:migrate` needs `CREATEDB`.** `prisma migrate
+dev` creates a throwaway shadow database to diff against, so a least-privilege
+role — the sensible default for a shared server — fails with `P3014: could not
+create the shadow database`. Grant `CREATEDB` to the development role, or point
+Prisma at a shadow database you create yourself.
+
 The command validates the environment, generates the Prisma client, applies any
 database migrations you add and launches:
 

package/template/_env.example

@@ -1,4 +1,7 @@
 NODE_ENV=development
+# Replace USER:PASSWORD before the first `bun run dev` — it refuses to start
+# while they are here. The role also needs CREATEDB if it will run
+# `db:migrate`: `prisma migrate dev` creates a shadow database to diff against.
 DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
 # The throwaway database `bun run acceptance:local` creates and writes to. The
 # runtime gates WRITE, so they get one of their own: the harness refuses to

package/template/docs/ADDING_A_FEATURE.md

@@ -7,7 +7,7 @@ same files beside it.
 
 ## 1. Define the wire data
 
-Create `packages/shared/src/schemas/status.ts`:
+Create `packages/shared/src/schemas/status.ts` (created in this step):
 
 ```ts
 import { z } from 'zod'
@@ -21,7 +21,7 @@ Export it from the shared package. Do not introduce a second handwritten DTO.
 
 ## 2. Define the HTTP/tool contract separately
 
-Create `packages/shared/src/contracts/status.ts` and import the named schemas:
+Create `packages/shared/src/contracts/status.ts` (created in this step) and import the named schemas:
 
 ```ts
 import { defineContract } from 'stitchkit'
@@ -44,7 +44,7 @@ The contract owns transport identity. Do not add a raw route or duplicate path.
 
 ## 3. Implement and register the service
 
-Create `packages/backend/src/transport/status-service.ts` with `implement()`.
+Create `packages/backend/src/transport/status-service.ts` (created in this step) with `implement()`.
 Keep persistence and business rules in a domain/service module; the contract
 handler calls that module once. Add the returned service to the `services` array
 in `packages/backend/src/surface.ts`. That one registration drives HTTP,
@@ -52,20 +52,44 @@ OpenAPI, MCP, agent tools and CLI discovery.
 
 ## 4. Add typed browser access
 
-Export `statusContract` from `packages/shared/src/index.ts`. In
-`packages/frontend/src/lib/api/client.ts`, create `statusApi` with the same
-`createClient(statusContract, http)` pattern used by the application's other
-contracts. Create the query key and react-query-kit query/mutation hooks in
-`packages/frontend/src/lib/api/status.ts`. On mutation success, update or
-invalidate that canonical key.
+Export `statusContract` from `packages/shared/src/index.ts`.
+
+The scaffold ships no browser transport layer, and that is the first thing this
+step builds. It also makes one decision for you, because the starter already
+made it: **no address is compiled into the artifact.** `packages/frontend/src/env.ts`
+declares no `client` block on purpose — a `NEXT_PUBLIC_` variable is substituted
+at build time, which freezes a value of the place into the bundle. So the client
+is a factory over an origin the server reads per request, never a module-level
+constant.
+
+Create `packages/frontend/src/lib/api/client.ts` (created in this step):
+
+```ts
+import { createClient, createHttpClient } from 'stitchkit'
+import { statusContract } from '@app/shared'
+
+/** One origin per request, supplied by the server — never read from the bundle. */
+export function createStatusApi(origin: string) {
+  return createClient(statusContract, createHttpClient({ prefixUrl: origin }))
+}
+```
+
+Create `packages/frontend/src/lib/api/status.ts` (created in this step) for the
+query key and the react-query-kit hooks, and keep the key canonical — one key
+per resource, updated or invalidated on mutation success.
+
+A server component reads `env.PUBLIC_API_ORIGIN` and hands it down as a prop;
+the client component calls `createStatusApi(origin)`. That is the whole reason
+`PUBLIC_API_ORIGIN` is a server variable rather than a public one.
 
 Render the hook from a feature component. Pages compose features; they do not
 call `fetch`, construct `/api/status` or decode error bodies themselves.
 
 ## 5. Add realtime only when another client must observe the change
 
-Declare the event in the shared realtime source and use a named Zod schema for
-its tuple. The server emits after the domain change succeeds; the frontend cache
+Create `packages/shared/src/realtime.ts` (created in this step) and declare the
+event there with a named Zod schema for its tuple — the scaffold ships no
+realtime module, so this step introduces it rather than assuming it. The server emits after the domain change succeeds; the frontend cache
 bridge reacts by updating or invalidating the status query. Keep handshake auth,
 authorization and room membership in the application. Socket.IO delivery,
 reconnection, retained subscriptions and validation belong to Stitchkit.

package/template/package.json

@@ -11,8 +11,9 @@
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
-    "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
+    "check": "bun run db:generate && bun run check:authored && bun run check:guides && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
+    "check:guides": "bun scripts/guide-paths.ts",
     "test": "bun test scripts && bun run --filter '*' test",
     "build": "bun scripts/build-inputs.ts && bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build && bun scripts/build-stamp.ts",
     "start:api": "bun --filter @app/backend start",

package/template/scripts/check-authored.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'bun:test';
+import { inspect } from './check-authored';
+
+describe('check:authored — assertions', () => {
+  test('lets a const assertion through: it narrows and cannot launder a type', () => {
+    const source = [
+      "export const benchKeys = { jobs: ['bench', 'jobs'] as const };",
+      "export const modes = ['fast', 'full'] as const;",
+      '',
+    ].join('\n');
+    expect(inspect('packages/shared/src/bench.ts', source)).toEqual([]);
+  });
+
+  test('still refuses a real assertion, and the finding names what to do instead', () => {
+    const findings = inspect(
+      'packages/shared/src/parse.ts',
+      'const parsed = JSON.parse(raw) as Payload;\n',
+    );
+    expect(findings).toHaveLength(1);
+    const [finding] = findings;
+    // Line and file, so it is navigable…
+    expect(finding).toContain('packages/shared/src/parse.ts:1');
+    // …and the remedy, so the reader does not have to search for the sanctioned way.
+    expect(finding).toContain('satisfies');
+    expect(finding).toContain('schema at the boundary');
+  });
+
+  test('the angle-bracket form is refused too, and explicit any separately', () => {
+    expect(inspect('scripts/x.ts', 'const a = <Foo>bar;\n')).toHaveLength(1);
+    const anyFindings = inspect('scripts/y.ts', 'function f(a: any) { return a; }\n');
+    expect(anyFindings).toHaveLength(1);
+    expect(anyFindings[0]).toContain('explicit any');
+  });
+
+  test('a const assertion beside a real one reports only the real one', () => {
+    const findings = inspect(
+      'scripts/mixed.ts',
+      "const keys = ['a'] as const;\nconst value = raw as Payload;\n",
+    );
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toContain('scripts/mixed.ts:2');
+  });
+});

package/template/scripts/check-authored.ts

@@ -20,15 +20,42 @@ function lineAt(source: string, offset: number): number {
   return source.slice(0, offset).split('\n').length;
 }
 
-function inspect(path: string, source: string): string[] {
+/**
+ * `as const` is not the assertion this gate exists for.
+ *
+ * The gate refuses a cast because a cast can LAUNDER a type — claim something the value has not
+ * been shown to be. A const-assertion cannot: it only narrows, it introduces no name, and it
+ * cannot widen. Refusing it made five of the first fifteen findings on a real adoption false, in
+ * a gate whose whole value is that its findings are worth acting on.
+ *
+ * `const` is a reserved word, so no type can be named `const` — the check has no false positive
+ * of its own.
+ */
+function isConstAssertion(node: { typeAnnotation?: unknown }): boolean {
+  const annotation = node.typeAnnotation;
+  if (!isRecord(annotation) || annotation.type !== 'TSTypeReference') return false;
+  const typeName = annotation.typeName;
+  return isRecord(typeName) && typeName.type === 'Identifier' && typeName.name === 'const';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** What to do instead — a finding that only names the sin costs the reader a search. */
+const ASSERTION_REMEDY =
+  'type assertion — use `satisfies` to check a literal against a type, or parse the value with its schema at the boundary';
+
+export function inspect(path: string, source: string): string[] {
   const result = parseSync(path, source);
   const failures = result.errors.map((error) => `${path}: parse error: ${error.message}`);
   const visitor = new Visitor({
     TSAsExpression(node) {
-      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
+      if (isConstAssertion(node)) return;
+      failures.push(`${path}:${lineAt(source, node.start)}: ${ASSERTION_REMEDY}`);
     },
     TSTypeAssertion(node) {
-      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
+      failures.push(`${path}:${lineAt(source, node.start)}: ${ASSERTION_REMEDY}`);
     },
     TSAnyKeyword(node) {
       failures.push(`${path}:${lineAt(source, node.start)}: explicit any`);
@@ -91,21 +118,25 @@ async function visitDirectory(directory: string): Promise<string[]> {
   return failures;
 }
 
-const failures = [
-  ...(await Promise.all(roots.map(visitDirectory))).flat(),
-  ...(
-    await Promise.all(
-      rootFiles.map(async (path) => inspect(path, await readFile(path, 'utf8'))),
-    )
-  ).flat(),
-];
-const webPackage = await readFile('packages/frontend/package.json', 'utf8');
-if (webPackage.includes(replacedThemePackage)) {
-  failures.push(
-    'packages/frontend/package.json: use @wrksz/themes as the single theme runtime',
-  );
-}
-if (failures.length > 0) {
-  for (const failure of failures) console.error(failure);
-  process.exit(1);
+// Guarded so the module can be imported by its own test without running the gate over the
+// repository — importing a script that scans the tree and exits is not a testable unit.
+if (import.meta.main) {
+  const failures = [
+    ...(await Promise.all(roots.map(visitDirectory))).flat(),
+    ...(
+      await Promise.all(
+        rootFiles.map(async (path) => inspect(path, await readFile(path, 'utf8'))),
+      )
+    ).flat(),
+  ];
+  const webPackage = await readFile('packages/frontend/package.json', 'utf8');
+  if (webPackage.includes(replacedThemePackage)) {
+    failures.push(
+      'packages/frontend/package.json: use @wrksz/themes as the single theme runtime',
+    );
+  }
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(failure);
+    process.exit(1);
+  }
 }

package/template/scripts/dev.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { z } from 'zod';
 import { appDeclaration } from '../packages/config/src/declaration';
-import { ensureLocalEnvironment } from './local-env';
+import { assertUsableEnvironment, ensureLocalEnvironment } from './local-env';
 import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
 import { runDeclaredReleaseSteps } from './release-steps';
 import { inheritToolingEnvironment } from './tooling-env';
@@ -21,9 +21,14 @@ async function run(command: string[], environment?: Record<string, string>): Pro
 
 export async function runDevelopment(environment?: Record<string, string>): Promise<void> {
   ensureLocalEnvironment(root);
+  // Before pm2, before anything: an unusable environment is the reader's problem to fix, and
+  // making them read a supervisor error first only delays the sentence that matters.
+  assertUsableEnvironment(root);
   assertToolAvailable('pm2', 'Install PM2 with `bun add --global pm2`, then rerun.');
   await run(['pm2', 'ping']);
   const environmentForRun = await developmentEnvironment(environment);
+  // Kept for an environment supplied from the shell rather than from `.env`, which the file
+  // check above cannot see.
   if (environmentForRun.DATABASE_URL?.includes('USER:PASSWORD')) {
     throw new Error(
       'DATABASE_URL still contains the starter placeholder. Create a PostgreSQL database, update DATABASE_URL in .env, then rerun `bun run dev`.',

package/template/scripts/guide-paths.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import { inspectGuide, inspectGuides } from './guide-paths';
+
+const present = (path: string) => path === 'packages/shared/src/index.ts';
+
+describe('guide paths', () => {
+  test('reports a path the guide names but the scaffold lacks', () => {
+    const findings = inspectGuide(
+      'docs/G.md',
+      'In `packages/frontend/src/lib/api/client.ts`, create the api.\n',
+      present,
+    );
+    expect(findings).toEqual([
+      { guide: 'docs/G.md', line: 1, path: 'packages/frontend/src/lib/api/client.ts' },
+    ]);
+  });
+
+  test('a path the guide creates is declared, not broken', () => {
+    const source = 'Create `packages/shared/src/realtime.ts` (created in this step) and…\n';
+    expect(inspectGuide('docs/G.md', source, present)).toEqual([]);
+  });
+
+  test('an existing path is quiet, and prose without a path is quiet', () => {
+    expect(
+      inspectGuide('docs/G.md', 'Export it from `packages/shared/src/index.ts`.\n', present),
+    ).toEqual([]);
+    expect(inspectGuide('docs/G.md', 'Pages compose features.\n', present)).toEqual([]);
+  });
+
+  test('the real guide resolves every path it does not create', async () => {
+    // The denominator matters: a guide the scanner cannot read would also return [].
+    const findings = await inspectGuides(`${import.meta.dir}/..`);
+    expect(findings).toEqual([]);
+    const anyPath = inspectGuide('docs/G.md', 'See `packages/absent/x.ts`.\n', () => false);
+    expect(anyPath).toHaveLength(1);
+  });
+});

package/template/scripts/guide-paths.ts

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+/**
+ * Every repository path a guide names has to exist.
+ *
+ * `ADDING_A_FEATURE.md` is the one document a new consumer executes literally, and two of its
+ * steps pointed at files the scaffold does not contain — `lib/api/client.ts` and a "shared
+ * realtime source". The reader does not learn that by reading; they learn it by opening the path
+ * and finding nothing, after having already trusted the sentence around it.
+ *
+ * A path the guide tells you to CREATE is not a broken reference, so those are declared by the
+ * guide itself: a line that introduces one carries `(created in this step)`. Everything else
+ * must resolve.
+ */
+const GUIDES = ['docs/ADDING_A_FEATURE.md'];
+const PATH_PATTERN = /`((?:packages|scripts|docs|e2e)\/[A-Za-z0-9_./-]+)`/g;
+
+export interface GuidePathFinding {
+  readonly guide: string;
+  readonly line: number;
+  readonly path: string;
+}
+
+export function inspectGuide(
+  guide: string,
+  source: string,
+  exists: (path: string) => boolean,
+): GuidePathFinding[] {
+  const findings: GuidePathFinding[] = [];
+  source.split('\n').forEach((text, index) => {
+    if (text.includes('(created in this step)')) return;
+    for (const match of text.matchAll(PATH_PATTERN)) {
+      const path = match[1];
+      if (!path || exists(path)) continue;
+      findings.push({ guide, line: index + 1, path });
+    }
+  });
+  return findings;
+}
+
+export async function inspectGuides(root: string): Promise<GuidePathFinding[]> {
+  const findings: GuidePathFinding[] = [];
+  for (const guide of GUIDES) {
+    const absolute = resolve(root, guide);
+    if (!existsSync(absolute)) {
+      findings.push({ guide, line: 0, path: guide });
+      continue;
+    }
+    findings.push(
+      ...inspectGuide(guide, await readFile(absolute, 'utf8'), (path) =>
+        existsSync(join(root, path)),
+      ),
+    );
+  }
+  return findings;
+}
+
+if (import.meta.main) {
+  const findings = await inspectGuides(resolve(import.meta.dir, '..'));
+  for (const { guide, line, path } of findings) {
+    console.error(`${guide}:${line}: names ${path}, which does not exist`);
+  }
+  if (findings.length > 0) process.exit(1);
+}

package/template/scripts/local-env.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { appDeclaration } from '../packages/config/src/declaration';
-import { ensureLocalEnvironment } from './local-env';
+import { assertUsableEnvironment, ensureLocalEnvironment } from './local-env';
 
 describe('ensureLocalEnvironment', () => {
   test('renders the application identity into a fresh .env and never touches an existing one', async () => {
@@ -13,7 +13,10 @@ describe('ensureLocalEnvironment', () => {
         join(root, '.env.example'),
         'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
       );
+      // Rendering succeeds — a generator that refuses to generate would break `--no-install`
+      // scaffolding — and the separate usability check is what refuses.
       ensureLocalEnvironment(root);
+      expect(() => assertUsableEnvironment(root)).toThrow(/USER:PASSWORD/);
       const created = await readFile(join(root, '.env'), 'utf8');
       // In the neutral dev workspace the slug IS the neutral identity, so the
       // substitution is proven end-to-end by the starter lane on a renamed
@@ -39,10 +42,56 @@ describe('ensureLocalEnvironment', () => {
         'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
       );
       ensureLocalEnvironment(root);
+      expect(() => assertUsableEnvironment(root)).toThrow(/USER:PASSWORD/);
       const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
       expect(await readFile(join(root, '.env'), 'utf8')).toContain(`5432/${databaseName}`);
     } finally {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test('an unedited .env is refused on every later run, not only the one that wrote it', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-env-again-'));
+    try {
+      // No example at all: the file is already there, exactly as a second `bun run dev` finds it.
+      await writeFile(
+        join(root, '.env'),
+        'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/app\n',
+      );
+      let message = '';
+      try {
+        assertUsableEnvironment(root);
+      } catch (error) {
+        message = error instanceof Error ? error.message : String(error);
+      }
+      // The message has to name the file, the line and the privilege the next step needs —
+      // a refusal that only says "invalid" moves the search back to the reader.
+      expect(message).toContain('.env:1');
+      expect(message).toContain('DATABASE_URL');
+      expect(message).toContain('CREATEDB');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test('a commented example line is not mistaken for an unresolved credential', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-env-comment-'));
+    try {
+      // The placeholder is assembled rather than written: spelled out it is a credential inside
+      // a URL, which the publication-privacy gate refuses on sight — rightly, since "it is only
+      // a fixture" is the argument every leak makes. Same idiom as `check-authored.ts`.
+      const placeholder = ['USER', 'PASSWORD'].join(':');
+      await writeFile(
+        join(root, '.env'),
+        [
+          `# DATABASE_URL=postgresql://${placeholder}@127.0.0.1:5432/example`,
+          'DATABASE_URL=postgresql://127.0.0.1:5432/app',
+          '',
+        ].join('\n'),
+      );
+      expect(() => assertUsableEnvironment(root)).not.toThrow();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/template/scripts/local-env.ts

@@ -19,18 +19,62 @@ import { appIdentity } from '../packages/config/src/app-identity.generated';
  * environment too. Synchronous on purpose: `playwright.config.ts` and other
  * synchronous entry points must be able to self-heal before validating.
  */
-export function ensureLocalEnvironment(root: string): void {
+/**
+ * The credentials this file renders but cannot know.
+ *
+ * `.env.example` ships a connection string with literal `USER:PASSWORD`, and this script
+ * substitutes only the database name. A file that is generated, edited by the generator and then
+ * left unusable is the worst of the three: the reader assumes a generated file is ready. So the
+ * placeholder is named here rather than discovered as a driver stack on the first request.
+ */
+function unresolvedCredentialLines(destination: string): string[] {
+  return readFileSync(destination, 'utf8')
+    .split('\n')
+    .map((line, index) => ({ line: line.trim(), number: index + 1 }))
+    .filter(({ line }) => !line.startsWith('#') && line.includes('USER:PASSWORD'))
+    .map(({ line, number }) => `  ${destination}:${number}  ${line.split('=')[0] ?? line}`);
+}
+
+/**
+ * Refuse to start on an environment that still carries the example credentials.
+ *
+ * Separate from rendering on purpose: a generator that refuses to generate is wrong — `--no-install`
+ * scaffolding renders `.env` before anyone could have filled it in — while a start that proceeds
+ * into a driver stack is the defect. So `env:ensure` writes and reports; `dev` writes and refuses.
+ */
+export function assertUsableEnvironment(root: string): void {
   const destination = resolve(root, '.env');
-  if (existsSync(destination)) return;
-  const publicExample = resolve(root, '.env.example');
-  const example = readFileSync(
-    existsSync(publicExample) ? publicExample : resolve(root, '_env.example'),
-    'utf8',
+  const unresolved = unresolvedCredentialLines(destination);
+  if (unresolved.length === 0) return;
+  throw new Error(
+    `This environment still carries the example credentials.\n${unresolved.join('\n')}\n` +
+      'Replace USER:PASSWORD with a role that can reach your PostgreSQL server. ' +
+      'A role that runs `db:migrate` also needs CREATEDB, because `prisma migrate dev` ' +
+      'creates a shadow database.',
   );
-  const databaseName = appIdentity.slug.replaceAll('-', '_');
-  writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
+}
+
+export function ensureLocalEnvironment(root: string): void {
+  const destination = resolve(root, '.env');
+  if (!existsSync(destination)) {
+    const publicExample = resolve(root, '.env.example');
+    const example = readFileSync(
+      existsSync(publicExample) ? publicExample : resolve(root, '_env.example'),
+      'utf8',
+    );
+    const databaseName = appIdentity.slug.replaceAll('-', '_');
+    writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
+  }
 }
 
 if (import.meta.main) {
-  ensureLocalEnvironment(resolve(import.meta.dir, '..'));
+  const root = resolve(import.meta.dir, '..');
+  ensureLocalEnvironment(root);
+  // Reported, not fatal: this command's job is to produce the file, and it has.
+  const unresolved = unresolvedCredentialLines(resolve(root, '.env'));
+  if (unresolved.length > 0) {
+    process.stderr.write(
+      `.env still carries the example credentials — \`bun run dev\` will refuse until they are replaced:\n${unresolved.join('\n')}\n`,
+    );
+  }
 }