@mindbricks/genesis-set 0.0.0-stage → 0.1.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 +34 -0
- package/LICENSE +202 -0
- package/README.md +147 -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 +220 -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 +43 -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,246 @@
|
|
|
1
|
+
# Reading a compile result
|
|
2
|
+
|
|
3
|
+
What a finished (or failed) Genesis build tells you, field by field, and what it does not
|
|
4
|
+
tell you. The compile result an agent reads is the job from `genesis_getServiceBuild`
|
|
5
|
+
(`GET /jobs/:jobId`), one per service. For the calls that start and list builds see
|
|
6
|
+
[compiler-api.md](compiler-api.md); to run what was generated see [run-locally.md](run-locally.md).
|
|
7
|
+
|
|
8
|
+
## 1. Which result to read
|
|
9
|
+
|
|
10
|
+
- `genesis_buildService` answers the build and a `jobId` per service. `genesis_getBuilds`
|
|
11
|
+
lists builds with the `jobId`, status and line counts of each service.
|
|
12
|
+
- The build row (`GET /builds/:id`) is the summary: status, per-service status, line counts,
|
|
13
|
+
`totals`, `deployArtifacts`. The log tail and the file list are NOT on it: they live on the job.
|
|
14
|
+
- Read the JOB for anything you need to act on. Poll it with a growing interval (5 s, 10 s,
|
|
15
|
+
then 30 s) until the status is final: `succeeded`, `failed` or `cancelled`.
|
|
16
|
+
- A job of another account answers `404 GENESIS_JOB_NOT_FOUND`, the same as a wrong id.
|
|
17
|
+
|
|
18
|
+
## 2. Statuses
|
|
19
|
+
|
|
20
|
+
Job (service) status: `pending`, `running`, `succeeded`, `failed`, `cancelled`.
|
|
21
|
+
|
|
22
|
+
Build status: `queued`, `running`, then one of:
|
|
23
|
+
|
|
24
|
+
| Build status | Meaning | What to do |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `succeeded` | every service of the build succeeded | read each job before saying so (section 3) |
|
|
27
|
+
| `partial` | some services succeeded, some failed (a failed service never stops the others) | use the complete services, repair the failed ones one by one |
|
|
28
|
+
| `failed` | no service could be generated; `error.code` is `GENESIS_BUILD_FAILED`, or `GENESIS_INTERNAL_ERROR` / `GENESIS_BUILD_INTERRUPTED` (section 5) | read the job errors, then the code table |
|
|
29
|
+
| `cancelled` | a cancel arrived; services not started are `cancelled`, a finished service keeps its result | start a new build when you still want the rest |
|
|
30
|
+
|
|
31
|
+
Services of one build are compiled one after the other, in the order you gave. A queued or
|
|
32
|
+
pending job is not a result.
|
|
33
|
+
|
|
34
|
+
## 3. The job fields
|
|
35
|
+
|
|
36
|
+
| Field | How to read it |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `id`, `buildId`, `serviceName`, `codename`, `language`, `dryRun` | which build and service this is. `language` is `nodejs` for `mcpbff` whatever the build language is. `dryRun: true` means the code was generated and measured and nothing was pushed (the only mode for now) |
|
|
39
|
+
| `status` | section 2 |
|
|
40
|
+
| `createdAt`, `startedAt`, `finishedAt` | `startedAt` is null while the job waits; a long gap between `createdAt` and `startedAt` is queueing, not slowness |
|
|
41
|
+
| `addedLines`, `deletedLines` | the git diff of the generated tree against the previous state of the service repo (an empty base on a first build) |
|
|
42
|
+
| `files`, `binaryFiles` | count of changed text files and of changed binary files |
|
|
43
|
+
| `fileList`, `fileListTruncated` | the changed paths, at most 2000, the manifest file left out. `fileListTruncated: true` means the list is cut, the counts are not |
|
|
44
|
+
| `tokens` | the billed amount of this job: it equals `addedLines`. A dry run is not charged while charging is not open |
|
|
45
|
+
| `manifest` | what the build did to the files already in the repo (section 4) |
|
|
46
|
+
| `commitSha`, `pullRequestUrl` | null while builds are dry runs; they name the pushed commit / pull request once pushing opens. Null is not a failure |
|
|
47
|
+
| `deployArtifacts` | null when no `deployTargets` were asked; otherwise one entry per target with `status` (`emitted` or `skipped`), `path`, `files`, `reason` |
|
|
48
|
+
| `error` | null, or `{ code, message }` (section 5). `message` is cut at 2000 characters, workspace paths are masked |
|
|
49
|
+
| `logTail` | the last 50 lines of the service's compile log, each cut at 500 characters; the queue's own scheduling lines are dropped |
|
|
50
|
+
|
|
51
|
+
Rules:
|
|
52
|
+
|
|
53
|
+
- A `succeeded` job with `addedLines: 0` and `deletedLines: 0` means the generated tree equals
|
|
54
|
+
what the repo already holds. That is correct after a rebuild without blueprint change.
|
|
55
|
+
- A big `deletedLines` on a rebuild is either a blueprint change that removed code or
|
|
56
|
+
your edits to generated files being overwritten (section 4). Check `manifest` before
|
|
57
|
+
blaming the compiler.
|
|
58
|
+
- `deployArtifacts[].status: "skipped"` is normal for a part that has no container image
|
|
59
|
+
(the document service, the frontend prompt docs). Its `reason` says so.
|
|
60
|
+
- `fileList` is the way to see what a build touched. Open a few generated files; do not
|
|
61
|
+
take the counts as proof the right code exists.
|
|
62
|
+
|
|
63
|
+
## 4. The `manifest` summary
|
|
64
|
+
|
|
65
|
+
Every build writes `.genesis/manifest.json` (schema `genesis-manifest/1`) into the service
|
|
66
|
+
repo: the generated paths, each with its git blob id. The next build sorts the files already
|
|
67
|
+
in the repo with it. Never edit that file. The job's `manifest` object counts the result:
|
|
68
|
+
|
|
69
|
+
| Field | Meaning |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `firstBuild` | no previous manifest was found: every file already in the repo is yours and was kept |
|
|
72
|
+
| `generatedFiles` | files the build wrote and listed in the manifest |
|
|
73
|
+
| `customerFiles` | files that are not in the previous manifest, kept untouched (they cost no lines) |
|
|
74
|
+
| `removedFiles` | files the previous manifest listed that the blueprint no longer generates: deleted |
|
|
75
|
+
| `editedFilesOverwritten` | generated files you had edited: your edit is gone and the re-added lines are counted |
|
|
76
|
+
| `customerFilesOverwritten` | your files at a path the build now generates (or a folder path it writes as a file): replaced by the generated file |
|
|
77
|
+
|
|
78
|
+
What to do with it:
|
|
79
|
+
|
|
80
|
+
- `editedFilesOverwritten > 0` or `customerFilesOverwritten > 0` is a warning, not a
|
|
81
|
+
failure. Diff the repo against its last commit, restore what mattered through the
|
|
82
|
+
blueprint (custom code belongs in the places `custom-code.md` names) and rebuild.
|
|
83
|
+
- `removedFiles > 0` after you renamed or removed a design object is expected. After no
|
|
84
|
+
blueprint change it is not: look at which files with `fileList`.
|
|
85
|
+
- Everything under `service-files/` is always yours: it is kept even over a generated
|
|
86
|
+
path and never listed in the manifest.
|
|
87
|
+
- A broken manifest in the repo (not JSON, wrong schema, a bad path) is not treated as a
|
|
88
|
+
first build: the job fails with `GENESIS_MANIFEST_INVALID`. Restore `.genesis/manifest.json`
|
|
89
|
+
from git history, or remove the file only when you accept that the next build treats
|
|
90
|
+
every file in the repo as yours.
|
|
91
|
+
|
|
92
|
+
## 5. Failure codes
|
|
93
|
+
|
|
94
|
+
On a job, `error.code` is one of these. On the build row the same field carries the
|
|
95
|
+
build-level ones.
|
|
96
|
+
|
|
97
|
+
| Code | Where | Meaning | What to do |
|
|
98
|
+
|---|---|---|---|
|
|
99
|
+
| `GENESIS_SERVICE_BUILD_FAILED` | job | the compiler could not generate this service. `error.message` is the compiler's message, `logTail` the end of its log | section 6: classify, then repair the blueprint or report it |
|
|
100
|
+
| `GENESIS_DEPLOY_ARTIFACTS_FAILED` | job | the code was generated but writing `deploy/<target>/` failed | rebuild; if it repeats, report it with the job id. The service is not complete: do not use its tree |
|
|
101
|
+
| `GENESIS_MANIFEST_INVALID` | job | `.genesis/manifest.json` of the repo is invalid (section 4) | repair the manifest file, rebuild |
|
|
102
|
+
| `GENESIS_DIFF_FAILED` | job | the code was generated but could not be measured against the repo | rebuild once; if it repeats, report it with the job id and the log tail |
|
|
103
|
+
| `GENESIS_BUILD_FAILED` | build | no service of the build could be generated | read each job's own error |
|
|
104
|
+
| `GENESIS_BUILD_INTERRUPTED` | build | the worker stopped (no sign of life for 10 minutes); unfinished services are `cancelled` | start a new build with a NEW idempotency key. Services that finished keep their result |
|
|
105
|
+
| `GENESIS_INTERNAL_ERROR` | build | the compiler could not finish the build | one retry with a new key; if it repeats, report it, do not loop |
|
|
106
|
+
|
|
107
|
+
Also on the paths you call: `GENESIS_JOB_NOT_FOUND` and `GENESIS_BUILD_NOT_FOUND` (404: wrong
|
|
108
|
+
id or another account's), `GENESIS_BUILD_FINISHED` (409: cancel of a finished build),
|
|
109
|
+
`GENESIS_BAD_FILTER` / `GENESIS_BAD_CURSOR` (400: a list call with a bad filter or cursor).
|
|
110
|
+
|
|
111
|
+
## 6. Where compiler-level diagnostics show up
|
|
112
|
+
|
|
113
|
+
The job has no structured list of compiler errors. The text of a failure is in two places:
|
|
114
|
+
|
|
115
|
+
1. `error.message` of a `GENESIS_SERVICE_BUILD_FAILED` job.
|
|
116
|
+
2. `logTail`, the last 50 lines. The cause is usually in the last lines; a long message is cut
|
|
117
|
+
at 500 characters per line, so a very long compiler message may need the next step.
|
|
118
|
+
|
|
119
|
+
For more than the tail, compile the generated service yourself (section 8): the target
|
|
120
|
+
language's own compiler gives the full, authoritative list.
|
|
121
|
+
|
|
122
|
+
Shapes you will meet in the log or in a local compile of a nodejs service, and what they mean:
|
|
123
|
+
|
|
124
|
+
- **A library or edge function body that uses a name nothing declares** fails the build before
|
|
125
|
+
anything is written. The message names the function, the identifier and the line. Fix the
|
|
126
|
+
body in the blueprint.
|
|
127
|
+
- **Any other compile error in code you authored** (an MScript, a library body, an edge body)
|
|
128
|
+
also fails the build: a service whose emitted code does not compile cannot boot. The message
|
|
129
|
+
carries the TypeScript code and the compiler text. Two common ones:
|
|
130
|
+
- `TS2801`: the result of a `LIB.*` call (a promise) is tested in a condition without being
|
|
131
|
+
awaited. Await it first, test the result after.
|
|
132
|
+
- `TS18047`: `const p = this.instance; p.x` with no null check. Guard the value before the
|
|
133
|
+
member access.
|
|
134
|
+
- Validation warns about these shapes before a build: `MSCRIPT_LIB_CALL_IN_SYNC_CALLBACK`,
|
|
135
|
+
`MSCRIPT_LIB_RESULT_VAR_NOT_AWAITED`, `MSCRIPT_NULLABLE_MEMBER_UNGUARDED`. A warning you
|
|
136
|
+
left standing is the first suspect for a failed build. Warning-tier compiler diagnostics
|
|
137
|
+
never block a build.
|
|
138
|
+
- The first compile error is the cause; later ones are often its echo. Fix the first,
|
|
139
|
+
rebuild, then read the next.
|
|
140
|
+
|
|
141
|
+
### Translator gates (non-nodejs languages)
|
|
142
|
+
|
|
143
|
+
Validation success does not guarantee that every authored expression translates to another
|
|
144
|
+
language. For dotnet, fiscal hooks, feed expressions and socket predicate / mapper / lifecycle
|
|
145
|
+
bodies refuse an unsupported translation, or the warnings the translator added. API arrow
|
|
146
|
+
bodies refuse on the `FAITHFUL_WARNINGS` set; agent post-process also refuses on the
|
|
147
|
+
`POST_PROCESS_LOUD_WARNINGS` set. When a job fails this way, the log names the authored
|
|
148
|
+
slot:
|
|
149
|
+
|
|
150
|
+
- Keep the expression portable (the plain JS form the other languages translate) and
|
|
151
|
+
simplify it, or move it to a supported shape. Do not bypass the gate, and do not rewrite
|
|
152
|
+
the blueprint in the target language.
|
|
153
|
+
- If the same form is supported on nodejs, say so in your report: it is a known per-language
|
|
154
|
+
gap, not your blueprint's fault.
|
|
155
|
+
|
|
156
|
+
## 7. Blueprint fault or compiler fault
|
|
157
|
+
|
|
158
|
+
Classify before acting; the remedy differs.
|
|
159
|
+
|
|
160
|
+
| Evidence | Class | Remedy |
|
|
161
|
+
|---|---|---|
|
|
162
|
+
| the message names an authored slot (an MScript path, a library or edge function, a property) | blueprint | fix the blueprint, `genesis_validateApplication`, rebuild |
|
|
163
|
+
| the message is a translator gate (section 6) | blueprint (shape) or known language gap | simplify, or report the unsupported form |
|
|
164
|
+
| a reference, role or object the message names does not exist in the blueprint | blueprint | add or correct it |
|
|
165
|
+
| the failing code is generated framework code you did not author, with no authored slot in the message | compiler | keep the job id, the log tail and the blueprint hash; report it |
|
|
166
|
+
| `GENESIS_INTERNAL_ERROR`, `GENESIS_BUILD_INTERRUPTED` | service side | one retry with a new key, then report |
|
|
167
|
+
|
|
168
|
+
Rules:
|
|
169
|
+
|
|
170
|
+
- Never hand-edit generated code as the fix. The next build overwrites it (and counts the
|
|
171
|
+
overwrite). The blueprint is the source.
|
|
172
|
+
- A missing structured cause proves nothing. "No authored slot in the message" does not by
|
|
173
|
+
itself make it the compiler's fault: read the log before deciding.
|
|
174
|
+
- **A workaround you ship is a bug report in disguise.** If your repair is one of these,
|
|
175
|
+
the real defect is probably in the compiler: a data-clause override that forces a value the
|
|
176
|
+
generated clause set wrong; moving a write to another milestone because the main operation
|
|
177
|
+
overwrote it; raw database writes because the managed write does the wrong thing; manual
|
|
178
|
+
cache invalidation because a write did not invalidate; a runtime guard (`if (!x) return`)
|
|
179
|
+
against an undefined the data shape says cannot happen; skipping a test that shows real
|
|
180
|
+
behaviour. Report it before you call the work done.
|
|
181
|
+
- **Cap: three build attempts per service for one failure.** After the third, stop and bring
|
|
182
|
+
the evidence to the user. Each build adds lines to the bill; thrashing costs money.
|
|
183
|
+
- Build one wave: validate the whole blueprint, compile the services, read every job, then
|
|
184
|
+
repair. Do not rebuild a service after each small authoring step.
|
|
185
|
+
|
|
186
|
+
## 8. Compiling the generated service yourself
|
|
187
|
+
|
|
188
|
+
The job proves that code was generated and measured. A repo that builds is a separate
|
|
189
|
+
fact, and the language's own toolchain is the only judge:
|
|
190
|
+
|
|
191
|
+
| Language | Check |
|
|
192
|
+
|---|---|
|
|
193
|
+
| nodejs | `npm install` then the TypeScript compile the repo's scripts give (run `npx tsc --noEmit` when the scripts name none) |
|
|
194
|
+
| dotnet | `dotnet build`, and `dotnet publish` for what the image runs |
|
|
195
|
+
| other languages | the repo's own build command (see its `README.md` / Dockerfile) |
|
|
196
|
+
|
|
197
|
+
Rules:
|
|
198
|
+
|
|
199
|
+
- A job that is `succeeded` with a log tail free of errors is **not** a compiler pass.
|
|
200
|
+
For a language other than nodejs, a generation can finish without the emitted code ever
|
|
201
|
+
being compiled by the target toolchain. Say "generated, compile unverified" until you
|
|
202
|
+
compiled it.
|
|
203
|
+
- A local `dotnet build` pass does not prove `dotnet publish` inside the image: a different
|
|
204
|
+
SDK or image can still fail, for example the native protoc step failing with `MSB6003`
|
|
205
|
+
although generation succeeded. Build the image the deploy will use (`Dockerfile.prod` or
|
|
206
|
+
the compose file) before calling a service deployable.
|
|
207
|
+
- Any frontend code you build from the frontend prompt docs needs its own toolchain; the
|
|
208
|
+
backend result says nothing about it.
|
|
209
|
+
- Record target, toolchain version, commit and the command beside the verdict.
|
|
210
|
+
"Compiles" without these is a guess.
|
|
211
|
+
- Pin the check to a commit. The repo's HEAD, the job's `commitSha` (once pushing exists)
|
|
212
|
+
and what you run must be the same code. A local edit of a generated file makes your result
|
|
213
|
+
about the edit, not the build.
|
|
214
|
+
|
|
215
|
+
## 9. Alive is not ready, a link is not health
|
|
216
|
+
|
|
217
|
+
Generated and running are different facts, and a green build says nothing about running.
|
|
218
|
+
After you start the service yourself (see [run-locally.md](run-locally.md)):
|
|
219
|
+
|
|
220
|
+
- `GET /health` answering `{"status":"ok"}` is liveness: the process is up.
|
|
221
|
+
- The same answer carries `readiness: { ready, schema: { outcome, phase?, reason? } }`.
|
|
222
|
+
`ready: false` means the initial schema materialisation failed (for example
|
|
223
|
+
`phase: "missing_tables"`, `reason: "permission_denied"`): the service answers 200 but
|
|
224
|
+
every request that touches a missing table fails. Restarting does not fix it: read the
|
|
225
|
+
service's log, fix the design or the database permission, rebuild and restart. A pending
|
|
226
|
+
migration, an absent optional Elasticsearch or Kafka, ledger and index policies never make
|
|
227
|
+
`ready` false.
|
|
228
|
+
- The generated service never exits at boot on a missing dependency or credential: it starts
|
|
229
|
+
and answers errors. A running process and an open port prove nothing.
|
|
230
|
+
- Do not probe business endpoints to "verify" a build. They need a session, a body and
|
|
231
|
+
fixtures you do not have yet, and every probe answers 401, 403, 400 or 404 from a layer you
|
|
232
|
+
do not control. Test endpoints with a plan and fixtures ([testing.md](testing.md)).
|
|
233
|
+
- Copy routes from the generated service's API documents or route list; never build a URL
|
|
234
|
+
from a blueprint `routePath` or from REST habit. For example the login route is
|
|
235
|
+
`POST /login`, not `POST /auth/login`.
|
|
236
|
+
- A pull request URL, a commit sha, a `fileList` or a `succeeded` status are links and
|
|
237
|
+
counts. None of them is a passing compile, a booted service or working business logic.
|
|
238
|
+
Report each fact with its own evidence: validated, generated, measured, compiled,
|
|
239
|
+
booted, healthy, tested.
|
|
240
|
+
|
|
241
|
+
## 10. Before you report a result
|
|
242
|
+
|
|
243
|
+
Write, per service: the job id, the status, `addedLines` / `deletedLines`, the `manifest`
|
|
244
|
+
overwrite counts, the error code and the first failing line of the message when there is one,
|
|
245
|
+
and which of the facts in section 9 you actually observed. Never report a build you did not
|
|
246
|
+
see finish, and never report "no errors" when you only saw no error field.
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
# The Genesis Compiler API
|
|
2
|
+
|
|
3
|
+
> **Builds are dry runs for now** (section 6): the code is generated and measured, nothing is
|
|
4
|
+
> pushed. Do not tell a user a validation or a build ran when you did not see its answer, and
|
|
5
|
+
> do not invent one: when a call answers `GENESIS_UNREACHABLE`, say the API could not be
|
|
6
|
+
> reached and stop.
|
|
7
|
+
|
|
8
|
+
The Genesis Compiler API compiles an OpenAPPL blueprint into the source code of its services.
|
|
9
|
+
You write and validate the blueprint locally with mind-set; Genesis turns it into code; you run,
|
|
10
|
+
test and deploy that code yourself. No project is created or managed anywhere: everything the
|
|
11
|
+
compiler needs comes from the blueprint and the request.
|
|
12
|
+
|
|
13
|
+
You call it through five MCP tools that genesis-set installs (section 3). For CI or a script
|
|
14
|
+
without an agent, the same endpoints are plain REST (section 9).
|
|
15
|
+
|
|
16
|
+
## 1. What Genesis generates
|
|
17
|
+
|
|
18
|
+
- Every service of the blueprint: `auth`, `bff`, `notification`, the agent hub when it is
|
|
19
|
+
declared, and each business service, in the language of the request (`nodejs` unless the API
|
|
20
|
+
enables more).
|
|
21
|
+
- The derived services: `mcpbff` (always nodejs), `document` (the project's documentation
|
|
22
|
+
service) and `frontend` (the per-service frontend prompt documents). They are part of the
|
|
23
|
+
service list `genesis_validateApplication` answers.
|
|
24
|
+
- Not generated: the admin panel (`panel`) and a platform SDK repository (`sdk`). Asking for them
|
|
25
|
+
answers `422 GENESIS_SERVICE_NOT_AVAILABLE`.
|
|
26
|
+
- Optionally, per build, deploy artifacts for your own deploy (section 7 and [deploy.md](deploy.md)).
|
|
27
|
+
|
|
28
|
+
Genesis never deploys anything and never runs your services.
|
|
29
|
+
|
|
30
|
+
## 2. Identity comes from the blueprint
|
|
31
|
+
|
|
32
|
+
- The **codename** is `projectSettings.basicSettings.name`: one lowercase word. It prefixes the
|
|
33
|
+
repository names (`<codename>-<service>-service`), index names and event topics, and it is the
|
|
34
|
+
`codename` filter of `genesis_getBuilds`. Choose it once: renaming it later renames everything
|
|
35
|
+
generated from it.
|
|
36
|
+
- The display name is `projectSettings.basicSettings.fullname`.
|
|
37
|
+
- The generated services may use a **project id**. When you create a new blueprint, write a
|
|
38
|
+
stable id into it once (a fresh UUID) and never change it. To Genesis that id is an opaque
|
|
39
|
+
label: it selects nothing, so the same blueprint compiles the same way for any account.
|
|
40
|
+
- There is no binding file in the project folder, and genesis-set never writes one.
|
|
41
|
+
|
|
42
|
+
## 3. Setup
|
|
43
|
+
|
|
44
|
+
1. `genesis-set install` registers the MCP server `genesis` for Claude Code and Codex. Restart
|
|
45
|
+
the agent afterwards so it loads the tools.
|
|
46
|
+
2. The API key.
|
|
47
|
+
- **Getting it:** the user creates it on the Genesis portal's API keys page,
|
|
48
|
+
`https://portal.genesiscompiler.com/keys` (for the stage API `sapi.genesiscompiler.com`,
|
|
49
|
+
`https://stage.genesiscompiler.com/keys`). It is shown once. Give the user that link.
|
|
50
|
+
- **Setting it:** the environment variable `GENESIS_API_KEY`, or `genesis-set config set-key`
|
|
51
|
+
run by the user in their own terminal. That command reads the key from stdin and stores it
|
|
52
|
+
in `~/.genesis-set/config.json`, readable only by the user. `genesis-set install` offers the
|
|
53
|
+
same prompt at its end when it runs on a terminal.
|
|
54
|
+
- **Easiest with an agent:** `genesis_requestKey` with `name: "genesis-api-key"` answers the
|
|
55
|
+
local key page link; the user pastes the key there, and the genesis_* tools use it at once.
|
|
56
|
+
- **Never** ask the user to paste the key into the chat, a project file or the blueprint, and
|
|
57
|
+
never print it.
|
|
58
|
+
- A call without a key answers `GENESIS_API_KEY_MISSING`. Its message names the portal page
|
|
59
|
+
and how to set the key: pass it on as it is.
|
|
60
|
+
3. The API base is `https://api.genesiscompiler.com`. Change it only when the user names
|
|
61
|
+
another one (`GENESIS_API_BASE`, or `genesis-set config set-base <url>`).
|
|
62
|
+
4. `genesis-set doctor` says where the key comes from (never its value), the API base and
|
|
63
|
+
whether each agent has the MCP server.
|
|
64
|
+
|
|
65
|
+
## 4. The tools
|
|
66
|
+
|
|
67
|
+
| Tool | Endpoint | Use it to |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| `genesis_validateApplication` | `POST /validate` | Validate the whole blueprint; learn the codename and the services Genesis would build. |
|
|
70
|
+
| `genesis_validateService` | `POST /validate/service` | Validate one service, from the whole blueprint or from that service's JSON alone. |
|
|
71
|
+
| `genesis_buildService` | `POST /builds` (one service) | Compile one service; answers its `jobId`. |
|
|
72
|
+
| `genesis_getServiceBuild` | `GET /jobs/:jobId` | Follow one service build to its end and read its result. |
|
|
73
|
+
| `genesis_getBuilds` | `GET /builds` | List your builds, newest first. |
|
|
74
|
+
|
|
75
|
+
Every answer is JSON: the API's body with `httpStatus` added. A failure is always
|
|
76
|
+
`{ "error": { "code": "GENESIS_...", "message": "...", "details": {} } }` and the tool marks
|
|
77
|
+
it as an error. Report the code and the message; do not paraphrase a failure into a success.
|
|
78
|
+
|
|
79
|
+
### 4.1 The blueprint source
|
|
80
|
+
|
|
81
|
+
- `blueprintPath`: the blueprint JSON file on this machine. The tool reads it, checks the size
|
|
82
|
+
(10 MiB of compact JSON, the API's limit) and sends the object inline. The path itself is never
|
|
83
|
+
sent. A file over the limit answers `GENESIS_BLUEPRINT_TOO_LARGE` with
|
|
84
|
+
`details.checkedLocally: true` before anything is sent; a missing file
|
|
85
|
+
`GENESIS_BLUEPRINT_FILE_NOT_FOUND`; a file that is not one JSON object
|
|
86
|
+
`GENESIS_BLUEPRINT_FILE_INVALID`. A relative path is read from the folder the agent was
|
|
87
|
+
started in: prefer an absolute path.
|
|
88
|
+
- `fragmentPath` (`genesis_validateService` only): a JSON file holding one entry of the
|
|
89
|
+
blueprint's `services` list.
|
|
90
|
+
- `repo`: `{ "provider": "github" | "gitlab", "repo": "<owner>/<name>", "ref", "path" }`, the
|
|
91
|
+
blueprint in a git repository, for CI. It is passed through as given. **Not available yet:**
|
|
92
|
+
the API answers `422 GENESIS_BLUEPRINT_SOURCE_NOT_AVAILABLE`; use `blueprintPath`.
|
|
93
|
+
|
|
94
|
+
Give exactly one source. An unknown argument is refused (`GENESIS_BAD_ARGUMENTS`) before any
|
|
95
|
+
call: the tools send the blueprint and the parameters they name, nothing else.
|
|
96
|
+
|
|
97
|
+
### 4.2 `genesis_validateApplication`
|
|
98
|
+
|
|
99
|
+
Arguments: the source, optional `language`, optional `services` (check only that these exist and
|
|
100
|
+
can be built).
|
|
101
|
+
|
|
102
|
+
- `200 { "valid": true, "codename", "language", "blueprintHash", "services": [...] }`: `services`
|
|
103
|
+
is the build order Genesis uses.
|
|
104
|
+
- `422 { "valid": false, "error": { "code": "GENESIS_BLUEPRINT_INVALID", "details": { "errors", "warnings" } } }`:
|
|
105
|
+
every finding has `path`, `code` and `message`. Fix the blueprint, run `mind-set validate`
|
|
106
|
+
again, then call again.
|
|
107
|
+
- `429 GENESIS_RATE_LIMITED`: the validation budget (per user, per minute, shared with
|
|
108
|
+
`genesis_validateService`) is spent; wait a minute. Do not loop on validation.
|
|
109
|
+
|
|
110
|
+
Validation is free. A warning is a decision: fix it, or record why it stays (the mind-set
|
|
111
|
+
validation rules hold for the Genesis answer too).
|
|
112
|
+
|
|
113
|
+
### 4.3 `genesis_validateService`
|
|
114
|
+
|
|
115
|
+
Arguments: `serviceName` and one source (`blueprintPath`, `fragmentPath` or `repo`), optional
|
|
116
|
+
`language`. Same answer shape as 4.2 plus `scope` (`blueprint` or `fragment`) and `notChecked`.
|
|
117
|
+
|
|
118
|
+
- With the whole blueprint the service is judged exactly as its build will judge it.
|
|
119
|
+
- With a fragment the service is judged alone. A finding that only exists because the context is
|
|
120
|
+
missing (another service, a role of the authentication module, a provider or log declared in
|
|
121
|
+
`projectSettings`, the hubs, the integrations) is listed under `notChecked`
|
|
122
|
+
(`code: GENESIS_NOT_CHECKED`, `context`, `reference`, the validator's code as `reason`), never as
|
|
123
|
+
an error. `notChecked` is not a pass: validate the whole blueprint before you build.
|
|
124
|
+
- A fragment whose own name is not `serviceName` answers `422 GENESIS_FRAGMENT_MISMATCH`.
|
|
125
|
+
|
|
126
|
+
Use the fragment form while iterating on one service; use the whole blueprint before a build.
|
|
127
|
+
|
|
128
|
+
### 4.4 `genesis_buildService`
|
|
129
|
+
|
|
130
|
+
Arguments: `serviceName`, the source (`blueprintPath` or `repo`), optional `deployTargets`,
|
|
131
|
+
`language`, `dryRun` (default and only accepted value today: `true`) and `idempotencyKey`.
|
|
132
|
+
|
|
133
|
+
- `202 { "build": { "id", "status": "queued", ... }, "jobId", "idempotencyKey" }`. The build runs
|
|
134
|
+
asynchronously; follow `jobId` with `genesis_getServiceBuild`.
|
|
135
|
+
- The tool sends a fresh `Idempotency-Key` and returns it. If the answer is lost (a timeout, a
|
|
136
|
+
dropped connection), call again with the SAME `idempotencyKey` and the same arguments: you get
|
|
137
|
+
the same build (`200`), never a second one. The same key with a different request answers
|
|
138
|
+
`409 GENESIS_IDEMPOTENCY_CONFLICT`. A new build needs no key (omit it).
|
|
139
|
+
- Refusals before the build starts: `GENESIS_SERVICE_UNKNOWN` (with `details.available`),
|
|
140
|
+
`GENESIS_SERVICE_NOT_AVAILABLE` (panel, sdk), `GENESIS_BLUEPRINT_INVALID` (the same findings as
|
|
141
|
+
4.2), `GENESIS_DRY_RUN_REQUIRED`, `GENESIS_OPTION_NOT_AVAILABLE`, `GENESIS_UNKNOWN_DEPLOY_TARGET`
|
|
142
|
+
/ `GENESIS_BAD_DEPLOY_TARGETS` (with `details.allowed`), `GENESIS_LANGUAGE_NOT_ALLOWED`.
|
|
143
|
+
|
|
144
|
+
### 4.5 `genesis_getServiceBuild`
|
|
145
|
+
|
|
146
|
+
Argument: `jobId`. Answers `{ "job": { ... } }`: `status` (`pending`, `running`, `succeeded`,
|
|
147
|
+
`failed`, `cancelled`), times, `addedLines`, `deletedLines`, `files`, `fileList`, `tokens`, the
|
|
148
|
+
`manifest` summary, `deployArtifacts`, `error`, and the tail of the build log. How to read each
|
|
149
|
+
field and each failure: [compile-results.md](compile-results.md).
|
|
150
|
+
|
|
151
|
+
- Poll with a growing interval: 5 s, then 10 s, then every 30 s, and stop at a final status
|
|
152
|
+
(`succeeded`, `failed`, `cancelled`). Never report a build you did not see finish.
|
|
153
|
+
- `404 GENESIS_JOB_NOT_FOUND`: the id is wrong, or the job is another account's.
|
|
154
|
+
- A build whose worker stopped is failed with `GENESIS_BUILD_INTERRUPTED`: start a new build
|
|
155
|
+
(a new key).
|
|
156
|
+
|
|
157
|
+
### 4.6 `genesis_getBuilds`
|
|
158
|
+
|
|
159
|
+
Filters: `codename`, `status` (`queued`, `running`, `succeeded`, `partial`, `failed`,
|
|
160
|
+
`cancelled`), `serviceName`, `since` / `until` (ISO 8601), `limit` (default 20, at most 100) and
|
|
161
|
+
`cursor` (the `nextCursor` of the previous page; `null` on the last page). Each build lists, per
|
|
162
|
+
service, `serviceName`, `jobId`, `status`, `addedLines` and `deletedLines`. A bad filter answers
|
|
163
|
+
`400 GENESIS_BAD_FILTER`, a cursor this API did not give `400 GENESIS_BAD_CURSOR`. Use it to find
|
|
164
|
+
a `jobId` again after a lost session, and to show the user what was compiled.
|
|
165
|
+
|
|
166
|
+
## 5. How to compile a project
|
|
167
|
+
|
|
168
|
+
1. Author the blueprint with mind-set and validate it with `mind-set validate blueprint.json`.
|
|
169
|
+
2. `genesis_validateApplication` with the whole blueprint; repair until it is valid. While you
|
|
170
|
+
work on one service, `genesis_validateService` with its fragment is the fast loop; finish with
|
|
171
|
+
the whole blueprint.
|
|
172
|
+
3. **Author everything, validate everything, then compile once.** Once charging opens, each
|
|
173
|
+
build's added lines will count toward usage (section 6). Compiling a service again after a
|
|
174
|
+
dependency changes can add another charge. Compile `auth` first when the other services or
|
|
175
|
+
your tests need its live shape.
|
|
176
|
+
4. Compile one service per `genesis_buildService` call, in the order `genesis_validateApplication`
|
|
177
|
+
answered. Recompile `mcpbff`, `document` and `frontend` after the services they describe
|
|
178
|
+
change.
|
|
179
|
+
5. Follow each job to its final status. Report, per service: status, added / deleted lines,
|
|
180
|
+
files, deploy artifacts, and every failure with its code. A failed service does not stop the
|
|
181
|
+
others; fix the cause (a blueprint fault: fix, validate, compile again; a compiler fault:
|
|
182
|
+
report it with the job id and the exact error) and compile only that service again.
|
|
183
|
+
6. Check whether you have the generated service repositories. A successful dry run provides job
|
|
184
|
+
results and a file inventory. It leaves no checkout, archive or deploy files you can use locally.
|
|
185
|
+
If the user already has the matching generated repositories, follow [run-locally.md](run-locally.md)
|
|
186
|
+
and [testing.md](testing.md). Otherwise report the dry-run results and wait for an artifact-producing
|
|
187
|
+
build before starting the run and test steps. Author custom code in the blueprint, as described in
|
|
188
|
+
[custom-code.md](custom-code.md).
|
|
189
|
+
|
|
190
|
+
## 6. Dry run, credit and the overdraft rule
|
|
191
|
+
|
|
192
|
+
- **Every build is a dry run today:** the code is generated and measured, nothing is written
|
|
193
|
+
anywhere and nothing is charged. The job's `addedLines`, `deletedLines`, `files` and `fileList`
|
|
194
|
+
show what the build would write.
|
|
195
|
+
- **Credit is counted per added line of each build's own diff.** `tokens` on a job is its added
|
|
196
|
+
lines. Every build is counted again, and the counts add up: compiling the same unchanged
|
|
197
|
+
service twice costs nothing the second time (an empty diff), but every real change costs its
|
|
198
|
+
added lines, including lines that overwrite your own edits of generated files.
|
|
199
|
+
- **The overdraft rule:** before each service starts, Genesis asks whether the account may build.
|
|
200
|
+
A running build may go over the credit by at most one service; the next service is refused with
|
|
201
|
+
a Genesis `402` and the user is told to top up. Plan builds so a top-up does not land in the
|
|
202
|
+
middle of a dependent set.
|
|
203
|
+
- Charging and the usage endpoint are not open yet; until then nothing is charged.
|
|
204
|
+
|
|
205
|
+
## 7. Where the code goes
|
|
206
|
+
|
|
207
|
+
- **One repository per service**, named `<codename>-<service>-service`, in the user's own GitHub
|
|
208
|
+
or GitLab account or group (connected in the Genesis portal).
|
|
209
|
+
- **Push mode:** a direct push to the base branch by default; the user can switch to pull-request
|
|
210
|
+
mode in the portal. Not available yet: today every build is a dry run (`push` and `target`
|
|
211
|
+
answer `GENESIS_OPTION_NOT_AVAILABLE`).
|
|
212
|
+
- **Your files are kept.** Each build writes `.genesis/manifest.json` (the files it generated).
|
|
213
|
+
On the next build a file the previous manifest does not list is yours and survives; a generated
|
|
214
|
+
file you edited is overwritten (and its lines are counted); a file no longer generated is
|
|
215
|
+
removed. Everything under `service-files/` is always yours. The job's `manifest` summary counts
|
|
216
|
+
each case.
|
|
217
|
+
- **Service files** (bytes the blueprint's service library refers to) live in your service
|
|
218
|
+
repository, not in Genesis. Until builds compile onto your repositories, a build cannot read
|
|
219
|
+
them; the build log says so.
|
|
220
|
+
- **Deploy artifacts:** `deployTargets` (`"docker-compose"`, `"railway"`, `"fly"`, `"render"`)
|
|
221
|
+
writes `deploy/<target>/` into each service (generated files, counted like any other).
|
|
222
|
+
Genesis never deploys: you, or the user's own tools, run the deploy with the
|
|
223
|
+
user's own login. Commands per target: [deploy.md](deploy.md).
|
|
224
|
+
|
|
225
|
+
## 8. Failures at a glance
|
|
226
|
+
|
|
227
|
+
| Code | Status | Meaning, and what to do |
|
|
228
|
+
|---|---|---|
|
|
229
|
+
| `GENESIS_API_KEY_MISSING` | local | No key: pass the message on (it says how to set it). |
|
|
230
|
+
| `GENESIS_UNAUTHENTICATED`, `GENESIS_BAD_CREDENTIALS` | 401, 400 | The key was not accepted: the user sets the right one. |
|
|
231
|
+
| `GENESIS_ACCOUNT_REQUIRED` | 403 | A service credential was used; a user API key is needed. |
|
|
232
|
+
| `GENESIS_UNREACHABLE`, `GENESIS_TIMEOUT`, `GENESIS_BAD_RESPONSE` | local | The API did not answer properly. Say so; do not retry in a loop. A build retry reuses its key. |
|
|
233
|
+
| `GENESIS_RATE_LIMITED` | 429 | Validation budget spent: wait a minute. |
|
|
234
|
+
| `GENESIS_BLUEPRINT_INVALID` | 422 | Fix the findings in `details`. |
|
|
235
|
+
| `GENESIS_BLUEPRINT_UNREADABLE` | 422 | The blueprint could not be loaded at all: check its structure with `mind-set validate`. |
|
|
236
|
+
| `GENESIS_BLUEPRINT_TOO_LARGE`, `GENESIS_PAYLOAD_TOO_LARGE` | local, 413 | Over the size limit. |
|
|
237
|
+
| `GENESIS_SERVICE_UNKNOWN`, `GENESIS_SERVICE_NOT_AVAILABLE` | 422 | Wrong service name, or panel / sdk. |
|
|
238
|
+
| `GENESIS_LANGUAGE_NOT_ALLOWED`, `GENESIS_LANGUAGE_NOT_SUPPORTED` | 422 | Use a language the API lists (today `nodejs` and `rust`). |
|
|
239
|
+
| `GENESIS_IDEMPOTENCY_CONFLICT` | 409 | The key belongs to another request: omit the key for a new build. |
|
|
240
|
+
| `GENESIS_DRY_RUN_REQUIRED`, `GENESIS_OPTION_NOT_AVAILABLE` | 422 | Only dry runs today. |
|
|
241
|
+
| `GENESIS_JOB_NOT_FOUND`, `GENESIS_BUILD_NOT_FOUND` | 404 | Wrong id, or another account's. |
|
|
242
|
+
| `GENESIS_SERVICE_BUILD_FAILED`, `GENESIS_BUILD_INTERRUPTED`, ... | on the job | See [compile-results.md](compile-results.md). |
|
|
243
|
+
|
|
244
|
+
## 9. The REST surface
|
|
245
|
+
|
|
246
|
+
Every path is below `{apiBase}/genesis/compiler/v1`, with `Authorization: Bearer <key>` and JSON
|
|
247
|
+
bodies. The tools are thin wrappers over these calls:
|
|
248
|
+
|
|
249
|
+
| Call | Body or query |
|
|
250
|
+
|---|---|
|
|
251
|
+
| `POST /validate` | `{ "blueprint": { "inline": {...} }, "language"?, "services"? }` |
|
|
252
|
+
| `POST /validate/service` | `{ "serviceName", "blueprint": { "inline": {...} } \| { "fragment": {...} } }` |
|
|
253
|
+
| `POST /builds` | header `Idempotency-Key`; `{ "blueprint": {...}, "services": [...], "dryRun": true, "deployTargets"?, "language"? }` (several services in one build are allowed) |
|
|
254
|
+
| `GET /builds/:id` | the build with every service row |
|
|
255
|
+
| `POST /builds/:id/cancel` | stops a running build; services not started are cancelled; a finished build answers `409 GENESIS_BUILD_FINISHED` |
|
|
256
|
+
| `GET /jobs/:jobId` | one service build |
|
|
257
|
+
| `GET /builds` | the filters of 4.6 as the query |
|
|
258
|
+
|
|
259
|
+
## 10. Not available yet
|
|
260
|
+
|
|
261
|
+
Announced; do not call them, and say so when the user asks:
|
|
262
|
+
|
|
263
|
+
- reading the blueprint from a git repository (`repo` / `"blueprint": { "git": ... }`);
|
|
264
|
+
- pushing to the user's repositories (direct or pull request) and reading service files there;
|
|
265
|
+
- credit, usage and the overdraft refusal (`402`).
|