@mindbricks/genesis-set 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +44 -0
- package/LICENSE +202 -0
- package/README.md +148 -2
- package/bin/genesis-set.mjs +153 -0
- package/corpus/README.md +25 -0
- package/corpus/genesis/compile-results.md +246 -0
- package/corpus/genesis/compiler-api.md +265 -0
- package/corpus/genesis/custom-code.md +519 -0
- package/corpus/genesis/deploy.md +190 -0
- package/corpus/genesis/pitfalls.md +231 -0
- package/corpus/genesis/procedures/README.md +17 -0
- package/corpus/genesis/procedures/agent-hub-blueprint.md +13 -0
- package/corpus/genesis/procedures/auth-blueprint.md +14 -0
- package/corpus/genesis/procedures/bff-blueprint.md +16 -0
- package/corpus/genesis/procedures/blueprint-authoring.md +16 -0
- package/corpus/genesis/procedures/howto-mail-to-tasks.md +26 -0
- package/corpus/genesis/procedures/howto-payment-flow.md +112 -0
- package/corpus/genesis/procedures/howto-subscription.md +33 -0
- package/corpus/genesis/procedures/notifications-blueprint.md +13 -0
- package/corpus/genesis/procedures/patterns-catalog.md +12 -0
- package/corpus/genesis/procedures/project-lifecycle.md +27 -0
- package/corpus/genesis/run-locally.md +310 -0
- package/corpus/genesis/testing.md +532 -0
- package/lib/config-cli.mjs +179 -0
- package/lib/install.mjs +639 -0
- package/lib/mcp-config.mjs +222 -0
- package/lib/semver.mjs +94 -0
- package/mcp/blueprint.mjs +64 -0
- package/mcp/client.mjs +141 -0
- package/mcp/config.mjs +166 -0
- package/mcp/key-page-html.mjs +275 -0
- package/mcp/key-page.mjs +217 -0
- package/mcp/key-store.mjs +204 -0
- package/mcp/key-tools.mjs +225 -0
- package/mcp/server.mjs +164 -0
- package/mcp/tools.mjs +270 -0
- package/package.json +44 -4
- package/skills/genesis-compiler-api/SKILL.md +56 -0
- package/skills/genesis-deploy/SKILL.md +36 -0
- package/skills/genesis-generated-code/SKILL.md +48 -0
- package/skills/genesis-run-and-test/SKILL.md +43 -0
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# Deploying the generated services yourself
|
|
2
|
+
|
|
3
|
+
**Genesis never deploys.** It writes the files a deploy needs into each service repository; the
|
|
4
|
+
deploy itself is run by the user, or by you on the user's behalf, with the user's own login on
|
|
5
|
+
the target. No deploy credential ever goes to Genesis, into the blueprint or into a project file.
|
|
6
|
+
This page lists, per target, what Genesis writes and the commands that deploy it.
|
|
7
|
+
|
|
8
|
+
> **Not deployable yet.** Builds are dry runs for now: the deploy files are generated and
|
|
9
|
+
> counted (the job's `deployArtifacts`), but nothing is pushed to the user's repositories, so
|
|
10
|
+
> there is nothing to deploy yet. Until pushing opens, say so, and do not write a target's files
|
|
11
|
+
> by hand as if Genesis had generated them.
|
|
12
|
+
|
|
13
|
+
## 1. Asking for the deploy files
|
|
14
|
+
|
|
15
|
+
Name the targets in the build: `genesis_buildService` with, for example,
|
|
16
|
+
`deployTargets: ["docker-compose", "fly"]`. Each target writes `deploy/<target>/` into the
|
|
17
|
+
service. These are generated files: they are in the manifest, counted in the build's added lines,
|
|
18
|
+
and rewritten by every build that names the target (do not edit them; keep your own deploy
|
|
19
|
+
files outside `deploy/<target>/`). The job's `deployArtifacts` lists per target
|
|
20
|
+
`{ target, status: "emitted" | "skipped", path, files, reason? }`; a part without a container
|
|
21
|
+
image (`document`, `frontend`) is `skipped`.
|
|
22
|
+
|
|
23
|
+
| Target | Status | Folder |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `docker-compose` | available | `deploy/docker-compose/`: `docker-compose.yml`, `.env.example`, `.providers.secrets.env.example`, `README.md` |
|
|
26
|
+
| `railway` | available | `deploy/railway/`: `railway.json`, `variables.env`, `README.md` |
|
|
27
|
+
| `fly` | available | `deploy/fly/`: `fly.toml`, `secrets.env`, `README.md` |
|
|
28
|
+
| `render` | available | `deploy/render/`: `render.yaml`, `README.md` |
|
|
29
|
+
|
|
30
|
+
An unknown target answers `400 GENESIS_UNKNOWN_DEPLOY_TARGET` with `details.allowed`: that list,
|
|
31
|
+
not this page, is the truth for the API you call. There is no frontend target: the user places
|
|
32
|
+
the frontend themselves.
|
|
33
|
+
|
|
34
|
+
The generated `README.md` of each target is written for that service and that build (its service
|
|
35
|
+
names, ports and variables). Read it before you run anything; where it and this page differ,
|
|
36
|
+
it wins.
|
|
37
|
+
|
|
38
|
+
## 2. What every target needs
|
|
39
|
+
|
|
40
|
+
- **The secrets are references, never values.** Every password and key in the generated files is
|
|
41
|
+
a `${VAR}` / `${VAR:?}` / `${{...}}` reference or a blank line. The user fills them on the
|
|
42
|
+
target (or in a gitignored local file), never in a committed file.
|
|
43
|
+
- **A signing key per service.** Each service signs its tokens with its own Ed25519 key. Without
|
|
44
|
+
one the service starts degraded (the login service cannot issue sessions). Per service:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
openssl genpkey -algorithm ed25519 -out <service>.pem # PKCS#8 PEM
|
|
48
|
+
uuidgen # its key id
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Set them as secret variables on the target (`SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` per
|
|
52
|
+
service on Railway, `<SERVICE>_SERVICE_PRIVATE_KEY_PEM` / `<SERVICE>_SERVICE_KID` in the
|
|
53
|
+
compose `.env`). Never commit a key file.
|
|
54
|
+
- **Peer addresses.** In the test, stage and prod slot files the addresses of the other services
|
|
55
|
+
(`AUTH_SERVICE_URL`, `SERVICE_<NAME>_URL`, ...) are blank on purpose: the deploy sets them.
|
|
56
|
+
The compose file and the Railway variables already wire the services of the same build.
|
|
57
|
+
- **Provider credentials** (payment, mail, storage, AI): the keys each service reads are listed
|
|
58
|
+
in its `.providers.secrets.env.example` (compose) or as shared variables (Railway). Missing ones
|
|
59
|
+
do not stop the service from starting; it answers errors where they are needed (see
|
|
60
|
+
[pitfalls.md](pitfalls.md)).
|
|
61
|
+
- **For a local file** (`.env`, `*.secrets.env`): ask for each key on the local key page
|
|
62
|
+
(`genesis_requestKey`, then `genesis_writeKeyToEnvFile`), never in the chat.
|
|
63
|
+
- **On a hosting target:** the user enters the key in the target's own secret settings.
|
|
64
|
+
- **The test transport.** Every generated nodejs service mounts super-admin-only test routes
|
|
65
|
+
(`/<service>-api/admin/test-transport`, [testing.md](testing.md)) on any explicit non-production
|
|
66
|
+
slot: the `dev`, `test` and `stage` images. The Railway, Fly.io and Render files run the PROD
|
|
67
|
+
slot, where they are closed. On
|
|
68
|
+
any other shared deploy that is not prod, set `MB_TEST_TRANSPORT=off` unless the user wants the
|
|
69
|
+
surface reachable there.
|
|
70
|
+
- **Health:** every service answers `/health`. A deploy is done when `/health` reports ready,
|
|
71
|
+
not when the container runs ([run-locally.md](run-locally.md)).
|
|
72
|
+
|
|
73
|
+
## 3. docker-compose: the whole stack on one machine
|
|
74
|
+
|
|
75
|
+
The compose file holds every deployable service of the build, each built from its own repository
|
|
76
|
+
with its DEV slot image, plus the infrastructure they read: PostgreSQL or MongoDB (by each
|
|
77
|
+
service's database type), Redis and Elasticsearch for the backend services, and Kafka. Every
|
|
78
|
+
service repository carries the same stack.
|
|
79
|
+
|
|
80
|
+
1. Check the service repositories out side by side (the generated README lists the folder names,
|
|
81
|
+
`<codename>-<service>-service/`).
|
|
82
|
+
2. Then, in any one of them:
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
cd deploy/docker-compose
|
|
86
|
+
cp .env.example .env
|
|
87
|
+
cp .providers.secrets.env.example .providers.secrets.env
|
|
88
|
+
# fill in .env (passwords, signing keys) and the provider credentials you use
|
|
89
|
+
docker compose up --build
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
3. `docker compose ps` shows the health of each container; `docker compose logs -f <service>`
|
|
93
|
+
follows one service.
|
|
94
|
+
|
|
95
|
+
Notes:
|
|
96
|
+
- Docker Compose 2.24 or newer is needed (the provider file is an optional `env_file`).
|
|
97
|
+
- Neither `.env` nor `.providers.secrets.env` is committed: the generated `.gitignore` ignores
|
|
98
|
+
both. Use URL-safe passwords (the MongoDB password goes into a connection URL). Put a PEM into
|
|
99
|
+
`.env` in double quotes.
|
|
100
|
+
- The infrastructure is reachable only inside the compose network.
|
|
101
|
+
|
|
102
|
+
## 4. Railway
|
|
103
|
+
|
|
104
|
+
Per service, `deploy/railway/` holds the config-as-code file (the PROD slot Dockerfile, health
|
|
105
|
+
check `/health`, restart on failure), `variables.env` (the variables in Railway's Raw Editor
|
|
106
|
+
format, with Railway references for the databases and the other services) and a README naming
|
|
107
|
+
what the references expect.
|
|
108
|
+
|
|
109
|
+
The user logs in with their own Railway account; the login stays in the Railway CLI or their
|
|
110
|
+
browser, never in the project. In one Railway project:
|
|
111
|
+
|
|
112
|
+
1. Add the databases the README names: a PostgreSQL service named `Postgres` (for PostgreSQL
|
|
113
|
+
services), a MongoDB service named `MongoDB` (for MongoDB services) and a Redis service named
|
|
114
|
+
`Redis` (for backend services). The variable references use exactly these names.
|
|
115
|
+
2. For each service of the build, create a Railway service from its repository, named as its
|
|
116
|
+
README says (the other services' references use those names).
|
|
117
|
+
3. In that service's settings, set the config-as-code path to `deploy/railway/railway.json`.
|
|
118
|
+
4. In its Variables, open the Raw Editor and paste `deploy/railway/variables.env`. Fill the
|
|
119
|
+
shared variables the README lists (a missing one resolves to empty) and set
|
|
120
|
+
`SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` as sealed variables.
|
|
121
|
+
5. Generate a public domain for each service that serves the outside world.
|
|
122
|
+
|
|
123
|
+
With the Railway CLI the same steps are `railway login`, `railway link` (or `railway init` for a
|
|
124
|
+
new project) and, per service, `railway up` from the service repository; check
|
|
125
|
+
`railway --help` for the version the user has instead of guessing flags. In CI the token is a
|
|
126
|
+
secret of the CI system (`RAILWAY_TOKEN`), never a file of the repository.
|
|
127
|
+
|
|
128
|
+
## 5. Fly.io
|
|
129
|
+
|
|
130
|
+
One Fly app per service, named after its repository (`<codename>-<service>-service`).
|
|
131
|
+
`deploy/fly/` holds `fly.toml` (the PROD slot Dockerfile, `http_service` on the slot's port,
|
|
132
|
+
the `/health` check, an explicit VM size), `secrets.env` (every value the user gives, as blank
|
|
133
|
+
lines, in the form `fly secrets import` reads) and a README with the app names, the
|
|
134
|
+
infrastructure and the sizing.
|
|
135
|
+
|
|
136
|
+
- **Peers** talk over Fly's private network: `[env]` already holds each peer's
|
|
137
|
+
`http://<app>.flycast` address. Every app needs a private IP for that (Flycast).
|
|
138
|
+
- **Machines:** a service with a Kafka consumer or an in-process cron job is always on
|
|
139
|
+
(`auto_stop_machines = "off"`, `min_machines_running = 1`); only a service the tree proves
|
|
140
|
+
request-only scales to zero. A service whose README says ONE Machine runs in-process cron jobs
|
|
141
|
+
without a cross-Machine lock: deploy it with `--ha=false`.
|
|
142
|
+
- **Infrastructure:** PostgreSQL can be Fly Postgres and Redis Upstash for Redis; Kafka,
|
|
143
|
+
Elasticsearch and MongoDB come from outside Fly (a hosted provider) or the user's own Machines
|
|
144
|
+
with volumes. Their addresses and credentials go into `secrets.env`.
|
|
145
|
+
- No volume is mounted: the root filesystem is lost on every restart.
|
|
146
|
+
|
|
147
|
+
The user logs in with their own Fly account (`fly auth login`). Per service, from the service
|
|
148
|
+
repository root (the build context; `fly.toml` names the Dockerfile relative to itself):
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
fly apps create <app> # the app name from the README
|
|
152
|
+
fly ips allocate-v6 --private -a <app> # the Flycast address the peers use
|
|
153
|
+
# fill deploy/fly/secrets.env locally (never commit the filled file), then:
|
|
154
|
+
fly secrets import -a <app> < deploy/fly/secrets.env
|
|
155
|
+
fly deploy --config deploy/fly/fly.toml # add --ha=false where the README says ONE Machine
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Check `fly --help` for the version the user has instead of guessing flags. In CI the token is a
|
|
159
|
+
secret of the CI system (`FLY_API_TOKEN`), never a file of the repository.
|
|
160
|
+
|
|
161
|
+
## 6. Render
|
|
162
|
+
|
|
163
|
+
`deploy/render/render.yaml` is a Render Blueprint: one Docker `web` service built from the PROD
|
|
164
|
+
slot Dockerfile, with `/health` and an explicit size. The ONE repository that owns the project's
|
|
165
|
+
shared infrastructure (the login service, or the first backend service) also declares a Render
|
|
166
|
+
Postgres instance (every PostgreSQL service creates its own database on it) and a Key Value
|
|
167
|
+
(Redis) instance every service shares. The README of each service says which repository that is.
|
|
168
|
+
|
|
169
|
+
1. Apply the owner repository's Blueprint first: in the Render dashboard, New Blueprint from that
|
|
170
|
+
repository, Blueprint Path `deploy/render/render.yaml`.
|
|
171
|
+
2. Then the Blueprint of every other service repository, the same way.
|
|
172
|
+
3. When a Blueprint is first applied, Render asks for the `sync: false` values: the README lists
|
|
173
|
+
them. Peer addresses are among them: Render publishes a peer's private address as `host:port`,
|
|
174
|
+
so give it as `http://<host:port>`. Set `SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` there too.
|
|
175
|
+
4. Kafka, Elasticsearch and MongoDB come from outside Render; give their addresses and
|
|
176
|
+
credentials the same way.
|
|
177
|
+
|
|
178
|
+
A service that runs continuously (a Kafka consumer, in-process cron jobs) must stay off Render's
|
|
179
|
+
Free plan, whose instances spin down after 15 minutes without traffic. Keep ONE instance where
|
|
180
|
+
the README says so. The user signs in to Render with their own account; nothing about it goes to
|
|
181
|
+
Genesis or into the repository.
|
|
182
|
+
|
|
183
|
+
## 7. What you never do
|
|
184
|
+
|
|
185
|
+
- Ask the user for a deploy token to send to Genesis, or store one in the project, the blueprint
|
|
186
|
+
or a commit.
|
|
187
|
+
- Report a deploy as done without the target's own evidence: the platform's deploy log and
|
|
188
|
+
`/health` ready on the public address.
|
|
189
|
+
- Edit `deploy/<target>/` files to make a deploy work: the next build rewrites them. Fix the
|
|
190
|
+
blueprint and compile again, or report the generated file as a compiler fault with the job id.
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Genesis pitfalls: compiler facts
|
|
2
|
+
|
|
3
|
+
Behaviours of the code Genesis generates that surprise people who run it themselves. Each
|
|
4
|
+
entry: symptom, cause, what to do. Entries marked **nodejs** are verified for the nodejs
|
|
5
|
+
runtime only; other languages follow in their own time. Facts about HTTP shapes, seeding and
|
|
6
|
+
stale reads are in `procedures/pitfalls.md` (mind-set); this page adds what changes because
|
|
7
|
+
you run the service on your own machine or servers. Run steps are in
|
|
8
|
+
[run-locally.md](run-locally.md), failed builds in [compile-results.md](compile-results.md).
|
|
9
|
+
|
|
10
|
+
## 1. The slot decides everything: `CONFIG_ENV`
|
|
11
|
+
|
|
12
|
+
The generated service learns which environment it is in from `CONFIG_ENV`, written into each
|
|
13
|
+
slot file (`.dev.env` has `dev`, `.test.env` `test`, `.stage.env` `stage`, `.prod.env`
|
|
14
|
+
`prod`). Several behaviours below depend on it.
|
|
15
|
+
|
|
16
|
+
- **Unset or empty `CONFIG_ENV` resolves to `prod`**, with a loud console error. The service
|
|
17
|
+
keeps running, with the strictest behaviour (no verification codes in answers, no SMS sink).
|
|
18
|
+
A local run must load `.dev.env` or set `CONFIG_ENV=dev`.
|
|
19
|
+
- **A value it does not know throws** at start (a typo such as `prd`). Fix the deployment;
|
|
20
|
+
the service does not guess. Accepted: `dev`, `test`, `stage`, `prod` and the older
|
|
21
|
+
aliases `development`, `local`, `staging`, `production`.
|
|
22
|
+
- The slot is the only input. No header, body field or blueprint setting changes it, and the
|
|
23
|
+
blueprint's `verificationMode` is retired (a value other than the default only draws the
|
|
24
|
+
warning `VERIFICATION_MODE_INERT`).
|
|
25
|
+
|
|
26
|
+
## 2. Verification codes in the start answer (nodejs)
|
|
27
|
+
|
|
28
|
+
**Symptom:** a flow answers `emailVerificationNeeded` and no code reaches you, or the
|
|
29
|
+
`secretCode` is missing from the start answer.
|
|
30
|
+
|
|
31
|
+
**Cause:** the code is echoed in the `start` answer (with the `userId`, for an existing
|
|
32
|
+
account) only when the slot is `dev` or `test`. In `stage` and `prod` it is never in the
|
|
33
|
+
answer, whatever the blueprint says: it travels only through the real mail or SMS provider,
|
|
34
|
+
or lands in a sink (sections 3 and 4).
|
|
35
|
+
|
|
36
|
+
**Do:**
|
|
37
|
+
|
|
38
|
+
- Locally (`dev`), chain the two calls as `procedures/pitfalls.md` shows: `start`, then
|
|
39
|
+
`complete` with the returned `secretCode` as a string.
|
|
40
|
+
- On a `stage` or `prod` slot, read the code from the real inbox or handset when the
|
|
41
|
+
provider has credentials, otherwise from the mail sink. Do not set the slot to `dev` on a
|
|
42
|
+
reachable deployment to get codes: that is the one switch that turns the echo on.
|
|
43
|
+
- A missing `secretCode` on a `dev` or `test` slot for an existing account is worth
|
|
44
|
+
checking against `CONFIG_ENV` first (section 1), then reporting with the request and answer.
|
|
45
|
+
- A `start` answered 403 "too frequent" means a recent code exists. Wait or use another
|
|
46
|
+
account.
|
|
47
|
+
|
|
48
|
+
## 3. Mail falls to a sink, and a green send is not delivery (nodejs)
|
|
49
|
+
|
|
50
|
+
**Symptom:** verification and notification mails "send" and nobody receives them; or every
|
|
51
|
+
send fails with an SMTP connect error to `mail-sink`.
|
|
52
|
+
|
|
53
|
+
**Cause, in four parts:**
|
|
54
|
+
|
|
55
|
+
1. An email provider declared only under `mailAccounts` is NOT a send channel. A project with
|
|
56
|
+
no complete email provider (declared with all credential keys) has no real channel at all.
|
|
57
|
+
Validation warns once with `MAIL_FLOWS_GO_TO_SINK`.
|
|
58
|
+
2. With no complete email provider the framework routes every notification and every
|
|
59
|
+
verification mail to its built-in mock SMTP sink (the delivery rows name the provider
|
|
60
|
+
`__mailsink__`). It does so in every slot, `prod` included.
|
|
61
|
+
3. The sink is an SMTP host the environment must provide. The default address is
|
|
62
|
+
`mail-sink` port `465`; `MAILSINK_HOST` and `MAILSINK_PORT` point the service at another
|
|
63
|
+
one, `MAILSINK_REJECT_UNAUTHORIZED` is for a sink with a certificate the service does not
|
|
64
|
+
trust.
|
|
65
|
+
4. The generated `deploy/docker-compose/` stack does not list a mail-sink service. In that
|
|
66
|
+
stack the send fails after retries, one `failed` delivery row per message. It looks like an
|
|
67
|
+
outage; it is the same missing channel seen from the other side.
|
|
68
|
+
|
|
69
|
+
**Do:**
|
|
70
|
+
|
|
71
|
+
- For development, run any SMTP capture server your stack can reach, and set `MAILSINK_HOST`
|
|
72
|
+
/ `MAILSINK_PORT` for the service. Then a send is captured and reports success.
|
|
73
|
+
- Judge mail by the channel, never by the send status: success against the sink means
|
|
74
|
+
"stored in the sink", not "reached a recipient".
|
|
75
|
+
- For stage and production, declare a real email provider in the blueprint and give it its
|
|
76
|
+
credentials (`$ENV:` references in the blueprint, values in the service's secrets file).
|
|
77
|
+
- Reserved demo recipients can force the sink even with complete credentials. If a real
|
|
78
|
+
address gets nothing, check the recipient.
|
|
79
|
+
|
|
80
|
+
## 4. SMS: sink rules differ from mail (nodejs)
|
|
81
|
+
|
|
82
|
+
- An SMS provider that is declared but has incomplete credentials sends to the **SMS sink**
|
|
83
|
+
when `CONFIG_ENV` is set and is not `prod`. In `prod` it never falls back: the send fails at
|
|
84
|
+
the provider and the boot report names it.
|
|
85
|
+
- The SMS sink stores each message in the same mail sink as section 3: one mail per SMS to
|
|
86
|
+
`sms-<digits>@sms-sink.invalid` (digits of the number only), subject `SMS to <number>`,
|
|
87
|
+
provider name `__smssink__`. Search the inbox by the number. It needs the same sink host.
|
|
88
|
+
- A project with **no SMS provider declared at all** still builds the mobile flows, and every
|
|
89
|
+
SMS goes to the sink in every slot, `prod` included (validation warns once with
|
|
90
|
+
`SMS_FLOWS_GO_TO_SINK`). Name the real SMS provider before production.
|
|
91
|
+
- A sunk SMS was not delivered to a handset.
|
|
92
|
+
|
|
93
|
+
## 5. Credential fallbacks, and what each one proves (nodejs)
|
|
94
|
+
|
|
95
|
+
Missing credentials never stop the service. The runtime falls back, per family:
|
|
96
|
+
|
|
97
|
+
| Family | With credentials missing or incomplete |
|
|
98
|
+
|---|---|
|
|
99
|
+
| mail | the mail sink (section 3), every slot |
|
|
100
|
+
| SMS | the SMS sink on non-prod slots (section 4) |
|
|
101
|
+
| bucket | the service's own native store |
|
|
102
|
+
| payment | the provider's mock, for `stripe`, `iyzico` and `adyen`; other brands have no mock and REFUSE at payment start |
|
|
103
|
+
| AI | no fallback: the call fails |
|
|
104
|
+
|
|
105
|
+
Use the four evidence outcomes when you report a provider. Never put key values in the
|
|
106
|
+
report.
|
|
107
|
+
|
|
108
|
+
| Outcome | Evidence | What it proves |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| Configured test provider | a declared test brand or transport and an observed operation | only that test path |
|
|
111
|
+
| Selected fallback | the runtime's own status names the sink / native / mock mode and the reason | the fallback, not vendor delivery |
|
|
112
|
+
| Placeholder-only | a required secret is still `ENTER_CREDENTIAL` or absent | the provider is bound; the real operation is unverified |
|
|
113
|
+
| Measured delivery | the real operation plus a receipt or captured artifact | that operation in that slot; a sink capture is not a recipient's delivery |
|
|
114
|
+
|
|
115
|
+
Rules:
|
|
116
|
+
|
|
117
|
+
- `ENTER_CREDENTIAL` is the placeholder for a secret that is not provided. It passes
|
|
118
|
+
authoring and counts as "not configured" at runtime; it is no proof of anything. A
|
|
119
|
+
realistic fake value is worse than the placeholder: it looks configured.
|
|
120
|
+
- A required key that is NOT a secret (a sender address on your own domain) takes the real
|
|
121
|
+
value, never the placeholder: a placeholder there reads as a value and the provider fails at
|
|
122
|
+
send time with nothing warning first.
|
|
123
|
+
- `<PREFIX>_CREDENTIAL_MODE` in a slot's environment (`auto`, `sandbox`, `live`, `mock`) is
|
|
124
|
+
read BEFORE the credential check: `mock` engages the mock or sink whatever credentials are
|
|
125
|
+
present; `live` lifts the payment live-key guard on a non-prod slot. Unrecognised or blank
|
|
126
|
+
means `auto`.
|
|
127
|
+
- A payment live key in a non-prod slot is refused by a guard unless the mode is `live`.
|
|
128
|
+
Keep live keys in the `prod` slot's secrets file only.
|
|
129
|
+
- Check what the service decided, not what you configured: `GET /health` carries a
|
|
130
|
+
`providerCredentials` block (`status` `ok` / `incomplete` / `error`, `deploymentEnv`,
|
|
131
|
+
`providerCount`, `findings`), and the payment service serves
|
|
132
|
+
`GET /<order-service>-api/v1/payments/mock-status` (one row per provider with `mock`,
|
|
133
|
+
`reason`, `transport`, `blocking`; plus `anyMock`, `blocking`, `health`). Read your
|
|
134
|
+
provider's row. `transport: "absent"` means the brand has no mock and payment start
|
|
135
|
+
refuses.
|
|
136
|
+
- Never call a live provider from a test. The runtime ladders for payments and
|
|
137
|
+
subscriptions are in `procedures/howto-payment-flow.md`, with the Genesis additions in
|
|
138
|
+
`genesis/procedures/howto-payment-flow.md` of this corpus.
|
|
139
|
+
|
|
140
|
+
## 6. Payment tables need auth compiled after the provider is bound
|
|
141
|
+
|
|
142
|
+
**Symptom:** starting a payment answers 500 through a missing `/auth-api/paymentcustomers`.
|
|
143
|
+
|
|
144
|
+
**Cause:** the auth service's payment tables (`sys_paymentCustomer`, `sys_paymentMethod`) and
|
|
145
|
+
their routes are generated only when a payment provider is bound in the blueprint. An auth
|
|
146
|
+
service compiled before the provider was bound does not have them.
|
|
147
|
+
|
|
148
|
+
**Do:** bind the provider, validate, compile `auth` again, re-run the service from the new
|
|
149
|
+
code (and rebuild its image if you deploy images). Then retry the payment start.
|
|
150
|
+
|
|
151
|
+
## 7. `column "x" does not exist` is schema drift
|
|
152
|
+
|
|
153
|
+
**Symptom:** a 500 whose message says `column "x" does not exist` or `relation "x" does not
|
|
154
|
+
exist`.
|
|
155
|
+
|
|
156
|
+
**Cause:** the database schema is behind the generated models: the code was regenerated and
|
|
157
|
+
the running service or its database was not brought forward.
|
|
158
|
+
|
|
159
|
+
**Do:** run the newly generated code and let it start: boot re-syncs the schema. Check
|
|
160
|
+
`GET /health` `readiness` afterwards (see [compile-results.md](compile-results.md) section 9).
|
|
161
|
+
Never hand-write `ALTER`, `DROP` or `TRUNCATE` to fix drift. If a restart on fresh code does
|
|
162
|
+
not clear it, report the exact message. A 500 with `Cannot read properties of undefined` or an
|
|
163
|
+
MScript error is NOT drift: the cause is in the code path.
|
|
164
|
+
|
|
165
|
+
## 8. Each service needs its own signing key
|
|
166
|
+
|
|
167
|
+
**Symptom:** the login service starts but issues no session; other services reject tokens.
|
|
168
|
+
|
|
169
|
+
**Cause:** every service signs its tokens with its own Ed25519 key. Without
|
|
170
|
+
`SERVICE_PRIVATE_KEY_PEM` and `SERVICE_KID` (in compose: `<SVC>_SERVICE_PRIVATE_KEY_PEM`,
|
|
171
|
+
`<SVC>_SERVICE_KID`) the service starts degraded.
|
|
172
|
+
|
|
173
|
+
**Do:** generate one per service (`openssl genpkey -algorithm ed25519`), pick any UUID as the
|
|
174
|
+
key id, keep both in the service's gitignored secrets file or the deployer's secret store.
|
|
175
|
+
Every other service reads the public key from the auth service at `AUTH_SERVICE_URL` +
|
|
176
|
+
`/publickey`.
|
|
177
|
+
|
|
178
|
+
## 9. Empty peer addresses in test, stage and prod
|
|
179
|
+
|
|
180
|
+
**Symptom:** a service starts and `/health` is fine, but calls to another service, token
|
|
181
|
+
checks or links fail; documents show `<codename>-stage.example`.
|
|
182
|
+
|
|
183
|
+
**Cause:** in the `test`, `stage` and `prod` slot files, `SERVICE_URL`, `AUTH_SERVICE_URL`,
|
|
184
|
+
`SERVICE_<NAME>_URL` and `SERVICE_MCPBFF_URL` are empty lines on purpose. The `dev` slot keeps
|
|
185
|
+
local addresses. Document hosts use the reserved `.example` names.
|
|
186
|
+
|
|
187
|
+
**Do:** pass the real addresses as container environment variables (they override the file).
|
|
188
|
+
`GEOIP_SERVICE_URL` stays empty (lookup off) until you provide one. Buckets with a virus scan
|
|
189
|
+
get `CLAMAV_ENABLED=false` unless the blueprint gave its own host or url: turn it on only
|
|
190
|
+
with a scanner you run.
|
|
191
|
+
|
|
192
|
+
## 10. The service never exits at boot
|
|
193
|
+
|
|
194
|
+
**Symptom:** the process is up, the port answers, every request returns a generic error.
|
|
195
|
+
|
|
196
|
+
**Cause:** a missing dependency or credential does not stop a generated service. A "critical"
|
|
197
|
+
problem makes every request fail with a generic error. Silence at boot is not health.
|
|
198
|
+
|
|
199
|
+
**Do:** read the service log first, then `GET /health` (liveness, `readiness`, the dependency
|
|
200
|
+
checks for the database, Redis and Elasticsearch where the service uses them, and
|
|
201
|
+
`providerCredentials`). Fix the named cause, restart.
|
|
202
|
+
|
|
203
|
+
## 11. Scheduled work (nodejs unless noted)
|
|
204
|
+
|
|
205
|
+
- A cron controller or service cron job runs on **one replica per tick** by default: each tick
|
|
206
|
+
is claimed in the `sys_cronJobRun` table. With `"singleReplica": false`, and for every
|
|
207
|
+
non-nodejs language, the job runs on EVERY replica. Three replicas then run three times
|
|
208
|
+
per tick. One local container hides this.
|
|
209
|
+
- An edge controller's `edgeCronSettings` schedules nothing (warning `EDGE_CRON_NOT_SCHEDULED`).
|
|
210
|
+
Use a cron job.
|
|
211
|
+
- A `onceEver` job that has succeeded never runs again, even after a redeploy: its manual
|
|
212
|
+
run route answers 409, and `{ "force": true }` works only for a superAdmin session.
|
|
213
|
+
Renaming the job starts a new history and runs it again.
|
|
214
|
+
- A run-once data move must be safe to repeat: a failed or timed out run leaves part of the
|
|
215
|
+
data moved and the next tick retries, nothing is rolled back. Back up first and check
|
|
216
|
+
`GET /cron-jobs/<name>/runs`.
|
|
217
|
+
- `timeoutSeconds` does not kill the function: the run is recorded `timed_out` and
|
|
218
|
+
`ctx.signal` fires. A function that ignores the signal keeps running; check
|
|
219
|
+
`ctx.signal.aborted` between batches.
|
|
220
|
+
- Edge REST paths are served below `/edge` (or `EDGE_MOUNT_PATH` when the deployment sets it):
|
|
221
|
+
do not repeat `/edge` in the declared path.
|
|
222
|
+
|
|
223
|
+
## 12. Build-side facts that look like runtime faults
|
|
224
|
+
|
|
225
|
+
- Files you add to a generated repo survive every rebuild; edits to generated files do not
|
|
226
|
+
(the build counts them in `manifest.editedFilesOverwritten`). A "fix" in generated code
|
|
227
|
+
that vanishes after the next build is this, not a regression.
|
|
228
|
+
- A rebuilt service needs a restart of the running copy; a blueprint edit is not live until
|
|
229
|
+
it was compiled, pulled into the repo, and the service restarted on it.
|
|
230
|
+
- Compiling `auth` first matters when other services read its user, tenant and role shapes;
|
|
231
|
+
after a change to those, compile the dependants again.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Genesis additions to the mind-set procedures
|
|
2
|
+
|
|
3
|
+
One file per mind-set procedure that has Genesis-specific steps. Read the mind-set
|
|
4
|
+
procedure (`~/.mind-set/current/procedures/<name>.md`) and, next to it, its file here.
|
|
5
|
+
|
|
6
|
+
| Additions | mind-set procedure | Places |
|
|
7
|
+
|---|---|---|
|
|
8
|
+
| [agent-hub-blueprint.md](agent-hub-blueprint.md) | `procedures/agent-hub-blueprint.md` | 1 |
|
|
9
|
+
| [auth-blueprint.md](auth-blueprint.md) | `procedures/auth-blueprint.md` | 1 |
|
|
10
|
+
| [bff-blueprint.md](bff-blueprint.md) | `procedures/bff-blueprint.md` | 1 |
|
|
11
|
+
| [blueprint-authoring.md](blueprint-authoring.md) | `procedures/blueprint-authoring.md` | 1 |
|
|
12
|
+
| [howto-mail-to-tasks.md](howto-mail-to-tasks.md) | `procedures/howto-mail-to-tasks.md` | 1 |
|
|
13
|
+
| [howto-payment-flow.md](howto-payment-flow.md) | `procedures/howto-payment-flow.md` | 2 |
|
|
14
|
+
| [howto-subscription.md](howto-subscription.md) | `procedures/howto-subscription.md` | 1 |
|
|
15
|
+
| [notifications-blueprint.md](notifications-blueprint.md) | `procedures/notifications-blueprint.md` | 1 |
|
|
16
|
+
| [patterns-catalog.md](patterns-catalog.md) | `procedures/patterns-catalog.md` | 1 |
|
|
17
|
+
| [project-lifecycle.md](project-lifecycle.md) | `procedures/project-lifecycle.md` | 2 |
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Genesis additions: AgentHub module authoring
|
|
2
|
+
|
|
3
|
+
These notes add to the mind-set procedure `procedures/agent-hub-blueprint.md` (installed at
|
|
4
|
+
`~/.mind-set/current/procedures/agent-hub-blueprint.md`). Follow that procedure; at each place below,
|
|
5
|
+
do what this file says. They hold what is true of the Genesis compiler and the code it
|
|
6
|
+
generates, and the Genesis Compiler API steps.
|
|
7
|
+
|
|
8
|
+
## 1. In "6. Validate, build, gate"
|
|
9
|
+
|
|
10
|
+
Instead of the mind-set step that starts "2. Building the system service **`agentHub`** and checking its health ...":
|
|
11
|
+
|
|
12
|
+
2. Compile the system service **`agentHub`** with the Genesis Compiler API
|
|
13
|
+
(the genesis-compiler-api skill) and check its health where you run it.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Genesis additions: Auth module authoring
|
|
2
|
+
|
|
3
|
+
These notes add to the mind-set procedure `procedures/auth-blueprint.md` (installed at
|
|
4
|
+
`~/.mind-set/current/procedures/auth-blueprint.md`). Follow that procedure; at each place below,
|
|
5
|
+
do what this file says. They hold what is true of the Genesis compiler and the code it
|
|
6
|
+
generates, and the Genesis Compiler API steps.
|
|
7
|
+
|
|
8
|
+
## 1. In "5. Validate, build, gate"
|
|
9
|
+
|
|
10
|
+
Instead of the mind-set step that starts "2. Phase 3 must not start before the `authentication` module validates ...":
|
|
11
|
+
|
|
12
|
+
2. Compile the system service **`auth`** with the Genesis Compiler API (the
|
|
13
|
+
genesis-compiler-api skill) and check its health where you run it — Phase 3
|
|
14
|
+
must not start before the `auth` service is compiled and healthy.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Genesis additions: BFF module authoring
|
|
2
|
+
|
|
3
|
+
These notes add to the mind-set procedure `procedures/bff-blueprint.md` (installed at
|
|
4
|
+
`~/.mind-set/current/procedures/bff-blueprint.md`). Follow that procedure; at each place below,
|
|
5
|
+
do what this file says. They hold what is true of the Genesis compiler and the code it
|
|
6
|
+
generates, and the Genesis Compiler API steps.
|
|
7
|
+
|
|
8
|
+
## 1. In "5. Validate, build, gate"
|
|
9
|
+
|
|
10
|
+
Instead of the mind-set step that starts "2. The notifications module authoring starts only after":
|
|
11
|
+
|
|
12
|
+
2. Compile the system service **`bff`** with the Genesis Compiler API (the
|
|
13
|
+
genesis-compiler-api skill) and check its health; the notifications module
|
|
14
|
+
authoring starts only after
|
|
15
|
+
the DataViews exist (its `dataViewName` references are checked against
|
|
16
|
+
them).
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Genesis additions: Blueprint authoring
|
|
2
|
+
|
|
3
|
+
These notes add to the mind-set procedure `procedures/blueprint-authoring.md` (installed at
|
|
4
|
+
`~/.mind-set/current/procedures/blueprint-authoring.md`). Follow that procedure; at each place below,
|
|
5
|
+
do what this file says. They hold what is true of the Genesis compiler and the code it
|
|
6
|
+
generates, and the Genesis Compiler API steps.
|
|
7
|
+
|
|
8
|
+
## 1. In "9. The authoring loop and the completeness gate"
|
|
9
|
+
|
|
10
|
+
Instead of the mind-set step that starts "Keep portable `js` by default and use optional native sources ...":
|
|
11
|
+
|
|
12
|
+
Keep portable `js` by default, use optional native sources deliberately,
|
|
13
|
+
and read a failed slot's provenance in the compile result's build log
|
|
14
|
+
(the .NET translator gates are a Genesis compiler step). Supported direct awaited
|
|
15
|
+
Internal API forms from #6546 work on the current generator; do not
|
|
16
|
+
prescribe blanket C# rewrites or warning suppression.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Genesis additions: How-to: incoming mail opens tasks and meetings, answered from the owner's mailbox
|
|
2
|
+
|
|
3
|
+
These notes add to the mind-set procedure `procedures/howto-mail-to-tasks.md` (installed at
|
|
4
|
+
`~/.mind-set/current/procedures/howto-mail-to-tasks.md`). Follow that procedure; at each place below,
|
|
5
|
+
do what this file says. They hold what is true of the Genesis compiler and the code it
|
|
6
|
+
generates, and the Genesis Compiler API steps.
|
|
7
|
+
|
|
8
|
+
## 1. In "4. Who is admitted (do not fight it, design with it)"
|
|
9
|
+
|
|
10
|
+
Instead of the mind-set step that starts "## 5. Validate the blueprint 1. `mind-set validate blueprint.json` is ...":
|
|
11
|
+
|
|
12
|
+
#### 5. Verify the running service
|
|
13
|
+
|
|
14
|
+
1. Compile; the Genesis Compiler API's validation is green (the template
|
|
15
|
+
has no address and its own listen topic; every mail action on it
|
|
16
|
+
carries `mailbox`).
|
|
17
|
+
2. As a user, connect a mailbox: `GET /my-mailboxes` lists `workMail`
|
|
18
|
+
with `connect: oauth`; the consent lands back with `?mailbox=<address>`.
|
|
19
|
+
3. `GET /health/details` (operator) on the mcpbff shows the
|
|
20
|
+
`connectedMailboxes` block with `listening: 1`.
|
|
21
|
+
4. Send a mail to that address. Within the poll interval the Kafka api
|
|
22
|
+
runs: a `task` / `meeting` row stamped with the owner, and, when
|
|
23
|
+
`acknowledge` fired, a reply in the sender's inbox FROM the owner's
|
|
24
|
+
address, threaded.
|
|
25
|
+
5. Negative: call `POST /mail/workMail/read` with another user's session
|
|
26
|
+
and the first user's address: `404 MAILBOX_NOT_FOUND`.
|