create-justscale 0.1.0

package/templates/skills/multi-instance-test/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: multi-instance-test
+description: Scaffold a JustScale multi-instance e2e test that spawns two real Node worker processes coordinating through a shared Postgres + Redis. Verifies cross-instance invariants — lock mutual exclusion, signal NOTIFY routing, channel delivery, process resumption after crash. Use when testing distributed primitives, NEVER for single-node logic.
+---
+
+# Skill: multi-instance-test
+
+Scaffold an e2e test that spawns TWO real worker processes and asserts an
+invariant holds across them. The canonical pattern lives at
+`packages/misc/e2e/test/mixed-adapter-multi-process.e2e.test.ts`. Read it
+before extending it.
+
+## Why two real processes
+
+JustScale's distributed primitives — locks, channels, signals, durable
+processes — are meaningless under a single Node process. A single-process
+test cannot catch:
+
+- Two nodes both believing they hold the same lock.
+- A signal `NOTIFY` routing to the wrong process replica.
+- A channel publish that the second subscriber misses.
+- A durable process suspending on instance A and resuming on instance B.
+
+For these primitives the multi-process test IS the test. Memory rule from
+this repo: **don't fake the second instance with a mock or a second
+builder in the same process**. The whole point is two real OS processes
+coordinating through a real shared backend.
+
+## Requirements
+
+- Docker Postgres on port `5433` (default `PG_URL=postgres://justscale:justscale@localhost:5433/postgres`).
+- Docker Redis on port `6380` (default `REDIS_URL=redis://localhost:6380`).
+- The test should `before(...)` probe both and **skip with a clear message** if either is unreachable. Don't fail — let CI decide.
+
+## Two-file pattern
+
+A multi-instance test is always two files in the same folder:
+
+1. **`<scenario>/worker.ts`** — the entrypoint each spawned process runs.
+   Reads its wiring from env vars, builds the app, calls `listen()`,
+   prints `READY <port>` to stdout once `app.ready` resolves.
+2. **`<scenario>.e2e.test.ts`** — the driver. Spawns workers via
+   `child_process.spawn`, talks to them over HTTP, asserts.
+
+## Worker template
+
+```typescript
+// <scenario>/worker.ts
+import { listen } from '@justscale/http';
+import { makeApp } from './app.js';
+
+async function main() {
+  const port = Number(process.env.PORT);
+  const pgUrl = process.env.PG_URL!;
+  const redisUrl = process.env.REDIS_URL!;
+  const lockBackend = process.env.LOCK_BACKEND as 'pg-advisory' | 'redis';
+  const channelBackend = process.env.CHANNEL_BACKEND as 'pg' | 'redis' | 'memory';
+  const instanceId = process.env.INSTANCE_ID ?? 'X';
+  const prefix = process.env.CHANNEL_PREFIX!;
+
+  const { builder } = makeApp({ port, pgUrl, redisUrl, lockBackend, channelBackend, instanceId, prefix });
+  const built = builder.build();
+  const app = built.compile();
+  await app.ready;
+
+  const server = listen(app, port);
+  await new Promise<void>((resolve, reject) => {
+    server.once('listening', resolve);
+    server.once('error', reject);
+  });
+
+  // Stdout liveness signal — the driver waits for this line.
+  console.log(`READY ${port}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+## Driver template
+
+```typescript
+// <scenario>.e2e.test.ts
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { once } from 'node:events';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKER = path.join(__dirname, '<scenario>', 'worker.ts');
+const TSX = path.join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+
+const PG_URL = process.env.PG_URL ?? 'postgres://justscale:justscale@localhost:5433/postgres';
+const REDIS_URL = process.env.REDIS_URL ?? 'redis://localhost:6380';
+
+async function spawnWorker(opts: { port: number; instanceId: 'A' | 'B'; prefix: string }): Promise<ChildProcess> {
+  const child = spawn(process.execPath, [TSX, WORKER], {
+    env: {
+      ...process.env,
+      PORT: String(opts.port),
+      INSTANCE_ID: opts.instanceId,
+      CHANNEL_PREFIX: opts.prefix,
+      PG_URL,
+      REDIS_URL,
+      LOCK_BACKEND: 'pg-advisory',
+      CHANNEL_BACKEND: 'pg',
+      JUSTSCALE_NO_SOCKET: '1', // no cluster socket — coordinate purely through pg/redis
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Wait for the READY <port> liveness line on stdout
+  await new Promise<void>((resolve, reject) => {
+    child.stdout!.on('data', (chunk: Buffer) => {
+      if (chunk.toString().includes(`READY ${opts.port}`)) resolve();
+    });
+    child.once('exit', (code) => reject(new Error(`worker exited early (${code})`)));
+    setTimeout(() => reject(new Error('worker boot timeout')), 15000);
+  });
+
+  return child;
+}
+
+describe('<scenario>', () => {
+  let workerA: ChildProcess;
+  let workerB: ChildProcess;
+
+  before(async () => {
+    // TODO: probe pg + redis liveness; skip if either is unreachable.
+    const prefix = `<scenario>_${Date.now()}`;
+    workerA = await spawnWorker({ port: 6401, instanceId: 'A', prefix });
+    workerB = await spawnWorker({ port: 6402, instanceId: 'B', prefix });
+  });
+
+  after(async () => {
+    workerA?.kill('SIGTERM');
+    workerB?.kill('SIGTERM');
+    await Promise.all([
+      workerA && once(workerA, 'exit'),
+      workerB && once(workerB, 'exit'),
+    ]);
+  });
+
+  it('invariant holds across two instances', async () => {
+    // 1. Trigger the action on workerA via HTTP (port 6401).
+    // 2. Assert workerB observes the consequence (HTTP poll on 6402, or DB read).
+    // 3. Assert no double-execution.
+  });
+});
+```
+
+## Before scaffolding, ask
+
+1. **Invariant** — what should be true after the trigger? ("exactly one
+   process resumed", "B observes the channel publish", "only one of A/B
+   holds the lock at any moment".)
+2. **Trigger** — what HTTP call on A produces the observable on B?
+3. **Adapter set** — `pg-advisory` + `pg`, `redis` + `redis`, or mixed.
+   Multi-adapter coverage is the whole point of `packages/misc/e2e/`.
+
+## Anti-patterns
+
+- **Don't** put both apps in one Node process via `JustScale().build()`
+  twice. They'd share memory and module-level state — every distributed
+  bug invisible.
+- **Don't** mock the shared backend. The point is real pg/redis under
+  contention.
+- **Don't** rely on `app.serve({ socketPath })`. The cluster socket is for
+  CLI ↔ app, not for two workers to find each other. Set
+  `JUSTSCALE_NO_SOCKET=1` and coordinate through the chosen distributed
+  adapters.
+
+## After scaffolding
+
+- Print both file paths.
+- Remind the user: run with `tsx --test <driver>`. Don't add to the
+  package's `test` script until it passes twice clean — leaked workers
+  between runs are the most common failure mode.
+- Read the canonical e2e (`mixed-adapter-multi-process.e2e.test.ts`) for
+  details on liveness probes, port collision avoidance, and adapter-matrix
+  parameterization.

package/templates/skills/new-process/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: new-process
+description: Scaffold a new JustScale durable process — generates `<name>.signals.ts` and `<name>.process.ts` matching this repo's idiom. Forces `.types({...})` on every signal path param, `Locked<T>` mutators, no string IDs, imports only from `@justscale/core/process` and `@justscale/core/models`. Trigger when the user asks to create a process, durable workflow, saga, or signal-driven flow.
+---
+
+# Skill: new-process
+
+Scaffold a new durable process. Match the simple-app idiom — every signal
+path param `.types()`d, every mutator `Locked<T>`, no string IDs leaking
+through.
+
+## Usage
+
+`/new-process <name> [Model]`
+
+Example: `/new-process orderFulfillment Order`
+
+If the user didn't specify a Model or a domain folder, ask once.
+Placing files in the wrong domain folder is harder to fix than asking.
+
+## What to generate
+
+Two files in the same domain folder as the related Model:
+
+1. `<name>.signals.ts` — `defineSignals(...)`
+2. `<name>.process.ts` — `createProcess(...)`
+
+## Rules — non-negotiable
+
+The framework enforces these at compile time. Writing the file correctly
+the first time is faster than chasing type errors.
+
+1. **Every signal path parameter MUST be `.types({...})`d.** The path is
+   the topic on the cluster bus; typed params are the routing key. Two
+   forms are valid:
+   - Explicit: `.types({ cart: Cart })` — for path `/cart/:cart/...`
+   - Lowercased shorthand: `.types({ Cart })` — also for `:cart`
+   Prefer the explicit form. It's what `examples/simple-app/` uses and
+   it's unambiguous when param names don't match model names.
+2. **Service mutators take `Locked<T>`** — never `Ref<T>` or string ID.
+   If a method changes state, its signature must declare the lock.
+3. **Path parameter names match the model token in `.types({...})`.** A
+   mismatch is a compile error.
+4. **`signal.data<T>` is for non-routable payload only.** Anything that
+   identifies an entity goes in the path with `.types`, never in `.data`.
+5. **No string IDs in the process file.** If a `Locked<T>` isn't already
+   in scope from the signal payload, the handler `await`s the `Ref` to
+   materialise a `Persistent`.
+6. **Imports come from `@justscale/core/process` and
+   `@justscale/core/models` only.** Never reach into infra packages
+   (`@justscale/postgres`, `@justscale/redis`) from a process file.
+
+## Template
+
+`<name>.signals.ts`:
+
+```typescript
+import { defineSignals } from '@justscale/core/process';
+import { <Model> } from './<model>.model.js';
+
+export class <Name>Signals extends defineSignals((signal) => ({
+  <eventName>: signal('/<root>/:<param>/<verb>')
+    .data<{ /* optional non-routable payload */ }>()
+    .types({ <param>: <Model> }),
+})) {}
+```
+
+`<name>.process.ts`:
+
+```typescript
+import { createProcess, signal, race, delay } from '@justscale/core/process';
+import { <Model> } from './<model>.model.js';
+import { <Name>Signals } from './<name>.signals.js';
+
+export const <name> = createProcess({
+  path: '/<root>/:<param>/<verb>',
+  types: { <param>: <Model> },
+  inject: { signals: <Name>Signals },
+
+  async handler({ signals }, { <param> }) {
+    const r = race();
+    switch (true) {
+      case signal(r, signals.<eventName>):
+        // r.<param> is Locked<<Model>> — the signal carried the locked entity.
+        return { status: 'done' as const };
+      case delay.days(r, 3):
+        return { status: 'timeout' as const };
+    }
+  },
+});
+```
+
+## Reference
+
+The canonical examples are:
+
+- `examples/simple-app/src/domains/cart/cart.signals.ts` — explicit
+  `.types({ cart: Cart })` form, `.data<{...}>()` payloads.
+- `examples/simple-app/src/domains/cart/cart-lifecycle.process.ts` —
+  `while (true) { race + signal/delay switch }` shape.
+
+When in doubt, copy the structure of those files.
+
+## After generating
+
+- Print both file paths.
+- Remind the user to register the signal class and the process in the
+  domain's `.feature.ts` (or `app.ts` for tiny projects):
+  - `.add(<Name>Signals)`
+  - `.add(<name>)`
+- Do NOT modify `app.ts` or `*.feature.ts` automatically. Bootstrap
+  edits cause merge churn — let the user wire it.
+
+## When NOT to use this skill
+
+- Plain async helpers that don't need to suspend → write a
+  `defineService`, not a process.
+- One-shot HTTP handlers → use a controller route.
+- Cron-style schedules → use the scheduled-task primitive.