create-qpq-app 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -26,7 +26,7 @@
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:bin-perms": "node -e \"require('fs').chmodSync('lib/commonjs/bin/createQpqApp.js', 0o755)\"",
     "snapshot-template": "node ./scripts/snapshotTemplate.mjs",
-    "smoke-test": "node ./scripts/smokeTest.mjs",
+    "scaffold-test": "node ./scripts/scaffoldTest.mjs",
     "prepack": "npm run snapshot-template",
     "lint": "npx eslint .",
     "lint:fix": "npx eslint . --fix",
@@ -55,7 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.17"
+    "quidproquo-tsconfig": "0.1.18"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/apps/qpqjs/packages/constants/src/QpqjsServiceEnum.ts

@@ -3,6 +3,8 @@ export enum QpqjsServiceEnum {
   Auth = 'auth',
   Design = 'design',
   Shell = 'shell',
+  Test = 'test',
+  TestA = 'testa',
 }
 
 export type QpqjsServiceEnumValues = `${QpqjsServiceEnum}`;

package/template/apps/qpqjs/packages/constants/src/index.ts

@@ -1,3 +1,4 @@
 export * from './domain';
 export * from './QpqjsServiceEnum';
+export * from './smokeProbe';
 export * from './userDirectory';

package/template/apps/qpqjs/packages/constants/src/smokeProbe.ts

@@ -0,0 +1,13 @@
+// Smoke probe resources owned by the test service and reached cross-service
+// by testa (which declares them with owner: { module: test }). App-level
+// because both services must agree on the names.
+export const SMOKE_PROBE_STORE = 'smokeProbe';
+// Lowercase with a hyphen: this becomes an S3 bucket name, which must be lowercase.
+export const SMOKE_PROBE_DRIVE = 'smoke-probe';
+
+// The testa service functions the cross-service smoke tests invoke, one per
+// foreign grant (the store and the drive are separate IAM statements).
+export const SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME =
+  'crossKvsProbe';
+export const SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME =
+  'crossDriveProbe';

package/template/apps/qpqjs/services/test/config/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@qpqjs/test-config",
+  "version": "0.0.1",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "type": "commonjs",
+  "main": "./dist/src/index.js",
+  "typings": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

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

@@ -0,0 +1,2 @@
+// Intentionally empty — noop placeholder package for the qpqjs app.
+export {};

package/template/apps/qpqjs/services/test/config/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/template/apps/qpqjs/services/test/config/tsconfig.lib.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "types": [
+      "node"
+    ],
+    "rootDir": ".",
+    "composite": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "jest.config.ts",
+    "src/**/*.spec.ts"
+  ]
+}

package/template/apps/qpqjs/services/test/models/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@qpqjs/test-models",
+  "version": "0.0.1",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "type": "commonjs",
+  "main": "./dist/src/index.js",
+  "typings": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/template/apps/qpqjs/services/test/models/src/SmokeProbeRecord.ts

@@ -0,0 +1,8 @@
+// A row in the smokeProbe store. `category` is the store's GSI partition key,
+// so querying by it proves index access under the tag-conditioned grant.
+// External: testa writes these rows cross-service.
+export type SmokeProbeRecord = {
+  probeId: string;
+  category: string;
+  value: number;
+};

package/template/apps/qpqjs/services/test/models/src/SmokeRun.ts

@@ -0,0 +1,14 @@
+import { Nullable } from 'quidproquo';
+
+import { SmokeRunStatus } from './SmokeRunStatus';
+import { SmokeTestResult } from './SmokeTestResult';
+
+// One smoke run: POST /smoke/run creates it, GET /smoke/run/{runId} polls it.
+// The shape is the part-2 contract; part 3 only grows what `tests` contains.
+export type SmokeRun = {
+  runId: string;
+  status: SmokeRunStatus;
+  startedAt: string;
+  finishedAt: Nullable<string>;
+  tests: SmokeTestResult[];
+};

package/template/apps/qpqjs/services/test/models/src/SmokeRunStatus.ts

@@ -0,0 +1,5 @@
+export enum SmokeRunStatus {
+  running = 'running',
+  passed = 'passed',
+  failed = 'failed',
+}

package/template/apps/qpqjs/services/test/models/src/SmokeRunSummary.ts

@@ -0,0 +1,8 @@
+// Counts derived from a run's test entries at read time, never stored, so they
+// cannot drift from the entries themselves.
+export type SmokeRunSummary = {
+  total: number;
+  completed: number;
+  passed: number;
+  failed: number;
+};

package/template/apps/qpqjs/services/test/models/src/SmokeRunWithSummary.ts

@@ -0,0 +1,7 @@
+import { SmokeRun } from './SmokeRun';
+import { SmokeRunSummary } from './SmokeRunSummary';
+
+// What GET /smoke/run/{runId} returns: the stored run plus derived counts.
+export type SmokeRunWithSummary = SmokeRun & {
+  summary: SmokeRunSummary;
+};

package/template/apps/qpqjs/services/test/models/src/SmokeTestResult.ts

@@ -0,0 +1,15 @@
+import { Nullable } from 'quidproquo';
+
+import { SmokeTestStatus } from './SmokeTestStatus';
+
+// One registered test's entry in a run. `name` is the stable key; `id` is the
+// test's 1-based position in the registry, for humans, and shifts if the
+// registry is reordered, so nothing should key on it.
+export type SmokeTestResult = {
+  id: number;
+  name: string;
+  status: SmokeTestStatus;
+  message: string;
+  startedAt: Nullable<string>;
+  finishedAt: Nullable<string>;
+};

package/template/apps/qpqjs/services/test/models/src/SmokeTestStatus.ts

@@ -0,0 +1,6 @@
+export enum SmokeTestStatus {
+  pending = 'pending',
+  running = 'running',
+  passed = 'passed',
+  failed = 'failed',
+}

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

@@ -0,0 +1,7 @@
+export * from './SmokeProbeRecord';
+export * from './SmokeRun';
+export * from './SmokeRunStatus';
+export * from './SmokeRunSummary';
+export * from './SmokeRunWithSummary';
+export * from './SmokeTestResult';
+export * from './SmokeTestStatus';

package/template/apps/qpqjs/services/test/models/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/template/apps/qpqjs/services/test/models/tsconfig.lib.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "types": [
+      "node"
+    ],
+    "rootDir": ".",
+    "composite": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "jest.config.ts",
+    "src/**/*.spec.ts"
+  ]
+}

package/template/apps/qpqjs/services/test/service/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@qpqjs/test-service",
+  "version": "0.0.1",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "validate-ts": "tsc -p tsconfig.app.json --noEmit"
+  }
+}

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

@@ -0,0 +1,19 @@
+import { defineDevServerOptions } from 'quidproquo-dev-server/config';
+
+import { QpqjsServiceEnum } from '@qpqjs/constants';
+import { defineQpqjsService } from '@qpqjs/service-utils';
+
+import { defineSmoke } from './smoke/config/defineSmoke';
+
+export default [
+  defineDevServerOptions({ port: 3083 }),
+
+  // never change the app name, it will result in a new stack!
+  defineQpqjsService(
+    QpqjsServiceEnum.Test,
+    __dirname,
+    '../../../../../../dist/apps/qpqjs/services/test/service'
+  ),
+
+  defineSmoke(),
+];

package/template/apps/qpqjs/services/test/service/src/smoke/config/defineSmoke.ts

@@ -0,0 +1,102 @@
+import {
+  defineEventBus,
+  defineKeyValueStore,
+  defineParameter,
+  defineQueue,
+  defineRoute,
+  defineSecret,
+  defineStorageDrive,
+  QPQConfig,
+  QpqFunctionRuntime,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_DRIVE, SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import { SmokeProbeRecord } from '@qpqjs/test-models';
+
+import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+import {
+  SMOKE_PROBE_EVENT_BUS,
+  SMOKE_PROBE_EVENT_QUEUE,
+  SMOKE_PROBE_EVENT_TYPE,
+  SMOKE_PROBE_PARAMETER,
+  SMOKE_PROBE_PARAMETER_VALUE,
+  SMOKE_PROBE_SECRET,
+} from '../constants/smokeProbe';
+import {
+  SMOKE_RUN_QUEUE,
+  SMOKE_RUN_REQUESTED_MESSAGE_TYPE,
+} from '../constants/smokeRunQueue';
+
+// Everything the smoke feature needs: the run store, the queue runs execute
+// on, and the two routes. Runtimes are located relative to this file, so the
+// module can move as a unit.
+//
+// The routes look public (no user directory, no api keys) but carry a
+// per-runtime action processor override that swaps the route auth decode for
+// the GitHub OIDC validator - so ONLY a GitHub Actions run of our repo,
+// holding an OIDC token with the qpq-smoke audience and matching pinned
+// claims, gets past the preamble. Everything else 401s, tokenless included.
+export const defineSmoke = (): QPQConfig => {
+  const githubOidcAuth: QpqFunctionRuntime[] = [
+    {
+      basePath: __dirname,
+      relativePath: '../processors/github/getGithubOidcAuthProcessors',
+      functionName: 'getGithubOidcAuthProcessors',
+    },
+  ];
+
+  return [
+    // One record per run, keyed by runId; the queue entry updates it as tests
+    // complete and the GET route polls it.
+    defineKeyValueStore(SMOKE_RUNS_STORE, 'runId'),
+
+    defineQueue(SMOKE_RUN_QUEUE, {
+      [SMOKE_RUN_REQUESTED_MESSAGE_TYPE]: {
+        basePath: __dirname,
+        relativePath: '../queue/onSmokeRunRequested',
+        functionName: 'onSmokeRunRequested',
+      },
+    }),
+
+    // Throwaway probe resources, one per kind of owned resource the tag-based
+    // IAM grants cover. The store's `category` index is what the KVS test
+    // queries through, proving the `table/*/index/*` half of the grant.
+    defineKeyValueStore<SmokeProbeRecord>(SMOKE_PROBE_STORE, 'probeId', [], {
+      indexes: ['category'],
+    }),
+    defineParameter(SMOKE_PROBE_PARAMETER, {
+      value: SMOKE_PROBE_PARAMETER_VALUE,
+    }),
+    defineSecret(SMOKE_PROBE_SECRET),
+    defineStorageDrive(SMOKE_PROBE_DRIVE),
+
+    // Event bus test path: publish to the bus, the subscribed queue's entry
+    // writes a marker into the probe store, the test polls for it.
+    defineEventBus(SMOKE_PROBE_EVENT_BUS),
+    defineQueue(
+      SMOKE_PROBE_EVENT_QUEUE,
+      {
+        [SMOKE_PROBE_EVENT_TYPE]: {
+          basePath: __dirname,
+          relativePath: '../queue/onSmokeProbeEvent',
+          functionName: 'onSmokeProbeEvent',
+        },
+      },
+      { eventBusSubscriptions: [SMOKE_PROBE_EVENT_BUS] }
+    ),
+
+    defineRoute('POST', '/smoke/run', {
+      basePath: __dirname,
+      relativePath: '../controller/askRunSmokeTests',
+      functionName: 'askRunSmokeTests',
+      actionProcessors: githubOidcAuth,
+    }),
+
+    defineRoute('GET', '/smoke/run/{runId}', {
+      basePath: __dirname,
+      relativePath: '../controller/askGetSmokeRun',
+      functionName: 'askGetSmokeRun',
+      actionProcessors: githubOidcAuth,
+    }),
+  ];
+};

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

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

package/template/apps/qpqjs/services/test/service/src/smoke/constants/SMOKE_RUNS_STORE.ts

@@ -0,0 +1,2 @@
+// Key value store holding one record per smoke run, keyed by runId.
+export const SMOKE_RUNS_STORE = 'smokeRuns';

package/template/apps/qpqjs/services/test/service/src/smoke/constants/githubOidc.ts

@@ -0,0 +1,19 @@
+// The pinned claims for GitHub Actions OIDC tokens accepted by the smoke
+// endpoint. All public, none secret.
+
+// The only issuer GitHub Actions OIDC tokens can come from.
+export const GITHUB_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+
+// Where GitHub publishes the signing keys for its Actions OIDC tokens.
+export const GITHUB_OIDC_JWKS_URL =
+  'https://token.actions.githubusercontent.com/.well-known/jwks';
+
+// Dedicated audience the deployed-smoke workflow job requests its token with.
+// Tokens minted for any other purpose (e.g. the AWS deploy role) carry a
+// different audience and are rejected.
+export const GITHUB_OIDC_AUDIENCE = 'qpq-smoke';
+
+// The immutable GitHub id of qpqjs/quidproquo, fetched once with
+// `gh api repos/qpqjs/quidproquo --jq .id`. Pinned instead of the repo NAME
+// because names can be reassigned; ids cannot.
+export const GITHUB_REPOSITORY_ID = '571382961';

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

@@ -0,0 +1,4 @@
+export * from './githubOidc';
+export * from './SMOKE_RUNS_STORE';
+export * from './smokeProbe';
+export * from './smokeRunQueue';

package/template/apps/qpqjs/services/test/service/src/smoke/constants/smokeProbe.ts

@@ -0,0 +1,14 @@
+// Throwaway resources the smoke tests exercise, one per kind of owned
+// resource the service role is granted by tag / name convention (see the
+// tag-based IAM grants in quidproquo-deploy-awscdk). Nothing else uses them.
+// The store and drive names live in @qpqjs/constants because testa reaches
+// them cross-service.
+export const SMOKE_PROBE_PARAMETER = 'smokeProbe';
+export const SMOKE_PROBE_PARAMETER_VALUE = 'smoke-probe-parameter';
+export const SMOKE_PROBE_SECRET = 'smokeProbe';
+export const SMOKE_PROBE_EVENT_BUS = 'smokeProbe';
+
+// The queue subscribed to the probe event bus, and the message type that
+// flows bus -> queue -> store marker for the event bus test.
+export const SMOKE_PROBE_EVENT_QUEUE = 'smokeProbeEvents';
+export const SMOKE_PROBE_EVENT_TYPE = 'smokeProbeEvent';

package/template/apps/qpqjs/services/test/service/src/smoke/constants/smokeRunQueue.ts

@@ -0,0 +1,6 @@
+// The queue a smoke run is executed from, and the one message type on it.
+// POST /smoke/run creates the run record and sends this message; the queue
+// entry picks it up and runs the registered tests, so the request returns at
+// once and polling shows real progress.
+export const SMOKE_RUN_QUEUE = 'smokeRuns';
+export const SMOKE_RUN_REQUESTED_MESSAGE_TYPE = 'smokeRunRequested';

package/template/apps/qpqjs/services/test/service/src/smoke/controller/askGetSmokeRun.ts

@@ -0,0 +1,27 @@
+import {
+  AskResponse,
+  HTTPEvent,
+  HTTPEventResponse,
+  qpqWebServerUtils,
+} from 'quidproquo';
+
+import { askFindSmokeRun } from '../logic/smokeRun/askFindSmokeRun';
+import { summarizeSmokeRun } from '../logic/smokeRun/summarizeSmokeRun';
+
+// GET /smoke/run/{runId}. The deployed-smoke script polls this until the run
+// leaves 'running' or its deadline passes.
+export function* askGetSmokeRun(
+  event: HTTPEvent,
+  params: { runId: string }
+): AskResponse<HTTPEventResponse> {
+  const smokeRun = yield* askFindSmokeRun(params.runId);
+
+  if (!smokeRun) {
+    return qpqWebServerUtils.toJsonEventResponse(
+      { message: `no smoke run [${params.runId}]` },
+      404
+    );
+  }
+
+  return qpqWebServerUtils.toJsonEventResponse(summarizeSmokeRun(smokeRun));
+}

package/template/apps/qpqjs/services/test/service/src/smoke/controller/askRunSmokeTests.ts

@@ -0,0 +1,19 @@
+import {
+  AskResponse,
+  HTTPEvent,
+  HTTPEventResponse,
+  qpqWebServerUtils,
+} from 'quidproquo';
+
+import { askStartSmokeRun } from '../logic/smokeRun/askStartSmokeRun';
+
+// POST /smoke/run. Auth happened in the route preamble via the GitHub OIDC
+// decode override attached to this route's runtime. Starts the run on the
+// queue and hands back the runId; status is polled separately.
+export function* askRunSmokeTests(
+  event: HTTPEvent
+): AskResponse<HTTPEventResponse> {
+  const smokeRun = yield* askStartSmokeRun();
+
+  return qpqWebServerUtils.toJsonEventResponse({ runId: smokeRun.runId });
+}

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

@@ -0,0 +1,2 @@
+export * from './askGetSmokeRun';
+export * from './askRunSmokeTests';

package/template/apps/qpqjs/services/test/service/src/smoke/data/askGetSmokeRunById.ts

@@ -0,0 +1,16 @@
+import { askKeyValueStoreGet, AskResponse, Nullable } from 'quidproquo';
+
+import { SmokeRun } from '@qpqjs/test-models';
+
+import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+
+export function* askGetSmokeRunById(
+  runId: string
+): AskResponse<Nullable<SmokeRun>> {
+  const smokeRun = yield* askKeyValueStoreGet<SmokeRun>(
+    SMOKE_RUNS_STORE,
+    runId
+  );
+
+  return smokeRun || null;
+}

package/template/apps/qpqjs/services/test/service/src/smoke/data/askSaveSmokeRun.ts

@@ -0,0 +1,9 @@
+import { askKeyValueStoreUpsert, AskResponse } from 'quidproquo';
+
+import { SmokeRun } from '@qpqjs/test-models';
+
+import { SMOKE_RUNS_STORE } from '../constants/SMOKE_RUNS_STORE';
+
+export function* askSaveSmokeRun(smokeRun: SmokeRun): AskResponse<void> {
+  yield* askKeyValueStoreUpsert<SmokeRun>(SMOKE_RUNS_STORE, smokeRun);
+}

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

@@ -0,0 +1,2 @@
+export * from './askGetSmokeRunById';
+export * from './askSaveSmokeRun';

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

@@ -0,0 +1,9 @@
+export * from './config';
+export * from './constants';
+export * from './controller';
+export * from './data';
+export * from './logic';
+export * from './models';
+export * from './processors';
+export * from './queue';
+export * from './tests';

package/template/apps/qpqjs/services/test/service/src/smoke/logic/github/index.ts

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