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.
@@ -1,8 +1,8 @@
1
1
  # Stack components
2
2
 
3
- Genesis core knows no framework, language, database, package manager, or
4
- environment-variable name, and it ships no technology pieces. A Stack package
5
- is an ordinary npm package with one static manifest pointer:
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 declared directory. Genesis reads the
15
- manifest and Markdown only; it never imports or executes package code. Catalog
16
- names are explicit, collisions fail, and the selected package is recorded in
17
- the project's `## Stack packages` section. The first-party optional
18
- `genesis-stack` package contains the complete curated catalog; Genesis core does
19
- not depend on it. A framework contributes to that catalog rather than requiring
20
- a compiler release or a separate catalog package.
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
- What this component contributes.
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: `@example/agent-docs`
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
- ```json genesis-resource
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 `EXAMPLE_DRIVER`: `example`
69
-
70
- ## Guidance
53
+ - Default `DB_CLIENT`: `pg`
71
54
 
72
- ### Technology-specific behavior
55
+ ## Environment files
73
56
 
74
- - Concise supplemental guidance used during implementation, explanation,
75
- review, and cleanup.
57
+ - Dotenv: `.env`
76
58
 
77
- ## Adoption
59
+ ## Verification
78
60
 
79
- - Evidence and technology-specific contracts an agent must reconcile when
80
- importing an existing application.
61
+ - Verify `application`: `npm` `run` `verify`
81
62
 
82
- ## Environment files
63
+ ## Guidance
83
64
 
84
- - Dotenv `.env`
65
+ - General project-work guidance.
85
66
 
86
- ## Workspace setup
67
+ ## Adoption
87
68
 
88
- - Prepare `Install dependencies` with `example-runtime`: `example-install` `--locked`
89
- - Prepare `Install web dependencies` with `nodejs` in `web`: `npm` `install`
69
+ - Existing-project import guidance.
90
70
 
91
71
  ## Deslop
92
72
 
93
- - Concise technology-specific cleanup guidance.
73
+ - Technology-specific cleanup guidance.
94
74
 
95
- ## Commands
75
+ ## Consumer operation
96
76
 
97
- - Verify `tests`: `npm` `test`
77
+ ```json example.consumer-operation.v1
78
+ {
79
+ "version": 1,
80
+ "data": "owned entirely by the consumer"
81
+ }
82
+ ```
83
+ ````
98
84
 
99
- ## Launch
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
- ### Target `app`: Run app
92
+ ## Genesis-owned declarations
102
93
 
103
- - Default.
104
- - Workdir: `.`
105
- - Preferred port: `3000`
106
- - URL path: `/`
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
- #### Preview identity
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
- - Command: `tools/preview-identity`
115
- - Protocol: `genesis.preview-identity.command.v1`
116
- - Identity types: `email` `login` `user-id`
117
- - Enabled environment: `APP_PREVIEW_IDENTITY_ENABLED`
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
- `Description` and `Requires` are the only required sections. `Requires` forms
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
- - Prepare `label` with `runtime` `another-runtime` in `optional/workdir` when `optional/marker` exists: `command` `argument`
112
+ ## Verification
113
+
114
+ - Verify `tests`: `npm` `test`
115
+ - Verify `build`: `npm` `run` `build`
158
116
  ```
159
117
 
160
- Every command and argument is a separate backticked value and is returned as
161
- an `argv` array. Runtime names are opaque technology ids. Omitted `in` means
162
- the project root; otherwise the working directory must be canonical and
163
- project-relative. The optional `when` path is also canonical and
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
- ```markdown
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
- Every command and argument is a separate backticked value returned as an argv
272
- array; shell source is rejected. Workdir is canonical and project-relative.
273
- Prepare, Build, and Migrate steps are optional and retain their declared order.
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
- ```markdown
338
- # Stack customization: example
129
+ Composition is intentionally small:
339
130
 
340
- ## Add
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
- ### Description
136
+ Call `inspectStackSection({ name, projectRoot })` or:
343
137
 
344
- Additional project context.
138
+ ```bash
139
+ genesis inspect section 'Consumer operation' --json
140
+ ```
345
141
 
346
- ### Guidance
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
- - Additional implementation, explanation, review, and cleanup guidance.
148
+ ## Selection and identity
349
149
 
350
- ### Adoption
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
- - Additional existing-project import requirements.
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
- ### Deslop
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
- - Additional cleanup guidance.
166
+ ## Project customization
357
167
 
358
- ## Override
168
+ A selected component may have one prose-only customization at
169
+ `genesis/stack/<id>.md`:
359
170
 
360
- ### Description
171
+ ```markdown
172
+ # Stack customization: example
361
173
 
362
- Replacement component description.
174
+ ## Add
363
175
 
364
176
  ### Guidance
365
177
 
366
- - Replacement installed general guidance.
178
+ - Additional project guidance.
367
179
 
368
- ### Adoption
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
- Each field is optional. `Override` replaces only that installed field; `Add`
378
- then follows the installed or overridden value. These customization files
379
- cannot alter dependencies, conflicts, Agent Skill source, indexers, resources,
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
- `genesis prepare` runs each declared argv directly without a shell, in order,
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
- Preview hosts read the normalized Launch contract independently:
193
+ Hosts may inspect Genesis-owned environment declarations separately:
463
194
 
464
195
  ```js
465
- import { inspectLaunch } from 'genesis-compiler';
196
+ import { inspectEnvironment, inspectStackSection } from 'genesis-compiler';
466
197
 
467
- const launch = await inspectLaunch({ projectRoot, environment });
198
+ const environment = await inspectEnvironment({ projectRoot });
199
+ const operation = await inspectStackSection({
200
+ name: 'Consumer operation',
201
+ projectRoot,
202
+ });
468
203
  ```
469
204
 
470
- The result has `status` (`ready`, `blocked`, or `unconfigured`), `stackHash`,
471
- selected `components`, public `environmentDefaults`, distinct
472
- `runtimeRequirements`, declared `resources`,
473
- normalized `targets`, and resource `diagnostics`. Each target reports its
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.12",
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",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "genesis",
3
- "version": "1.2.12",
3
+ "version": "1.2.13",
4
4
  "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
5
5
  "author": {
6
6
  "name": "Mobily Enterprises"