create-qpq-app 0.1.19 → 0.1.21

package/template/docusaurus/docs/use-cases.md

@@ -154,12 +154,6 @@ export const api = createApi({
 });
 ```
 
-**Automatic OpenAPI Documentation**
-- Generate OpenAPI specs from your route definitions
-- Type-safe request/response contracts
-- Automatic validation against schemas
-- Interactive API documentation
-
 **Built-in Authentication & Authorization**
 ```typescript
 function* protectedRoute(request: HTTPRequest) {

package/template/docusaurus/docusaurus.config.ts

@@ -1,6 +1,6 @@
+import type { PrismTheme } from 'prism-react-renderer';
 import type * as Preset from '@docusaurus/preset-classic';
-import type {Config} from '@docusaurus/types';
-import type {PrismTheme} from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
@@ -12,16 +12,36 @@ const qpqPrismTheme: PrismTheme = {
     backgroundColor: 'transparent',
   },
   styles: [
-    {types: ['keyword', 'operator', 'atrule'], style: {color: '#7dd3fc'}},
-    {types: ['function', 'function-variable'], style: {color: '#8df6ff'}},
-    {types: ['string', 'char', 'attr-value', 'url', 'regex'], style: {color: '#fbbf77'}},
-    {types: ['class-name', 'maybe-class-name', 'builtin', 'namespace'], style: {color: '#86efac'}},
-    {types: ['comment', 'prolog', 'doctype', 'cdata'], style: {color: '#5c7181', fontStyle: 'italic' as const}},
-    {types: ['number', 'boolean', 'constant', 'symbol', 'property', 'attr-name', 'variable'], style: {color: '#c4b5fd'}},
-    {types: ['punctuation'], style: {color: '#8fa8b8'}},
-    {types: ['tag', 'selector'], style: {color: '#7dd3fc'}},
-    {types: ['deleted'], style: {color: '#ff5f57'}},
-    {types: ['inserted'], style: {color: '#28c840'}},
+    { types: ['keyword', 'operator', 'atrule'], style: { color: '#7dd3fc' } },
+    { types: ['function', 'function-variable'], style: { color: '#8df6ff' } },
+    {
+      types: ['string', 'char', 'attr-value', 'url', 'regex'],
+      style: { color: '#fbbf77' },
+    },
+    {
+      types: ['class-name', 'maybe-class-name', 'builtin', 'namespace'],
+      style: { color: '#86efac' },
+    },
+    {
+      types: ['comment', 'prolog', 'doctype', 'cdata'],
+      style: { color: '#5c7181', fontStyle: 'italic' as const },
+    },
+    {
+      types: [
+        'number',
+        'boolean',
+        'constant',
+        'symbol',
+        'property',
+        'attr-name',
+        'variable',
+      ],
+      style: { color: '#c4b5fd' },
+    },
+    { types: ['punctuation'], style: { color: '#8fa8b8' } },
+    { types: ['tag', 'selector'], style: { color: '#7dd3fc' } },
+    { types: ['deleted'], style: { color: '#ff5f57' } },
+    { types: ['inserted'], style: { color: '#28c840' } },
   ],
 };
 
@@ -65,11 +85,15 @@ const config: Config = {
   headTags: [
     {
       tagName: 'link',
-      attributes: {rel: 'preconnect', href: 'https://fonts.googleapis.com'},
+      attributes: { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
     },
     {
       tagName: 'link',
-      attributes: {rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: 'anonymous'},
+      attributes: {
+        rel: 'preconnect',
+        href: 'https://fonts.gstatic.com',
+        crossorigin: 'anonymous',
+      },
     },
   ],
   stylesheets: [

package/template/docusaurus/sidebars.ts

@@ -1,4 +1,4 @@
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
   tutorialSidebar: [
@@ -9,20 +9,20 @@ const sidebars: SidebarsConfig = {
     'architecture-overview',
     'eslint-plugin',
   ],
-  
+
   apiSidebar: [
     'api/index',
     {
       type: 'category',
       label: 'Config',
-      items: [{type: 'autogenerated', dirName: 'config'}],
+      items: [{ type: 'autogenerated', dirName: 'config' }],
     },
     {
       type: 'category',
       label: 'Action Requesters',
-      items: [{type: 'autogenerated', dirName: 'actions'}],
+      items: [{ type: 'autogenerated', dirName: 'actions' }],
     },
   ],
 };
 
-export default sidebars;
+export default sidebars;

package/template/docusaurus/src/components/HomepageFeatures/index.tsx

@@ -1,5 +1,5 @@
 import clsx from 'clsx';
-import type {ReactNode} from 'react';
+import type { ReactNode } from 'react';
 import Heading from '@theme/Heading';
 
 import styles from './styles.module.css';
@@ -43,7 +43,7 @@ const FeatureList: FeatureItem[] = [
   },
 ];
 
-function Feature({title, Svg, description}: FeatureItem) {
+function Feature({ title, Svg, description }: FeatureItem) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">

package/template/scripts/deployedSmoke.mjs

@@ -1,29 +1,34 @@
 #!/usr/bin/env node
-// 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 the smoke suite against a just-deployed test service on EVERY root
+// domain and exits non-zero if any root does not pass. Per root it runs the
+// edge checks (scripts/smoke/runEdgeChecks.mjs: aliases, certs, cross-root
+// cors, no token) and then the api smoke run (scripts/smoke/runSmokeRun.mjs,
+// shared with localSmoke.mjs); this file only resolves where to point them.
 //
 // 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
+//   SMOKE_ROOTS                     optional comma list to run a subset of the roots
 //
-// The api url is derived, not configured: the apex domain comes from the app's
-// deploy.config.json, non-production environments are a subdomain of it, and
-// 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>
+// Urls are derived, not configured: the roots come from the app's constants
+// package (the same list every service's defineDns reads), hosts follow the
+// app's default domain shape (see getRootHosts), and the api gateway maps each
+// service under its own base path:
+//   https://api.<environment>.<root>/<service>
 
-import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { getRootHosts, runEdgeChecks } from './smoke/runEdgeChecks.mjs';
 import { runSmokeRun } from './smoke/runSmokeRun.mjs';
 
 const SERVICE_NAME = 'test';
-const DEPLOY_CONFIG_PATH = join(
+// The built constants package: the deploy job builds the app before this runs.
+const DOMAIN_CONSTANTS_PATH = join(
   dirname(fileURLToPath(import.meta.url)),
-  '../apps/qpqjs/deploy.config.json'
+  '../apps/qpqjs/packages/constants/dist/src/domain.js'
 );
 
 const log = (message) => console.log(`deployed-smoke: ${message}`);
@@ -41,21 +46,75 @@ const requireEnv = (name) => {
   return value;
 };
 
-const deriveApiUrl = (environment) => {
-  const { domain } = JSON.parse(readFileSync(DEPLOY_CONFIG_PATH, 'utf8'));
-  if (!domain) {
-    fail(`no "domain" in ${DEPLOY_CONFIG_PATH}`);
+const getRoots = () => {
+  const { QPQJS_DOMAINS } = createRequire(import.meta.url)(
+    DOMAIN_CONSTANTS_PATH
+  );
+  if (!QPQJS_DOMAINS?.length) {
+    fail(`no QPQJS_DOMAINS in ${DOMAIN_CONSTANTS_PATH}; build the app first`);
   }
-  const envDomain =
-    environment === 'production' ? domain : `${environment}.${domain}`;
-  return `https://api.${envDomain}/${SERVICE_NAME}`;
+
+  const subset = process.env.SMOKE_ROOTS?.split(',')
+    .map((root) => root.trim())
+    .filter(Boolean);
+  if (!subset?.length) {
+    return QPQJS_DOMAINS;
+  }
+
+  const unknown = subset.filter((root) => !QPQJS_DOMAINS.includes(root));
+  if (unknown.length > 0) {
+    fail(`SMOKE_ROOTS names roots not in QPQJS_DOMAINS: ${unknown.join(', ')}`);
+  }
+  return subset;
+};
+
+const printTable = (root, results) => {
+  for (const result of results) {
+    log(
+      `  [${root}] ${result.ok ? 'pass' : 'FAIL'}  ${result.name.padEnd(36)} ${result.detail}`
+    );
+  }
+};
+
+// Every root runs to the end, so one report covers all of them.
+const smokeRoot = async (hosts, allHosts) => {
+  const rootLog = (message) => log(`[${hosts.root}] ${message}`);
+  rootLog(`edge checks against ${hosts.site}`);
+
+  const edge = await runEdgeChecks(hosts, allHosts);
+  printTable(hosts.root, edge);
+  const edgeOk = edge.every((result) => result.ok);
+
+  const apiUrl = `https://${hosts.api}/${SERVICE_NAME}`;
+  rootLog(`api smoke against ${apiUrl}`);
+  let apiOk = true;
+  try {
+    await runSmokeRun(apiUrl, rootLog);
+  } catch (error) {
+    apiOk = false;
+    rootLog(
+      `api smoke failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  return edgeOk && apiOk;
 };
 
 const environment = requireEnv('SMOKE_ENVIRONMENT');
-const apiUrl = deriveApiUrl(environment);
+const roots = getRoots();
+const allHosts = roots.map((root) => getRootHosts(root, environment));
 
-log(`environment=${environment} api=${apiUrl}`);
+log(`environment=${environment} roots=${roots.join(', ')}`);
 
-runSmokeRun(apiUrl, log).catch((error) =>
-  fail(error instanceof Error ? error.message : String(error))
-);
+const outcomes = [];
+for (const hosts of allHosts) {
+  outcomes.push({ root: hosts.root, ok: await smokeRoot(hosts, allHosts) });
+}
+
+for (const outcome of outcomes) {
+  log(`${outcome.ok ? 'PASS' : 'FAIL'} ${outcome.root}`);
+}
+
+if (outcomes.some((outcome) => !outcome.ok)) {
+  fail(`${outcomes.filter((outcome) => !outcome.ok).length} root(s) failed`);
+}

package/template/scripts/smoke/runEdgeChecks.mjs

@@ -0,0 +1,152 @@
+// Edge checks for one root domain: what the in-lambda smoke suite cannot see
+// from inside, namely the CloudFront aliases, the api gateway custom domain,
+// the certificates and the cross-root CORS listing. Plain fetches, no token.
+//
+// Every check returns { name, ok, detail } rather than throwing, so a root
+// reports its whole table before the run decides pass or fail.
+
+const TIMEOUT_MS = 15 * 1000;
+
+const fetchWithTimeout = (url, init = {}) =>
+  fetch(url, {
+    ...init,
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    redirect: 'manual',
+  });
+
+// Hosts for one root under the app's default shape (`<sub>.<env>.<root>`, no
+// environment label in production). If the app ever adds a domain resolver
+// pointer, derive these with quidproquo-webserver's resolveHosts instead.
+export const getRootHosts = (root, environment) => {
+  const site = environment === 'production' ? root : `${environment}.${root}`;
+
+  return {
+    root,
+    site,
+    api: `api.${site}`,
+    views: `views.${site}`,
+    docs: `docs.${site}`,
+  };
+};
+
+const check = async (name, run) => {
+  try {
+    const detail = await run();
+    return { name, ok: true, detail };
+  } catch (error) {
+    return {
+      name,
+      ok: false,
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+const expectStatus = async (url, statuses) => {
+  const response = await fetchWithTimeout(url);
+  if (!statuses.includes(response.status)) {
+    throw new Error(`${url} -> ${response.status}`);
+  }
+  return `${response.status}`;
+};
+
+// CloudFront serves index.html for the site root and the docs; the views host
+// is a module-federation remote root, whose own root may 403 while its manifest
+// serves, so accept either a 200 or a redirect there.
+const checkServed = (hosts) => [
+  check('site root served', () =>
+    expectStatus(`https://${hosts.site}/`, [200, 301, 302])
+  ),
+  check('docs served', () =>
+    expectStatus(`https://${hosts.docs}/`, [200, 301, 302])
+  ),
+  check('views served', () =>
+    expectStatus(`https://${hosts.views}/`, [200, 301, 302, 403, 404])
+  ),
+  check('api health', () =>
+    expectStatus(`https://${hosts.api}/shell/v1/health`, [200])
+  ),
+];
+
+// The OpenAPI servers list is the runtime's own view of the roots: it proves
+// the deployed lambda resolves every root, not just the one it was reached on.
+const checkOpenApiServers = (hosts, allHosts) =>
+  check('openapi lists every root', async () => {
+    const response = await fetchWithTimeout(
+      `https://${hosts.api}/test/v1/docs/openapi.json`
+    );
+    if (!response.ok) {
+      throw new Error(`openapi.json -> ${response.status}`);
+    }
+    const servers = ((await response.json()).servers ?? []).map(
+      (server) => server.url
+    );
+    const missing = allHosts
+      .map((other) => other.api)
+      .filter((api) => !servers.some((url) => url.includes(api)));
+    if (missing.length > 0) {
+      throw new Error(
+        `servers ${JSON.stringify(servers)} missing ${missing.join(', ')}`
+      );
+    }
+    return `${servers.length} servers`;
+  });
+
+// A page on root B calls the api on root A: the preflight must echo B's origin.
+const checkCrossRootCors = (hosts, allHosts) =>
+  allHosts
+    .filter((other) => other.root !== hosts.root)
+    .map((other) =>
+      check(`api cors allows ${other.site}`, async () => {
+        const origin = `https://${other.site}`;
+        const response = await fetchWithTimeout(
+          `https://${hosts.api}/shell/v1/health`,
+          {
+            method: 'OPTIONS',
+            headers: { Origin: origin, 'Access-Control-Request-Method': 'GET' },
+          }
+        );
+        const allowed = response.headers.get('access-control-allow-origin');
+        if (allowed !== origin && allowed !== '*') {
+          throw new Error(
+            `allow-origin ${allowed ?? '(none)'} for origin ${origin}`
+          );
+        }
+        return allowed;
+      })
+    );
+
+// The module-federation remotes are baked to the primary root, so a page on
+// an alternate root loads them cross-origin; the views web entry's cors policy
+// must allow that origin.
+const checkViewsAssetCors = (hosts, allHosts) =>
+  allHosts
+    .filter((other) => other.root !== hosts.root)
+    .map((other) =>
+      check(`views cors allows ${other.site}`, async () => {
+        const origin = `https://${other.site}`;
+        const response = await fetchWithTimeout(
+          `https://${hosts.views}/shell/mf-manifest.json`,
+          { headers: { Origin: origin } }
+        );
+        const allowed = response.headers.get('access-control-allow-origin');
+        if (!allowed) {
+          throw new Error(
+            `no allow-origin header (status ${response.status}) for origin ${origin}`
+          );
+        }
+        return allowed;
+      })
+    );
+
+/**
+ * Run every edge check for one root against the full root list and resolve the
+ * results, never throwing; `ok` is false on every row that failed.
+ */
+export const runEdgeChecks = async (hosts, allHosts) =>
+  Promise.all([
+    ...checkServed(hosts),
+    checkOpenApiServers(hosts, allHosts),
+    ...checkCrossRootCors(hosts, allHosts),
+    ...checkViewsAssetCors(hosts, allHosts),
+  ]);

package/template/scripts/smoke/runSmokeRun.mjs

@@ -4,7 +4,7 @@
 //
 // 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
+//   deployedSmoke.mjs  the just-deployed environment, from the app domain constant
 //   localSmoke.mjs     a dev server it started, on localhost
 //
 // Both talk to the same routes over the same protocol with the same token, so

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

@@ -1,83 +0,0 @@
-import {
-  askCatch,
-  askDateNow,
-  AskResponse,
-  askThrowError,
-  ErrorTypeEnum,
-} from 'quidproquo';
-
-import {
-  SmokeRun,
-  SmokeRunStatus,
-  SmokeTestResult,
-  SmokeTestStatus,
-} from '@qpqjs/test-models';
-
-import { askGetSmokeRunById } from '../../data/askGetSmokeRunById';
-import { askSaveSmokeRun } from '../../data/askSaveSmokeRun';
-import { SmokeTestDefinition } from '../../tests/SmokeTestDefinition';
-import { smokeTestRegistry } from '../../tests/smokeTestRegistry';
-
-// Runs one registered test, returning its completed result entry.
-function* askRunSmokeTest(
-  test: SmokeTestDefinition,
-  pending: SmokeTestResult,
-  runId: string
-): AskResponse<SmokeTestResult> {
-  const startedAt = yield* askDateNow();
-  const outcome = yield* askCatch(test.askRun(runId));
-  const finishedAt = yield* askDateNow();
-
-  return {
-    ...pending,
-    status: outcome.success ? SmokeTestStatus.passed : SmokeTestStatus.failed,
-    message: outcome.success ? 'passed' : outcome.error.errorText,
-    startedAt,
-    finishedAt,
-  };
-}
-
-// Executes every registered test for an existing run (created by
-// askStartSmokeRun), persisting the record after each test so a poll sees
-// progress, then finalizes the run status.
-export function* askExecuteSmokeRun(runId: string): AskResponse<SmokeRun> {
-  const existing = yield* askGetSmokeRunById(runId);
-  if (!existing) {
-    return yield* askThrowError(
-      ErrorTypeEnum.NotFound,
-      `no smoke run [${runId}] to execute`
-    );
-  }
-
-  let smokeRun: SmokeRun = existing;
-
-  for (let index = 0; index < smokeTestRegistry.length; index += 1) {
-    const result = yield* askRunSmokeTest(
-      smokeTestRegistry[index],
-      smokeRun.tests[index],
-      runId
-    );
-
-    smokeRun = {
-      ...smokeRun,
-      tests: smokeRun.tests.map((t) => (t.id === result.id ? result : t)),
-    };
-
-    yield* askSaveSmokeRun(smokeRun);
-  }
-
-  const finishedAt = yield* askDateNow();
-  const anyFailed = smokeRun.tests.some(
-    (t) => t.status !== SmokeTestStatus.passed
-  );
-
-  smokeRun = {
-    ...smokeRun,
-    status: anyFailed ? SmokeRunStatus.failed : SmokeRunStatus.passed,
-    finishedAt,
-  };
-
-  yield* askSaveSmokeRun(smokeRun);
-
-  return smokeRun;
-}

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

@@ -1,9 +0,0 @@
-import { QueueEvent, QueueMessage } from 'quidproquo';
-
-export type SmokeRunRequestedPayload = {
-  runId: string;
-};
-
-export type SmokeRunRequestedQueueEvent = QueueEvent<
-  QueueMessage<SmokeRunRequestedPayload>
->;

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

@@ -1,15 +0,0 @@
-import { AskResponse, QueueEventResponse } from 'quidproquo';
-
-import { askExecuteSmokeRun } from '../logic/smokeRun/askExecuteSmokeRun';
-import { SmokeRunRequestedQueueEvent } from '../models/SmokeRunRequestedQueueEvent';
-
-// Queue entry for a requested smoke run: executes the registered tests
-// against the run record askStartSmokeRun created. A throw here (e.g. the
-// record is missing) fails the message so the platform can redeliver it.
-export function* onSmokeRunRequested(
-  event: SmokeRunRequestedQueueEvent
-): AskResponse<QueueEventResponse> {
-  yield* askExecuteSmokeRun(event.message.payload.runId);
-
-  return true;
-}

package/template/docusaurus/docs/actions/webserver/open-api-spec/_category_.json

@@ -1 +0,0 @@
-{ "label": "OpenAPI Spec", "link": { "type": "generated-index", "description": "Read the service's generated OpenAPI spec from within a story." } }

package/template/docusaurus/docs/actions/webserver/open-api-spec/ask-get-open-api-spec.md

@@ -1,43 +0,0 @@
----
-title: askGetOpenApiSpec
-description: Return the service's generated OpenAPI spec as a string.
----
-
-# askGetOpenApiSpec
-
-Returns the service's **OpenAPI spec** as a string. Use it in a route handler to serve the spec (for documentation UIs or client generation) directly from the running service.
-
-- **Action type:** `OpenApiSpecActionType.GetOpenApiSpec`
-
-```typescript
-import { askGetOpenApiSpec } from 'quidproquo-webserver';
-
-export function* getOpenApiRoute() {
-  const spec = yield* askGetOpenApiSpec();
-
-  return {
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-    body: spec,
-  };
-}
-```
-
-## Signature
-
-```typescript
-function* askGetOpenApiSpec(): AskResponse<string>;
-```
-
-## Parameters
-
-None.
-
-## Returns
-
-`string` — the OpenAPI spec. Associate a spec with the service using [defineOpenApi](../../../config/webserver/open-api.md).
-
-## Related
-
-- [defineOpenApi](../../../config/webserver/open-api.md) — declares the spec this action returns.
-- [defineRoute](../../../config/webserver/route.md) — expose the spec at an HTTP path.

package/template/docusaurus/docs/config/webserver/open-api.md

@@ -1,36 +0,0 @@
----
-title: defineOpenApi
-description: Point a service at an OpenAPI spec file describing its HTTP API.
----
-
-# defineOpenApi
-
-Registers an **OpenAPI spec** for the service by pointing at a spec file on disk. This associates a machine-readable description of the service's HTTP API with the config.
-
-- **On AWS:** no infrastructure of its own — it records the spec path in the config. The generated spec is retrievable at runtime with [askGetOpenApiSpec](../../actions/webserver/open-api-spec/ask-get-open-api-spec.md).
-
-```typescript
-import { defineOpenApi } from 'quidproquo-webserver';
-
-export default [
-  defineOpenApi('./openapi.json'),
-];
-```
-
-## Signature
-
-```typescript
-function defineOpenApi(openApiSpecPath: string): OpenApiQPQWebServerConfigSetting;
-```
-
-## Parameters
-
-### `openApiSpecPath` — `string` (required)
-
-Path to the OpenAPI spec file for the service. This value is also the setting's `uniqueKey`.
-
-## Related
-
-- [askGetOpenApiSpec](../../actions/webserver/open-api-spec/ask-get-open-api-spec.md) — read the OpenAPI spec from within a story.
-- [defineApi](./api.md) — the HTTP API the spec describes.
-- [defineRoute](./route.md) — the routes that make up the API surface.