feat(cli): prisma-composer dev — bring the whole app up locally, credential-free

.github/workflows/ci.yml

@@ -76,6 +76,25 @@ jobs:
       # under CI concurrency.
       - name: Build packages
         run: pnpm build
+      # `@prisma/dev` (the ORM's local-Postgres server — the local-dev
+      # integration proofs' postgres-main daemon hosts it programmatically
+      # via `startPrismaDevServer`) downloads its database engine binaries
+      # on its first-ever invocation on a machine. A dev workstation
+      # accumulates that cache across sessions; a CI runner starts genuinely
+      # cold every time. Isolating the download in its own step (the `prisma`
+      # CLI drives the same `@prisma/dev` engine cache) gives it a clear,
+      # attributable failure (network egress to the engine host, disk
+      # space, ...) instead of surfacing buried inside a 5-service
+      # `alchemy deploy` three provider frames deep — which is exactly what
+      # made the failure this step's own commit message references
+      # undiagnosable. The instance itself is disposable; only its download
+      # populates the shared engine cache every later invocation (the
+      # integration proofs') reuses.
+      - name: Warm the prisma dev engine cache
+        working-directory: test/integration
+        run: |
+          pnpm exec prisma dev --name ci-engine-warmup --detach
+          pnpm exec prisma dev rm ci-engine-warmup --force
       - name: Test
         env:
           STATE_TEST_DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres

packages/0-framework/1-core/core/src/control/app-config.ts

@@ -145,6 +145,8 @@ export interface LocalTargetAttachInput {
 }
 
 export interface LocalTargetAttachment {
+  /** Start every stopped service from its last deployment (the session-resume signal — a no-op converge cannot start anything). */
+  startServices(): Promise<void>;
   /** Every service's local endpoint, for the front door. */
   endpoints(): Promise<readonly { readonly address: string; readonly url: string }[]>;
   /** Merged, line-oriented log stream across the app's services (including services that appear after later converges). Ends when `signal` aborts. */

packages/0-framework/3-tooling/cli/package.json

@@ -19,6 +19,7 @@
     "@internal/core": "workspace:0.2.0",
     "@internal/foundation": "workspace:0.2.0",
     "c12": "^3.3.4",
+    "chokidar": "^4.0.3",
     "clipanion": "^3.2.1"
   },
   "devDependencies": {

packages/0-framework/3-tooling/cli/src/__tests__/main.test.ts

@@ -10,6 +10,7 @@ describe('parseArgs() (clipanion-backed)', () => {
       name: undefined,
       stage: undefined,
       production: false,
+      fresh: false,
     });
   });
 
@@ -21,6 +22,7 @@ describe('parseArgs() (clipanion-backed)', () => {
         name: 'ci-run',
         stage: 'prod',
         production: false,
+        fresh: false,
       },
     );
     expect(parseArgs(['deploy', '--stage', 'prod', 'src/service.ts', '--name', 'ci-run'])).toEqual({
@@ -29,6 +31,7 @@ describe('parseArgs() (clipanion-backed)', () => {
       name: 'ci-run',
       stage: 'prod',
       production: false,
+      fresh: false,
     });
   });
 
@@ -39,6 +42,7 @@ describe('parseArgs() (clipanion-backed)', () => {
       name: undefined,
       stage: undefined,
       production: true,
+      fresh: false,
     });
   });
 
@@ -77,6 +81,37 @@ describe('parseArgs() (clipanion-backed)', () => {
       name: '',
       stage: undefined,
       production: false,
+      fresh: false,
     });
   });
+
+  test('parses a bare dev invocation', () => {
+    expect(parseArgs(['dev', 'src/service.ts'])).toEqual({
+      command: 'dev',
+      entry: 'src/service.ts',
+      name: undefined,
+      stage: undefined,
+      production: false,
+      fresh: false,
+    });
+  });
+
+  test('parses dev --name and --fresh', () => {
+    expect(parseArgs(['dev', 'src/service.ts', '--name', 'ci-run', '--fresh'])).toEqual({
+      command: 'dev',
+      entry: 'src/service.ts',
+      name: 'ci-run',
+      stage: undefined,
+      production: false,
+      fresh: true,
+    });
+  });
+
+  test('throws UsageError when dev is passed --stage', () => {
+    expect(() => parseArgs(['dev', 'src/service.ts', '--stage', 'prod'])).toThrow(UsageError);
+  });
+
+  test('throws UsageError when dev is passed --production', () => {
+    expect(() => parseArgs(['dev', 'src/service.ts', '--production'])).toThrow(UsageError);
+  });
 });

packages/0-framework/3-tooling/cli/src/dev/__tests__/generate-dev-stack.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'bun:test';
+import { renderDevStackFile } from '../generate-dev-stack.ts';
+
+describe('renderDevStackFile()', () => {
+  test('renders the config + app imports (relative), resolved dev providers, localState(), no report', () => {
+    const content = renderDevStackFile({
+      entryPath: '/repo/app/module.ts',
+      cwd: '/repo/app',
+      configPath: '/repo/app/prisma-composer.config.ts',
+      name: 'app',
+      assembled: {
+        bundles: {
+          web: { dir: '/repo/app/modules/web/dist/bundle', entry: 'server.js' },
+        },
+      },
+    });
+
+    expect(content).toContain("import { lower } from '@prisma/composer/deploy';");
+    expect(content).toContain("import { deserializeContainers } from '@prisma/composer/config';");
+    expect(content).toContain(
+      "import { DEV_DIR, localTargetProviders, resolveLocalTargets } from '@prisma/composer/local-target';",
+    );
+    expect(content).toContain("import { localState } from 'alchemy/State/LocalState';");
+    expect(content).toContain('import config from "../../prisma-composer.config.ts";');
+    expect(content).toContain('import app from "../../module.ts";');
+    // The one orchestration point (spec § 3 REVISED): containers
+    // deserialized, `localTarget` thunks resolved by top-level await,
+    // providers + state passed explicitly — and no `dev` flag, which no
+    // longer exists on LowerOptions.
+    expect(content).toContain(
+      'const containers = deserializeContainers(config.extensions, process.env);',
+    );
+    expect(content).toContain('const resolved = await resolveLocalTargets(config);');
+    expect(content).toContain('const devDir = path.join(process.cwd(), DEV_DIR);');
+    expect(content).toContain('lower(app, config, {');
+    expect(content).toContain('name: "app"');
+    expect(content).toContain('providers: localTargetProviders(resolved, containers, devDir)');
+    expect(content).toContain('state: localState()');
+    expect(content).not.toContain('dev: true');
+    expect(content).toContain(
+      '"web": { dir: "/repo/app/modules/web/dist/bundle", entry: "server.js" }',
+    );
+    // Dev prints its own front door — no report hook in the generated module.
+    expect(content).not.toContain('report:');
+    expect(content).not.toContain('deploymentReport');
+  });
+
+  test('the header comment names the --stage dev reproduction command', () => {
+    const content = renderDevStackFile({
+      entryPath: '/repo/app/module.ts',
+      cwd: '/repo/app',
+      configPath: '/repo/app/prisma-composer.config.ts',
+      name: 'app',
+      assembled: { bundles: {} },
+    });
+
+    expect(content).toContain('alchemy deploy .prisma-composer/dev/alchemy.run.ts --stage dev');
+  });
+});

packages/0-framework/3-tooling/cli/src/dev/__tests__/run-dev.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test';
+import { renderFrontDoor } from '../run-dev.ts';
+
+describe('renderFrontDoor()', () => {
+  test('starts with "[dev] ready:", then orders by address depth (fewest dots first), then lexicographic', () => {
+    const lines = renderFrontDoor([
+      { address: 'storefront.web', url: 'http://localhost:3002' },
+      { address: 'web', url: 'http://localhost:3000' },
+      { address: 'api', url: 'http://localhost:3001' },
+      { address: 'storefront.admin', url: 'http://localhost:3003' },
+    ]);
+
+    expect(lines).toEqual([
+      '[dev] ready:',
+      '[dev] api  http://localhost:3001',
+      '[dev] web  http://localhost:3000',
+      '[dev] storefront.admin  http://localhost:3003',
+      '[dev] storefront.web  http://localhost:3002',
+    ]);
+  });
+
+  test('an empty endpoint list still prints the ready line alone', () => {
+    expect(renderFrontDoor([])).toEqual(['[dev] ready:']);
+  });
+});

packages/0-framework/3-tooling/cli/src/dev/__tests__/watch.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { startWatch, watchTargetsFrom } from '../watch.ts';
+
+function tempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'cli-watch-'));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('watchTargetsFrom()', () => {
+  test('a bundle with no watch field is reported unwatchable, not a target', () => {
+    const { targets, unwatchable } = watchTargetsFrom({
+      web: { dir: '/tmp/web', entry: 'server.js' },
+    });
+    expect(targets).toEqual([]);
+    expect(unwatchable).toEqual(['web']);
+  });
+});
+
+describe('startWatch()', () => {
+  test('debounces a burst of changes across several files into one callback, 300ms after the last change', async () => {
+    const dir = tempDir();
+    const fileA = path.join(dir, 'a.txt');
+    const fileB = path.join(dir, 'b.txt');
+    fs.writeFileSync(fileA, 'a');
+    fs.writeFileSync(fileB, 'b');
+
+    let calls = 0;
+    const stop = startWatch(
+      [
+        { address: 'a', paths: [fileA] },
+        { address: 'b', paths: [fileB] },
+      ],
+      () => {
+        calls += 1;
+      },
+    );
+
+    try {
+      // A burst across both files, all inside the 300ms debounce window.
+      fs.writeFileSync(fileA, 'a2');
+      await sleep(50);
+      fs.writeFileSync(fileB, 'b2');
+      await sleep(50);
+      fs.writeFileSync(fileA, 'a3');
+
+      // Still inside the debounce window from the last write — no callback yet.
+      await sleep(100);
+      expect(calls).toBe(0);
+
+      // Past the 300ms debounce from the last write.
+      await sleep(300);
+      expect(calls).toBe(1);
+    } finally {
+      stop();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }, 10_000);
+
+  test('a stopped watch fires no further callbacks', async () => {
+    const dir = tempDir();
+    const file = path.join(dir, 'a.txt');
+    fs.writeFileSync(file, 'a');
+
+    let calls = 0;
+    const stop = startWatch([{ address: 'a', paths: [file] }], () => {
+      calls += 1;
+    });
+    stop();
+
+    fs.writeFileSync(file, 'a2');
+    await sleep(500);
+    expect(calls).toBe(0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }, 10_000);
+
+  test('survives a delete-then-recreate rebuild of the watched file (rm -rf && bun build --outfile)', async () => {
+    // A single-file `fs.watch` bound to the original inode goes silently
+    // dead after the file is unlinked and a new one created at the same
+    // path — exactly what `rm -rf dist && bun build --outfile dist/x.mjs`
+    // does on every rebuild. Found live against examples/store's catalog
+    // service during the S5 proving pass; the fix at the time was a
+    // hand-rolled parent-directory watch, since replaced by chokidar
+    // (design tip 74272d8), which absorbs this class of rename/inode-swap
+    // itself. The regression this test guards against is unchanged, so its
+    // assertions stay exactly as they were — only the engine underneath
+    // changed.
+    const dir = tempDir();
+    const file = path.join(dir, 'server.mjs');
+    fs.writeFileSync(file, 'v1');
+
+    let calls = 0;
+    const stop = startWatch([{ address: 'catalog', paths: [file] }], () => {
+      calls += 1;
+    });
+    // chokidar's own watch setup is asynchronous (it returns synchronously,
+    // then finishes attaching OS-level watches shortly after) — a grace
+    // window before the first change, not a change to what's asserted.
+    await sleep(100);
+
+    try {
+      fs.rmSync(file);
+      fs.writeFileSync(file, 'v2');
+      await sleep(400);
+      expect(calls).toBe(1);
+
+      // A SECOND delete+recreate — the exact case that broke a
+      // file-bound (not directory-bound) watch.
+      fs.rmSync(file);
+      fs.writeFileSync(file, 'v3');
+      await sleep(400);
+      expect(calls).toBe(2);
+    } finally {
+      stop();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }, 10_000);
+});