genesis-compiler 1.0.0 → 1.2.0

package/skills/genesis-program/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis Program"
+  short_description: "Explain product intent and public operations"
+  default_prompt: "Use $genesis-program to reconcile the Blueprint and subsystem Program with this codebase."

package/skills/genesis-project/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: genesis-project
+description: Work safely in a Genesis-enriched codebase using its Blueprint, Stack, subsystem Program, path-focused context, and concrete verification. Use for implementation or review in a repository containing genesis/blueprint.md.
+---
+
+# Genesis project work
+
+Genesis is an explanatory and verification companion. It does not replace the
+codebase, tests, Git review, or the coding agent.
+
+## Establish context
+
+1. Read `genesis/blueprint.md` for non-technical product intent.
+2. Read `genesis/stack.md` for the selected technical composition, resources,
+   and verification commands.
+3. Locate the source involved in the request.
+4. Run `genesis index <name-or-path>` before adding a helper or public operation.
+   Reuse an existing function when it already owns the behavior.
+5. Run `genesis context <path...>` for the relevant Program explanations and
+   selected Stack context.
+6. Load applicable technology skills from `.agents/skills/` or from the
+   agent's own installed skill catalog.
+
+Program is concise, fallible explanation. Its Sources and optional
+Implementation maps aid navigation but never substitute for reading code,
+tests, and runtime behavior.
+
+`.genesis/machine-city.json` is a derived detailed file/function map.
+`.genesis/program-city.json` is a derived simpler subsystem/operation map.
+Neither is authority or proof; both may be regenerated with `genesis index`.
+
+## Implement ordinary local work
+
+- 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 Vibe64 may request
+  an application preview identity. Record only capability metadata and
+  environment variable names there, never environment values or secrets.
+- 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
+  environment-variable names as data. Report the missing resource and preserve
+  useful work.
+- Keep the implementation direct and cohesive. Run focused checks when useful.
+
+## 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.

package/skills/genesis-project/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis Project"
+  short_description: "Work safely in a Genesis project"
+  default_prompt: "Use $genesis-project to make this change with the project Blueprint, Program, Stack, and verification context."

package/src/cli.js

@@ -0,0 +1,276 @@
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+
+import {
+  addStack,
+  adoptProject,
+  check,
+  generatePrompt,
+  getContext,
+  indexCodebase,
+  initialize,
+  installCodex,
+  listStackPieces,
+  verify,
+} from './index.js';
+import {
+  codexAdoptionRecommendation,
+  codexSessionContext,
+  completeCodexTurn,
+  discardCodexTurn,
+  recordCodexTurn,
+} from './index/codex-hooks.js';
+import { asDiagnostic, fail } from './index/errors.js';
+
+const USAGE = `Usage:
+  genesis init
+  genesis adopt [product guidance...]
+  genesis codex install
+  genesis stack list
+  genesis stack add <piece...>
+  genesis context <path...>
+  genesis index [function-or-path...]
+  genesis prompt [request...]
+  genesis prompt --task <start|work|deslop|program|blueprint|describe|review> [request...]
+  genesis verify
+  genesis check
+
+Options:
+  --project-root <path>  Set the project root (default: current directory)
+  --task <task>          Select the prompt task (default: work)
+  --json                 Emit one machine-readable result
+  -h, --help             Show this help
+
+Genesis generates prompts; it never starts or manages an AI agent. Give the
+prompt to the agent you already use. Review all edits through the ordinary Git
+diff, then run genesis verify for the Stack's concrete checks.
+`;
+
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prompt', 'stack', 'verify']);
+
+function parseCommand(argv) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
+    return { command: 'help', operands: [], options: {} };
+  }
+  const [command, ...rest] = argv;
+  if (!COMMANDS.has(command)) fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        json: { type: 'boolean', default: false },
+        'project-root': { type: 'string' },
+        task: { type: 'string' },
+      },
+    });
+  } catch (error) {
+    fail('CLI_ARGUMENT_INVALID', error.message);
+  }
+  const options = {
+    json: parsed.values.json,
+    projectRoot: parsed.values['project-root'],
+    task: parsed.values.task,
+  };
+  const operands = parsed.positionals;
+  if (options.task !== undefined && command !== 'prompt') {
+    fail('CLI_OPTION_NOT_APPLICABLE', `Option --task is not applicable to ${command}.`);
+  }
+  if (command === 'stack') {
+    if (!['list', 'add'].includes(operands[0])) {
+      fail('CLI_STACK_ACTION_REQUIRED', 'Command stack requires list or add.');
+    }
+    if (operands[0] === 'add' && operands.length < 2) {
+      fail('CLI_STACK_PIECE_REQUIRED', 'Command stack add requires at least one piece.');
+    }
+    if (operands[0] === 'list' && operands.length !== 1) {
+      fail('CLI_EXTRA_ARGUMENT', 'Command stack list accepts no extra arguments.');
+    }
+  } else if (command === 'codex') {
+    if (operands.length !== 1 || operands[0] !== 'install') {
+      fail('CLI_CODEX_ACTION_REQUIRED', 'Command codex requires exactly: install.');
+    }
+  } else if (command === 'context' && operands.length === 0) {
+    fail('CONTEXT_PATH_REQUIRED', 'Command context requires at least one project path.');
+  } else if (command === 'hook' && (operands.length !== 1 || !['begin', 'discover', 'end', 'session', 'stop'].includes(operands[0]))) {
+    fail('CLI_HOOK_ACTION_REQUIRED', 'Command hook requires exactly one of: discover, session, begin, stop, end.');
+  } else if (!['adopt', 'context', 'hook', 'index', 'prompt'].includes(command) && operands.length > 0) {
+    fail('CLI_EXTRA_ARGUMENT', `Command ${command} accepts no arguments.`);
+  }
+  return { command, operands, options };
+}
+
+function line(stream, value = '') {
+  stream.write(`${String(value).replace(/\n$/u, '')}\n`);
+}
+
+function namedItems(label, values) {
+  if (!Array.isArray(values) || values.length === 0) return;
+  line(process.stdout, `${label}:`);
+  for (const value of values) line(process.stdout, `  - ${value}`);
+}
+
+function writeCheck(result) {
+  line(process.stdout, `Blueprint: ${result.blueprint}`);
+  line(process.stdout, `Stack: ${result.stack}`);
+  line(process.stdout, `Agent Skills: ${result.skills}`);
+  line(process.stdout, `Program: ${result.program}`);
+  line(process.stdout, `Resource inputs: ${result.resources}`);
+  line(process.stdout, `Verification: ${result.verification}`);
+  namedItems('Program files', result.programFiles);
+  namedItems('Subsystems', result.subsystems);
+  for (const item of result.diagnostics) line(process.stdout, `${item.code}: ${item.message}`);
+  if (result.guidance) line(process.stdout, result.guidance);
+  line(process.stdout, `Check: ${result.status}`);
+}
+
+function writeResult(command, result) {
+  if (command === 'prompt') {
+    process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
+    return;
+  }
+  if (command === 'adopt') {
+    if (result.summary) line(process.stdout, result.summary);
+    namedItems('Changed files', result.changedFiles);
+    if (result.guidance) line(process.stdout, result.guidance);
+    line(process.stdout, '');
+    process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
+    return;
+  }
+  if (command === 'check') {
+    writeCheck(result);
+    return;
+  }
+  if (command === 'context') {
+    process.stdout.write(result.context.endsWith('\n') ? result.context : `${result.context}\n`);
+    return;
+  }
+  if (command === 'index') {
+    line(process.stdout, result.summary);
+    line(process.stdout, `Machine City: ${result.paths.machine}`);
+    line(process.stdout, `Program City: ${result.paths.program}`);
+    if (result.totalMatches > 0) {
+      line(process.stdout, 'Matching functions:');
+      for (const entry of result.matches) {
+        const signature = `${entry.qualifiedName}(${entry.parameters.join(', ')})`;
+        line(process.stdout, `  - ${entry.visibility} ${signature} — ${entry.path}:${entry.line}`);
+      }
+      if (result.totalMatches > result.matches.length) {
+        line(process.stdout, `  - ... and ${result.totalMatches - result.matches.length} more`);
+      }
+    }
+    for (const item of result.diagnostics || []) line(process.stdout, `${item.code}: ${item.message}`);
+    line(process.stdout, `index: ${result.status}`);
+    return;
+  }
+  if (command === 'hook') {
+    if (['discover', 'session'].includes(result.kind) && result.output) line(process.stdout, result.output);
+    else if (result.kind === 'stop') line(process.stdout, JSON.stringify(result.output));
+    return;
+  }
+  if (command === 'stack' && Array.isArray(result.pieces)) {
+    for (const piece of result.pieces) {
+      line(process.stdout, `${piece.id}: ${piece.description}`);
+      if (piece.requires.length > 0) line(process.stdout, `  requires: ${piece.requires.join(', ')}`);
+      if (piece.indexers.length > 0) line(process.stdout, `  indexers: ${piece.indexers.join(', ')}`);
+    }
+    return;
+  }
+  if (result.summary) line(process.stdout, result.summary);
+  namedItems('Changed files', result.changedFiles);
+  namedItems('Commands', result.commands?.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
+  for (const item of result.diagnostics || []) {
+    line(process.stdout, `${item.code}: ${item.message}`);
+    for (const field of ['stdout', 'stderr']) {
+      const output = item.details?.[field]?.trim();
+      if (output) line(process.stdout, output);
+    }
+  }
+  if (result.guidance) line(process.stdout, result.guidance);
+  line(process.stdout, `${command}: ${result.status}`);
+}
+
+async function hookInput() {
+  if (process.stdin.isTTY) fail('CODEX_HOOK_INPUT_INVALID', 'Codex hook input must be supplied on stdin.');
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 1024 * 1024) fail('CODEX_HOOK_INPUT_INVALID', 'Codex hook input exceeds 1 MiB.');
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch (error) {
+    fail('CODEX_HOOK_INPUT_INVALID', `Codex hook input is invalid JSON: ${error.message}.`);
+  }
+}
+
+async function execute({ command, operands, options }) {
+  const projectRoot = options.projectRoot || process.cwd();
+  if (command === 'init') return initialize({ projectRoot });
+  if (command === 'adopt') {
+    return adoptProject({ projectRoot, request: operands.join(' ') });
+  }
+  if (command === 'codex') return installCodex();
+  if (command === 'stack') {
+    if (operands[0] === 'list') return { status: 'ok', pieces: await listStackPieces() };
+    return addStack({ pieces: operands.slice(1), projectRoot });
+  }
+  if (command === 'prompt') {
+    return generatePrompt({
+      projectRoot,
+      task: options.task || 'work',
+      request: operands.join(' '),
+    });
+  }
+  if (command === 'context') return getContext({ paths: operands, projectRoot });
+  if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'hook') {
+    if (operands[0] === 'discover') {
+      return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
+    }
+    if (operands[0] === 'session') {
+      return { kind: 'session', ...await codexSessionContext({ projectRoot }) };
+    }
+    const input = await hookInput();
+    if (operands[0] === 'begin') {
+      return { kind: 'begin', ...await recordCodexTurn({ input, projectRoot }) };
+    }
+    if (operands[0] === 'end') {
+      return { kind: 'end', ...await discardCodexTurn({ input, projectRoot }) };
+    }
+    return { kind: 'stop', status: 'ready', output: await completeCodexTurn({ input, projectRoot }) };
+  }
+  if (command === 'verify') {
+    return verify({
+      projectRoot,
+      onEvent: (event) => {
+        if (!options.json) line(process.stderr, event.message);
+      },
+    });
+  }
+  if (command === 'check') return check({ projectRoot });
+  fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  let options = {};
+  try {
+    const parsed = parseCommand(argv);
+    if (parsed.command === 'help') {
+      process.stdout.write(USAGE);
+      return 0;
+    }
+    options = parsed.options;
+    const result = await execute(parsed);
+    if (options.json) line(process.stdout, JSON.stringify(result));
+    else writeResult(parsed.command, result);
+    return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;
+  } catch (error) {
+    const diagnostic = asDiagnostic(error);
+    if (options.json) line(process.stderr, JSON.stringify(diagnostic));
+    else line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
+    return 1;
+  }
+}