genesis-compiler 1.2.0 → 1.2.2

package/README.md

@@ -13,7 +13,7 @@ interaction.
 ```text
 genesis/
   blueprint.md       non-technical product intent
-  stack.md           selected technology guidance, checks, setup, and launch data
+  stack.md           selected technology guidance, checks, setup, launch, and deployment data
   stack/             optional per-component Description, Guidance, and Deslop customization
   program/           concise explanations grouped into conceptual subsystems
 .agents/skills/
@@ -98,7 +98,7 @@ that, use Codex normally. No technology is assumed until you explicitly select
 Stack components:
 
 ```bash
-genesis stack add nodejs         # or jskit jskit-mysql
+genesis stack add nodejs         # or jskit jskit-mysql / jskit-postgresql
 ```
 
 Genesis does not install substitute generic `nodejs`, `vue`, `php`, or similar
@@ -131,25 +131,51 @@ Genesis does not run the recipe. Stack resources such as database variables do
 not gate dependency installation.
 
 Hosts that manage project environments can call `inspectEnvironment()`.
+Concrete Stack integrations may declare public, non-secret Environment
+defaults such as the database driver selected by that integration. Explicit
+host or user values take precedence. The built-in JSKIT MySQL and PostgreSQL
+pieces respectively declare `DB_CLIENT=mysql2` and `DB_CLIENT=pg`, so users
+provide connection values rather than restating a deterministic technology
+choice.
 An optional readable `## Environment files` section declares safe
 project-relative dotenv projections such as `.env`. A project declaration
 replaces component defaults, including with `- Nothing.`; otherwise component
-paths compose. Genesis reports resource declarations, value-free missing-input
-diagnostics, and paths. It never returns values, writes files, stores secrets,
-or decides which resolved values a host should materialize.
+paths compose. Genesis reports public defaults, resource declarations,
+value-free missing-input diagnostics, and paths. It never returns supplied
+environment values, writes files, stores secrets, or decides which resolved
+host values should be materialized.
 
 Hosts that provide previews can call the public `inspectLaunch()` API. An
 optional readable `## Launch` section in `genesis/stack.md` declares labeled
 targets, exact backticked argument tokens, relative working directories,
 abstract runtime requirements, `{host}`/`{port}` substitutions, and an optional
 application-owned Preview identity block. Concrete components may provide a
-default: `jskit` declares build followed by `npm start`; generic `nodejs` and
-`php` do not guess. Genesis starts nothing itself. It returns preview identity
+default: `jskit` declares its app-owned `npm run develop` command; generic
+`nodejs` and `php` do not guess. Genesis starts nothing itself. It returns preview identity
 command metadata and environment variable names, never their values. The host
-continues to own pinned runtimes, ports, processes, readiness, identity-command
-execution and secrets, browser binaries, Git, and credentials. See
+continues to own pinned runtimes, ports, processes, readiness probing and
+timeouts, identity-command execution and secrets, browser binaries, Git, and
+credentials. Genesis owns only the exact HTTP readiness predicate declared by
+the selected Stack. See
 [`docs/stack-components.md`](docs/stack-components.md) for the v1 contract.
 
+Hosts that publish applications can call the separate public
+`inspectDeployment()` API. An optional readable `## Deployment` section
+declares an ordered production recipe: project-relative workdir, abstract
+runtimes, exact Prepare/Build/Migrate/Serve argv, and one HTTP readiness
+predicate. A concrete component may provide the recipe; the built-in `jskit`
+piece declares production dependency installation, build, database preparation,
+`npm start`, and `/api/health`. Generic language pieces do not guess. A project
+section replaces component defaults wholesale, and `- Nothing.` explicitly
+disables publishing.
+
+Genesis only validates and reports this recipe and the Stack's abstract resource
+requirements. It does not provision a database, resolve credentials, copy a
+release, run commands, start a service, reserve a port, route traffic, issue TLS,
+or roll back. A deployment host owns all of those operational responsibilities,
+including the mapping from `mysql` or `postgresql` resources to its managed
+services.
+
 At session start, Codex receives only a short explanation of how Genesis is
 organized. After it locates the source involved in a request, it can load the
 specific explanatory and technology context with:
@@ -300,13 +326,13 @@ List and select the built-in Stack components:
 
 ```bash
 genesis stack list
-genesis stack add jskit jskit-mysql
+genesis stack add jskit jskit-mysql      # or jskit-postgresql
 ```
 
 `genesis/stack.md` records component ids and optional project verification
 commands. Selecting no components is valid. Built-in components include the
-eleven common language families listed above, plus Vue, MySQL, JSKIT, and JSKIT
-with MySQL. Components may contribute:
+eleven common language families listed above, plus Vue, MySQL, PostgreSQL,
+JSKIT, and JSKIT database integrations. Components may contribute:
 
 - a concise description and supplemental Guidance used across relevant tasks;
 - one authoritative Agent Skill directory when the component owns one;
@@ -321,7 +347,7 @@ cleanup tasks; `Deslop` adds cleanup-only rules. Neither shadows an official
 generic technology skill nor assumes that an upstream skill contains every rule
 Genesis needs.
 
-Genesis core contains no MySQL, JSKIT, Vue, Laravel, or other platform-specific
+Genesis core contains no database, framework, language, or platform-specific
 controller behavior. See [Stack components](docs/stack-components.md).
 
 ## Verification
@@ -332,8 +358,11 @@ Run the Stack's declared checks explicitly:
 genesis verify
 ```
 
-Genesis first evaluates generic Stack resource declarations, then runs each
-declared command without a shell. A complete successful run writes only
+Genesis first waits for any technology-declared Workspace setup marker. A
+missing marker is `unconfigured`, not a failed command. Once the workspace
+exists, Genesis applies public Stack defaults beneath explicit environment
+values, evaluates generic resource declarations, and runs each declared
+command without a shell. A complete successful run writes only
 `.genesis/verification.json`, recording:
 
 - the exact Git-visible code hash;
@@ -413,10 +442,10 @@ to execute with its own pinned runtimes, caches, process isolation, and
 credentials. A configured recipe may remain unconfigured while it waits for a
 technology-declared project marker.
 `inspectEnvironment()` returns normalized Stack resource declarations,
-value-free missing-input diagnostics, and dotenv projection paths without
-returning any environment value.
+public non-secret defaults, value-free missing-input diagnostics, and dotenv
+projection paths without returning any supplied environment value.
 `inspectLaunch()` returns a validated, normalized Stack launch declaration for
-a host to execute with its own runtime, port, process, readiness, preview
+a host to execute with its own runtime, port, process, readiness probe, preview
 identity, secret, and browser policy.
 
 A host such as Vibe64 can send the generated prompt to its existing agent:

package/docs/stack-components.md

@@ -29,6 +29,7 @@ What this component contributes.
 ```json genesis-resource
 {
   "id": "service",
+  "kind": "example-service",
   "environmentAlternatives": [
     { "required": ["SERVICE_URL"] },
     { "required": ["SERVICE_HOST", "SERVICE_PORT"] }
@@ -36,6 +37,10 @@ What this component contributes.
 }
 ```
 
+## Environment defaults
+
+- Default `EXAMPLE_DRIVER`: `example`
+
 ## Guidance
 
 ### Technology-specific behavior
@@ -68,6 +73,7 @@ What this component contributes.
 - Workdir: `.`
 - Preferred port: `3000`
 - URL path: `/`
+- Ready when: `GET` `/api/health` returns `200`
 - Runtimes: `nodejs`
 - Prepare `Build`: `npm` `run` `build`
 - Serve `Start`: `npm` `run` `server` `--` `--host` `{host}` `--port` `{port}`
@@ -92,7 +98,9 @@ from Genesis or from the declared npm package. Its `SKILL.md`, `references/`,
 Genesis expanding every manual into every prompt. `Resources` declares generic
 alternative environment-name sets reported by prompt generation and checked
 before verification. `allowEmpty` may name a required variable whose empty
-string is valid. `Guidance` is supplemental prose used by work, review, Program,
+string is valid. `Environment defaults` declares public non-secret constants
+owned by a concrete integration; explicit host values take precedence.
+`Guidance` is supplemental prose used by work, review, Program,
 description, and cleanup prompts, as well as path-focused context. `Deslop`
 adds cleanup-only prose to explicit cleanup and the automatic Codex cleanup
 continuation. With no selected component, only the `genesis-deslop` skill
@@ -131,6 +139,16 @@ Precedence is intentionally small and deterministic:
 General Stack resources do not gate Workspace setup. In particular, missing
 database variables do not prevent an otherwise independent dependency install.
 
+Each `Environment defaults` entry is one `Default` bullet with a backticked
+environment name and value. Selected
+component defaults compose by name; identical declarations collapse and
+different values fail rather than silently choosing one. Defaults participate
+in Stack identity, resource preflight, prompt context, Launch inspection, and
+verification execution. The JSKIT database integrations use this contract for
+their deterministic `DB_CLIENT` driver ids; generic database pieces do not.
+Secrets and deployment-specific connection values remain host inputs and must
+never be declared as defaults.
+
 `Environment files` optionally declares project-relative dotenv projections a
 host may materialize from its own resolved project environment. Genesis
 validates and returns only the format and path; it never reads environment
@@ -144,8 +162,9 @@ The declaration is useful independently of Launch and Workspace setup.
 offer a preview without guessing how a concrete technology starts. Repeat a
 ``### Target `id`: label`` block to declare several targets. Default, Workdir,
 Preferred port, URL path, and Runtimes are optional; their normalized defaults
-are false, `.`, null, `/`, and no runtime requirements. Every Prepare or Serve
-command and argument is a separate backticked value returned as an `argv`
+are false, `.`, null, `/`, and no runtime requirements. Every target declares
+one HTTP readiness predicate with a project path and an exact successful status
+from 200 through 399. Every Prepare or Serve command and argument is a separate backticked value returned as an `argv`
 array, never a shell program. A target has exactly one final Serve step; any
 earlier steps must be Prepare steps. Workdir is canonical and project-relative,
 Preferred port is only a hint from 1024 through 65535, and URL path is an
@@ -154,7 +173,8 @@ application path rather than a URL. The only substitutions are `{host}` and
 Launch section to disable component targets.
 
 Genesis validates and reports Launch data but does not select a runtime,
-reserve a port, start a process, decide readiness, or control a browser.
+reserve a port, start a process, probe readiness, or control a browser. The host
+executes the declared predicate and owns its timeout and retry policy.
 
 The optional `#### Preview identity` block is specific to hosts that implement
 the declared `vibe64.preview-identity.command.v1` protocol. Its executable is a
@@ -175,7 +195,41 @@ the ids it supports to its own pinned runtime packs; for example, it may map
 dependencies such as `composer`, or treats an unknown id as something similar.
 Declare each independently required runtime. Generic language pieces such as
 `nodejs` and `php` provide no Launch recipe. A concrete piece such as `jskit`
-may declare one; Genesis does not invent missing targets.
+may declare its app-owned `npm run develop` command; Genesis does not invent
+missing targets or supervise framework-specific subprocesses.
+
+`Deployment` is a separate optional readable production recipe. It must not be
+inferred from Launch because preview preparation and production publication have
+different safety, dependency, migration, artifact, and rollback concerns. Its
+complete form is:
+
+```markdown
+## Deployment
+
+- Workdir: `.`
+- Runtimes: `nodejs`
+- Ready when: `GET` `/api/health` returns `200`
+- Prepare `Install production dependencies`: `npm` `install` `--omit=dev`
+- Build `Build`: `npm` `run` `build`
+- Migrate `Prepare database`: `npm` `run` `db:prepare`
+- Serve `Start`: `npm` `start`
+```
+
+Every command and argument is a separate backticked value returned as an argv
+array; shell source is rejected. Workdir is canonical and project-relative.
+Prepare, Build, and Migrate steps are optional and retain their declared order.
+There is exactly one final Serve step and one exact HTTP readiness predicate
+whose successful status is from 200 through 399. Runtime ids remain abstract.
+
+A project `## Deployment` section replaces every component recipe as one unit,
+including with `- Nothing.`. Without a project section, exactly one selected
+component recipe may apply; several are blocked as ambiguous and never merged.
+Genesis returns the Stack's existing resource declarations with the recipe but
+does not check production values, provision services, execute commands, package
+artifacts, start processes, probe health, route traffic, manage TLS, or retain
+releases. Those are host responsibilities. This keeps the same project portable:
+Genesis alone explains the production requirements, while a host such as Vibe64
+Online can map `mysql` or `postgresql` to a pinned managed service.
 
 `Indexers` selects installed structural adapters for the derived Machine City.
 The shared ast-grep engine owns traversal, bounds, diagnostics, JSON, and
@@ -229,7 +283,7 @@ Replacement component description.
 Each field is optional. `Override` replaces only that installed field; `Add`
 then follows the installed or overridden value. These files cannot alter
 dependencies, conflicts, Agent Skill source, indexers, resources, environment
-files, commands, Workspace setup, or Launch declarations.
+defaults, environment files, commands, Workspace setup, or Launch declarations.
 `genesis stack add` preserves the files and composes their effective prose after
 dependency resolution.
 
@@ -247,8 +301,8 @@ rather than a prompt or controller special case.
 Description, Guidance, Agent Skill, and Deslop prose are instructions, not
 verification evidence. Changes to them do not stale an exact successful
 verification record; selected component ids, resources, environment files,
-Workspace setup, launch targets, and verification commands remain part of the
-Stack identity.
+environment defaults, Workspace setup, launch targets, and verification
+commands remain part of the Stack identity.
 
 Hosts inspect normalized environment requirements independently:
 
@@ -259,9 +313,10 @@ const projectEnvironment = await inspectEnvironment({ environment, projectRoot }
 ```
 
 The result has `status` (`ready`, `missing-inputs`, or `unconfigured`),
-`stackHash`, selected `components`, declared `resources`, value-free
-`diagnostics`, and normalized `files`. Each file contains `format`, `path`, and
-`source`. Environment values never cross this API boundary.
+`stackHash`, selected `components`, public non-secret `environmentDefaults`,
+declared `resources`, value-free `diagnostics`, and normalized `files`. Each default has
+`name`, `value`, and component `sources`; each file contains `format`, `path`,
+and `source`. Supplied environment values never cross this API boundary.
 
 Fresh-workspace hosts read setup from the package root:
 
@@ -291,11 +346,12 @@ const launch = await inspectLaunch({ projectRoot, environment });
 ```
 
 The result has `status` (`ready`, `blocked`, or `unconfigured`), `stackHash`,
-selected `components`, distinct `runtimeRequirements`, declared `resources`,
+selected `components`, public `environmentDefaults`, distinct
+`runtimeRequirements`, declared `resources`,
 normalized `targets`, and resource `diagnostics`. Each target reports its
 `source`, `available`, and `disabledReason`, plus its normalized
-`previewIdentity` declaration when present. Environment values are inspected
-but never returned. Here, `available` means only that the Stack's declared
+`previewIdentity` declaration when present. Supplied environment values are
+inspected but never returned. Here, `available` means only that the Stack's declared
 resource inputs are present: the host must still reject runtime requirements it
 cannot map. `unconfigured` means there are no targets, `blocked` means declared
 resource inputs are missing, and `ready` means neither condition applies. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/prompts/start.txt

@@ -13,6 +13,11 @@ the non-technical Blueprint from the user's answers before implementation.
 If the product direction becomes clear while Stack is still empty, do not end
 the turn after only writing or summarizing the Blueprint: present the relevant
 Stack choices in that same turn and ask the user to select one explicitly.
+This opening turn owns product direction and Stack selection, not final
+verification. Do not run `genesis verify` before implementation has created
+the selected technology's workspace substrate. If structural validation is
+useful, run `genesis check`; treat missing workspace markers as unconfigured,
+not as an implementation failure.
 
 When `projectKind` is `existing`, ask what the user wants to understand or
 change. Use the current Blueprint, Stack, Program, and code index when present.

package/skills/genesis-project/SKILL.md

@@ -48,6 +48,9 @@ Neither is authority or proof; both may be regenerated with `genesis index`.
 
 ## Verify and report
 
-Use `genesis verify` for the Stack's declared final checks. Report files
-changed, checks actually run, and anything still requiring attention. Never
-claim that an unrun check passed or that passing checks prove the whole product.
+After the selected technology's workspace substrate exists, use `genesis
+verify` for the Stack's declared final checks. An unconfigured result means the
+declared workspace or checks do not exist yet; it is not a failing check. Report
+files changed, checks actually run, and anything still requiring attention.
+Never claim that an unrun check passed or that passing checks prove the whole
+product.

package/src/index/check.js

@@ -6,6 +6,7 @@ import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 
 function invalidResult(area, error) {
   return {
@@ -55,7 +56,10 @@ export async function checkProject({ environment = process.env, projectRoot } =
   } catch (error) {
     skills = { status: 'invalid', diagnostics: [asDiagnostic(error)], skills: [] };
   }
-  const missingResources = missingStackResources({ environment, resources: stack.resources });
+  const missingResources = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const verification = await inspectVerification({ projectRoot: root, stack });
   const diagnostics = [
     ...(program.diagnostic ? [program.diagnostic] : []),

package/src/index/deployment.js

@@ -0,0 +1,31 @@
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { sha256, stableJson, uniqueSorted } from './utils.js';
+
+/** Read the Stack's production recipe without provisioning or publishing anything. */
+export async function inspectProjectDeployment({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = [...stack.deployment.diagnostics];
+  let status = 'unconfigured';
+  if (diagnostics.length > 0) status = 'blocked';
+  else if (stack.deployment.steps.length > 0) status = 'ready';
+  const recipe = {
+    version: stack.deployment.version,
+    workdir: stack.deployment.workdir,
+    runtimeRequirements: stack.deployment.runtimeRequirements,
+    readiness: stack.deployment.readiness,
+    steps: stack.deployment.steps,
+  };
+  return {
+    status,
+    stackHash: stack.identityHash,
+    recipeHash: status === 'ready' ? sha256(stableJson(recipe)) : '',
+    components: stack.components.map(({ id }) => id),
+    source: stack.deployment.source,
+    runtimeRequirements: uniqueSorted(stack.deployment.runtimeRequirements),
+    resources: stack.resources,
+    ...recipe,
+    diagnostics,
+  };
+}

package/src/index/environment-files.js

@@ -1,17 +1,24 @@
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 
-/** Inspect Stack environment requirements without returning or writing values. */
+/** Inspect Stack environment requirements without returning supplied host values. */
 export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
-  const configured = stack.environmentFiles.length > 0 || stack.resources.length > 0;
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
+  const configured = stack.environmentDefaults.length > 0
+    || stack.environmentFiles.length > 0
+    || stack.resources.length > 0;
   return {
     status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     files: stack.environmentFiles,
     resources: stack.resources,
     diagnostics,

package/src/index/launch.js

@@ -1,5 +1,6 @@
 import { gitContext } from './git.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { readStack } from './stack.js';
 import { uniqueSorted } from './utils.js';
 
@@ -10,7 +11,10 @@ export async function inspectProjectLaunch({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const disabledReason = diagnostics.length === 0
     ? null
     : diagnostics.map(({ message }) => message).join(' ');
@@ -26,6 +30,7 @@ export async function inspectProjectLaunch({
     status,
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     runtimeRequirements: uniqueSorted(targets.flatMap((target) => target.runtimeRequirements)),
     resources: stack.resources,
     targets,

package/src/index/prompt.js

@@ -9,6 +9,7 @@ import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { isProjectContentPath } from './paths.js';
@@ -305,7 +306,10 @@ export async function generateProjectPrompt({
     buildProjectIndex({ projectRoot: root, write: false }),
     inspectProjectSkills({ projectRoot: root, stack }),
   ]);
-  const missing = missingStackResources({ environment, resources: stack.resources });
+  const missing = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const warnings = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...missing,

package/src/index/stack-catalog.js

@@ -64,6 +64,7 @@ export async function listBuiltinStackPieces() {
       requires: piece.requires,
       conflicts: piece.conflicts,
       indexers: piece.indexers,
+      environmentDefaults: piece.environmentDefaults,
       launchTargets: piece.launchTargets.map(({ id }) => id),
       workspaceSetup: piece.workspaceSetupSteps,
       skill: piece.skill === null ? null : piece.skill.path,