create-qpq-app 0.1.18 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -55,7 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.18"
+    "quidproquo-tsconfig": "0.1.19"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/apps/qpqjs/services/test/service/src/infrastructure.ts

@@ -4,6 +4,7 @@ import { QpqjsServiceEnum } from '@qpqjs/constants';
 import { defineQpqjsService } from '@qpqjs/service-utils';
 
 import { defineSmoke } from './smoke/config/defineSmoke';
+import { defineTick } from './tick/config/defineTick';
 
 export default [
   defineDevServerOptions({ port: 3083 }),
@@ -16,4 +17,6 @@ export default [
   ),
 
   defineSmoke(),
+
+  defineTick(),
 ];

package/template/apps/qpqjs/services/test/service/src/smoke/logic/smokeRun/askExecuteSmokeRun.ts

@@ -21,10 +21,11 @@ import { smokeTestRegistry } from '../../tests/smokeTestRegistry';
 // Runs one registered test, returning its completed result entry.
 function* askRunSmokeTest(
   test: SmokeTestDefinition,
-  pending: SmokeTestResult
+  pending: SmokeTestResult,
+  runId: string
 ): AskResponse<SmokeTestResult> {
   const startedAt = yield* askDateNow();
-  const outcome = yield* askCatch(test.askRun());
+  const outcome = yield* askCatch(test.askRun(runId));
   const finishedAt = yield* askDateNow();
 
   return {
@@ -53,7 +54,8 @@ export function* askExecuteSmokeRun(runId: string): AskResponse<SmokeRun> {
   for (let index = 0; index < smokeTestRegistry.length; index += 1) {
     const result = yield* askRunSmokeTest(
       smokeTestRegistry[index],
-      smokeRun.tests[index]
+      smokeRun.tests[index],
+      runId
     );
 
     smokeRun = {

package/template/apps/qpqjs/services/test/service/src/smoke/tests/SmokeTestDefinition.ts

@@ -2,7 +2,13 @@ import { AskResponse } from 'quidproquo';
 
 // A registered smoke test. `askRun` passes by returning and fails by throwing
 // (askThrowError); the runner catches and records the error text as the message.
+//
+// The run id is handed to every test, and most ignore it: a test that leaves a
+// mark somewhere durable stamps it, so what it later reads back is provably
+// its own rather than the previous run's. Declaring the parameter costs the
+// tests that do not want it nothing, since a zero-argument function still
+// satisfies this.
 export type SmokeTestDefinition = {
   name: string;
-  askRun: () => AskResponse<void>;
+  askRun: (runId: string) => AskResponse<void>;
 };

package/template/apps/qpqjs/services/test/service/src/smoke/tests/schedule/askRunScheduleTest.ts

@@ -0,0 +1,88 @@
+import {
+  askDateNow,
+  askDelay,
+  askKeyValueStoreGet,
+  askKeyValueStoreUpsert,
+  AskResponse,
+  Nullable,
+} from 'quidproquo';
+
+import { SCHEDULE_TICK_NAME } from '../../../tick/constants/scheduleTickName';
+import { SCHEDULE_TICK_STORE } from '../../../tick/constants/scheduleTickStore';
+import { ScheduleTickRecord } from '../../../tick/models/ScheduleTickRecord';
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The schedule runs every minute, so the wait has to cover a full boundary
+// plus the stream hop after it. Generous rather than tight: the first fire
+// after a deploy is the slowest one, and a flake here blocks a deploy.
+const POLL_ATTEMPTS = 40;
+const POLL_INTERVAL_MS = 3000;
+
+// Which link stalled, from the state the chain left behind. Worth the few
+// lines: "the schedule never fired" and "the stream never fired" send you to
+// completely different places, and a bare timeout says neither.
+const describeStall = (
+  tick: Nullable<ScheduleTickRecord>,
+  runId: string
+): string => {
+  if (!tick) {
+    return 'the seeded tick row is gone, so something else deleted it';
+  }
+
+  if (tick.runId !== runId) {
+    return `the tick row now belongs to run [${tick.runId}], so a concurrent smoke run overwrote it`;
+  }
+
+  if (!tick.processedAt) {
+    return 'the schedule never fired: the row was never marked processed';
+  }
+
+  return `the schedule fired at ${tick.processedAt} but the store's stream never acknowledged it`;
+};
+
+/**
+ * Proves a recurring schedule fires, and that a key-value store's change
+ * stream delivers, in one wait.
+ *
+ * Seeds one row stamped with this run, then waits for that same row to come
+ * back acknowledged - which only happens if the schedule picked it up and
+ * stamped processedAt, and the store's stream then saw that change and stamped
+ * acknowledgedAt. Deployed that is an EventBridge rule and a DynamoDB stream;
+ * locally it is the dev server's ticker and its stream implementation. Same
+ * assertion either way.
+ *
+ * Matching on the run id is what makes this unambiguous without deleting
+ * anything first: a stale row is one that does not match, so there is never a
+ * window where the record is missing, and never a question of whether what was
+ * read is recent enough to count.
+ *
+ * Slow by nature - up to a minute of real time, because that is how long a
+ * per-minute schedule can take to come round.
+ */
+export function* askRunScheduleTest(runId: string): AskResponse<void> {
+  yield* askKeyValueStoreUpsert<ScheduleTickRecord>(SCHEDULE_TICK_STORE, {
+    scheduleName: SCHEDULE_TICK_NAME,
+    runId,
+    requestedAt: yield* askDateNow(),
+  });
+
+  let tick: Nullable<ScheduleTickRecord> = null;
+
+  for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt += 1) {
+    yield* askDelay(POLL_INTERVAL_MS);
+
+    tick = yield* askKeyValueStoreGet<ScheduleTickRecord>(
+      SCHEDULE_TICK_STORE,
+      SCHEDULE_TICK_NAME
+    );
+
+    if (tick?.runId === runId && tick.acknowledgedAt) {
+      return;
+    }
+  }
+
+  yield* askSmokeAssert(
+    false,
+    `no acknowledgement within ${(POLL_ATTEMPTS * POLL_INTERVAL_MS) / 1000}s: ${describeStall(tick, runId)}`
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/schedule/index.ts

@@ -0,0 +1 @@
+export * from './askRunScheduleTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/smokeTestRegistry.ts

@@ -4,6 +4,7 @@ import { askRunEventBusTest } from './eventBus/askRunEventBusTest';
 import { askRunKeyValueStoreTest } from './keyValueStore/askRunKeyValueStoreTest';
 import { askRunNoopTest } from './noop/askRunNoopTest';
 import { askRunParameterTest } from './parameter/askRunParameterTest';
+import { askRunScheduleTest } from './schedule/askRunScheduleTest';
 import { askRunSecretTest } from './secret/askRunSecretTest';
 import { askRunStorageDriveTest } from './storageDrive/askRunStorageDriveTest';
 import { SmokeTestDefinition } from './SmokeTestDefinition';
@@ -26,4 +27,5 @@ export const smokeTestRegistry: SmokeTestDefinition[] = [
     name: 'crossServiceStorageDrive',
     askRun: askRunCrossServiceStorageDriveTest,
   },
+  { name: 'schedule', askRun: askRunScheduleTest },
 ];

package/template/apps/qpqjs/services/test/service/src/tick/config/defineTick.ts

@@ -0,0 +1,50 @@
+import {
+  defineKeyValueStore,
+  defineRecurringSchedule,
+  QPQConfig,
+} from 'quidproquo';
+
+import { SCHEDULE_TICK_STORE } from '../constants/scheduleTickStore';
+import { ScheduleTickRecord } from '../models/ScheduleTickRecord';
+
+/**
+ * A heartbeat schedule, and the one row that lets a test prove it fired.
+ *
+ * The chain the smoke suite's schedule test drives, all on a single record:
+ *
+ *   test seeds it     ->  the schedule stamps processedAt
+ *                     ->  the store's stream stamps acknowledgedAt
+ *                     ->  the test sees acknowledgedAt for its own run
+ *
+ * One wait covers three things that are otherwise untested together: that a
+ * declared schedule fires at all, that it fires the same way locally as
+ * deployed, and that a key-value store's change stream delivers.
+ *
+ * Every minute, which is the fastest a schedule can go and the only cadence a
+ * test can reasonably wait out.
+ */
+export const defineTick = (): QPQConfig => [
+  defineKeyValueStore<ScheduleTickRecord>(
+    SCHEDULE_TICK_STORE,
+    'scheduleName',
+    [],
+    {
+      onStream: {
+        runtime: {
+          basePath: __dirname,
+          relativePath: '../entry/kvsStream/onScheduleTickStream',
+          functionName: 'onScheduleTickStream',
+        },
+      },
+    }
+  ),
+
+  defineRecurringSchedule(
+    { everyMinutes: 1 },
+    {
+      basePath: __dirname,
+      relativePath: '../entry/schedule/onTick',
+      functionName: 'onTick',
+    }
+  ),
+];

package/template/apps/qpqjs/services/test/service/src/tick/config/index.ts

@@ -0,0 +1 @@
+export * from './defineTick';

package/template/apps/qpqjs/services/test/service/src/tick/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './scheduleTickName';
+export * from './scheduleTickStore';

package/template/apps/qpqjs/services/test/service/src/tick/constants/scheduleTickName.ts

@@ -0,0 +1,3 @@
+// Key of the single heartbeat row. One row, overwritten every tick, so the
+// store answers exactly one question: when did this schedule last fire.
+export const SCHEDULE_TICK_NAME = 'onTick';

package/template/apps/qpqjs/services/test/service/src/tick/constants/scheduleTickStore.ts

@@ -0,0 +1,3 @@
+// The store the tick schedule writes its heartbeat into. Local to this
+// service: unlike the smoke probe resources, nothing cross-service reaches it.
+export const SCHEDULE_TICK_STORE = 'scheduleTick';

package/template/apps/qpqjs/services/test/service/src/tick/entry/kvsStream/index.ts

@@ -0,0 +1 @@
+export * from './onScheduleTickStream';

package/template/apps/qpqjs/services/test/service/src/tick/entry/kvsStream/onScheduleTickStream.ts

@@ -0,0 +1,41 @@
+import {
+  askDateNow,
+  askKeyValueStoreUpsert,
+  AskResponse,
+  KvsStreamEventResponse,
+  KvsStreamRecord,
+} from 'quidproquo';
+
+import { SCHEDULE_TICK_STORE } from '../../constants/scheduleTickStore';
+import { ScheduleTickRecord } from '../../models/ScheduleTickRecord';
+
+/**
+ * Stamps acknowledgedAt on a tick row the schedule has marked processed.
+ *
+ * The last link in the smoke chain: the test seeds a row, the schedule marks
+ * it, and this proves the store's change stream delivered that change. Nothing
+ * else in the suite exercises a stream, so a stream that stopped firing would
+ * otherwise go unnoticed.
+ *
+ * It writes back into the store it streams from, which is the shape that
+ * usually means an infinite loop. It terminates here because the guard is
+ * self-limiting: the only write it makes is the one that sets acknowledgedAt,
+ * and a row with acknowledgedAt already set falls out at the first line. So
+ * one processed row costs exactly one extra no-op delivery, and testing that
+ * no-op is part of the point - a handler writing to its own table is ordinary,
+ * and getting the guard wrong is the interesting failure.
+ */
+export function* onScheduleTickStream(
+  record: KvsStreamRecord<ScheduleTickRecord>
+): AskResponse<KvsStreamEventResponse> {
+  // Also covers the test's own seed write (no processedAt yet) and a Remove
+  // (no new image at all), both of which arrive here and are not ours to act on.
+  if (!record.newImage?.processedAt || record.newImage.acknowledgedAt) {
+    return;
+  }
+
+  yield* askKeyValueStoreUpsert<ScheduleTickRecord>(SCHEDULE_TICK_STORE, {
+    ...record.newImage,
+    acknowledgedAt: yield* askDateNow(),
+  });
+}

package/template/apps/qpqjs/services/test/service/src/tick/entry/schedule/index.ts

@@ -0,0 +1 @@
+export * from './onTick';

package/template/apps/qpqjs/services/test/service/src/tick/entry/schedule/onTick.ts

@@ -0,0 +1,45 @@
+import {
+  askKeyValueStoreGet,
+  askKeyValueStoreUpsert,
+  askLogCreate,
+  AskResponse,
+  LogLevelEnum,
+  ScheduledEventParams,
+} from 'quidproquo';
+
+import { SCHEDULE_TICK_NAME } from '../../constants/scheduleTickName';
+import { SCHEDULE_TICK_STORE } from '../../constants/scheduleTickStore';
+import { ScheduleTickRecord } from '../../models/ScheduleTickRecord';
+
+/**
+ * The heartbeat. Deployed this is an EventBridge rule; locally the dev
+ * server's ticker fires it on the same minute.
+ *
+ * Marks a pending request as processed, and does nothing when there is no
+ * request outstanding - so between smoke runs this is a log line and a read,
+ * not a write every minute forever.
+ *
+ * Records the event's own `time` rather than reading a clock, because that is
+ * what the scheduler believes the firing minute to be, and agreement on that
+ * between the two runtimes is the thing worth proving.
+ */
+export function* onTick(event: ScheduledEventParams): AskResponse<void> {
+  yield* askLogCreate(
+    LogLevelEnum.Info,
+    `tick ${event.time} (correlation ${event.correlation})`
+  );
+
+  const pending = yield* askKeyValueStoreGet<ScheduleTickRecord>(
+    SCHEDULE_TICK_STORE,
+    SCHEDULE_TICK_NAME
+  );
+
+  if (!pending || pending.processedAt) {
+    return;
+  }
+
+  yield* askKeyValueStoreUpsert<ScheduleTickRecord>(SCHEDULE_TICK_STORE, {
+    ...pending,
+    processedAt: event.time,
+  });
+}

package/template/apps/qpqjs/services/test/service/src/tick/index.ts

@@ -0,0 +1 @@
+export * from './config';

package/template/apps/qpqjs/services/test/service/src/tick/models/ScheduleTickRecord.ts

@@ -0,0 +1,17 @@
+// The single row the whole schedule chain writes to, one field per actor:
+//
+//   requestedAt    the smoke test, seeding the run
+//   processedAt    the schedule, when its minute comes round
+//   acknowledgedAt the store's own change stream, having seen processedAt
+//
+// `runId` is the smoke run that seeded it, so what the test reads back is
+// provably its own rather than the previous run's. Nothing is ever deleted: a
+// stale row is one whose runId does not match, so there is no window where the
+// record is missing.
+export type ScheduleTickRecord = {
+  scheduleName: string;
+  runId: string;
+  requestedAt: string;
+  processedAt?: string;
+  acknowledgedAt?: string;
+};

package/template/apps/qpqjs/services/test/service/src/tick/models/index.ts

@@ -0,0 +1 @@
+export * from './ScheduleTickRecord';

package/template/docusaurus/docs/config/core/recurring-schedule.md

@@ -1,20 +1,21 @@
 ---
 title: defineRecurringSchedule
-description: Define a recurring schedule — a cron-driven trigger that runs a story on a timetable.
+description: Define a recurring schedule, a trigger that runs a story on a timetable.
 ---
 
 # defineRecurringSchedule
 
-Defines a **recurring schedule**: a time-based trigger that runs a story on a cron timetable, with no incoming request. Use it for periodic work — nightly cleanups, polling, report generation, cache warming. Like a [queue](./queue.md) or [event bus](./event-bus.md), a schedule is an **event source**: each fire delivers a `ScheduledEvent` to the target story through the same [askProcessEvent](../../actions/core/event/ask-process-event.md) pipeline.
+Defines a **recurring schedule**: a time-based trigger that runs a story on a timetable, with no incoming request. Use it for periodic work — nightly cleanups, polling, report generation, cache warming. Like a [queue](./queue.md) or [event bus](./event-bus.md), a schedule is an **event source**: each fire delivers a `ScheduledEvent` to the target story through the same [askProcessEvent](../../actions/core/event/ask-process-event.md) pipeline.
 
-- **On AWS:** deploys an **EventBridge rule** with a cron schedule expression and a **consumer Lambda** as its target (`QpqCoreRecurringScheduleConstruct` in `quidproquo-deploy-awscdk`). The rule fires on the cron cadence and invokes the Lambda, passing the schedule's `metadata` as the event `detail`. The Lambda has a 15-minute timeout, and `maxConcurrentExecutions` (when set) becomes the Lambda's reserved concurrent executions.
+- **Locally:** the dev server ticks once a minute and runs any schedule whose recurrence matches that UTC minute. See [Locally](#locally) below.
+- **On AWS:** deploys an **EventBridge rule** whose cron expression is rendered from the recurrence and a **consumer Lambda** as its target (`QpqCoreRecurringScheduleConstruct` in `quidproquo-deploy-awscdk`). The rule fires on the cron cadence and invokes the Lambda, passing the schedule's `metadata` as the event `detail`. The Lambda has a 15-minute timeout, and `maxConcurrentExecutions` (when set) becomes the Lambda's reserved concurrent executions.
 
 ```typescript
 import { defineRecurringSchedule } from 'quidproquo-core';
 
 export default [
-  // Every day at 3 AM (server time)
-  defineRecurringSchedule('0 0 3 * * ? *', '/entry/schedule/onNightlyCleanup::onNightlyCleanup'),
+  // Every day at 3am UTC
+  defineRecurringSchedule({ dailyAtUtc: { hour: 3, minute: 0 } }, '/entry/schedule/onNightlyCleanup::onNightlyCleanup'),
 ];
 ```
 
@@ -22,7 +23,7 @@ export default [
 
 ```typescript
 function defineRecurringSchedule(
-  cronExpression: string,
+  recurrence: ScheduleRecurrence,
   runtime: QpqFunctionRuntime,
   options?: QPQConfigAdvancedScheduleSettings,
 ): ScheduleQPQConfigSetting;
@@ -30,29 +31,21 @@ function defineRecurringSchedule(
 
 ## Parameters
 
-### `cronExpression` — `string` (required)
+### `recurrence` — `ScheduleRecurrence` (required)
 
-The cron expression that controls when the schedule fires. On AWS this is wrapped as `cron(<cronExpression>)` in the EventBridge rule, so it uses the six-field AWS EventBridge cron syntax:
+When the schedule fires, declared as intent rather than as a cron string. It is deliberately platform-neutral: an AWS EventBridge cron expression is one *rendering* of it, produced at deploy time, and the dev server matches the same declaration against the clock.
 
-```
-minutes hours day-of-month month day-of-week year
-```
+| Recurrence | Fires |
+| --- | --- |
+| `{ everyMinutes: n }` | every `n` minutes, on the hour. `n` must divide 60 |
+| `{ everyHours: n, atMinute?: m }` | every `n` hours at minute `m` (default 0). `n` must divide 24 |
+| `{ dailyAtUtc: { hour, minute } }` | once a day |
+| `{ weeklyAtUtc: { day, hour, minute } }` | once a week, `day` being a `DayOfWeek` |
+| `{ monthlyAtUtc: { dayOfMonth, hour, minute } }` | once a month. A date past the end of a short month simply does not occur that month |
 
-| Field | Values | Wildcards |
-| --- | --- | --- |
-| Minutes | `0-59` | `,` `-` `*` `/` |
-| Hours | `0-23` | `,` `-` `*` `/` |
-| Day-of-month | `1-31` | `,` `-` `*` `?` `/` `L` `W` |
-| Month | `1-12` or `JAN-DEC` | `,` `-` `*` `/` |
-| Day-of-week | `1-7` or `SUN-SAT` | `,` `-` `*` `?` `L` `#` |
-| Year | `1970-2199` | `,` `-` `*` `/` |
+**Every time is UTC.** The deployed scheduler evaluates in UTC, so there is no local-timezone option: 3am in Brisbane is `{ dailyAtUtc: { hour: 17, minute: 0 } }`, and saying so in the config beats a comment that goes stale twice a year.
 
-You cannot use `*` in both the day-of-month and day-of-week fields at once — put `?` in the one you don't want to constrain. Examples:
-
-- `'* * * * ? *'` — every minute
-- `'0/10 * * * ? *'` — every 10 minutes
-- `'0 0 3 * * ? *'` — every day at 3 AM
-- `'0 0 3 ? * 1 *'` — every Monday at 3 AM
+An interval that cannot be scheduled evenly (`{ everyMinutes: 7 }`) throws an `InvalidScheduleRecurrenceError` when the config is evaluated, so it fails at synth and at dev-server boot rather than at some unlucky hour in production. The reason it is refused rather than approximated: AWS renders an interval as `0/n`, which restarts at the top of every hour, so seven-minute steps would fire at :00 :07 ... :56 and then leave a four-minute gap.
 
 ### `runtime` — `QpqFunctionRuntime` (required)
 
@@ -99,19 +92,29 @@ import { defineRecurringSchedule } from 'quidproquo-core';
 
 export default [
   // Poll an upstream every 10 minutes
-  defineRecurringSchedule('0/10 * * * ? *', '/entry/schedule/onPoll::onPoll'),
+  defineRecurringSchedule({ everyMinutes: 10 }, '/entry/schedule/onPoll::onPoll'),
 
   // Nightly report, capped to a single concurrent run, with metadata
-  defineRecurringSchedule('0 0 2 * * ? *', '/entry/schedule/onNightlyReport::onNightlyReport', {
+  defineRecurringSchedule({ dailyAtUtc: { hour: 2, minute: 0 } }, '/entry/schedule/onNightlyReport::onNightlyReport', {
     maxConcurrentExecutions: 1,
     metadata: { report: 'daily-summary' },
   }),
 ];
 ```
 
+## Locally
+
+The dev server arms every schedule its services own and ticks once a minute, running any whose recurrence matches that UTC minute. It lists what it armed at boot:
+
+```
+[schedule] 2 schedule(s) armed (utc):
+[schedule]   flow/onPoll {"everyMinutes":10}
+[schedule]   flow/onNightlyReport {"dailyAtUtc":{"hour":2,"minute":0}}
+```
+
 ## Related
 
 - [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the target story for each schedule fire.
 - [defineQueue](./queue.md) and [defineEventBus](./event-bus.md) — the other core event sources.
 - [defineDeployEvent](./deploy-event.md) — a related time/lifecycle-based trigger that runs at deploy time rather than on a timetable.
-- **AWS implementation:** `QpqCoreRecurringScheduleConstruct` (EventBridge rule + target Lambda) in `quidproquo-deploy-awscdk`.
+- **AWS implementation:** `QpqCoreRecurringScheduleConstruct` (EventBridge rule + target Lambda) in `quidproquo-deploy-awscdk`. `renderAwsCronExpression`, alongside it, is the only place in the codebase that knows the EventBridge cron dialect.

package/template/scripts/deployedSmoke.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-// Drives one smoke run against a deployed test service and exits non-zero if
-// it does not pass: mint a GitHub Actions OIDC token, POST /smoke/run, poll
-// GET /smoke/run/{runId} until the run finishes or the deadline passes.
+// Runs the smoke suite against a just-deployed test service and exits non-zero
+// if it does not pass. The run itself lives in scripts/smoke/runSmokeRun.mjs,
+// shared with localSmoke.mjs; this file only resolves which api to point it at.
 //
-// Runs inside the deployed-smoke workflow job, which supplies:
+// Runs inside the deploy workflow's deploy job, which supplies:
 //   SMOKE_ENVIRONMENT               the environment that was just deployed (development, staging)
 //   ACTIONS_ID_TOKEN_REQUEST_URL    provided by Actions when the job has id-token: write
 //   ACTIONS_ID_TOKEN_REQUEST_TOKEN  provided by Actions when the job has id-token: write
@@ -13,16 +13,13 @@
 // the api gateway maps each service under its own base path (see the
 // CfnBasePathMapping in quidproquo-deploy-awscdk's api construct):
 //   https://api.<environment>.<domain>/<service>
-//
-// No dependencies: Node 24's global fetch is all it needs.
 
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const AUDIENCE = 'qpq-smoke';
-const DEADLINE_MS = 5 * 60 * 1000;
-const POLL_MS = 5 * 1000;
+import { runSmokeRun } from './smoke/runSmokeRun.mjs';
+
 const SERVICE_NAME = 'test';
 const DEPLOY_CONFIG_PATH = join(
   dirname(fileURLToPath(import.meta.url)),
@@ -56,79 +53,9 @@ const deriveApiUrl = (environment) => {
 
 const environment = requireEnv('SMOKE_ENVIRONMENT');
 const apiUrl = deriveApiUrl(environment);
-const tokenRequestUrl = requireEnv('ACTIONS_ID_TOKEN_REQUEST_URL');
-const tokenRequestToken = requireEnv('ACTIONS_ID_TOKEN_REQUEST_TOKEN');
 
 log(`environment=${environment} api=${apiUrl}`);
 
-// OIDC tokens are short-lived (minutes), about as long as the poll deadline,
-// so every request mints a fresh one rather than racing the expiry.
-const mintToken = async () => {
-  const response = await fetch(`${tokenRequestUrl}&audience=${AUDIENCE}`, {
-    headers: { Authorization: `bearer ${tokenRequestToken}` },
-  });
-  if (!response.ok) {
-    throw new Error(`token request failed with ${response.status}`);
-  }
-  const body = await response.json();
-  if (!body.value) {
-    throw new Error('token request returned no value');
-  }
-  return body.value;
-};
-
-const callApi = async (method, path) => {
-  const response = await fetch(`${apiUrl}${path}`, {
-    method,
-    headers: { Authorization: `Bearer ${await mintToken()}` },
-  });
-  if (!response.ok) {
-    throw new Error(
-      `${method} ${path} failed with ${response.status}: ${await response.text()}`
-    );
-  }
-  return response.json();
-};
-
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-const printTests = (tests) => {
-  for (const test of tests) {
-    log(
-      `  #${test.id} ${test.name.padEnd(24)} ${test.status.padEnd(8)} ${test.message}`
-    );
-  }
-};
-
-const main = async () => {
-  const { runId } = await callApi('POST', '/smoke/run');
-  if (!runId) {
-    fail('POST /smoke/run returned no runId');
-  }
-  log(`started run ${runId}`);
-
-  const deadline = Date.now() + DEADLINE_MS;
-  while (Date.now() < deadline) {
-    const run = await callApi('GET', `/smoke/run/${runId}`);
-    const { summary } = run;
-    log(
-      `status=${run.status} completed ${summary.completed}/${summary.total} passed ${summary.passed} failed ${summary.failed}`
-    );
-
-    if (run.status === 'passed' || run.status === 'failed') {
-      printTests(run.tests);
-      if (run.status === 'failed') {
-        fail(`run ${runId} failed`);
-      }
-      return;
-    }
-
-    await sleep(POLL_MS);
-  }
-
-  fail(`timed out waiting for run ${runId}`);
-};
-
-main().catch((error) =>
+runSmokeRun(apiUrl, log).catch((error) =>
   fail(error instanceof Error ? error.message : String(error))
 );

package/template/scripts/localSmoke.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Runs the smoke suite against a dev server this script starts, and exits
+// non-zero if it does not pass. The run itself lives in
+// scripts/smoke/runSmokeRun.mjs, shared with deployedSmoke.mjs.
+//
+// This is a pre-flight gate, not a replacement for the deployed smoke: the
+// same stories run against the dev server's implementations instead of AWS, so
+// it catches a broken probe, or the dev server drifting from deployed
+// behaviour, on a pull request rather than after a deploy. It cannot catch
+// anything the deployed run exists for - iam grants, resource naming, cdk
+// wiring, api gateway base path mapping.
+//
+// Needs a GitHub Actions job with `permissions: id-token: write` and
+// `environment: development`, because the smoke routes validate the token's
+// environment claim against the service's own module environment - and a dev
+// server is always development (primeDeployEnvFromConfig defaults it), whatever
+// environment the deploy that follows is targeting.
+//
+// The api url is derived, not configured, same as the deployed script - but to
+// a different SHAPE, which is why the two derive separately rather than
+// sharing a template. Deployed, api gateway maps each service under its own
+// base path on the api domain. Locally the dev server routes on
+// /{apiSubdomain}/{serviceName} (see apiImplementation's devPath), and the app
+// declares defineApi('api', ...):
+//   http://localhost:8080/api/test
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runSmokeRun } from './smoke/runSmokeRun.mjs';
+
+// The dev server defaults to this anyway; set explicitly so a CI runner that
+// already has ENVIRONMENT set (the deploy workflow does) cannot change what
+// the smoke routes expect from the token. Must match the job's `environment:`.
+const ENVIRONMENT = 'development';
+
+// There is more than one app under apps/, so the app has to be named: without
+// it the cli exits with the app list rather than picking one.
+const APP_NAME = 'qpqjs';
+
+// 8080 is the dev server's api port, set in the generated entry.
+const BASE_URL = 'http://localhost:8080';
+const API_URL = `${BASE_URL}/api/test`;
+const READY_URL = `${BASE_URL}/admin/service/ready`;
+
+// Generous: a cold start bundles every service with rspack before the server
+// process even launches.
+const READY_TIMEOUT_MS = 5 * 60 * 1000;
+const READY_POLL_MS = 2 * 1000;
+
+// Above the dev server's own 5s worst-case shutdown budget.
+const STOP_TIMEOUT_MS = 15 * 1000;
+
+const APP_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// The .bin shim npm links on install, which points at the cli's built entry.
+const QPQ_BIN = join(APP_ROOT, 'node_modules', '.bin', 'qpq');
+
+const log = (message) => console.log(`local-smoke: ${message}`);
+
+const fail = (message) => {
+  console.error(`local-smoke: ${message}`);
+  process.exit(1);
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Wait until the dev server reports every plugin started.
+ *
+ * Deliberately not a TCP connect: the api plugin binds its port partway
+ * through the start sequence, so a socket opens before the queue and the
+ * stores are up, and the first POST would race them.
+ */
+const waitForReady = async (server) => {
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null) {
+      throw new Error(
+        `dev server exited with ${server.exitCode} before it was ready`
+      );
+    }
+
+    try {
+      const response = await fetch(READY_URL);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Not listening yet. Nothing to report until the deadline passes.
+    }
+
+    await sleep(READY_POLL_MS);
+  }
+
+  throw new Error(`dev server was not ready within ${READY_TIMEOUT_MS}ms`);
+};
+
+/**
+ * Stop the dev server and resolve with how it went.
+ *
+ * SIGTERM rather than SIGKILL because the graceful path is part of what this
+ * script checks: the server should stop accepting, drain the smoke run's
+ * in-flight work and checkpoint its stores, then exit 0.
+ *
+ * Code and signal are both reported because they mean different things and
+ * only one of them is ever a number. A code of 0 is the pass; a non-zero code
+ * means a teardown broke or a phase ran out of budget; a null code with a
+ * signal means nothing handled the signal and the process was killed where it
+ * stood, which is a shutdown that never ran rather than one that failed.
+ */
+const stopServer = (server) =>
+  new Promise((resolve) => {
+    if (server.exitCode !== null) {
+      resolve({ code: server.exitCode, signal: null });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      log(
+        `dev server did not stop within ${STOP_TIMEOUT_MS}ms, sending SIGKILL`
+      );
+      server.kill('SIGKILL');
+    }, STOP_TIMEOUT_MS);
+
+    server.once('exit', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal });
+    });
+
+    server.kill('SIGTERM');
+  });
+
+const main = async () => {
+  log(`starting dev server (app=${APP_NAME} env=${ENVIRONMENT})`);
+
+  // node on the cli directly, NOT `npx qpq`: npx is another process in front
+  // of the one we need to signal, and SIGTERM stops at it. The cli would never
+  // hear the stop, its dev server child would never drain, and the exit would
+  // come back as a signal kill. One less layer means the signal lands where
+  // the handler is.
+  const server = spawn(
+    process.execPath,
+    [QPQ_BIN, 'go:dev:api', '--app', APP_NAME],
+    {
+      cwd: APP_ROOT,
+      stdio: 'inherit',
+      env: { ...process.env, ENVIRONMENT },
+    }
+  );
+
+  // The server is stopped either way, but a smoke failure is reported ahead of
+  // a dirty shutdown: it is the more useful of the two, and letting the
+  // shutdown check throw first would bury it.
+  let smokeError = null;
+
+  try {
+    await waitForReady(server);
+    log(`dev server ready, api=${API_URL}`);
+
+    await runSmokeRun(API_URL, log);
+  } catch (error) {
+    smokeError = error;
+  }
+
+  const { code, signal } = await stopServer(server);
+  log(`dev server exited with code=${code} signal=${signal}`);
+
+  if (smokeError) {
+    throw smokeError;
+  }
+
+  if (signal) {
+    throw new Error(
+      `dev server was killed by ${signal} instead of shutting down, so its teardown never ran`
+    );
+  }
+
+  if (code !== 0) {
+    throw new Error(`dev server did not shut down cleanly (exit ${code})`);
+  }
+};
+
+main().catch((error) =>
+  fail(error instanceof Error ? error.message : String(error))
+);

package/template/scripts/smoke/runSmokeRun.mjs

@@ -0,0 +1,100 @@
+// Drives one smoke run against a test service and reports whether it passed:
+// mint a GitHub Actions OIDC token, POST /smoke/run, poll GET
+// /smoke/run/{runId} until the run finishes or the deadline passes.
+//
+// Target-agnostic on purpose. The two callers differ only in the api url they
+// resolve, which each derives for itself:
+//   deployedSmoke.mjs  the just-deployed environment, from deploy.config.json
+//   localSmoke.mjs     a dev server it started, on localhost
+//
+// Both talk to the same routes over the same protocol with the same token, so
+// a local run rehearses the deployed one rather than approximating it.
+//
+// No dependencies: Node's global fetch is all it needs.
+
+const AUDIENCE = 'qpq-smoke';
+const DEADLINE_MS = 5 * 60 * 1000;
+const POLL_MS = 5 * 1000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// OIDC tokens are short-lived (minutes), about as long as the poll deadline,
+// so every request mints a fresh one rather than racing the expiry.
+const mintToken = async () => {
+  const tokenRequestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const tokenRequestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+
+  if (!tokenRequestUrl || !tokenRequestToken) {
+    throw new Error(
+      'ACTIONS_ID_TOKEN_REQUEST_URL / ACTIONS_ID_TOKEN_REQUEST_TOKEN are not set. This needs a GitHub Actions job with `permissions: id-token: write`'
+    );
+  }
+
+  const response = await fetch(`${tokenRequestUrl}&audience=${AUDIENCE}`, {
+    headers: { Authorization: `bearer ${tokenRequestToken}` },
+  });
+  if (!response.ok) {
+    throw new Error(`token request failed with ${response.status}`);
+  }
+  const body = await response.json();
+  if (!body.value) {
+    throw new Error('token request returned no value');
+  }
+  return body.value;
+};
+
+const printTests = (log, tests) => {
+  for (const test of tests) {
+    log(
+      `  #${test.id} ${test.name.padEnd(24)} ${test.status.padEnd(8)} ${test.message}`
+    );
+  }
+};
+
+/**
+ * Run the smoke suite against `apiUrl` and resolve if it passed.
+ *
+ * Throws on anything else (a failed run, an unreachable api, a run that never
+ * finishes) so a caller can let it reach its top-level catch and exit 1.
+ */
+export const runSmokeRun = async (apiUrl, log) => {
+  const callApi = async (method, path) => {
+    const response = await fetch(`${apiUrl}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${await mintToken()}` },
+    });
+    if (!response.ok) {
+      throw new Error(
+        `${method} ${path} failed with ${response.status}: ${await response.text()}`
+      );
+    }
+    return response.json();
+  };
+
+  const { runId } = await callApi('POST', '/smoke/run');
+  if (!runId) {
+    throw new Error('POST /smoke/run returned no runId');
+  }
+  log(`started run ${runId}`);
+
+  const deadline = Date.now() + DEADLINE_MS;
+  while (Date.now() < deadline) {
+    const run = await callApi('GET', `/smoke/run/${runId}`);
+    const { summary } = run;
+    log(
+      `status=${run.status} completed ${summary.completed}/${summary.total} passed ${summary.passed} failed ${summary.failed}`
+    );
+
+    if (run.status === 'passed' || run.status === 'failed') {
+      printTests(log, run.tests);
+      if (run.status === 'failed') {
+        throw new Error(`run ${runId} failed`);
+      }
+      return;
+    }
+
+    await sleep(POLL_MS);
+  }
+
+  throw new Error(`timed out waiting for run ${runId}`);
+};