@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.
Files changed (41) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/LICENSE +202 -0
  3. package/README.md +148 -2
  4. package/bin/genesis-set.mjs +153 -0
  5. package/corpus/README.md +25 -0
  6. package/corpus/genesis/compile-results.md +246 -0
  7. package/corpus/genesis/compiler-api.md +265 -0
  8. package/corpus/genesis/custom-code.md +519 -0
  9. package/corpus/genesis/deploy.md +190 -0
  10. package/corpus/genesis/pitfalls.md +231 -0
  11. package/corpus/genesis/procedures/README.md +17 -0
  12. package/corpus/genesis/procedures/agent-hub-blueprint.md +13 -0
  13. package/corpus/genesis/procedures/auth-blueprint.md +14 -0
  14. package/corpus/genesis/procedures/bff-blueprint.md +16 -0
  15. package/corpus/genesis/procedures/blueprint-authoring.md +16 -0
  16. package/corpus/genesis/procedures/howto-mail-to-tasks.md +26 -0
  17. package/corpus/genesis/procedures/howto-payment-flow.md +112 -0
  18. package/corpus/genesis/procedures/howto-subscription.md +33 -0
  19. package/corpus/genesis/procedures/notifications-blueprint.md +13 -0
  20. package/corpus/genesis/procedures/patterns-catalog.md +12 -0
  21. package/corpus/genesis/procedures/project-lifecycle.md +27 -0
  22. package/corpus/genesis/run-locally.md +310 -0
  23. package/corpus/genesis/testing.md +532 -0
  24. package/lib/config-cli.mjs +179 -0
  25. package/lib/install.mjs +639 -0
  26. package/lib/mcp-config.mjs +222 -0
  27. package/lib/semver.mjs +94 -0
  28. package/mcp/blueprint.mjs +64 -0
  29. package/mcp/client.mjs +141 -0
  30. package/mcp/config.mjs +166 -0
  31. package/mcp/key-page-html.mjs +275 -0
  32. package/mcp/key-page.mjs +217 -0
  33. package/mcp/key-store.mjs +204 -0
  34. package/mcp/key-tools.mjs +225 -0
  35. package/mcp/server.mjs +164 -0
  36. package/mcp/tools.mjs +270 -0
  37. package/package.json +44 -4
  38. package/skills/genesis-compiler-api/SKILL.md +56 -0
  39. package/skills/genesis-deploy/SKILL.md +36 -0
  40. package/skills/genesis-generated-code/SKILL.md +48 -0
  41. 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 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 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 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 config set-base <url>`).
62
+ 4. `genesis 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 `mindset 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 `mindset 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 `mindset 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`).