create-qpq-app 0.1.19 → 0.1.21

package/lib/commonjs/steps/006_applyDomain.js

@@ -14,19 +14,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyDomain = void 0;
 const path_1 = __importDefault(require("path"));
-const readJsonFile_1 = require("../lib/readJsonFile");
 const replaceInFileExact_1 = require("../lib/replaceInFileExact");
-const writeJsonFile_1 = require("../lib/writeJsonFile");
-// The template's domain, replaced wherever it's authoritative: the deploy
-// config and the app's domain constant (everything else derives from those).
+// The template's domain, replaced where it's authoritative: the app's domain
+// constant (everything else derives from it). One root at scaffold time; more
+// can be appended later.
 const TEMPLATE_DOMAIN = 'todo.quidproquojs.com';
 exports.applyDomain = {
     name: 'Applying domain',
     run: (_a) => __awaiter(void 0, [_a], void 0, function* ({ targetDirectory, answers }) {
-        const deployConfigPath = path_1.default.join(targetDirectory, 'apps', answers.appName, 'deploy.config.json');
-        const deployConfig = (0, readJsonFile_1.readJsonFile)(deployConfigPath);
-        deployConfig.domain = answers.domain;
-        (0, writeJsonFile_1.writeJsonFile)(deployConfigPath, deployConfig);
         (0, replaceInFileExact_1.replaceInFileExact)(path_1.default.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'), TEMPLATE_DOMAIN, answers.domain);
     }),
 };

package/lib/commonjs/steps/006_applyDomain.js.map

@@ -1 +1 @@
-{"version":3,"file":"006_applyDomain.js","sourceRoot":"","sources":["../../../src/steps/006_applyDomain.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,gDAAwB;AAExB,sDAAmD;AACnD,kEAA+D;AAC/D,wDAAqD;AAGrD,0EAA0E;AAC1E,6EAA6E;AAC7E,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEnC,QAAA,WAAW,GAAqB;IAC3C,IAAI,EAAE,iBAAiB;IAEvB,GAAG,EAAE,KAAqC,EAAE,4CAAhC,EAAE,eAAe,EAAE,OAAO,EAAE;QACtC,MAAM,gBAAgB,GAAG,cAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACnG,MAAM,YAAY,GAAG,IAAA,2BAAY,EAAC,gBAAgB,CAAC,CAAC;QACpD,YAAY,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QACrC,IAAA,6BAAa,EAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;QAE9C,IAAA,uCAAkB,EAChB,cAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,EAChG,eAAe,EACf,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC,CAAA;CACF,CAAC","sourcesContent":["import path from 'path';\n\nimport { readJsonFile } from '../lib/readJsonFile';\nimport { replaceInFileExact } from '../lib/replaceInFileExact';\nimport { writeJsonFile } from '../lib/writeJsonFile';\nimport { CreateQpqAppStep } from '../types';\n\n// The template's domain, replaced wherever it's authoritative: the deploy\n// config and the app's domain constant (everything else derives from those).\nconst TEMPLATE_DOMAIN = 'todo.quidproquojs.com';\n\nexport const applyDomain: CreateQpqAppStep = {\n  name: 'Applying domain',\n\n  run: async ({ targetDirectory, answers }) => {\n    const deployConfigPath = path.join(targetDirectory, 'apps', answers.appName, 'deploy.config.json');\n    const deployConfig = readJsonFile(deployConfigPath);\n    deployConfig.domain = answers.domain;\n    writeJsonFile(deployConfigPath, deployConfig);\n\n    replaceInFileExact(\n      path.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'),\n      TEMPLATE_DOMAIN,\n      answers.domain,\n    );\n  },\n};\n"]}
+{"version":3,"file":"006_applyDomain.js","sourceRoot":"","sources":["../../../src/steps/006_applyDomain.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,gDAAwB;AAExB,kEAA+D;AAG/D,6EAA6E;AAC7E,8EAA8E;AAC9E,yBAAyB;AACzB,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEnC,QAAA,WAAW,GAAqB;IAC3C,IAAI,EAAE,iBAAiB;IAEvB,GAAG,EAAE,KAAqC,EAAE,4CAAhC,EAAE,eAAe,EAAE,OAAO,EAAE;QACtC,IAAA,uCAAkB,EAChB,cAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,EAChG,eAAe,EACf,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC,CAAA;CACF,CAAC","sourcesContent":["import path from 'path';\n\nimport { replaceInFileExact } from '../lib/replaceInFileExact';\nimport { CreateQpqAppStep } from '../types';\n\n// The template's domain, replaced where it's authoritative: the app's domain\n// constant (everything else derives from it). One root at scaffold time; more\n// can be appended later.\nconst TEMPLATE_DOMAIN = 'todo.quidproquojs.com';\n\nexport const applyDomain: CreateQpqAppStep = {\n  name: 'Applying domain',\n\n  run: async ({ targetDirectory, answers }) => {\n    replaceInFileExact(\n      path.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'),\n      TEMPLATE_DOMAIN,\n      answers.domain,\n    );\n  },\n};\n"]}

package/lib/commonjs/steps/013_printNextSteps.js

@@ -26,7 +26,7 @@ Next steps:
 ${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080
   npm run deploy     # build the docker image (then run the printed docker command)
 
-Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).
+Deploy config lives in apps/${answers.appName}/deploy.config.json; the domain (${answers.domain}) lives in the app's constants package.
 `);
     }),
 };

package/lib/commonjs/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services (admin, auth, design, shell and todo) and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,oCAAoC,OAAO,CAAC,MAAM;CAC9F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services (admin, auth, design, shell and todo) and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json; the domain (${answers.domain}) lives in the app's constants package.\n`);\n  },\n};\n"]}

package/lib/esm/steps/006_applyDomain.js

@@ -1,17 +1,12 @@
 import path from 'path';
-import { readJsonFile } from '../lib/readJsonFile';
 import { replaceInFileExact } from '../lib/replaceInFileExact';
-import { writeJsonFile } from '../lib/writeJsonFile';
-// The template's domain, replaced wherever it's authoritative: the deploy
-// config and the app's domain constant (everything else derives from those).
+// The template's domain, replaced where it's authoritative: the app's domain
+// constant (everything else derives from it). One root at scaffold time; more
+// can be appended later.
 const TEMPLATE_DOMAIN = 'todo.quidproquojs.com';
 export const applyDomain = {
     name: 'Applying domain',
     run: async ({ targetDirectory, answers }) => {
-        const deployConfigPath = path.join(targetDirectory, 'apps', answers.appName, 'deploy.config.json');
-        const deployConfig = readJsonFile(deployConfigPath);
-        deployConfig.domain = answers.domain;
-        writeJsonFile(deployConfigPath, deployConfig);
         replaceInFileExact(path.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'), TEMPLATE_DOMAIN, answers.domain);
     },
 };

package/lib/esm/steps/006_applyDomain.js.map

@@ -1 +1 @@
-{"version":3,"file":"006_applyDomain.js","sourceRoot":"","sources":["../../../src/steps/006_applyDomain.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,0EAA0E;AAC1E,6EAA6E;AAC7E,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,iBAAiB;IAEvB,GAAG,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1C,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACnG,MAAM,YAAY,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAC;QACpD,YAAY,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QACrC,aAAa,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;QAE9C,kBAAkB,CAChB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,EAChG,eAAe,EACf,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import path from 'path';\n\nimport { readJsonFile } from '../lib/readJsonFile';\nimport { replaceInFileExact } from '../lib/replaceInFileExact';\nimport { writeJsonFile } from '../lib/writeJsonFile';\nimport { CreateQpqAppStep } from '../types';\n\n// The template's domain, replaced wherever it's authoritative: the deploy\n// config and the app's domain constant (everything else derives from those).\nconst TEMPLATE_DOMAIN = 'todo.quidproquojs.com';\n\nexport const applyDomain: CreateQpqAppStep = {\n  name: 'Applying domain',\n\n  run: async ({ targetDirectory, answers }) => {\n    const deployConfigPath = path.join(targetDirectory, 'apps', answers.appName, 'deploy.config.json');\n    const deployConfig = readJsonFile(deployConfigPath);\n    deployConfig.domain = answers.domain;\n    writeJsonFile(deployConfigPath, deployConfig);\n\n    replaceInFileExact(\n      path.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'),\n      TEMPLATE_DOMAIN,\n      answers.domain,\n    );\n  },\n};\n"]}
+{"version":3,"file":"006_applyDomain.js","sourceRoot":"","sources":["../../../src/steps/006_applyDomain.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,6EAA6E;AAC7E,8EAA8E;AAC9E,yBAAyB;AACzB,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,iBAAiB;IAEvB,GAAG,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1C,kBAAkB,CAChB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,EAChG,eAAe,EACf,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import path from 'path';\n\nimport { replaceInFileExact } from '../lib/replaceInFileExact';\nimport { CreateQpqAppStep } from '../types';\n\n// The template's domain, replaced where it's authoritative: the app's domain\n// constant (everything else derives from it). One root at scaffold time; more\n// can be appended later.\nconst TEMPLATE_DOMAIN = 'todo.quidproquojs.com';\n\nexport const applyDomain: CreateQpqAppStep = {\n  name: 'Applying domain',\n\n  run: async ({ targetDirectory, answers }) => {\n    replaceInFileExact(\n      path.join(targetDirectory, 'apps', answers.appName, 'packages', 'constants', 'src', 'domain.ts'),\n      TEMPLATE_DOMAIN,\n      answers.domain,\n    );\n  },\n};\n"]}

package/lib/esm/steps/013_printNextSteps.js

@@ -14,7 +14,7 @@ Next steps:
 ${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080
   npm run deploy     # build the docker image (then run the printed docker command)
 
-Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).
+Deploy config lives in apps/${answers.appName}/deploy.config.json; the domain (${answers.domain}) lives in the app's constants package.
 `);
     },
 };

package/lib/esm/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services (admin, auth, design, shell and todo) and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,oCAAoC,OAAO,CAAC,MAAM;CAC9F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services (admin, auth, design, shell and todo) and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run dev        # api on http://localhost:8080, web on http://localhost:3080\n  npm run deploy     # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json; the domain (${answers.domain}) lives in the app's constants package.\n`);\n  },\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "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.19"
+    "quidproquo-tsconfig": "0.1.21"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/README.md

@@ -28,7 +28,7 @@ curl -H "Host: qpqjs.development.localhost" http://localhost:8080/api/shell/v1/h
 
 ```
 apps/<app>/                       # qpqjs
-  deploy.config.json              # { "prefix", "domain" }: dns config for deploy
+  deploy.config.json              # { "prefix", "environments" }: deploy identity per environment
   tsconfig.federated.json         # generated by `npm run prep`: cross-view type aliases
   packages/                       # app-wide libs (config, constants, service-utils)
   services/<svc>/
@@ -85,14 +85,17 @@ Every app-facing command (`prep`, `synth`, `go`, `go:docker`, `go:dev`, `go:dev:
 
 ```bash
 npm run deploy         # docker deploy (qpq go:docker)
+npx qpq setup          # new account/environment: checked steps (creds, IAM, zones, bucket names,
+                       # cdk bootstrap, account/domain/bootstrap stacks incl. the GitHub OIDC
+                       # provider + deploy role), run in order; then deploy services with go:docker
 npx qpq synth          # writes dist/apps/<app>/infrastructure/<svc>-config.json for cdk
 npx qpq go             # interactive aws deploy: pick app, services, stacks (inf/api/web/views)
                        # bundles (rspack production), cdk deploy, and s3 sync per phase
 ```
 
-`qpq go` needs AWS credentials plus a deploy identity: either an `"environments"` map in `apps/<app>/deploy.config.json` (`{ "prefix", "domain", "environments": { "<env>": { "accountId", "region" } } }`, selected with `--env <name>`) or the legacy `ENVIRONMENT` and `AWS_DEFAULT_*` env vars. App-specific bootstrap and account extras live in `apps/<app>/bootstrap.qpq.ts` and `apps/<app>/account.qpq.ts` as config fragments; the identity plumbing is provided by the generic CDK app in `quidproquo-deploy-awscdk`.
+`qpq go` needs AWS credentials plus a deploy identity: either an `"environments"` map in `apps/<app>/deploy.config.json` (`{ "prefix", "environments": { "<env>": { "accountId", "region" } } }`, selected with `--env <name>`) or the legacy `ENVIRONMENT` and `AWS_DEFAULT_*` env vars. App-specific bootstrap and account extras live in `apps/<app>/bootstrap.qpq.ts` and `apps/<app>/account.qpq.ts` as config fragments; the identity plumbing is provided by the generic CDK app in `quidproquo-deploy-awscdk`.
 
-- Production views bundles get prod remote URLs (`https://views.<feature>.<env>.<domain>/<svc>`) derived from `deploy.config.json` plus the service's qpq config. Dev bundles use localhost ports.
+- Production views bundles get prod remote URLs (the `views` host on the primary root, under the app's domain resolver) derived from the service's qpq config. Dev bundles use localhost ports.
 - `cdk.context.json` at the repo root is CDK's regenerable Route53 lookup cache. It is written on the first deploy, and checking it in means later synths need no live AWS lookups.
 
 ## Adding a service

package/template/apps/qpqjs/account.qpq.ts

@@ -7,33 +7,25 @@ import { QPQConfig } from 'quidproquo';
 import {
   AwsDataStoreRemovalPolicy,
   defineAccountBudget,
-  defineAccountCloudTrail,
+  defineAccountGithubOidcProvider,
   defineAccountSecurityServices,
   defineAwsDataStoreRemovalPolicy,
 } from 'quidproquo-config-aws';
 
 export default (): QPQConfig => [
-  // Dev account: deleting the account stack takes the CloudTrail bucket
-  // (and its audit history) with it.
+  // Dev account: data stores created by the account stack are torn down with it.
   defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.destroy),
 
-  defineAccountCloudTrail('main', {
-    cloudWatchLogs: {
-      retentionDays: 30,
-    },
-  }),
-
   defineAccountBudget('main', 30, ['joecoady@gmail.com']),
 
+  // GitHub Actions OIDC provider, trusted by every app's deploy role in this account.
+  defineAccountGithubOidcProvider(),
+
   defineAccountSecurityServices({
     // GuardDuty is org-managed for this account
     // (delegated admin 816650600287 auto-enables detectors - a stack-created one
     // would collide), and Security Hub is off pending the AWS Config cost decision.
     enableGuardDuty: false,
     enableSecurityHub: false,
-    cognitoAuthFailureAlert: {
-      emails: ['joecoady@gmail.com'],
-      thresholdPer5Minutes: 10,
-    },
   }),
 ];

package/template/apps/qpqjs/bootstrap.qpq.ts

@@ -1,10 +1,10 @@
-// App-specific bootstrap extras — WAF, api, and the domain certificates. The
-// identity plumbing (defineApplication + defineAwsServiceAccountInfo) is
-// provided by quidproquo-deploy-awscdk's workspace CDK app; this fragment must
-// not declare its own. Prefix/domain/environment arrive via the deploy context
-// (from deploy.config.json + qpq go).
-import { defineApi, QPQConfig } from 'quidproquo';
+// App-specific bootstrap extras: the root domains, WAF, the api domain, and the
+// domain certificates. The identity plumbing (defineApplication +
+// defineAwsServiceAccountInfo) is provided by quidproquo-deploy-awscdk's
+// workspace CDK app; this fragment must not declare its own.
+import { defineApi, defineDns, QPQConfig } from 'quidproquo';
 import {
+  defineAwsGithubDeployRole,
   defineBootstrapWaf,
   defineDomainCertificate,
   WafManagedRuleGroup,
@@ -12,7 +12,14 @@ import {
 } from 'quidproquo-config-aws';
 import { QpqAppDeployContext } from 'quidproquo-deploy-awscdk';
 
-export default ({ domain, region }: QpqAppDeployContext): QPQConfig => [
+import { QPQJS_DOMAINS, QpqjsServiceEnum } from '@qpqjs/constants';
+
+export default ({ region }: QpqAppDeployContext): QPQConfig => [
+  defineDns(QPQJS_DOMAINS),
+
+  // The role the deploy workflow assumes (ids from `gh api repos/qpqjs/quidproquo`).
+  defineAwsGithubDeployRole('qpqjs/quidproquo', { ownerId: 314167689, repositoryId: 571382961 }),
+
   defineBootstrapWaf({
     rateLimits: [{ name: 'all-traffic', limit: 2000 }],
     managedRuleGroups: [
@@ -28,15 +35,23 @@ export default ({ domain, region }: QpqAppDeployContext): QPQConfig => [
     },
   }),
 
-  defineApi('api', domain),
+  defineApi('api'),
 
+  // CloudFront (us-east-1): the site root plus every web entry, on every root domain.
   defineDomainCertificate(
-    domain,
     'us-east-1',
-    ['www', 'views', 'docs', 'storybook'],
-    {
-      includeApex: true,
-    }
+    [
+      { subdomain: 'www' },
+      { subdomain: 'views' },
+      { subdomain: 'docs' },
+      { subdomain: 'storybook' },
+    ],
+    { includeApex: true }
   ),
-  defineDomainCertificate(domain, region, ['api', 'ws.ws', 'qpqadmin.admin']),
+
+  // Regional API Gateway: the api and the admin websocket.
+  defineDomainCertificate(region, [
+    { subdomain: 'api' },
+    { subdomain: 'qpqadmin', service: QpqjsServiceEnum.Admin },
+  ]),
 ];

package/template/apps/qpqjs/deploy.config.json

@@ -1,6 +1,5 @@
 {
   "prefix": "qpqjs",
-  "domain": "quidproquojs.com",
   "environments": {
     "development": {
       "platform": "aws",

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

@@ -1 +1,3 @@
-export const QPQJS_DOMAIN = 'quidproquojs.com';
+// Root domains the app is served on, primary first. Every api, web entry and
+// websocket is created on each of them; absolute URLs bake to the primary.
+export const QPQJS_DOMAINS = ['quidproquojs.com', 'qpqjs.com'];

package/template/apps/qpqjs/packages/service-utils/src/defineQpqjsService.ts

@@ -11,19 +11,20 @@ import {
 } from 'quidproquo';
 import {
   ApiLayer,
+  AwsDataStoreRemovalPolicy,
+  defineAwsDataStoreRemovalPolicy,
   defineAwsServiceAccountInfo,
   defineWafProtection,
-  AwsDataStoreRemovalPolicy,
-  defineAwsDataStoreRemovalPolicy 
 } from 'quidproquo-config-aws';
 import {
   defineAdminSettings,
   defineAdminUserDirectory,
+  defineOpenApiRoutes,
 } from 'quidproquo-features';
 
 import { execSync } from 'child_process';
 import {
-  QPQJS_DOMAIN,
+  QPQJS_DOMAINS,
   QPQJS_USER_DIRECTORY,
   QpqjsServiceEnum,
   qpqjsServiceNames,
@@ -40,8 +41,7 @@ export const defineQpqjsService = (
   configRoot: string,
   apiBuildPath: string,
   apiLayers: ApiLayer[] = [],
-  lambdaMemoryInMiB = 1024,
-  domainName = QPQJS_DOMAIN
+  lambdaMemoryInMiB = 1024
 ): QPQConfig => [
   defineApplicationModule(
     modulePrefix,
@@ -58,7 +58,7 @@ export const defineQpqjsService = (
       .trim()}-${new Date().toISOString()}`
   ),
 
-  defineDns(domainName),
+  defineDns(QPQJS_DOMAINS),
 
   defineAdminUserDirectory({
     owner: {
@@ -111,7 +111,7 @@ export const defineQpqjsService = (
     sharedSingletons: ['chakra', 'zod'],
   }),
 
-  defineApi('api', domainName),
+  defineApi('api'),
   defineDefaultRouteOptions('api', {
     allowedOrigins: [
       'http://localhost:3080',
@@ -138,11 +138,17 @@ export const defineQpqjsService = (
     }
   ),
 
-  defineAdminSettings(QpqjsServiceEnum.Admin, QPQJS_DOMAIN, {
+  defineAdminSettings(QpqjsServiceEnum.Admin, {
     services: qpqjsServiceNames,
     coldStorageAfterDays: 90,
   }),
 
+  // Every service documents itself: reference page at /v1/docs, the generated
+  // OpenAPI document at /v1/docs/openapi.json. Public, like the docs site.
+  defineOpenApiRoutes({
+    info: { title: `${modulePrefix} ${service}`, version: '1.0.0' },
+  }),
+
   // turning this off is super painful for maintaince, dont be a nubbet.
-  defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.destroy)
+  defineAwsDataStoreRemovalPolicy(AwsDataStoreRemovalPolicy.destroy),
 ];

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/components/Infrastructure.tsx

@@ -29,8 +29,7 @@ const CONFIG_LINES: ReactNode[] = [
   </>,
   <>
     {'    '}
-    {pr('domain')}: {'{'} onRootDomain: {kw('true')}, rootDomain: QPQJS_DOMAIN{' '}
-    {'}'},
+    {pr('domain')}: {'{'} onRootDomain: {kw('true')} {'}'},
   </>,
   <>{'  }),'}</>,
   <>&nbsp;</>,

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

@@ -6,7 +6,7 @@ import {
 import { defineDevServerOptions } from 'quidproquo-dev-server/config';
 import { defineDynamicRoutes } from 'quidproquo-features';
 
-import { QPQJS_DOMAIN, QpqjsServiceEnum } from '@qpqjs/constants';
+import { QpqjsServiceEnum } from '@qpqjs/constants';
 import { defineQpqjsService } from '@qpqjs/service-utils';
 
 import * as dynamicRoutes from './entry/controller';
@@ -23,7 +23,6 @@ const webEntryOptions: QPQConfigAdvancedWebEntrySettings = {
   cacheSettingsName: 'default',
   domain: {
     onRootDomain: true,
-    rootDomain: QPQJS_DOMAIN,
   },
   storageDrive: {
     sourceStorageDrive: websiteWebEntryStorageDriveName,
@@ -40,7 +39,6 @@ const mfeHostWebEntryOptions: QPQConfigAdvancedWebEntrySettings = {
   domain: {
     subDomainName: 'views',
     onRootDomain: true,
-    rootDomain: QPQJS_DOMAIN,
   },
   storageDrive: {
     sourceStorageDrive: mfeHostWebEntryStorageDriveName,
@@ -65,7 +63,6 @@ const docsWebEntryOptions: QPQConfigAdvancedWebEntrySettings = {
   domain: {
     subDomainName: 'docs',
     onRootDomain: true,
-    rootDomain: QPQJS_DOMAIN,
   },
 };
 

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

@@ -2,7 +2,8 @@
   "name": "@qpqjs/test-models",
   "version": "0.0.1",
   "dependencies": {
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "zod": "^3.25.76"
   },
   "type": "commonjs",
   "main": "./dist/src/index.js",

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

@@ -0,0 +1,8 @@
+import { z } from 'zod/v4';
+
+// Body of POST /echo/{pathValue}: one value to be sent straight back.
+export const EchoRequestSchema = z.object({
+  bodyValue: z.string().min(1).describe('Any text; it comes back unchanged'),
+});
+
+export type EchoRequest = z.infer<typeof EchoRequestSchema>;

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

@@ -0,0 +1,9 @@
+import { z } from 'zod/v4';
+
+// What POST /echo/{pathValue} returns: the path and body values, untouched.
+export const EchoResponseSchema = z.object({
+  pathValue: z.string().describe('The {pathValue} segment of the url'),
+  bodyValue: z.string().describe('The bodyValue from the request body'),
+});
+
+export type EchoResponse = z.infer<typeof EchoResponseSchema>;

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

@@ -1,14 +1,16 @@
-import { Nullable } from 'quidproquo';
+import { z } from 'zod/v4';
 
 import { SmokeRunStatus } from './SmokeRunStatus';
-import { SmokeTestResult } from './SmokeTestResult';
+import { SmokeTestResultSchema } 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[];
-};
+export const SmokeRunSchema = z.object({
+  runId: z.string(),
+  status: z.enum(SmokeRunStatus),
+  startedAt: z.iso.datetime(),
+  finishedAt: z.iso.datetime().nullable(),
+  tests: z.array(SmokeTestResultSchema),
+});
+
+export type SmokeRun = z.infer<typeof SmokeRunSchema>;

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

@@ -0,0 +1,8 @@
+import { z } from 'zod/v4';
+
+// What POST /smoke/run returns: just the handle to poll with.
+export const SmokeRunStartedSchema = z.object({
+  runId: z.string().describe('Poll GET /smoke/run/{runId} with this'),
+});
+
+export type SmokeRunStarted = z.infer<typeof SmokeRunStartedSchema>;

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

@@ -1,8 +1,12 @@
+import { z } from 'zod/v4';
+
 // 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;
-};
+export const SmokeRunSummarySchema = z.object({
+  total: z.int().nonnegative().describe('Tests registered for the run'),
+  completed: z.int().nonnegative().describe('Tests that have passed or failed'),
+  passed: z.int().nonnegative(),
+  failed: z.int().nonnegative(),
+});
+
+export type SmokeRunSummary = z.infer<typeof SmokeRunSummarySchema>;

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

@@ -1,7 +1,11 @@
-import { SmokeRun } from './SmokeRun';
-import { SmokeRunSummary } from './SmokeRunSummary';
+import { z } from 'zod/v4';
+
+import { SmokeRunSchema } from './SmokeRun';
+import { SmokeRunSummarySchema } from './SmokeRunSummary';
 
 // What GET /smoke/run/{runId} returns: the stored run plus derived counts.
-export type SmokeRunWithSummary = SmokeRun & {
-  summary: SmokeRunSummary;
-};
+export const SmokeRunWithSummarySchema = SmokeRunSchema.extend({
+  summary: SmokeRunSummarySchema,
+});
+
+export type SmokeRunWithSummary = z.infer<typeof SmokeRunWithSummarySchema>;

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

@@ -1,15 +1,17 @@
-import { Nullable } from 'quidproquo';
+import { z } from 'zod/v4';
 
 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>;
-};
+export const SmokeTestResultSchema = z.object({
+  id: z.int().positive().describe('1-based position in the test registry'),
+  name: z.string().describe('Stable test name'),
+  status: z.enum(SmokeTestStatus),
+  message: z.string(),
+  startedAt: z.iso.datetime().nullable(),
+  finishedAt: z.iso.datetime().nullable(),
+});
+
+export type SmokeTestResult = z.infer<typeof SmokeTestResultSchema>;

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

@@ -1,5 +1,8 @@
+export * from './EchoRequest';
+export * from './EchoResponse';
 export * from './SmokeProbeRecord';
 export * from './SmokeRun';
+export * from './SmokeRunStarted';
 export * from './SmokeRunStatus';
 export * from './SmokeRunSummary';
 export * from './SmokeRunWithSummary';

package/template/apps/qpqjs/services/test/service/src/echo/config/defineEcho.ts

@@ -0,0 +1,9 @@
+import { QPQConfig } from 'quidproquo';
+import { defineDynamicRoutes } from 'quidproquo-features';
+
+import * as controllers from '../controller';
+
+// The echo routes carry their own method/path/schema on the handler; this just
+// registers the controller module under the service's src root.
+export const defineEcho = (): QPQConfig =>
+  defineDynamicRoutes(controllers, '/echo/controller');

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

@@ -0,0 +1,32 @@
+import { AskResponse, HTTPEventResponse, qpqWebServerUtils } from 'quidproquo';
+import { dynamicRoute } from 'quidproquo-features';
+
+import {
+  EchoRequestSchema,
+  EchoResponse,
+  EchoResponseSchema,
+} from '@qpqjs/test-models';
+
+// POST /echo/{pathValue}. Public. Exists to prove a value survives the trip
+// through the url and the validated body: the response is both, unchanged.
+export const echo = dynamicRoute(
+  ['POST', '/echo/{pathValue}'],
+  function* (event, params, { body }): AskResponse<HTTPEventResponse> {
+    const response: EchoResponse = {
+      pathValue: params.pathValue,
+      bodyValue: body.bodyValue,
+    };
+
+    return qpqWebServerUtils.toJsonEventResponse(response);
+  },
+  {
+    schema: {
+      summary: 'Echo a path and body value',
+      description:
+        'Returns the {pathValue} url segment and the bodyValue from the JSON body, untouched. Public, for trying the docs UI.',
+      tags: ['echo'],
+      body: EchoRequestSchema,
+      response: EchoResponseSchema,
+    },
+  }
+);

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

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

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

@@ -3,6 +3,7 @@ import { defineDevServerOptions } from 'quidproquo-dev-server/config';
 import { QpqjsServiceEnum } from '@qpqjs/constants';
 import { defineQpqjsService } from '@qpqjs/service-utils';
 
+import { defineEcho } from './echo/config/defineEcho';
 import { defineSmoke } from './smoke/config/defineSmoke';
 import { defineTick } from './tick/config/defineTick';
 
@@ -18,5 +19,7 @@ export default [
 
   defineSmoke(),
 
+  defineEcho(),
+
   defineTick(),
 ];