@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.
Files changed (41) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/LICENSE +202 -0
  3. package/README.md +147 -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 +220 -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 +43 -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
package/mcp/tools.mjs ADDED
@@ -0,0 +1,270 @@
1
+ // The genesis_* tools of the genesis-set MCP server and what each one sends.
2
+ //
3
+ // genesis_validateApplication POST /validate
4
+ // genesis_validateService POST /validate/service
5
+ // genesis_buildService POST /builds (exactly one service)
6
+ // genesis_getBuilds GET /builds
7
+ // genesis_getServiceBuild GET /jobs/:jobId
8
+ //
9
+ // and the local key tools of ./key-tools.mjs (genesis_requestKey,
10
+ // genesis_listKeys, genesis_openKeyManager, genesis_writeKeyToEnvFile), which
11
+ // never call the API and work without a Genesis API key.
12
+ //
13
+ // A tool sends the blueprint (read from the local file and sent inline, or the
14
+ // repository source passed through as given) and the parameters its schema
15
+ // names, nothing else: unknown arguments are refused before any call.
16
+
17
+ import { randomUUID } from 'node:crypto';
18
+
19
+ import { readLocalJson, LocalBlueprintError } from './blueprint.mjs';
20
+ import { callGenesis, genesisError } from './client.mjs';
21
+ import { missingKeyMessage } from './config.mjs';
22
+ import { KEY_TOOLS, isKeyTool, runKeyTool } from './key-tools.mjs';
23
+
24
+ const REPO_SOURCE = {
25
+ type: 'object',
26
+ description:
27
+ 'The blueprint in a git repository: { "provider": "github" | "gitlab", "repo": "<owner>/<name>", "ref": "<branch, tag or sha>", "path": "<file in the repo>" }. ' +
28
+ 'Passed to the API as it is. Not available yet: the API answers GENESIS_BLUEPRINT_SOURCE_NOT_AVAILABLE until reading from git ships; use blueprintPath.',
29
+ properties: {
30
+ provider: { type: 'string', enum: ['github', 'gitlab'] },
31
+ repo: { type: 'string' },
32
+ ref: { type: 'string' },
33
+ path: { type: 'string' },
34
+ },
35
+ };
36
+ const BLUEPRINT_PATH = {
37
+ type: 'string',
38
+ description:
39
+ 'Path of the blueprint JSON file on this machine (absolute, or relative to the folder the agent was started in). The file is read locally, size-checked and sent inline.',
40
+ };
41
+ const LANGUAGE = {
42
+ type: 'string',
43
+ description: 'Build language (default nodejs). The API answers GENESIS_LANGUAGE_NOT_ALLOWED for a language it has not enabled.',
44
+ };
45
+ const SERVICE_NAME = { type: 'string', description: 'The service name as the blueprint writes it (serviceSettings.serviceBasics.name).' };
46
+
47
+ const API_TOOLS = [
48
+ {
49
+ name: 'genesis_validateApplication',
50
+ title: 'Validate a blueprint with Genesis',
51
+ description:
52
+ 'Validate a whole OpenAPPL blueprint with the Genesis compiler (POST /validate). Free and rate limited. ' +
53
+ 'Answers valid: true with the codename and the services Genesis would build, or a 422 GENESIS_BLUEPRINT_INVALID with errors and warnings. ' +
54
+ 'Give exactly one of blueprintPath or repo.',
55
+ inputSchema: {
56
+ type: 'object',
57
+ properties: {
58
+ blueprintPath: BLUEPRINT_PATH,
59
+ repo: REPO_SOURCE,
60
+ language: LANGUAGE,
61
+ services: { type: 'array', items: { type: 'string' }, description: 'Only check that these services exist and can be built (default: all).' },
62
+ },
63
+ additionalProperties: false,
64
+ },
65
+ annotations: { readOnlyHint: true, openWorldHint: true },
66
+ },
67
+ {
68
+ name: 'genesis_validateService',
69
+ title: 'Validate one service with Genesis',
70
+ description:
71
+ 'Validate ONE service (POST /validate/service), from the whole blueprint (blueprintPath or repo) or from that service\'s JSON alone (fragmentPath: one entry of the blueprint\'s services list). ' +
72
+ 'A fragment check reports references it cannot see (other services, roles, providers) under notChecked, never as errors. Same rate limit as genesis_validateApplication. Give exactly one of blueprintPath, fragmentPath or repo.',
73
+ inputSchema: {
74
+ type: 'object',
75
+ properties: {
76
+ serviceName: SERVICE_NAME,
77
+ blueprintPath: BLUEPRINT_PATH,
78
+ fragmentPath: { type: 'string', description: 'Path of a JSON file holding one service (one services[] entry). Read locally and sent inline.' },
79
+ repo: REPO_SOURCE,
80
+ language: LANGUAGE,
81
+ },
82
+ required: ['serviceName'],
83
+ additionalProperties: false,
84
+ },
85
+ annotations: { readOnlyHint: true, openWorldHint: true },
86
+ },
87
+ {
88
+ name: 'genesis_buildService',
89
+ title: 'Compile one service with Genesis',
90
+ description:
91
+ 'Start compiling ONE service of the blueprint (POST /builds with that service). Asynchronous: answers the build and its jobId; follow it with genesis_getServiceBuild. ' +
92
+ 'Every build is a dry run for now (the code is generated and measured, nothing is pushed). The added lines of a build are what it is charged once charging opens. ' +
93
+ 'The tool sends a fresh Idempotency-Key and returns it: to retry the SAME build after a lost answer, pass that key back. Give exactly one of blueprintPath or repo.',
94
+ inputSchema: {
95
+ type: 'object',
96
+ properties: {
97
+ serviceName: SERVICE_NAME,
98
+ blueprintPath: BLUEPRINT_PATH,
99
+ repo: REPO_SOURCE,
100
+ deployTargets: {
101
+ type: 'array',
102
+ items: { type: 'string' },
103
+ description:
104
+ 'Deploy artifacts to emit into the service (deploy/<target>/): "docker-compose", "railway", "fly", "render" (the API answers GENESIS_UNKNOWN_DEPLOY_TARGET with the allowed list). Genesis never deploys.',
105
+ },
106
+ language: LANGUAGE,
107
+ dryRun: { type: 'boolean', description: 'Default true, the only mode the API accepts for now.' },
108
+ idempotencyKey: { type: 'string', description: 'Reuse the key a previous call returned to retry that same build; omit for a new build.' },
109
+ },
110
+ required: ['serviceName'],
111
+ additionalProperties: false,
112
+ },
113
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
114
+ },
115
+ {
116
+ name: 'genesis_getBuilds',
117
+ title: 'List your Genesis builds',
118
+ description:
119
+ 'Your builds, newest first (GET /builds), with per service the jobId, status and added / deleted lines. Pass nextCursor back as cursor for the next page.',
120
+ inputSchema: {
121
+ type: 'object',
122
+ properties: {
123
+ codename: { type: 'string', description: 'Only builds of this project codename (projectSettings.basicSettings.name).' },
124
+ status: { type: 'string', enum: ['queued', 'running', 'succeeded', 'partial', 'failed', 'cancelled'] },
125
+ serviceName: { type: 'string', description: 'Only builds that include this service.' },
126
+ since: { type: 'string', description: 'ISO 8601: builds created at or after.' },
127
+ until: { type: 'string', description: 'ISO 8601: builds created before.' },
128
+ limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size (default 20, at most 100).' },
129
+ cursor: { type: 'string', description: 'The nextCursor of the previous page.' },
130
+ },
131
+ additionalProperties: false,
132
+ },
133
+ annotations: { readOnlyHint: true, openWorldHint: true },
134
+ },
135
+ {
136
+ name: 'genesis_getServiceBuild',
137
+ title: 'Read one service build',
138
+ description:
139
+ 'One service build job (GET /jobs/:jobId): status, times, added / deleted lines, files and the file list, tokens, deploy artifacts, the error and the tail of the build log. ' +
140
+ 'Poll with a growing interval (5 s, 10 s, then 30 s) until the status is succeeded, failed or cancelled.',
141
+ inputSchema: {
142
+ type: 'object',
143
+ properties: { jobId: { type: 'string', description: 'The jobId genesis_buildService or genesis_getBuilds gave.' } },
144
+ required: ['jobId'],
145
+ additionalProperties: false,
146
+ },
147
+ annotations: { readOnlyHint: true, openWorldHint: true },
148
+ },
149
+ ];
150
+
151
+ export const TOOLS = [...API_TOOLS, ...KEY_TOOLS];
152
+
153
+ const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
154
+
155
+ class ArgumentError extends Error {}
156
+
157
+ function checkArguments(tool, args) {
158
+ if (args === undefined || args === null) args = {};
159
+ if (typeof args !== 'object' || Array.isArray(args)) throw new ArgumentError('the arguments must be an object');
160
+ const props = tool.inputSchema.properties;
161
+ const unknown = Object.keys(args).filter((k) => !(k in props));
162
+ if (unknown.length) throw new ArgumentError(`unknown argument(s): ${unknown.join(', ')}; allowed: ${Object.keys(props).join(', ')}`);
163
+ for (const k of tool.inputSchema.required ?? []) {
164
+ if (args[k] === undefined || args[k] === null || args[k] === '') throw new ArgumentError(`"${k}" is required`);
165
+ }
166
+ for (const [k, v] of Object.entries(args)) {
167
+ if (v === undefined) continue;
168
+ const s = props[k];
169
+ const okType =
170
+ s.type === 'string' ? typeof v === 'string'
171
+ : s.type === 'boolean' ? typeof v === 'boolean'
172
+ : s.type === 'integer' ? Number.isInteger(v)
173
+ : s.type === 'array' ? Array.isArray(v) && v.every((x) => typeof x === 'string')
174
+ : s.type === 'object' ? Boolean(v) && typeof v === 'object' && !Array.isArray(v)
175
+ : true;
176
+ if (!okType) throw new ArgumentError(`"${k}" must be ${s.type === 'array' ? 'a list of strings' : `a${s.type === 'integer' ? 'n' : ''} ${s.type}`}`);
177
+ if (s.enum && !s.enum.includes(v)) throw new ArgumentError(`"${k}" must be one of: ${s.enum.join(', ')}`);
178
+ }
179
+ return args;
180
+ }
181
+
182
+ /** The `blueprint` member of a request body from exactly one of the given source arguments. */
183
+ function blueprintSource(args, settings, sources) {
184
+ const given = sources.filter((s) => args[s] !== undefined);
185
+ if (given.length !== 1) throw new ArgumentError(`give exactly one of: ${sources.join(', ')}`);
186
+ const [which] = given;
187
+ if (which === 'repo') return { git: args.repo };
188
+ const kind = which === 'fragmentPath' ? 'fragment' : 'blueprint';
189
+ const value = readLocalJson(args[which], { maxBytes: settings.maxBlueprintBytes, kind, cwd: settings.cwd });
190
+ return which === 'fragmentPath' ? { fragment: value } : { inline: value };
191
+ }
192
+
193
+ function withDefined(obj) {
194
+ return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
195
+ }
196
+
197
+ const HANDLERS = {
198
+ async genesis_validateApplication(args, settings, signal) {
199
+ const body = withDefined({
200
+ blueprint: blueprintSource(args, settings, ['blueprintPath', 'repo']),
201
+ language: args.language,
202
+ services: args.services,
203
+ });
204
+ return callGenesis(settings, '/validate', { method: 'POST', body, signal });
205
+ },
206
+ async genesis_validateService(args, settings, signal) {
207
+ const body = withDefined({
208
+ serviceName: args.serviceName,
209
+ blueprint: blueprintSource(args, settings, ['blueprintPath', 'fragmentPath', 'repo']),
210
+ language: args.language,
211
+ });
212
+ return callGenesis(settings, '/validate/service', { method: 'POST', body, signal });
213
+ },
214
+ async genesis_buildService(args, settings, signal) {
215
+ const idempotencyKey = args.idempotencyKey ?? randomUUID();
216
+ const body = withDefined({
217
+ blueprint: blueprintSource(args, settings, ['blueprintPath', 'repo']),
218
+ services: [args.serviceName],
219
+ language: args.language,
220
+ deployTargets: args.deployTargets,
221
+ dryRun: args.dryRun ?? true,
222
+ });
223
+ const res = await callGenesis(settings, '/builds', {
224
+ method: 'POST',
225
+ body,
226
+ headers: { 'idempotency-key': idempotencyKey },
227
+ signal,
228
+ });
229
+ return { ...res, extra: { idempotencyKey } };
230
+ },
231
+ async genesis_getBuilds(args, settings, signal) {
232
+ return callGenesis(settings, '/builds', { query: args, signal });
233
+ },
234
+ async genesis_getServiceBuild(args, settings, signal) {
235
+ return callGenesis(settings, `/jobs/${encodeURIComponent(args.jobId)}`, { signal });
236
+ },
237
+ };
238
+
239
+ /** The MCP `tools/call` result of one call: the API answer (or the Genesis error) as JSON text. */
240
+ function toolResult({ ok, httpStatus, body, extra }) {
241
+ const payload = { httpStatus, ...(extra ?? {}), ...body };
242
+ return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: !ok };
243
+ }
244
+
245
+ export function hasTool(name) {
246
+ return BY_NAME.has(name);
247
+ }
248
+
249
+ /** Runs a tool. `settings` = resolveSettings() plus { cwd, userAgent }. Never throws. */
250
+ export async function runTool(name, rawArgs, settings, signal) {
251
+ const tool = BY_NAME.get(name);
252
+ try {
253
+ const args = checkArguments(tool, rawArgs);
254
+ if (isKeyTool(name)) return toolResult(await runKeyTool(name, args, settings));
255
+ if (!settings.apiKey) {
256
+ return toolResult({ ok: false, httpStatus: null, body: genesisError('GENESIS_API_KEY_MISSING', missingKeyMessage(settings.configFile, settings.apiBase)) });
257
+ }
258
+ return toolResult(await HANDLERS[name](args, settings, signal));
259
+ } catch (err) {
260
+ if (err instanceof ArgumentError) {
261
+ return toolResult({ ok: false, httpStatus: null, body: genesisError('GENESIS_BAD_ARGUMENTS', `${name}: ${err.message}`) });
262
+ }
263
+ if (err instanceof LocalBlueprintError) return toolResult({ ok: false, httpStatus: null, body: err.body });
264
+ return toolResult({
265
+ ok: false,
266
+ httpStatus: null,
267
+ body: genesisError('GENESIS_TOOL_FAILED', `${name} failed before reaching the API: ${err?.message ?? String(err)}`),
268
+ });
269
+ }
270
+ }
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@mindbricks/genesis-set",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "PRE-RELEASE. Genesis compiler skills for coding agents (Claude Code, Codex): the generated code, its runtime and the Genesis Compiler API, on top of mind-set.",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/Mindbricks/genesis-set.git"
9
+ },
10
+ "homepage": "https://github.com/Mindbricks/genesis-set#readme",
11
+ "bugs": {
12
+ "url": "https://github.com/Mindbricks/genesis-set/issues"
13
+ },
14
+ "type": "module",
15
+ "bin": {
16
+ "genesis-set": "bin/genesis-set.mjs"
17
+ },
18
+ "files": [
19
+ "bin/",
20
+ "lib/",
21
+ "mcp/",
22
+ "skills/",
23
+ "corpus/",
24
+ "README.md",
25
+ "LICENSE",
26
+ "CHANGELOG.md"
27
+ ],
28
+ "engines": {
29
+ "node": ">=18"
30
+ },
31
+ "scripts": {
32
+ "test": "node test/run.mjs"
33
+ },
34
+ "keywords": [
35
+ "openappl",
36
+ "genesis",
37
+ "compiler",
38
+ "claude-code",
39
+ "codex",
40
+ "agent-skills"
41
+ ],
42
+ "dependencies": {
43
+ "@mindbricks/mind-set": "^0.1.0"
44
+ }
45
+ }
@@ -0,0 +1,56 @@
1
+ ---
2
+ name: genesis-compiler-api
3
+ description: PRE-RELEASE. Compile a validated OpenAPPL blueprint into service code with the Genesis Compiler API through the genesis_* MCP tools (genesis_validateApplication, genesis_validateService, genesis_buildService, genesis_getServiceBuild, genesis_getBuilds), follow each service build and report what it produced. Use it after the blueprint is written and validated with mind-set, when the user wants generated code, deploy files or the status of a build. Do not use it to design or write the blueprint (the mind-set openappl-blueprint-* skills), to run or test the generated services (genesis-run-and-test) or to deploy them (genesis-deploy).
4
+ ---
5
+
6
+ # Genesis Compiler API
7
+
8
+ > **Builds are dry runs for now:** the code is generated and measured, nothing is pushed. When a
9
+ > tool answers `GENESIS_UNREACHABLE`, say so plainly and stop: never claim a validation or a
10
+ > build happened.
11
+
12
+ The guide is `{{CORPUS}}/genesis/compiler-api.md`. Read it fully before the first call. Reading a
13
+ service build's result is `{{CORPUS}}/genesis/compile-results.md`.
14
+
15
+ ## Before you call
16
+
17
+ 1. The blueprint is written and validated with mind-set (the openappl-blueprint-authoring skill
18
+ and `mind-set validate blueprint.json`, schema `{{MIND_SET}}/openappl.json`). Follow the
19
+ mind-set procedure `{{MIND_SET}}/procedures/project-lifecycle.md` with its Genesis additions
20
+ `{{CORPUS}}/genesis/procedures/project-lifecycle.md`.
21
+ 2. Identity is the blueprint's: the codename is `projectSettings.basicSettings.name`; a new
22
+ blueprint gets a stable project id (a UUID) once. Write no binding file or other compiler file
23
+ into the project folder.
24
+ 3. The `genesis_*` tools are there (the MCP server `genesis`; `genesis-set install` registers it,
25
+ then restart the agent). A call that answers `GENESIS_API_KEY_MISSING` carries the message that
26
+ tells the user where to create the key (the Genesis portal's API keys page) and how to set it
27
+ (`GENESIS_API_KEY`, or `genesis-set config set-key` in their own terminal): pass it on. The
28
+ easiest way for the user is the local key page: `genesis_requestKey` with
29
+ `name: "genesis-api-key"` answers its link; then check `genesis_listKeys`. Never ask for the key
30
+ in the chat, never write it into a file, never print it.
31
+
32
+ ## The calls
33
+
34
+ 1. `genesis_validateApplication` with `blueprintPath` (absolute). Fix every error, judge every
35
+ warning. While iterating on one service, `genesis_validateService` with `fragmentPath` is the
36
+ fast loop; `notChecked` is not a pass, so finish with the whole blueprint.
37
+ 2. Author everything and validate everything first, then compile each service once. During the
38
+ dry-run release the line counts are estimates and no credit is charged. Compile `auth` first
39
+ when the others or the tests need it.
40
+ 3. `genesis_buildService` per service, with `deployTargets` when the user wants deploy files.
41
+ Keep the returned `idempotencyKey`; after a lost answer, call again with the same key and the
42
+ same arguments (never a second build).
43
+ 4. `genesis_getServiceBuild` with the `jobId`: 5 s, 10 s, then every 30 s, until `succeeded`,
44
+ `failed` or `cancelled`. Never report a build you did not see finish.
45
+ 5. Report per service: status, added / deleted lines, files, deploy artifacts, every error code.
46
+ A failure is a blueprint fault (fix, validate, compile that service again) or a compiler fault
47
+ (report it with the job id and the exact error).
48
+ 6. `genesis_getBuilds` finds earlier builds and their job ids (filter by `codename`).
49
+ 7. Start the run-and-test skill when the matching generated service repositories are available.
50
+ A successful dry run provides a report and inventory. It leaves no checkout or local deploy files.
51
+
52
+ ## Not available yet
53
+
54
+ Reading the blueprint from git (`repo`), pushing to the user's repositories (direct or pull
55
+ request), credit and usage: the guide's section 10. Do
56
+ not call them; say so when asked.
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: genesis-deploy
3
+ description: Deploy the services the Genesis compiler generated, with the user's own login on the target - the docker-compose stack, Railway, Fly.io and Render - from the deploy files a Genesis build writes into each service (deploy/<target>/). Use it when the user wants the generated backend running somewhere: a server, Railway, Fly.io, Render. Genesis never deploys; this skill tells you how the user's own tools do it. Do not use it to compile (genesis-compiler-api) or for a local test run (genesis-run-and-test).
4
+ ---
5
+
6
+ # Deploying the generated services
7
+
8
+ **Genesis never deploys.** It writes the deploy files; you run the deploy with the user's own
9
+ login on the target. No deploy token or platform credential ever goes to Genesis, into the
10
+ blueprint, into a project file or into a commit.
11
+
12
+ Read `{{CORPUS}}/genesis/deploy.md` fully first. Each target folder also has a generated
13
+ `README.md` for that service and build: read it before you run anything; where it and the guide
14
+ differ, it wins.
15
+
16
+ Builds are dry runs for now: the deploy files are generated and counted but not pushed to the
17
+ user's repositories, so there is nothing to deploy yet (deploy.md says so first). Tell the user;
18
+ do not write the files by hand.
19
+
20
+ ## Steps
21
+
22
+ 1. The build must have asked for the target: `genesis_buildService` with
23
+ `deployTargets: ["docker-compose", "railway"]` (the genesis-compiler-api skill). The job's
24
+ `deployArtifacts` says per target `emitted` or `skipped`.
25
+ 2. Prepare what every target needs: one Ed25519 signing key and key id per service, the
26
+ provider credentials the service lists, the peer addresses the target does not wire itself.
27
+ Secrets go into the target's secret variables or a gitignored local file, never a committed one.
28
+ - **A local file:** ask for each key on the local key page (`genesis_requestKey`, the user saves
29
+ it, `genesis_writeKeyToEnvFile`). Never take a value from the chat.
30
+ - **A hosting target:** the user enters the key in the target's own secret settings.
31
+ 3. Deploy with the target's own tools and the user's own login (deploy.md, sections 3 to 6).
32
+ When a command needs the user's sign-in, ask the user to do it; do not handle their password.
33
+ 4. Verify on the target: its deploy log, then `/health` ready on the public address. Report the
34
+ address and the health verdict per service; never report a deploy you did not see succeed.
35
+ 5. A target the API does not accept (`GENESIS_UNKNOWN_DEPLOY_TARGET`): say it is not available;
36
+ do not write its config by hand as if Genesis had generated it.
@@ -0,0 +1,48 @@
1
+ ---
2
+ name: genesis-generated-code
3
+ description: Work with what the Genesis compiler generates from an OpenAPPL blueprint - the runtime behaviour of the generated services (payment and subscription ladders, verification codes, mail and SMS sinks, credential fallbacks, per-language support), custom code (library functions, edge controllers, dbLayer, LIB / API) and the Genesis steps next to the mind-set procedures. Use it while following a mind-set procedure for a project compiled by Genesis, when the blueprint needs custom code, and when a generated service behaves unexpectedly. Do not use it to write the blueprint itself (mind-set), to call the Compiler API (genesis-compiler-api) or to run and test the services (genesis-run-and-test).
4
+ ---
5
+
6
+ # The Genesis compiler's output
7
+
8
+ genesis-set adds to mind-set; it never repeats it. The procedures are mind-set's, at
9
+ `{{MIND_SET}}/procedures/`. For each procedure that has Genesis-specific steps, genesis-set
10
+ ships one additions file under `{{CORPUS}}/genesis/procedures/` with the same name; the index is
11
+ `{{CORPUS}}/genesis/procedures/README.md`.
12
+
13
+ ## How to read the additions
14
+
15
+ 1. Follow the mind-set procedure as it is.
16
+ 2. Before you start it, open its Genesis additions file (when the index lists one). Each section
17
+ names the heading of the mind-set procedure it belongs to, and either ADDS steps there or
18
+ REPLACES a step (the replaced mind-set text is quoted by its first words). Where a section
19
+ replaces a step, do the Genesis version.
20
+ 3. A rule in the additions about the generated runtime (error codes, admin routes, mock
21
+ transports, health fields) is how Genesis-generated code behaves; treat a different answer
22
+ from a running service as a finding to report, not as a reason to change the blueprint.
23
+
24
+ ## Custom code
25
+
26
+ Read `{{CORPUS}}/genesis/custom-code.md` before you write a library function, an edge
27
+ controller or an arrow-function action. The pattern shapes are mind-set's
28
+ (`{{MIND_SET}}/procedures/blueprint-authoring.md`, section 8); the page says what the compiler
29
+ generates from them, what the code can call (`LIB`, `API`, `dbLayer`, `common`) and what survives
30
+ a rebuild.
31
+
32
+ - Custom code lives in the blueprint and is re-injected at every compile.
33
+ - Keep edits in the blueprint. A compile overwrites direct edits to generated files, and added
34
+ lines will count toward usage when charging opens.
35
+ - Files you add to a service repository survive; `service-files/` is always yours.
36
+
37
+ ## When the generated runtime surprises you
38
+
39
+ `{{CORPUS}}/genesis/pitfalls.md` lists the compiler facts that look like bugs: the slot decides
40
+ the verification-code echo and the sinks (`CONFIG_ENV`), mail without a complete provider goes to
41
+ a sink, credential fallbacks, payment tables that need `auth` compiled after the provider, schema
42
+ drift, signing keys, empty peer addresses, a service that never exits at boot.
43
+
44
+ ## Where the fix goes
45
+
46
+ A wrong result from a generated service is a blueprint fault (fix the blueprint, validate,
47
+ compile again), a fault of your own deploy (env, keys, peers), or a compiler fault (report it
48
+ with the job id and the exact error; `{{CORPUS}}/genesis/compile-results.md`, section 7).
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: genesis-run-and-test
3
+ description: Run, debug and test the services the Genesis compiler generated, on the user's own machine - start the stack (the docker-compose deploy files or one service natively), read /health (alive is not ready), reproduce a failure and decide whose fault it is, write and run the API test suite, drive Kafka / cron / internal APIs through the generated test transport, and seed sample data. Use it after a Genesis build when the user wants to see the services work, test them or debug them. Do not use it to compile (genesis-compiler-api) or to deploy to a hosting target (genesis-deploy).
4
+ ---
5
+
6
+ # Running and testing the generated services
7
+
8
+ Genesis never runs anything for the user: you run the generated services with the user's own
9
+ tools. Everything stays on the user's machine; nothing is sent to Genesis.
10
+
11
+ ## Read first
12
+
13
+ - `{{CORPUS}}/genesis/run-locally.md`: what a generated service repository holds, env precedence,
14
+ ports and signing keys, starting the stack, health, reproducing a failure, whose fault it is.
15
+ - `{{CORPUS}}/genesis/testing.md`: the test suite, identity bootstrap, fixtures, the test
16
+ transport, reasoned skips, triage, and the sample-data seed.
17
+ - The test plan and the test report are mind-set's documents:
18
+ `{{MIND_SET}}/procedures/design/writers/test-plan.md` and
19
+ `{{MIND_SET}}/procedures/design/writers/test-report.md`. Write them as mind-set says; run them
20
+ as the pages above say.
21
+
22
+ ## Steps
23
+
24
+ 1. Check out every service repository of the build side by side, at the commit of the build you
25
+ test. Without push (pre-release), the repositories come from wherever the user keeps the
26
+ generated code.
27
+ 2. Start the stack: the `docker-compose` deploy files when the build asked for them
28
+ (`deploy/docker-compose/README.md`), or one service natively (`npm run dev`) against local
29
+ infrastructure. Generate an Ed25519 signing key per service first.
30
+ Check the container runtime first (`docker info`). When there is none, follow run-locally.md
31
+ section 4c: the user installs one (OrbStack or Docker Desktop on macOS, Docker Engine on
32
+ Linux, Docker Desktop with WSL 2 on Windows), or one service runs natively against a
33
+ database only, with what is missing said up front.
34
+ 3. Wait for `/health` to say ready (`readiness.ready: true`, `boot.state: ready`). A 200 alone is
35
+ only alive.
36
+ 4. Run the suite; drive what HTTP cannot reach through the test transport as super-admin; never
37
+ weaken an assertion to get green.
38
+ 5. A failure: reproduce it, then route the fix (blueprint, custom code, the user's own deploy, or
39
+ a compiler fault reported with the job id). Never patch a generated file.
40
+ 6. Payment and subscription flows: follow the ladders in
41
+ `{{CORPUS}}/genesis/procedures/howto-payment-flow.md` and
42
+ `{{CORPUS}}/genesis/procedures/howto-subscription.md` next to their mind-set procedures.
43
+ 7. Report what ran, what passed, what was skipped and why, and what is still running.