genesis-compiler 1.2.12 → 1.2.13
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/README.md +34 -90
- package/docs/prompt-integration.md +5 -5
- package/docs/stack-components.md +119 -393
- package/package.json +1 -2
- package/plugins/genesis/.codex-plugin/plugin.json +1 -1
- package/prompts/adopt.txt +14 -23
- package/prompts/start.txt +10 -12
- package/prompts/work.txt +8 -9
- package/src/cli.js +27 -55
- package/src/index/check.js +13 -21
- package/src/index/context.js +3 -3
- package/src/index/contracts.js +1 -3
- package/src/index/project-state.js +2 -2
- package/src/index/prompt.js +1 -1
- package/src/index/stack-catalog.js +1 -2
- package/src/index/stack-piece.js +25 -21
- package/src/index/stack-section-inspection.js +33 -0
- package/src/index/stack-section.js +82 -0
- package/src/index/stack-verification.js +54 -0
- package/src/index/stack.js +50 -84
- package/src/index/verification.js +2 -25
- package/src/index.js +3 -20
- package/docs/preview-identity-command.md +0 -113
- package/src/index/deployment.js +0 -34
- package/src/index/launch.js +0 -42
- package/src/index/stack-command.js +0 -65
- package/src/index/stack-deployment.js +0 -259
- package/src/index/stack-launch.js +0 -464
- package/src/index/stack-workspace-setup.js +0 -133
- package/src/index/workspace-setup.js +0 -156
package/docs/stack-components.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Stack components
|
|
2
2
|
|
|
3
|
-
Genesis core knows no framework, language, database, package manager, or
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Genesis core knows no framework, language, database, package manager, host, or
|
|
4
|
+
consumer operation. A Stack package is an ordinary npm package with one static
|
|
5
|
+
manifest pointer:
|
|
6
6
|
|
|
7
7
|
```json
|
|
8
8
|
{
|
|
@@ -11,472 +11,198 @@ is an ordinary npm package with one static manifest pointer:
|
|
|
11
11
|
}
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
Each piece is one Markdown file in that
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
14
|
+
Each piece is one Markdown file in that directory. Genesis reads the manifest
|
|
15
|
+
and Markdown only; it never imports or executes package code. Package names are
|
|
16
|
+
explicit, collisions fail, and selected packages are recorded in the project's
|
|
17
|
+
`## Stack packages` section.
|
|
18
|
+
|
|
19
|
+
## Piece format
|
|
20
|
+
|
|
21
|
+
A piece may use the Genesis-owned sections below:
|
|
21
22
|
|
|
22
23
|
````markdown
|
|
23
24
|
# Stack piece: example
|
|
24
25
|
|
|
25
26
|
## Description
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
Concise technology context.
|
|
28
29
|
|
|
29
30
|
## Requires
|
|
30
31
|
|
|
31
32
|
- `nodejs`
|
|
32
33
|
|
|
34
|
+
## Conflicts
|
|
35
|
+
|
|
36
|
+
- Nothing.
|
|
37
|
+
|
|
33
38
|
## Skill
|
|
34
39
|
|
|
35
|
-
- Package:
|
|
40
|
+
- Package: `example-agent-docs`
|
|
36
41
|
- Path: `skills/example`
|
|
37
42
|
|
|
38
43
|
## Indexers
|
|
39
44
|
|
|
40
45
|
- `javascript`
|
|
41
46
|
|
|
42
|
-
## City regions
|
|
43
|
-
|
|
44
|
-
- Ignore `**/test/**`
|
|
45
|
-
- Ignore `**/tests/**`
|
|
46
|
-
- Ignore `**/__tests__/**`
|
|
47
|
-
- Ignore `**/*.test.*`
|
|
48
|
-
- Ignore `**/*.spec.*`
|
|
49
|
-
- Match `packages` as `Packages`: `packages/**`
|
|
50
|
-
- Match `source` as `Source`: `src/**`
|
|
51
|
-
- Fallback `everything-else` as `Everything else`
|
|
52
|
-
|
|
53
47
|
## Resources
|
|
54
48
|
|
|
55
|
-
|
|
56
|
-
{
|
|
57
|
-
"id": "service",
|
|
58
|
-
"kind": "example-service",
|
|
59
|
-
"environmentAlternatives": [
|
|
60
|
-
{ "required": ["SERVICE_URL"] },
|
|
61
|
-
{ "required": ["SERVICE_HOST", "SERVICE_PORT"] }
|
|
62
|
-
]
|
|
63
|
-
}
|
|
64
|
-
```
|
|
49
|
+
- Resource `database` kind `postgresql`: `DATABASE_URL` OR `DB_HOST` + `DB_NAME`
|
|
65
50
|
|
|
66
51
|
## Environment defaults
|
|
67
52
|
|
|
68
|
-
- Default `
|
|
69
|
-
|
|
70
|
-
## Guidance
|
|
53
|
+
- Default `DB_CLIENT`: `pg`
|
|
71
54
|
|
|
72
|
-
|
|
55
|
+
## Environment files
|
|
73
56
|
|
|
74
|
-
-
|
|
75
|
-
review, and cleanup.
|
|
57
|
+
- Dotenv: `.env`
|
|
76
58
|
|
|
77
|
-
##
|
|
59
|
+
## Verification
|
|
78
60
|
|
|
79
|
-
-
|
|
80
|
-
importing an existing application.
|
|
61
|
+
- Verify `application`: `npm` `run` `verify`
|
|
81
62
|
|
|
82
|
-
##
|
|
63
|
+
## Guidance
|
|
83
64
|
|
|
84
|
-
-
|
|
65
|
+
- General project-work guidance.
|
|
85
66
|
|
|
86
|
-
##
|
|
67
|
+
## Adoption
|
|
87
68
|
|
|
88
|
-
-
|
|
89
|
-
- Prepare `Install web dependencies` with `nodejs` in `web`: `npm` `install`
|
|
69
|
+
- Existing-project import guidance.
|
|
90
70
|
|
|
91
71
|
## Deslop
|
|
92
72
|
|
|
93
|
-
-
|
|
73
|
+
- Technology-specific cleanup guidance.
|
|
94
74
|
|
|
95
|
-
##
|
|
75
|
+
## Consumer operation
|
|
96
76
|
|
|
97
|
-
-
|
|
77
|
+
```json example.consumer-operation.v1
|
|
78
|
+
{
|
|
79
|
+
"version": 1,
|
|
80
|
+
"data": "owned entirely by the consumer"
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
````
|
|
98
84
|
|
|
99
|
-
|
|
85
|
+
`Description`, `Guidance`, `Adoption`, and `Deslop` are prose. `Requires` and
|
|
86
|
+
`Conflicts` define component selection. `Skill` names one complete authoritative
|
|
87
|
+
Agent Skill directory. `Indexers` selects installed structural adapters.
|
|
88
|
+
`Resources`, `Environment defaults`, `Environment files`, and `Verification`
|
|
89
|
+
use the small Genesis grammars documented below. Every other `##` section is an
|
|
90
|
+
opaque extension.
|
|
100
91
|
|
|
101
|
-
|
|
92
|
+
## Genesis-owned declarations
|
|
102
93
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- Ready when: `GET` `/api/health` returns `200`
|
|
108
|
-
- Runtimes: `nodejs`
|
|
109
|
-
- Prepare `Build`: `npm` `run` `build`
|
|
110
|
-
- Serve `Start`: `npm` `run` `server` `--` `--host` `{host}` `--port` `{port}`
|
|
94
|
+
Resources describe required external inputs as alternatives of environment
|
|
95
|
+
variable names. Genesis can report which names are absent, but never reads a
|
|
96
|
+
service, provisions infrastructure, or returns a supplied value. A project
|
|
97
|
+
`## Resources` section replaces all component resource defaults.
|
|
111
98
|
|
|
112
|
-
|
|
99
|
+
Environment defaults are public, non-secret constants. Component defaults
|
|
100
|
+
compose by variable name; identical values collapse and conflicting values
|
|
101
|
+
fail. A project `## Environment defaults` section replaces component defaults.
|
|
102
|
+
Explicit process values always win.
|
|
113
103
|
|
|
114
|
-
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- Secret environment: `APP_PREVIEW_IDENTITY_SECRET`
|
|
119
|
-
- Runtimes: `nodejs`
|
|
120
|
-
- Timeout ms: `10000`
|
|
121
|
-
````
|
|
104
|
+
Environment files describe safe project-relative dotenv projection paths.
|
|
105
|
+
Genesis returns only the format and path. It does not materialize the file,
|
|
106
|
+
choose which values belong there, or store secrets. A project declaration
|
|
107
|
+
replaces component declarations; otherwise paths compose.
|
|
122
108
|
|
|
123
|
-
|
|
124
|
-
dependency closure. Optional `Conflicts` uses the same list format. `Skill`
|
|
125
|
-
selects one complete [Agent Skills](https://agentskills.io) directory, either
|
|
126
|
-
from Genesis or from the declared npm package. Its `SKILL.md`, `references/`,
|
|
127
|
-
`scripts/`, `assets/`, and `agents/` metadata are copied together to
|
|
128
|
-
`.agents/skills/<skill-name>/`; the agent loads them progressively instead of
|
|
129
|
-
Genesis expanding every manual into every prompt. Relative Markdown links and
|
|
130
|
-
images must resolve within that copied Skill root. Missing targets and paths
|
|
131
|
-
that escape the root are invalid, even if an escaped path happens to exist in
|
|
132
|
-
the source package or project. `Resources` declares generic
|
|
133
|
-
alternative environment-name sets reported by prompt generation and checked
|
|
134
|
-
before verification. `allowEmpty` may name a required variable whose empty
|
|
135
|
-
string is valid. `Environment defaults` declares public non-secret constants
|
|
136
|
-
owned by a concrete integration; explicit host values take precedence.
|
|
137
|
-
`Guidance` is supplemental prose used by work, review, Program,
|
|
138
|
-
description, and cleanup prompts, as well as path-focused context. `Adoption`
|
|
139
|
-
adds technology-specific evidence and contract requirements to the dedicated
|
|
140
|
-
existing-application import prompt. `Deslop`
|
|
141
|
-
adds cleanup-only prose to explicit cleanup and the automatic Codex cleanup
|
|
142
|
-
continuation. With no selected component, only the `genesis-deslop` skill
|
|
143
|
-
applies. `Commands` accepts only argument-safe `Verify` entries and runs only
|
|
144
|
-
through `genesis verify`.
|
|
145
|
-
|
|
146
|
-
A project may own a complete `## Resources` section in `genesis/stack.md` using
|
|
147
|
-
the same fenced `json genesis-resource` objects, or `- Nothing.` to declare
|
|
148
|
-
none. Its presence replaces every selected component Resource declaration.
|
|
149
|
-
This lets an existing application preserve its real queue, database, mail,
|
|
150
|
-
object-storage, or service environment names rather than inherit a framework's
|
|
151
|
-
vocabulary. Without a project section, component Resources compose as before.
|
|
152
|
-
|
|
153
|
-
`Workspace setup` is an optional exact, ordered recipe for a host preparing a
|
|
154
|
-
fresh workspace. Each entry uses this readable, shell-free form:
|
|
109
|
+
Verification contains exact argv tokens:
|
|
155
110
|
|
|
156
111
|
```markdown
|
|
157
|
-
|
|
112
|
+
## Verification
|
|
113
|
+
|
|
114
|
+
- Verify `tests`: `npm` `test`
|
|
115
|
+
- Verify `build`: `npm` `run` `build`
|
|
158
116
|
```
|
|
159
117
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
the
|
|
163
|
-
|
|
164
|
-
project-relative. Until it exists, inspection reports the recipe as
|
|
165
|
-
`unconfigured`; this lets a host safely re-inspect after an agent creates a
|
|
166
|
-
technology substrate without knowing that technology's filenames. `- Nothing.`
|
|
167
|
-
is valid only as the entire section and lets a
|
|
168
|
-
project explicitly disable component setup. Genesis validates and reports the
|
|
169
|
-
recipe but never chooses a runtime, runs a command, installs a dependency, or
|
|
170
|
-
infers a package manager. Generic language pieces such as `nodejs` and `php`
|
|
171
|
-
therefore declare no installer; a concrete piece such as `jskit` may declare
|
|
172
|
-
one.
|
|
173
|
-
|
|
174
|
-
Precedence is intentionally small and deterministic:
|
|
175
|
-
|
|
176
|
-
1. A project `## Workspace setup` section in `genesis/stack.md` replaces every
|
|
177
|
-
selected component default.
|
|
178
|
-
2. Without a project section, exactly one selected component recipe is used.
|
|
179
|
-
3. With no declaration the result is `unconfigured`; with several component
|
|
180
|
-
recipes it is `blocked` as ambiguous. Genesis never merges them.
|
|
181
|
-
|
|
182
|
-
General Stack resources do not gate Workspace setup. In particular, missing
|
|
183
|
-
database variables do not prevent an otherwise independent dependency install.
|
|
184
|
-
|
|
185
|
-
Each `Environment defaults` entry is one `Default` bullet with a backticked
|
|
186
|
-
environment name and value. Selected
|
|
187
|
-
component defaults compose by name; identical declarations collapse and
|
|
188
|
-
different values fail rather than silently choosing one. Defaults participate
|
|
189
|
-
in Stack identity, resource preflight, prompt context, Launch inspection, and
|
|
190
|
-
verification execution. The `genesis-stack` JSKIT database integrations use this contract for
|
|
191
|
-
their deterministic `DB_CLIENT` driver ids; generic database pieces do not.
|
|
192
|
-
Secrets and deployment-specific connection values remain host inputs and must
|
|
193
|
-
never be declared as defaults.
|
|
194
|
-
|
|
195
|
-
A project `## Environment defaults` section in `genesis/stack.md` likewise
|
|
196
|
-
replaces every component default and accepts `- Nothing.` as a complete empty
|
|
197
|
-
declaration. It is the complete declaration of public, non-secret constants
|
|
198
|
-
expected by the actual application; Genesis never keeps a framework default
|
|
199
|
-
beside it implicitly. `genesis stack add` preserves both project-owned sections
|
|
200
|
-
while changing component selection.
|
|
201
|
-
|
|
202
|
-
`Environment files` optionally declares project-relative dotenv projections a
|
|
203
|
-
host may materialize from its own resolved project environment. Genesis
|
|
204
|
-
validates and returns only the format and path; it never reads environment
|
|
205
|
-
values, writes a file, stores a secret, or chooses which variables belong in a
|
|
206
|
-
projection. A project `## Environment files` section in `genesis/stack.md`
|
|
207
|
-
replaces component declarations, including with `- Nothing.`. Without a
|
|
208
|
-
project section, component declarations compose and identical paths collapse.
|
|
209
|
-
The declaration is useful independently of Launch and Workspace setup.
|
|
210
|
-
|
|
211
|
-
`Launch` is an optional readable declarative recipe for hosts that need to
|
|
212
|
-
offer a preview without guessing how a concrete technology starts. Repeat a
|
|
213
|
-
``### Target `id`: label`` block to declare several targets. Default, Workdir,
|
|
214
|
-
Preferred port, URL path, and Runtimes are optional; their normalized defaults
|
|
215
|
-
are false, `.`, null, `/`, and no runtime requirements. Every target declares
|
|
216
|
-
one HTTP readiness predicate with a project path and an exact successful status
|
|
217
|
-
from 200 through 399. Every Prepare or Serve command and argument is a separate backticked value returned as an `argv`
|
|
218
|
-
array, never a shell program. A target has exactly one final Serve step; any
|
|
219
|
-
earlier steps must be Prepare steps. Workdir is canonical and project-relative,
|
|
220
|
-
Preferred port is only a hint from 1024 through 65535, and URL path is an
|
|
221
|
-
application path rather than a URL. The only substitutions are `{host}` and
|
|
222
|
-
`{port}`, supplied by the host. A project can use `- Nothing.` as its complete
|
|
223
|
-
Launch section to disable component targets.
|
|
224
|
-
|
|
225
|
-
Genesis validates and reports Launch data but does not select a runtime,
|
|
226
|
-
reserve a port, start a process, probe readiness, or control a browser. The host
|
|
227
|
-
executes the declared predicate and owns its timeout and retry policy.
|
|
228
|
-
|
|
229
|
-
The optional `#### Preview identity` block is specific to hosts that implement
|
|
230
|
-
the declared `genesis.preview-identity.command.v1` protocol. Its executable is
|
|
231
|
-
a committed, application-owned project-relative file; the
|
|
232
|
-
normalized command is an argv array, not a shell program. Identity types may
|
|
233
|
-
contain `email`, `login`, and `user-id`. Enabled environment and Secret
|
|
234
|
-
environment are optional variable
|
|
235
|
-
names the application recognizes; Genesis validates and returns names only and
|
|
236
|
-
never reads or returns their values. Runtimes lists opaque runtimes required
|
|
237
|
-
to execute this command, independently of the server target requirements, and
|
|
238
|
-
Timeout ms defaults to 10000 with a maximum of 30000. Genesis does not execute
|
|
239
|
-
the command, select identities, provide secrets, authenticate users, or control
|
|
240
|
-
the browser. Those remain host responsibilities. The complete transport
|
|
241
|
-
contract is defined in
|
|
242
|
-
[`preview-identity-command.md`](preview-identity-command.md).
|
|
243
|
-
|
|
244
|
-
`runtimeRequirements` contains opaque technology ids. A host explicitly maps
|
|
245
|
-
the ids it supports to its own pinned runtime packs; for example, it may map
|
|
246
|
-
`nodejs` to its Node 26 pack. Genesis never chooses versions, expands
|
|
247
|
-
dependencies such as `composer`, or treats an unknown id as something similar.
|
|
248
|
-
Declare each independently required runtime. Generic language pieces such as
|
|
249
|
-
`nodejs` and `php` provide no Launch recipe. A concrete piece such as `jskit`
|
|
250
|
-
may declare its app-owned `npm run develop` command; Genesis does not invent
|
|
251
|
-
missing targets or supervise framework-specific subprocesses.
|
|
252
|
-
|
|
253
|
-
`Deployment` is a separate optional readable production recipe. It must not be
|
|
254
|
-
inferred from Launch because preview preparation and production publication have
|
|
255
|
-
different safety, dependency, migration, artifact, and rollback concerns. Its
|
|
256
|
-
complete form is:
|
|
118
|
+
Genesis is the consumer of this section. `genesis verify` runs the declared
|
|
119
|
+
commands directly without a shell after generic resource preflight and records
|
|
120
|
+
the exact successful code, Stack, and command hashes. A project Verification
|
|
121
|
+
section replaces component defaults.
|
|
257
122
|
|
|
258
|
-
|
|
259
|
-
## Deployment
|
|
260
|
-
|
|
261
|
-
- Workdir: `.`
|
|
262
|
-
- Runtimes: `nodejs`
|
|
263
|
-
- Recreate on restore: `node_modules`
|
|
264
|
-
- Ready when: `GET` `/api/health` returns `200`
|
|
265
|
-
- Prepare `Install production dependencies`: `npm` `install` `--omit=dev`
|
|
266
|
-
- Build `Build`: `npm` `run` `build`
|
|
267
|
-
- Migrate `Prepare database`: `npm` `run` `db:prepare`
|
|
268
|
-
- Serve `Start`: `npm` `start`
|
|
269
|
-
```
|
|
123
|
+
## Opaque extensions
|
|
270
124
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
There is exactly one final Serve step and one exact HTTP readiness predicate
|
|
275
|
-
whose successful status is from 200 through 399. Runtime ids remain abstract.
|
|
276
|
-
|
|
277
|
-
`Recreate on restore` lists project-relative paths that a host may remove when
|
|
278
|
-
retaining an inactive release. Every listed path must be completely recreated
|
|
279
|
-
by the Deployment Prepare steps, which a host runs after restoring the release
|
|
280
|
-
and before Serve. Declaring these paths without a Prepare step is invalid.
|
|
281
|
-
An entry without `/` matches that path segment at every depth, so
|
|
282
|
-
`node_modules` covers root and nested workspace dependency trees. `*` stays
|
|
283
|
-
within one segment and `**` may cross path separators. A matched directory
|
|
284
|
-
includes its complete subtree.
|
|
285
|
-
This is application and Stack knowledge: for example, JSKIT declares
|
|
286
|
-
`node_modules`, while compiled output such as `dist` remains part of the
|
|
287
|
-
artifact because Prepare does not rebuild it. Genesis normalizes the paths but
|
|
288
|
-
does not remove, archive, restore, or reconstruct anything itself.
|
|
289
|
-
|
|
290
|
-
A project `## Deployment` section replaces every component recipe as one unit,
|
|
291
|
-
including with `- Nothing.`. Without a project section, exactly one selected
|
|
292
|
-
component recipe may apply; several are blocked as ambiguous and never merged.
|
|
293
|
-
Genesis returns the Stack's existing resource declarations with the recipe but
|
|
294
|
-
does not check production values, provision services, execute commands, package
|
|
295
|
-
artifacts, start processes, probe health, route traffic, manage TLS, or retain
|
|
296
|
-
releases. Those are host responsibilities. This keeps the same project portable:
|
|
297
|
-
Genesis alone explains the production requirements, while a host such as Vibe64
|
|
298
|
-
Online can map `mysql` or `postgresql` to a pinned managed service.
|
|
299
|
-
|
|
300
|
-
`Indexers` selects installed structural adapters for the derived Machine City.
|
|
301
|
-
The shared ast-grep engine owns traversal, bounds, diagnostics, JSON, and
|
|
302
|
-
queries; each adapter owns only language extensions, callable syntax, names,
|
|
303
|
-
containers, signatures, and public/internal visibility. Several Stack pieces
|
|
304
|
-
may contribute indexers, and duplicates are collapsed. Index output is
|
|
305
|
-
navigation data, not proof that every dynamic callable or framework edge was
|
|
306
|
-
discovered.
|
|
307
|
-
|
|
308
|
-
`City regions` is an optional complete presentation contract for Machine City.
|
|
309
|
-
Leading `Ignore` entries are canonical project-relative glob patterns using
|
|
310
|
-
only `*` within a path segment and `**` across segments. Genesis excludes their
|
|
311
|
-
matching files before it emits Machine City buildings or functions. This keeps
|
|
312
|
-
test/spec source out of the product City without requiring a host-side filter.
|
|
313
|
-
Each subsequent ordered `Match` entry declares one canonical project-relative
|
|
314
|
-
`path/**` prefix, stable id, and human title. Exactly one final `Fallback` entry
|
|
315
|
-
owns every remaining indexed path. Ignore patterns, ids, and prefixes must be
|
|
316
|
-
unique, prefixes must not overlap, and no more than one selected component may
|
|
317
|
-
declare the contract. Genesis resolves every indexed file and structural
|
|
318
|
-
district to a region and a campus while generating
|
|
319
|
-
`.genesis/machine-city.json`; a City renderer consumes those emitted facts and
|
|
320
|
-
must not reclassify or filter paths. Under a matched prefix, the first directory
|
|
321
|
-
is a campus, while files directly below the prefix belong to the prefix campus.
|
|
322
|
-
Under the fallback, each top-level directory is a campus and project-root files
|
|
323
|
-
belong to the project-root campus. The `genesis-stack` JSKIT piece excludes exact
|
|
324
|
-
`test`, `tests`, and `__tests__` path segments plus `*.test.*` and `*.spec.*`
|
|
325
|
-
files, then declares `Packages`, `Source`, and `Everything else`.
|
|
326
|
-
|
|
327
|
-
Do not create a Genesis-owned generic skill merely because a component is
|
|
328
|
-
named `nodejs`, `php`, or another common technology. Official, user, and host
|
|
329
|
-
skills with those names must coexist normally. Use `## Skill` only for an
|
|
330
|
-
authoritative directory this Stack component selects; put concise supplemental
|
|
331
|
-
rules in `## Guidance`, existing-project import requirements in `## Adoption`,
|
|
332
|
-
and cleanup-only additions in `## Deslop`.
|
|
333
|
-
|
|
334
|
-
A selected component may have one project customization at
|
|
335
|
-
`genesis/stack/<id>.md`:
|
|
125
|
+
Any other `##` heading is consumer-owned data. Genesis validates only the
|
|
126
|
+
section name and composition. It does not parse the body, infer its purpose,
|
|
127
|
+
validate a private schema, map runtimes, execute commands, or prove success.
|
|
336
128
|
|
|
337
|
-
|
|
338
|
-
# Stack customization: example
|
|
129
|
+
Composition is intentionally small:
|
|
339
130
|
|
|
340
|
-
|
|
131
|
+
1. A project section replaces component declarations with the same name.
|
|
132
|
+
2. Without a project section, one component declaration is returned unchanged.
|
|
133
|
+
3. Competing component declarations produce `STACK_SECTION_AMBIGUOUS`; Genesis
|
|
134
|
+
never merges their bodies.
|
|
341
135
|
|
|
342
|
-
|
|
136
|
+
Call `inspectStackSection({ name, projectRoot })` or:
|
|
343
137
|
|
|
344
|
-
|
|
138
|
+
```bash
|
|
139
|
+
genesis inspect section 'Consumer operation' --json
|
|
140
|
+
```
|
|
345
141
|
|
|
346
|
-
|
|
142
|
+
The result uses `genesis.stack-section.v1` and contains the exact lines,
|
|
143
|
+
content, source, section hash, Stack hash, and generic composition diagnostics.
|
|
144
|
+
The named consumer then owns all interpretation and action. This boundary works
|
|
145
|
+
equally for web applications, libraries, command-line tools, native programs,
|
|
146
|
+
firmware, desktop software, and future systems Genesis has never seen.
|
|
347
147
|
|
|
348
|
-
|
|
148
|
+
## Selection and identity
|
|
349
149
|
|
|
350
|
-
|
|
150
|
+
`genesis stack add` records selected packages and component dependency closure
|
|
151
|
+
without discarding project declarations. Stack identity includes component ids,
|
|
152
|
+
resources, environment declarations, Verification commands, City presentation,
|
|
153
|
+
and every opaque extension body. Changing any executable or consumer-owned
|
|
154
|
+
contract therefore stales prior Genesis verification evidence even though
|
|
155
|
+
Genesis does not interpret the extension.
|
|
351
156
|
|
|
352
|
-
|
|
157
|
+
Prose and Agent Skill contents are instructions rather than verification
|
|
158
|
+
evidence. Changes to Description, Guidance, Adoption, Deslop, or the installed
|
|
159
|
+
Skill do not rewrite what an already-run command proved.
|
|
353
160
|
|
|
354
|
-
|
|
161
|
+
`City regions` and `Indexers` control only the derived structural maps. Indexers
|
|
162
|
+
identify language adapters. City regions can exclude test/spec paths and group
|
|
163
|
+
indexed files into deterministic regions and campuses. Both projections are
|
|
164
|
+
navigation data, not proof of complete runtime behavior.
|
|
355
165
|
|
|
356
|
-
|
|
166
|
+
## Project customization
|
|
357
167
|
|
|
358
|
-
|
|
168
|
+
A selected component may have one prose-only customization at
|
|
169
|
+
`genesis/stack/<id>.md`:
|
|
359
170
|
|
|
360
|
-
|
|
171
|
+
```markdown
|
|
172
|
+
# Stack customization: example
|
|
361
173
|
|
|
362
|
-
|
|
174
|
+
## Add
|
|
363
175
|
|
|
364
176
|
### Guidance
|
|
365
177
|
|
|
366
|
-
-
|
|
178
|
+
- Additional project guidance.
|
|
367
179
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
- Replacement existing-project import requirements.
|
|
180
|
+
## Override
|
|
371
181
|
|
|
372
182
|
### Deslop
|
|
373
183
|
|
|
374
184
|
- Replacement cleanup guidance.
|
|
375
185
|
```
|
|
376
186
|
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
environment defaults, environment files, commands, Workspace setup, or Launch declarations.
|
|
381
|
-
`genesis stack add` preserves the files and composes their effective prose after
|
|
382
|
-
dependency resolution.
|
|
383
|
-
|
|
384
|
-
A project may select component ids in `genesis/stack.md`; replace component
|
|
385
|
-
Resources and Environment defaults with complete application-owned contracts;
|
|
386
|
-
replace component environment-file declarations; replace component Workspace
|
|
387
|
-
setup defaults with one project recipe; replace component Verify defaults with
|
|
388
|
-
its own `## Commands`; and replace every component Launch target with one
|
|
389
|
-
project `## Launch` contract. With no corresponding project section, selected
|
|
390
|
-
component declarations compose; conflicts are rejected rather than guessed.
|
|
391
|
-
`genesis stack add` preserves every existing project-owned contract section.
|
|
392
|
-
Adding another language, framework, database, or integration is therefore an
|
|
393
|
-
isolated Stack/indexer contribution rather than a prompt or controller special
|
|
394
|
-
case.
|
|
395
|
-
|
|
396
|
-
Description, Guidance, Adoption, Agent Skill, and Deslop prose are instructions, not
|
|
397
|
-
verification evidence. Changes to them do not stale an exact successful
|
|
398
|
-
verification record; selected component ids, resources, environment files,
|
|
399
|
-
environment defaults, Workspace setup, launch targets, and verification
|
|
400
|
-
commands remain part of the Stack identity.
|
|
401
|
-
|
|
402
|
-
Hosts inspect normalized environment requirements independently:
|
|
403
|
-
|
|
404
|
-
```js
|
|
405
|
-
import { inspectEnvironment } from 'genesis-compiler';
|
|
406
|
-
|
|
407
|
-
const projectEnvironment = await inspectEnvironment({ environment, projectRoot });
|
|
408
|
-
```
|
|
409
|
-
|
|
410
|
-
The result has `status` (`ready`, `missing-inputs`, or `unconfigured`),
|
|
411
|
-
`stackHash`, selected `components`, public non-secret `environmentDefaults`,
|
|
412
|
-
declared `resources`, value-free `diagnostics`, and normalized `files`. Each default has
|
|
413
|
-
`name`, `value`, and component `sources`; each file contains `format`, `path`,
|
|
414
|
-
and `source`. Supplied environment values never cross this API boundary.
|
|
415
|
-
|
|
416
|
-
Shell and non-Node hosts can inspect the same normalized contracts without
|
|
417
|
-
importing the JavaScript API or parsing Markdown:
|
|
418
|
-
|
|
419
|
-
```bash
|
|
420
|
-
genesis inspect environment --json
|
|
421
|
-
genesis inspect workspace --json
|
|
422
|
-
genesis inspect launch --json
|
|
423
|
-
genesis inspect deployment --json
|
|
424
|
-
```
|
|
425
|
-
|
|
426
|
-
These are projections of the same public inspectors. They do not create a
|
|
427
|
-
second parser or take ownership of execution.
|
|
428
|
-
|
|
429
|
-
Fresh-workspace hosts read setup from the package root:
|
|
430
|
-
|
|
431
|
-
```js
|
|
432
|
-
import { inspectWorkspaceSetup } from 'genesis-compiler';
|
|
433
|
-
|
|
434
|
-
const setup = await inspectWorkspaceSetup({ projectRoot, environment });
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
The setup result has `status` (`ready`, `blocked`, or `unconfigured`),
|
|
438
|
-
`stackHash`, an exact ready-recipe `recipeHash`, selected `components`, its `source`, distinct
|
|
439
|
-
`runtimeRequirements`, normalized ordered `steps`, and `diagnostics`. Each step
|
|
440
|
-
contains `label`, `argv`, `runtimeRequirements`, `workdir`, and an optional
|
|
441
|
-
`readyWhen` project path. `blocked` means component recipes conflict, not that
|
|
442
|
-
an unrelated Stack resource is absent. An absent `readyWhen` marker produces
|
|
443
|
-
the unconfigured diagnostic `STACK_WORKSPACE_SETUP_WAITING`, never a failed or
|
|
444
|
-
blocked result.
|
|
445
|
-
The optional environment object is accepted for a consistent host inspection
|
|
446
|
-
boundary, but Workspace setup v1 neither reads nor returns its values.
|
|
447
|
-
|
|
448
|
-
Standalone users may execute the same normalized recipe with their own
|
|
449
|
-
environment and installed toolchain:
|
|
450
|
-
|
|
451
|
-
```bash
|
|
452
|
-
genesis prepare
|
|
453
|
-
```
|
|
187
|
+
Customizations may add or override only Description, Guidance, Adoption, and
|
|
188
|
+
Deslop. They cannot mutate selection, resources, environment declarations,
|
|
189
|
+
Verification, Agent Skill ownership, indexers, or opaque consumer sections.
|
|
454
190
|
|
|
455
|
-
|
|
456
|
-
and stops at the first failure. It honors project-relative workdirs and
|
|
457
|
-
conditional paths. It does not provision databases, compilers, credentials,
|
|
458
|
-
runtimes, or other resources. Managed hosts remain free to consume
|
|
459
|
-
`inspectWorkspaceSetup()` and enforce their own execution, identity, runtime,
|
|
460
|
-
and permission policies.
|
|
191
|
+
## Public inspection
|
|
461
192
|
|
|
462
|
-
|
|
193
|
+
Hosts may inspect Genesis-owned environment declarations separately:
|
|
463
194
|
|
|
464
195
|
```js
|
|
465
|
-
import {
|
|
196
|
+
import { inspectEnvironment, inspectStackSection } from 'genesis-compiler';
|
|
466
197
|
|
|
467
|
-
const
|
|
198
|
+
const environment = await inspectEnvironment({ projectRoot });
|
|
199
|
+
const operation = await inspectStackSection({
|
|
200
|
+
name: 'Consumer operation',
|
|
201
|
+
projectRoot,
|
|
202
|
+
});
|
|
468
203
|
```
|
|
469
204
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
`source`, `available`, and `disabledReason`, plus its normalized
|
|
475
|
-
`previewIdentity` declaration when present. Supplied environment values are
|
|
476
|
-
inspected but never returned. Here, `available` means only that the Stack's declared
|
|
477
|
-
resource inputs are present: the host must still reject runtime requirements it
|
|
478
|
-
cannot map. `unconfigured` means there are no targets, `blocked` means declared
|
|
479
|
-
resource inputs are missing, and `ready` means neither condition applies. The
|
|
480
|
-
caller still owns exact runtimes, port allocation, process lifecycle, readiness
|
|
481
|
-
and proxy policy, identity selection and command execution, secrets, browser
|
|
482
|
-
binaries, Git, and credentials.
|
|
205
|
+
`inspectEnvironment()` uses `genesis.environment.v1` and never returns supplied
|
|
206
|
+
values. `inspectStackSection()` uses `genesis.stack-section.v1` and never
|
|
207
|
+
interprets the section. There is no generic Genesis API that executes an opaque
|
|
208
|
+
operation.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "genesis-compiler",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.13",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
|
|
6
6
|
"repository": {
|
|
@@ -25,7 +25,6 @@
|
|
|
25
25
|
".agents/plugins/marketplace.json",
|
|
26
26
|
"bin",
|
|
27
27
|
"docs/assurance-model.md",
|
|
28
|
-
"docs/preview-identity-command.md",
|
|
29
28
|
"docs/stack-components.md",
|
|
30
29
|
"docs/prompt-integration.md",
|
|
31
30
|
"prompts/blueprint.txt",
|