genesis-compiler 1.2.15 → 1.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.15",
+  "version": "1.2.17",
   "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.15",
+  "version": "1.2.17",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/skills/genesis-project/SKILL.md

@@ -22,12 +22,13 @@ codebase, tests, Git review, or the coding agent.
    agent's own installed skill catalog.
 
 For an existing application's first Stack selection, inspect its real setup,
-build, and launch commands before relying on component defaults. A selected
+build, and output commands before relying on component defaults. A selected
 component describes its current foundation; it does not silently port older
 source. When the existing commands differ, keep the implementation unchanged
-and declare exact project-owned `## Workspace setup` and `## Launch` overrides.
-Do not claim the inherited component recipe is usable until it matches the
-source.
+and declare exact project-owned consumer-operation overrides (for Vibe64,
+`## Workspace setup` and `## Outputs`). Genesis composes those sections as
+opaque text; the named consumer alone owns their meaning and execution. Do not
+claim the inherited component recipe is usable until it matches the source.
 
 Program is concise, fallible explanation. Its Sources and optional
 Implementation maps aid navigation but never substitute for reading code,
@@ -42,11 +43,12 @@ Neither is authority or proof; both may be regenerated with `genesis index`.
 - Work directly in the current Git tree and leave useful edits visible in the
   ordinary diff.
 - Do not edit the Blueprint, Program, or `.genesis/` during implementation; the
-  separate reconciliation turn owns explanatory updates. Keep an exact Stack
-  `## Launch` declaration aligned when the implementation establishes or
-  intentionally changes how the project is started or how a preview host may request
-  an application preview identity. Record only capability metadata and
-  environment variable names there, never environment values or secrets.
+  separate reconciliation turn owns explanatory updates. Keep exact
+  consumer-owned operation declarations, such as Vibe64 `## Outputs`, aligned
+  when implementation intentionally changes the corresponding commands or
+  capabilities. Record only capability metadata and environment-variable names
+  there, never values or secrets; do not infer or execute the section as
+  Genesis behavior.
 - Follow established project and technology seams instead of creating parallel
   frameworks, persistence layers, transports, validators, or UI systems.
 - Never invent unavailable external-resource values or pass literal

package/src/index/contracts.js

@@ -1,6 +1,6 @@
 export const GENESIS_CONTRACTS = Object.freeze({
   derivedArtifacts: 'genesis.derived-artifacts.v1',
-  environment: 'genesis.environment.v1',
+  environment: 'genesis.environment.v2',
   stackSection: 'genesis.stack-section.v1',
   verification: 'genesis.verification.v1',
 });

package/src/index/stack-piece.js

@@ -7,6 +7,8 @@ import { parseStackVerificationLines } from './stack-verification.js';
 import { normalizeSource } from './utils.js';
 
 const STACK_PIECE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const RESOURCE_SEMANTIC_PATTERN = /^[a-z][A-Za-z0-9]*$/u;
+const ENVIRONMENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 const STACK_CUSTOMIZATION_TITLE = /^# Stack customization: ([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/u;
 const STACK_CUSTOMIZATION_FIELDS = new Map([
   ['Description', 'description'],
@@ -190,6 +192,14 @@ export function parseStackResourceLines(lines, {
     }
     if (
       !resource
+      || typeof resource !== 'object'
+      || Array.isArray(resource)
+      || Object.keys(resource).some((name) => ![
+        'environmentAlternatives',
+        'id',
+        'kind',
+        'optionalBindings',
+      ].includes(name))
       || typeof resource.id !== 'string'
       || !STACK_PIECE_ID_PATTERN.test(resource.id)
       || typeof resource.kind !== 'string'
@@ -199,26 +209,70 @@ export function parseStackResourceLines(lines, {
     ) {
       invalid(resourcePath, 'A Stack resource needs an id, kind, and at least one environment alternative.');
     }
+    const optionalBindings = normalizeResourceBindings(
+      resource.optionalBindings === undefined ? {} : resource.optionalBindings,
+      resourcePath,
+      resource.id,
+      { allowEmpty: true },
+    );
+    const optionalSemantics = new Set(Object.keys(optionalBindings));
     const environmentAlternatives = resource.environmentAlternatives.map((alternative) => {
-      const required = alternative?.required;
-      const allowEmpty = alternative?.allowEmpty || [];
+      if (!alternative || typeof alternative !== 'object' || Array.isArray(alternative)) {
+        invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      }
+      const unknown = Object.keys(alternative).filter((name) => (
+        !['allowEmpty', 'bindings', 'preferred'].includes(name)
+      ));
+      const allowEmpty = alternative.allowEmpty === undefined ? [] : alternative.allowEmpty;
       if (
-        !Array.isArray(required)
+        unknown.length > 0
         || !Array.isArray(allowEmpty)
+        || (alternative.preferred !== undefined && typeof alternative.preferred !== 'boolean')
       ) {
         invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
       }
-      const names = [...required, ...allowEmpty];
+      const bindings = normalizeResourceBindings(
+        alternative.bindings,
+        resourcePath,
+        resource.id,
+      );
+      const semantics = Object.keys(bindings);
       if (
-        required.length === 0
-        || names.some((name) => typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name))
-        || allowEmpty.some((name) => !required.includes(name))
-        || new Set(required).size !== required.length
+        allowEmpty.some((semantic) => !semantics.includes(semantic))
+        || allowEmpty.some((semantic) => typeof semantic !== 'string')
         || new Set(allowEmpty).size !== allowEmpty.length
-      ) invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
-      return { required: [...required], allowEmpty: [...allowEmpty] };
+        || semantics.some((semantic) => optionalSemantics.has(semantic))
+        || Object.values(bindings).some((name) => Object.values(optionalBindings).includes(name))
+      ) {
+        invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      }
+      return {
+        allowEmpty: [...allowEmpty].sort(),
+        bindings,
+        preferred: alternative.preferred === true,
+      };
     });
-    return { id: resource.id, kind: resource.kind, environmentAlternatives };
+    if (environmentAlternatives.filter(({ preferred }) => preferred).length !== 1) {
+      invalid(resourcePath, `Stack resource ${resource.id} needs exactly one preferred environment alternative.`);
+    }
+    const semanticByEnvironment = new Map(Object.entries(optionalBindings).map(([semantic, name]) => [
+      name,
+      semantic,
+    ]));
+    for (const alternative of environmentAlternatives) {
+      for (const [semantic, name] of Object.entries(alternative.bindings)) {
+        if (semanticByEnvironment.has(name) && semanticByEnvironment.get(name) !== semantic) {
+          invalid(resourcePath, `Stack resource ${resource.id} assigns conflicting meanings to ${name}.`);
+        }
+        semanticByEnvironment.set(name, semantic);
+      }
+    }
+    return {
+      id: resource.id,
+      kind: resource.kind,
+      environmentAlternatives,
+      optionalBindings,
+    };
   });
   if (new Set(parsed.map(({ id }) => id)).size !== parsed.length) {
     invalid(resourcePath, '## Resources contains a duplicate resource id.');
@@ -226,6 +280,29 @@ export function parseStackResourceLines(lines, {
   return parsed;
 }
 
+function normalizeResourceBindings(value, resourcePath, resourceId, {
+  allowEmpty = false,
+} = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    invalid(resourcePath, `Stack resource ${resourceId} has invalid semantic environment bindings.`);
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+  if (!allowEmpty && entries.length === 0) {
+    invalid(resourcePath, `Stack resource ${resourceId} has an empty environment alternative.`);
+  }
+  if (
+    entries.some(([semantic, name]) => (
+      !RESOURCE_SEMANTIC_PATTERN.test(semantic)
+      || typeof name !== 'string'
+      || !ENVIRONMENT_NAME_PATTERN.test(name)
+    ))
+    || new Set(entries.map(([, name]) => name)).size !== entries.length
+  ) {
+    invalid(resourcePath, `Stack resource ${resourceId} has invalid semantic environment bindings.`);
+  }
+  return Object.fromEntries(entries);
+}
+
 function resources(all, piecePath) {
   return parseStackResourceLines(all.has('Resources') ? all.get('Resources') : undefined, {
     path: piecePath,

package/src/index/stack-preflight.js

@@ -1,8 +1,8 @@
-function present(environment, name, allowEmpty) {
+function present(environment, name, allowEmpty = false) {
   if (!Object.hasOwn(environment, name) || typeof environment[name] !== 'string') return false;
   const value = environment[name].trim();
   if (value === `$${name}` || value === `\${${name}}`) return false;
-  return value.length > 0 || allowEmpty.includes(name);
+  return value.length > 0 || allowEmpty;
 }
 
 /** Core reports declarations; each Stack component defines their meaning. */
@@ -11,11 +11,15 @@ export function missingStackResources({ environment = process.env, resources = [
     throw new TypeError('Stack resource inspection requires an environment object and resource declarations.');
   }
   return resources.flatMap(({ component, resource }) => {
-    const satisfied = resource.environmentAlternatives.some(({ required, allowEmpty }) => (
-      required.every((name) => present(environment, name, allowEmpty))
+    const satisfied = resource.environmentAlternatives.some(({ bindings, allowEmpty }) => (
+      Object.entries(bindings).every(([semantic, name]) => (
+        present(environment, name, allowEmpty.includes(semantic))
+      ))
     ));
     if (satisfied) return [];
-    const alternatives = resource.environmentAlternatives.map(({ required }) => required.join(' + '));
+    const alternatives = resource.environmentAlternatives.map(({ bindings }) => (
+      Object.values(bindings).join(' + ')
+    ));
     return [{
       code: 'STACK_RESOURCE_MISSING',
       message: `Stack component ${component} requires ${resource.id}: ${alternatives.join(' OR ')}.`,