genesis-compiler 1.2.4 → 1.2.6

package/README.md

@@ -201,8 +201,9 @@ genesis inspect deployment --json
 ```
 
 Without `--json`, the commands print concise human-readable summaries. They
-never execute setup, start a process, probe a server, materialize environment
-files, or deploy.
+never start the application, probe a server, materialize environment files, or
+deploy. `genesis prepare` is the separate explicit command that executes only
+the finite Workspace setup recipe.
 
 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
@@ -428,6 +429,8 @@ genesis check
 - Blueprint and Stack validity;
 - selected Agent Skill presence and structural validity;
 - Program presence and structural validity;
+- Workspace setup, environment, Launch, and Deployment as `ready`, `blocked`,
+  or honestly `unconfigured`;
 - missing Stack-declared environment inputs (without claiming the service is
   reachable);
 - verification evidence as `current`, `stale`, `missing`, `invalid`, or
@@ -484,6 +487,12 @@ identity, secret, and browser policy.
 `inspectDeployment()` returns the separate normalized production recipe without
 executing or provisioning it.
 
+Normalized operational results identify their stable public contract in the
+`contract` field: `genesis.workspace-setup.v1`, `genesis.environment.v1`,
+`genesis.launch.v1`, `genesis.deployment.v1`, or
+`genesis.verification.v1`. Hosts validate that identity instead of
+feature-detecting individual fields.
+
 A host such as Vibe64 can send the generated prompt to its existing agent:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -58,7 +58,7 @@
     "@ast-grep/lang-ruby": "^0.0.7",
     "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.45.1",
-    "@jskit-ai/agent-docs": "0.1.132",
+    "@jskit-ai/agent-docs": "0.1.134",
     "yaml": "^2.9.0"
   }
 }

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

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

package/prompts/adopt.txt

@@ -50,6 +50,12 @@ or tool-specific manifests as evidence and carry every still-valid fact into
 Genesis; never add a permanent legacy reader or shim. Do not delete an old
 manifest until all of its live facts have been accounted for.
 
+The resulting project contract may therefore own complete `## Resources`,
+`## Environment defaults`, `## Environment files`, `## Workspace setup`,
+`## Commands`, `## Launch`, and `## Deployment` sections. Treat these as one
+operational inventory: do not preserve setup while silently dropping its
+resource, launch, readiness, identity, verification, or deployment counterpart.
+
 Create the non-technical Blueprint and useful subsystem-oriented Program from
 current source and tests. Do not cite archive internals or Git object storage as
 implementation source; Program sources must be current Git-visible files.

package/src/cli.js

@@ -131,6 +131,10 @@ function writeCheck(result) {
   line(process.stdout, `Stack: ${result.stack}`);
   line(process.stdout, `Agent Skills: ${result.skills}`);
   line(process.stdout, `Program: ${result.program}`);
+  line(process.stdout, `Workspace setup: ${result.workspaceSetup}`);
+  line(process.stdout, `Environment: ${result.environment}`);
+  line(process.stdout, `Launch: ${result.launch}`);
+  line(process.stdout, `Deployment: ${result.deployment}`);
   line(process.stdout, `Resource inputs: ${result.resources}`);
   line(process.stdout, `Verification: ${result.verification}`);
   namedItems('Program files', result.programFiles);
@@ -262,7 +266,7 @@ async function hookInput() {
   }
 }
 
-async function execute({ command, operands, options }) {
+async function execute({ command, operands, options }, { signal } = {}) {
   const projectRoot = options.projectRoot || process.cwd();
   if (command === 'init') return initialize({ projectRoot });
   if (command === 'adopt') {
@@ -294,6 +298,7 @@ async function execute({ command, operands, options }) {
   if (command === 'prepare') {
     return prepareWorkspace({
       projectRoot,
+      signal,
       onEvent: (event) => {
         if (!options.json) line(process.stderr, event.message);
       },
@@ -318,6 +323,7 @@ async function execute({ command, operands, options }) {
   if (command === 'verify') {
     return verify({
       projectRoot,
+      signal,
       onEvent: (event) => {
         if (!options.json) line(process.stderr, event.message);
       },
@@ -329,6 +335,8 @@ async function execute({ command, operands, options }) {
 
 export async function runCli(argv = process.argv.slice(2)) {
   let options = {};
+  const controller = new AbortController();
+  const abort = () => controller.abort();
   try {
     const parsed = parseCommand(argv);
     if (parsed.command === 'help') {
@@ -336,7 +344,12 @@ export async function runCli(argv = process.argv.slice(2)) {
       return 0;
     }
     options = parsed.options;
-    const result = await execute(parsed);
+    const finiteCommand = ['prepare', 'verify'].includes(parsed.command);
+    if (finiteCommand) {
+      process.once('SIGINT', abort);
+      process.once('SIGTERM', abort);
+    }
+    const result = await execute(parsed, { signal: controller.signal });
     if (options.json) line(process.stdout, JSON.stringify(result));
     else writeResult(parsed.command, result);
     return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;
@@ -345,5 +358,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (options.json) line(process.stderr, JSON.stringify(diagnostic));
     else line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
     return 1;
+  } finally {
+    process.removeListener('SIGINT', abort);
+    process.removeListener('SIGTERM', abort);
   }
 }

package/src/index/check.js

@@ -7,6 +7,10 @@ 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 { inspectProjectEnvironment } from './environment-files.js';
+import { inspectProjectLaunch } from './launch.js';
+import { inspectProjectDeployment } from './deployment.js';
+import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
 
 function invalidResult(area, error) {
   return {
@@ -15,6 +19,10 @@ function invalidResult(area, error) {
     stack: area === 'stack' ? 'invalid' : 'unknown',
     skills: area === 'skills' ? 'invalid' : 'unknown',
     program: 'unknown',
+    workspaceSetup: 'unknown',
+    environment: 'unknown',
+    launch: 'unknown',
+    deployment: 'unknown',
     resources: 'unknown',
     verification: 'unknown',
     programFiles: [],
@@ -61,10 +69,18 @@ export async function checkProject({ environment = process.env, projectRoot } =
     resources: stack.resources,
   });
   const verification = await inspectVerification({ projectRoot: root, stack });
+  const [workspaceSetup, projectEnvironment, launch, deployment] = await Promise.all([
+    inspectWorkspaceSetupForStack({ projectRoot: root, stack }),
+    inspectProjectEnvironment({ environment, projectRoot: root }),
+    inspectProjectLaunch({ environment, projectRoot: root }),
+    inspectProjectDeployment({ projectRoot: root }),
+  ]);
   const diagnostics = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...skills.diagnostics,
     ...missingResources,
+    ...workspaceSetup.diagnostics.filter(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING'),
+    ...deployment.diagnostics,
     ...(verification.status === 'invalid' ? [{
       code: 'VERIFICATION_EVIDENCE_INVALID',
       message: 'Saved verification evidence is malformed.',
@@ -79,6 +95,8 @@ export async function checkProject({ environment = process.env, projectRoot } =
   if (missingResources.length > 0) {
     guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
   }
+  if (workspaceSetup.status === 'blocked') guidance.push('Repair the project Workspace setup declaration.');
+  if (deployment.status === 'blocked') guidance.push('Repair the project Deployment declaration.');
   if (['missing', 'stale'].includes(verification.status)) guidance.push('Run genesis verify to refresh concrete evidence.');
   if (verification.status === 'unconfigured') guidance.push('Add project verification commands to genesis/stack.md.');
   guidance.push('Use genesis prompt --task review for a semantic, evidence-based comparison.');
@@ -86,6 +104,8 @@ export async function checkProject({ environment = process.env, projectRoot } =
   const needsAttention = program.status === 'missing'
     || skills.status === 'missing'
     || missingResources.length > 0
+    || workspaceSetup.status === 'blocked'
+    || deployment.status === 'blocked'
     || ['missing', 'stale', 'unconfigured'].includes(verification.status);
 
   return {
@@ -96,6 +116,10 @@ export async function checkProject({ environment = process.env, projectRoot } =
     stack: 'valid',
     skills: skills.status,
     program: program.status,
+    workspaceSetup: workspaceSetup.status,
+    environment: projectEnvironment.status,
+    launch: launch.status,
+    deployment: deployment.status,
     resources: missingResources.length > 0 ? 'missing' : 'inputs-present',
     verification: verification.status,
     programFiles: program.files,

package/src/index/contracts.js

@@ -0,0 +1,7 @@
+export const GENESIS_CONTRACTS = Object.freeze({
+  deployment: 'genesis.deployment.v1',
+  environment: 'genesis.environment.v1',
+  launch: 'genesis.launch.v1',
+  verification: 'genesis.verification.v1',
+  workspaceSetup: 'genesis.workspace-setup.v1',
+});

package/src/index/deployment.js

@@ -1,6 +1,7 @@
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Read the Stack's production recipe without provisioning or publishing anything. */
 export async function inspectProjectDeployment({ projectRoot } = {}) {
@@ -18,6 +19,7 @@ export async function inspectProjectDeployment({ projectRoot } = {}) {
     steps: stack.deployment.steps,
   };
   return {
+    contract: GENESIS_CONTRACTS.deployment,
     status,
     stackHash: stack.identityHash,
     recipeHash: status === 'ready' ? sha256(stableJson(recipe)) : '',

package/src/index/environment-files.js

@@ -2,6 +2,7 @@ import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Inspect Stack environment requirements without returning supplied host values. */
 export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
@@ -15,6 +16,7 @@ export async function inspectProjectEnvironment({ environment = process.env, pro
     || stack.environmentFiles.length > 0
     || stack.resources.length > 0;
   return {
+    contract: GENESIS_CONTRACTS.environment,
     status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),

package/src/index/launch.js

@@ -3,6 +3,7 @@ import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { readStack } from './stack.js';
 import { uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Read the Stack's launch declaration without choosing or starting a runtime. */
 export async function inspectProjectLaunch({
@@ -27,6 +28,7 @@ export async function inspectProjectLaunch({
   if (targets.length === 0) status = 'unconfigured';
   else if (diagnostics.length > 0) status = 'blocked';
   return {
+    contract: GENESIS_CONTRACTS.launch,
     status,
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),

package/src/index/process.js

@@ -1,18 +1,120 @@
-import { execFile } from 'node:child_process';
+import { spawn } from 'node:child_process';
 
 import { GenesisError } from './errors.js';
 
 const MAX_DIAGNOSTIC_OUTPUT = 16_384;
+const DEFAULT_TERMINATION_GRACE_MS = 1_000;
 
-function executeFile(command, args, options) {
+function processTerminationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function signalProcessTree(child, signal) {
+  if (!Number.isSafeInteger(child?.pid) || child.pid < 1) return;
+  try {
+    if (process.platform === 'win32') child.kill(signal);
+    else process.kill(-child.pid, signal);
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
+
+function executeFile(command, args, {
+  maxBuffer,
+  signal,
+  terminationGraceMs = DEFAULT_TERMINATION_GRACE_MS,
+  timeoutMs,
+  ...options
+}) {
   return new Promise((resolve, reject) => {
-    const child = execFile(command, args, options, (error, stdout, stderr) => {
-      if (error) {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let forcedError = null;
+    let killTimer = null;
+    let spawnError = null;
+    let timeoutTimer = null;
+    let settled = false;
+    const cleanup = () => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      signal?.removeEventListener('abort', abort);
+    };
+    const child = spawn(command, args, {
+      ...options,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const terminate = (error) => {
+      if (settled || forcedError) return;
+      forcedError = error;
+      signalProcessTree(child, 'SIGTERM');
+      killTimer = setTimeout(() => {
+        if (!settled) signalProcessTree(child, 'SIGKILL');
+      }, terminationGraceMs);
+      killTimer.unref?.();
+    };
+    const collect = (chunks, chunk, stream) => {
+      chunks.push(chunk);
+      if (stream === 'stdout') stdoutBytes += chunk.length;
+      else stderrBytes += chunk.length;
+      if (Number.isFinite(maxBuffer) && Math.max(stdoutBytes, stderrBytes) > maxBuffer) {
+        terminate(processTerminationError(
+          'GENESIS_PROCESS_OUTPUT_LIMIT',
+          `${command} exceeded its diagnostic output limit.`,
+        ));
+      }
+    };
+    child.stdout.on('data', (chunk) => collect(stdoutChunks, chunk, 'stdout'));
+    child.stderr.on('data', (chunk) => collect(stderrChunks, chunk, 'stderr'));
+    child.once('error', (error) => {
+      spawnError = error;
+    });
+    child.once('close', (status, processSignal) => {
+      settled = true;
+      cleanup();
+      const stdout = Buffer.concat(stdoutChunks);
+      const stderr = Buffer.concat(stderrChunks);
+      if (forcedError) {
+        forcedError.stdout = stdout;
+        forcedError.stderr = stderr;
+        forcedError.signal = processSignal || null;
+        reject(forcedError);
+        return;
+      }
+      if (spawnError) {
+        spawnError.stdout = stdout;
+        spawnError.stderr = stderr;
+        spawnError.signal = processSignal || null;
+        reject(spawnError);
+        return;
+      }
+      if (status !== 0) {
+        const error = new Error(`${command} exited with status ${status ?? 'unknown'}.`);
+        error.code = status;
+        error.signal = processSignal || null;
+        error.stdout = stdout;
+        error.stderr = stderr;
         reject(error);
         return;
       }
       resolve({ stdout, stderr });
     });
+    const abort = () => terminate(processTerminationError(
+      'GENESIS_PROCESS_ABORTED',
+      `${command} was cancelled.`,
+    ));
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timeoutTimer = setTimeout(() => terminate(processTerminationError(
+        'GENESIS_PROCESS_TIMEOUT',
+        `${command} timed out after ${timeoutMs} ms.`,
+      )), timeoutMs);
+      timeoutTimer.unref?.();
+    }
     child.stdin?.end();
   });
 }
@@ -39,21 +141,33 @@ export async function runProcess(command, args, {
   env = process.env,
   maxBytes = 32 * 1024 * 1024,
   code = 'PROCESS_EXEC_FAILED',
+  signal,
+  terminationGraceMs,
+  timeoutMs,
 } = {}) {
   try {
     const { stdout, stderr } = await executeFile(command, args, {
       cwd,
+      detached: process.platform !== 'win32',
       env,
       encoding: 'buffer',
       maxBuffer: maxBytes,
       shell: false,
+      signal,
+      terminationGraceMs,
+      timeoutMs,
       windowsHide: true,
     });
     return { status: 0, signal: null, stdout, stderr };
   } catch (error) {
     const stdout = Buffer.isBuffer(error.stdout) ? error.stdout : Buffer.from(error.stdout || '');
     const stderr = Buffer.isBuffer(error.stderr) ? error.stderr : Buffer.from(error.stderr || '');
-    throw new GenesisError(code, `${command} failed: ${error.message}`, {
+    const diagnosticCode = error.code === 'GENESIS_PROCESS_ABORTED'
+      ? 'PROCESS_ABORTED'
+      : error.code === 'GENESIS_PROCESS_TIMEOUT'
+        ? 'PROCESS_TIMEOUT'
+        : code;
+    throw new GenesisError(diagnosticCode, `${command} failed: ${error.message}`, {
       command,
       args,
       status: typeof error.code === 'number' ? error.code : null,

package/src/index/verification.js

@@ -6,6 +6,9 @@ import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 import { readStack } from './stack.js';
 import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+
+const DEFAULT_FINITE_COMMAND_TIMEOUT_MS = 30 * 60 * 1_000;
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control verification. */ }
@@ -16,12 +19,15 @@ export async function verifyProject({
   onEvent,
   processRunner = runProcess,
   projectRoot,
+  signal,
+  timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
   const workspaceSetup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
   if (workspaceSetup.status === 'blocked') {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'blocked',
       summary: workspaceSetup.diagnostics.map(({ message }) => message).join(' '),
       commands: [],
@@ -33,6 +39,7 @@ export async function verifyProject({
   );
   if (waiting.length > 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'unconfigured',
       summary: waiting.map(({ message }) => message).join(' '),
       commands: [],
@@ -49,6 +56,7 @@ export async function verifyProject({
   });
   if (missing.length > 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'blocked',
       summary: missing.map(({ message }) => message).join(' '),
       commands: [],
@@ -57,6 +65,7 @@ export async function verifyProject({
   }
   if (stack.commands.length === 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'unconfigured',
       summary: 'The selected Stack declares no verification commands.',
       commands: [],
@@ -79,6 +88,8 @@ export async function verifyProject({
         env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'VERIFICATION_FAILED',
+        signal,
+        timeoutMs,
       });
       await emit(onEvent, {
         type: 'genesis.verification',
@@ -90,6 +101,7 @@ export async function verifyProject({
     }
     const evidence = await writeVerification({ projectRoot: root, stack });
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'passed',
       summary: `Passed ${commands.length} declared verification command${commands.length === 1 ? '' : 's'}.`,
       commands,
@@ -98,6 +110,7 @@ export async function verifyProject({
     };
   } catch (error) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'failed',
       summary: error.message,
       commands: [],

package/src/index/workspace-setup.js

@@ -7,6 +7,9 @@ import { runProcess } from './process.js';
 import { readStack } from './stack.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+
+const DEFAULT_FINITE_COMMAND_TIMEOUT_MS = 30 * 60 * 1_000;
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control preparation. */ }
@@ -54,6 +57,7 @@ export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }
     ? sha256(stableJson({ version: 1, steps: applicableSteps }))
     : '';
   return {
+    contract: GENESIS_CONTRACTS.workspaceSetup,
     status,
     stackHash: stack.identityHash,
     recipeHash,
@@ -82,6 +86,8 @@ export async function prepareProjectWorkspace({
   onEvent,
   processRunner = runProcess,
   projectRoot,
+  signal,
+  timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
@@ -114,6 +120,8 @@ export async function prepareProjectWorkspace({
         env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'WORKSPACE_PREPARATION_FAILED',
+        signal,
+        timeoutMs,
       });
       commands.push({
         label: step.label,

package/src/index.js

@@ -17,6 +17,8 @@ import {
   prepareProjectWorkspace,
 } from './index/workspace-setup.js';
 
+export { GENESIS_CONTRACTS } from './index/contracts.js';
+
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
   const refreshedOnly = result.status === 'unchanged' && index.changedFiles.length > 0;