genesis-compiler 1.0.0 → 1.2.0

package/src/index/codex-hooks.js

@@ -0,0 +1,367 @@
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { readInstalledAsset } from './assets.js';
+import { buildProjectIndex } from './code-index.js';
+import { GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { isProjectContentPath } from './paths.js';
+import { runGit, runGitText } from './process.js';
+import { readStack } from './stack.js';
+import { normalizeRelative, pathState, sha256, stableJson, writeFileAtomic } from './utils.js';
+
+const HOOKS_PATH = '.codex/hooks.json';
+const HOOK_STATE_SCHEMA_VERSION = 2;
+function hookCommand(action) {
+  const local = `const {runCli}=await import('genesis-compiler/cli');process.exitCode=await runCli(['hook','${action}'])`;
+  return `if command -v genesis >/dev/null 2>&1; then genesis hook ${action}; else node --input-type=module --eval "${local}"; fi`;
+}
+
+const HOOK_SPECS = [
+  {
+    event: 'SessionStart',
+    command: hookCommand('session'),
+    group: {
+      matcher: '^(startup|resume|clear|compact)$',
+      hooks: [{
+        type: 'command',
+        command: hookCommand('session'),
+        commandWindows: 'genesis hook session',
+        timeout: 5,
+        statusMessage: 'Loading Genesis guidance',
+        additionalContextLimit: 4000,
+      }],
+    },
+  },
+  {
+    event: 'UserPromptSubmit',
+    command: hookCommand('begin'),
+    group: {
+      hooks: [{
+        type: 'command',
+        command: hookCommand('begin'),
+        commandWindows: 'genesis hook begin',
+        timeout: 10,
+      }],
+    },
+  },
+  {
+    event: 'Stop',
+    command: hookCommand('stop'),
+    group: {
+      hooks: [{
+        type: 'command',
+        command: hookCommand('stop'),
+        commandWindows: 'genesis hook stop',
+        timeout: 30,
+        statusMessage: 'Checking whether Genesis follow-up work is needed',
+      }],
+    },
+  },
+  {
+    event: 'SessionEnd',
+    command: hookCommand('end'),
+    group: {
+      hooks: [{
+        type: 'command',
+        command: hookCommand('end'),
+        commandWindows: 'genesis hook end',
+        timeout: 3,
+      }],
+    },
+  },
+];
+
+function genesisHookInstalled(groups, command) {
+  return groups.some((group) => group?.hooks?.some((hook) => hook?.command === command));
+}
+
+async function installedHooksSource(location) {
+  try {
+    const source = await readFile(location, 'utf8');
+    const value = JSON.parse(source);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('expected an object');
+    if (value.hooks !== undefined && (!value.hooks || typeof value.hooks !== 'object' || Array.isArray(value.hooks))) {
+      throw new Error('hooks must be an object');
+    }
+    return { source, value };
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      return { source: null, value: { description: 'Genesis project hooks.', hooks: {} } };
+    }
+    throw new GenesisError('CODEX_HOOKS_INVALID', `${HOOKS_PATH} is not valid hook configuration: ${error.message}.`);
+  }
+}
+
+export async function installCodexHooks({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const location = path.join(root, HOOKS_PATH);
+  const { source, value } = await installedHooksSource(location);
+  value.hooks ||= {};
+  for (const spec of HOOK_SPECS) {
+    const groups = value.hooks[spec.event] ||= [];
+    if (!Array.isArray(groups)) {
+      throw new GenesisError('CODEX_HOOKS_INVALID', `${HOOKS_PATH} hooks.${spec.event} must be an array.`);
+    }
+    if (!genesisHookInstalled(groups, spec.command)) groups.push(spec.group);
+  }
+  const rendered = `${JSON.stringify(value, null, 2)}\n`;
+  if (source === rendered) return { status: 'unchanged', changedFiles: [] };
+  await writeFileAtomic(location, rendered);
+  return { status: 'updated', changedFiles: [HOOKS_PATH] };
+}
+
+async function optionalStack(projectRoot) {
+  try { return await readStack(projectRoot); } catch { return null; }
+}
+
+export async function codexSessionContext({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await optionalStack(root);
+  const selected = stack?.components.map(({ id }) => id) || [];
+  const stackStatus = stack
+    ? (selected.length > 0 ? selected.join(', ') : 'none')
+    : 'unavailable; run `genesis check`';
+  return {
+    status: 'ready',
+    output: [
+      'This is a Genesis-enriched project.',
+      '- `genesis/blueprint.md` describes non-technical product intent.',
+      '- `genesis/stack.md` selects optional technology guidance and verification.',
+      '- `genesis/program/<subsystem>/` explains public operations and useful internal seams.',
+      '- Project Agent Skills live in `.agents/skills/`; load applicable skills progressively.',
+      '- After locating relevant source files, run `genesis context <path...>` to load their Program and selected Stack material.',
+      '- Before creating a helper or public operation, run `genesis index <name-or-path>` and reuse an existing function when it already owns the behavior.',
+      '- `.genesis/machine-city.json` is the detailed code/function map; `.genesis/program-city.json` is the simpler subsystem/operation map.',
+      '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
+      '- Keep implementation focused; the Stop hook owns later Blueprint/Program reconciliation and Deslop turns.',
+      '- After a code-changing turn, Genesis may request separate explanation and behavior-preserving cleanup turns.',
+      `Selected Stack components: ${stackStatus}.`,
+    ].join('\n'),
+  };
+}
+
+export async function codexAdoptionRecommendation({ projectRoot = process.cwd() } = {}) {
+  let root;
+  try { root = (await gitContext(projectRoot)).repositoryRoot; } catch { return { status: 'not-applicable', output: '' }; }
+  if ((await pathState(path.join(root, 'genesis/blueprint.md'))).exists) {
+    return { status: 'not-applicable', output: '' };
+  }
+  const files = zeroPaths((await runGit(root, [
+    'ls-files', '-z', '--cached', '--others', '--exclude-standard',
+  ])).stdout).filter(isProjectContentPath);
+  if (files.length === 0) return { status: 'not-applicable', output: '' };
+  return {
+    status: 'ready',
+    output: [
+      'IMPORTANT GENESIS RECOMMENDATION:',
+      'This existing project has no Genesis explanatory layer.',
+      'In your first response, strongly recommend that the user run `genesis adopt` before substantial work.',
+      '`genesis adopt` preserves the implementation and returns the prompt for creating its initial Blueprint and Program.',
+      'Do not run it without the user\'s approval. If they agree, run it and follow the returned prompt in this conversation.',
+      'If the user declines, continue normally and do not repeat the recommendation in this session.',
+    ].join('\n'),
+  };
+}
+
+function hookId(input, field) {
+  const value = input?.[field];
+  if (typeof value !== 'string' || !value || value.length > 512) {
+    throw new GenesisError('CODEX_HOOK_INPUT_INVALID', `Codex hook input requires ${field}.`);
+  }
+  return value;
+}
+
+function zeroPaths(buffer) {
+  return buffer.toString('utf8').split('\0').filter(Boolean).map(normalizeRelative);
+}
+
+async function repositorySnapshot(projectRoot) {
+  const head = await runGitText(projectRoot, ['rev-parse', '--verify', 'HEAD']).catch(() => null);
+  const results = await Promise.all([
+    runGit(projectRoot, ['diff', '--no-ext-diff', '--no-renames', '--name-only', '-z']),
+    runGit(projectRoot, ['diff', '--cached', '--no-ext-diff', '--no-renames', '--name-only', '-z']),
+    runGit(projectRoot, ['ls-files', '-z', '--others', '--exclude-standard']),
+    runGit(projectRoot, ['ls-files', '-z', '--deleted']),
+  ]);
+  const dirty = [...new Set(results.flatMap(({ stdout }) => zeroPaths(stdout)))]
+    .filter(isProjectContentPath)
+    .sort();
+  return {
+    head,
+    dirty: await Promise.all(dirty.map(async (file) => ({
+      path: file,
+      state: await pathState(path.join(projectRoot, file)),
+    }))),
+  };
+}
+
+async function hookStatePath(projectRoot, input) {
+  const key = sha256(hookId(input, 'session_id')).slice('sha256:'.length);
+  const gitPath = await runGitText(projectRoot, ['rev-parse', '--git-path', `genesis/hooks/${key}.json`]);
+  return path.resolve(projectRoot, gitPath);
+}
+
+function writeTurnState(statePath, state) {
+  return writeFileAtomic(statePath, stableJson(state), { mode: 0o600 });
+}
+
+async function refreshProjectIndex(projectRoot) {
+  await buildProjectIndex({ projectRoot }).catch(() => null);
+}
+
+export async function recordCodexTurn({ input, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot || input?.cwd)).repositoryRoot;
+  const statePath = await hookStatePath(root, input);
+  const state = {
+    schemaVersion: HOOK_STATE_SCHEMA_VERSION,
+    turnId: hookId(input, 'turn_id'),
+    phase: 'implementation',
+    snapshot: await repositorySnapshot(root),
+  };
+  await writeTurnState(statePath, state);
+  return { status: 'recorded' };
+}
+
+async function readTurnState(statePath) {
+  try { return JSON.parse(await readFile(statePath, 'utf8')); } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return null;
+    throw error;
+  }
+}
+
+async function committedPaths(projectRoot, before, after) {
+  if (before === after) return [];
+  if (!after) return ['repository history changed'];
+  try {
+    const args = before
+      ? ['diff', '--no-renames', '--name-only', '-z', before, after]
+      : ['diff-tree', '--root', '--no-commit-id', '--no-renames', '--name-only', '-r', '-z', after];
+    return zeroPaths((await runGit(projectRoot, args)).stdout).filter(isProjectContentPath);
+  } catch {
+    return ['repository history changed'];
+  }
+}
+
+async function changedProjectPaths(projectRoot, before, after) {
+  const previous = new Map(before.dirty.map(({ path: file, state }) => [file, state]));
+  const current = new Map(after.dirty.map(({ path: file, state }) => [file, state]));
+  const dirtyChanges = [...new Set([...previous.keys(), ...current.keys()])].filter((file) => (
+    stableJson(previous.get(file)) !== stableJson(current.get(file))
+  ));
+  return [...new Set([
+    ...dirtyChanges,
+    ...await committedPaths(projectRoot, before.head, after.head),
+  ])].sort();
+}
+
+function changedPathLines(changedPaths) {
+  const shown = changedPaths.slice(0, 50);
+  const omitted = changedPaths.length - shown.length;
+  return [
+    ...shown.map((file) => `- ${file}`),
+    ...(omitted > 0 ? [`- ... and ${omitted} more`] : []),
+  ];
+}
+
+async function reconciliationContinuation(projectRoot, changedPaths) {
+  const [instructions, stack] = await Promise.all([
+    readInstalledAsset('reconcile'),
+    optionalStack(projectRoot),
+  ]);
+  return [
+    'This is the automatic Genesis explanation turn for the preceding implementation turn.',
+    'Use the same conversation context and the Git-visible changes below. Do not perform Deslop yet.',
+    '',
+    'CHANGED PROJECT PATHS',
+    '',
+    ...changedPathLines(changedPaths),
+    '',
+    instructions.trim(),
+    ...(stack?.guidance ? ['', 'SELECTED STACK GUIDANCE', '', stack.guidance] : []),
+  ].join('\n');
+}
+
+async function deslopContinuation(projectRoot, changedPaths) {
+  const [instructions, stack] = await Promise.all([
+    readInstalledAsset('deslop'),
+    optionalStack(projectRoot),
+  ]);
+  return [
+    'This is the final automatic Genesis Deslop turn for the preceding implementation.',
+    'Review only that work and the paths listed below. Do not broaden the task.',
+    '',
+    'CHANGED PROJECT PATHS',
+    '',
+    ...changedPathLines(changedPaths),
+    '',
+    instructions.trim(),
+    ...(stack?.guidance ? ['', 'SELECTED STACK GUIDANCE', '', stack.guidance] : []),
+    ...(stack?.deslop ? ['', 'SELECTED STACK CLEANUP GUIDANCE', '', stack.deslop] : []),
+    '',
+    'PROGRAM CITATION MAINTENANCE',
+    '',
+    'If this cleanup renames or moves a source or helper cited by an affected Program module,',
+    'update only that module\'s Sources or informational Implementation map. This narrow',
+    'exception overrides the default prohibition on editing `genesis/`; never change the',
+    'Blueprint or a Program public contract to excuse cleanup behavior.',
+  ].join('\n');
+}
+
+export async function completeCodexTurn({ input, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot || input?.cwd)).repositoryRoot;
+  const statePath = await hookStatePath(root, input);
+  const state = await readTurnState(statePath);
+  if (!state || state.schemaVersion !== HOOK_STATE_SCHEMA_VERSION) return {};
+
+  if (state.phase === 'implementation') {
+    if (input?.stop_hook_active === true || state.turnId !== hookId(input, 'turn_id')) {
+      await rm(statePath, { force: true });
+      return {};
+    }
+    const changedPaths = await changedProjectPaths(root, state.snapshot, await repositorySnapshot(root));
+    if (changedPaths.length === 0) {
+      await rm(statePath, { force: true });
+      return {};
+    }
+    await writeTurnState(statePath, {
+      ...state,
+      phase: 'reconcile',
+      changedPaths,
+    });
+    return {
+      decision: 'block',
+      reason: await reconciliationContinuation(root, changedPaths),
+    };
+  }
+
+  if (input?.stop_hook_active !== true) {
+    await rm(statePath, { force: true });
+    return {};
+  }
+
+  if (state.phase === 'reconcile') {
+    const currentPaths = await changedProjectPaths(root, state.snapshot, await repositorySnapshot(root));
+    const changedPaths = [...new Set([...state.changedPaths, ...currentPaths])].sort();
+    await refreshProjectIndex(root);
+    await writeTurnState(statePath, {
+      ...state,
+      phase: 'deslop',
+      changedPaths,
+    });
+    return {
+      decision: 'block',
+      reason: await deslopContinuation(root, changedPaths),
+    };
+  }
+
+  await refreshProjectIndex(root);
+  await rm(statePath, { force: true });
+  return {};
+}
+
+export async function discardCodexTurn({ input, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot || input?.cwd)).repositoryRoot;
+  await rm(await hookStatePath(root, input), { force: true });
+  return { status: 'discarded' };
+}

package/src/index/codex-plugin.js

@@ -0,0 +1,73 @@
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { fail } from './errors.js';
+import { runProcess } from './process.js';
+
+const MARKETPLACE_NAME = 'genesis';
+const PLUGIN_ID = 'genesis@genesis';
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+
+function parseCodexJson(result, operation) {
+  try {
+    return JSON.parse(result.stdout.toString('utf8'));
+  } catch (error) {
+    fail('CODEX_PLUGIN_INSTALL_FAILED', `Codex returned invalid JSON while ${operation}: ${error.message}.`);
+  }
+}
+
+async function canonicalPath(value) {
+  try { return await realpath(value); } catch { return path.resolve(value); }
+}
+
+export async function installCodexPlugin({ environment = process.env } = {}) {
+  const desiredRoot = await canonicalPath(packageRoot);
+  const marketplaceResult = await runProcess('codex', ['plugin', 'marketplace', 'list', '--json'], {
+    env: environment,
+    code: 'CODEX_PLUGIN_INSTALL_FAILED',
+  });
+  const marketplaces = parseCodexJson(marketplaceResult, 'listing plugin marketplaces').marketplaces || [];
+  const existingMarketplace = marketplaces.find(({ name }) => name === MARKETPLACE_NAME);
+  if (existingMarketplace) {
+    const existingRoot = await canonicalPath(existingMarketplace.root);
+    if (existingRoot !== desiredRoot) {
+      fail(
+        'CODEX_PLUGIN_MARKETPLACE_CONFLICT',
+        `Codex marketplace ${MARKETPLACE_NAME} already points to ${existingRoot}, not ${desiredRoot}.`,
+      );
+    }
+  } else {
+    await runProcess('codex', ['plugin', 'marketplace', 'add', desiredRoot, '--json'], {
+      env: environment,
+      code: 'CODEX_PLUGIN_INSTALL_FAILED',
+    });
+  }
+
+  const [pluginListResult, manifestSource] = await Promise.all([
+    runProcess('codex', ['plugin', 'list', '--json'], {
+      env: environment,
+      code: 'CODEX_PLUGIN_INSTALL_FAILED',
+    }),
+    readFile(path.join(desiredRoot, 'plugins/genesis/.codex-plugin/plugin.json'), 'utf8'),
+  ]);
+  const installed = (parseCodexJson(pluginListResult, 'listing installed plugins').installed || [])
+    .find(({ pluginId }) => pluginId === PLUGIN_ID);
+  const version = JSON.parse(manifestSource).version;
+  if (!installed || installed.version !== version || installed.enabled !== true) {
+    await runProcess('codex', ['plugin', 'add', PLUGIN_ID, '--json'], {
+      env: environment,
+      code: 'CODEX_PLUGIN_INSTALL_FAILED',
+    });
+  }
+
+  const changed = !existingMarketplace || !installed || installed.version !== version || installed.enabled !== true;
+  return {
+    status: changed ? 'updated' : 'unchanged',
+    summary: changed
+      ? 'Installed the Genesis discovery hook for Codex.'
+      : 'The Genesis discovery hook is already installed for Codex.',
+    changedFiles: [],
+    guidance: 'Start a new Codex session to use it. Existing projects without Genesis will receive the adoption recommendation before the first user prompt.',
+  };
+}

package/src/index/context.js

@@ -0,0 +1,137 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
+import { buildProjectIndex } from './code-index.js';
+import { asDiagnostic, GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { inspectProgram } from './program.js';
+import { readStack } from './stack.js';
+import { normalizeRelative } from './utils.js';
+
+function projectPath(projectRoot, workingDirectory, value) {
+  const absolute = path.resolve(workingDirectory, String(value));
+  return normalizeRelative(path.relative(projectRoot, absolute));
+}
+
+function citesTarget(module, target) {
+  return module.sources.some((source) => (
+    !target || source === target || source.startsWith(`${target}/`)
+  ));
+}
+
+function stackSummary(stack) {
+  if (stack.components.length === 0) return ['## Selected Stack', '', 'No Stack components are selected.'];
+  return [
+    '## Selected Stack',
+    '',
+    ...stack.components.map(({ id, description }) => `- \`${id}\` — ${description}`),
+  ];
+}
+
+function stackGuidance(stack) {
+  const pieces = stack.components.filter(({ guidance }) => guidance);
+  if (pieces.length === 0) return [];
+  return [
+    '',
+    '## Selected Stack guidance',
+    '',
+    ...pieces.flatMap(({ id, guidance }) => [
+      `### ${id}`,
+      '',
+      guidance,
+      '',
+    ]),
+  ];
+}
+
+function pathMatchesTarget(filePath, target) {
+  return !target || filePath === target || filePath.startsWith(`${target}/`);
+}
+
+export async function contextForProjectPaths({ paths, projectRoot } = {}) {
+  if (!Array.isArray(paths) || paths.length === 0) {
+    throw new GenesisError('CONTEXT_PATH_REQUIRED', 'Genesis context requires at least one project path.');
+  }
+  const location = await gitContext(projectRoot);
+  const root = location.repositoryRoot;
+  const targets = [...new Set(paths.map((value) => projectPath(root, location.workingDirectory, value)))];
+  const [program, stack] = await Promise.all([
+    inspectProgram(root).catch((error) => ({
+      status: 'invalid',
+      modules: [],
+      diagnostic: asDiagnostic(error),
+    })),
+    readStack(root),
+  ]);
+  const modules = program.modules.filter((module) => targets.some((target) => citesTarget(module, target)));
+  const moduleSources = await Promise.all(modules.map(async (module) => ({
+    ...module,
+    source: await readFile(path.join(root, module.path), 'utf8'),
+  })));
+  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
+  const index = await buildProjectIndex({ projectRoot: root, write: false });
+  const functions = index.machine.functions.filter((entry) => (
+    targets.some((target) => pathMatchesTarget(entry.path, target))
+  ));
+  const skills = renderAgentSkillCatalog(projectSkills.skills);
+  let programDetails;
+  if (program.diagnostic) {
+    programDetails = [`Program could not be used: ${program.diagnostic.code}: ${program.diagnostic.message}`];
+  } else if (moduleSources.length === 0) {
+    programDetails = ['No Program module cites these paths. Inspect the code normally; do not invent a subsystem mapping.'];
+  } else {
+    programDetails = moduleSources.flatMap((module) => [
+      `### ${module.path}`,
+      '',
+      module.source.trim(),
+      '',
+    ]);
+  }
+  const output = [
+    '# Genesis context',
+    '',
+    `Requested paths: ${targets.map((target) => `\`${target || '.'}\``).join(', ')}`,
+    '',
+    'Use Program as a concise, fallible explanation. Code, tests, and runtime behavior remain the evidence.',
+    '',
+    '## Relevant Program',
+    '',
+    ...programDetails,
+    ...stackSummary(stack),
+    ...stackGuidance(stack),
+    '',
+    '## Existing functions',
+    '',
+    ...(functions.length === 0
+      ? ['No indexed function is declared in these paths.']
+      : functions.slice(0, 100).map((entry) => (
+        `- ${entry.visibility} \`${entry.qualifiedName}(${entry.parameters.join(', ')})\` — \`${entry.path}:${entry.line}\``
+      ))),
+    ...(functions.length > 100 ? [`- ... and ${functions.length - 100} more; run \`genesis index ${targets.join(' ')}\`.`] : []),
+    '',
+    'Search the Machine City before adding a helper or public operation; reuse an existing function when it already owns the behavior.',
+    ...(skills ? ['', '## Agent Skills', '', skills] : []),
+    '',
+    '## Verification',
+    '',
+    ...(stack.commands.length === 0
+      ? ['No verification commands are configured.']
+      : stack.commands.map(({ label, argv }) => `- ${label}: ${argv.map((value) => `\`${value}\``).join(' ')}`)),
+    '',
+  ].join('\n');
+  return {
+    status: 'ready',
+    paths: targets,
+    modules: moduleSources.map(({ source: _source, ...module }) => module),
+    components: stack.components.map(({ id }) => id),
+    verificationCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    warnings: [
+      ...(program.diagnostic ? [program.diagnostic] : []),
+      ...projectSkills.diagnostics,
+      ...index.diagnostics,
+    ],
+    functions,
+    context: output,
+  };
+}

package/src/index/environment-files.js

@@ -0,0 +1,19 @@
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { missingStackResources } from './stack-preflight.js';
+
+/** Inspect Stack environment requirements without returning or writing 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;
+  return {
+    status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
+    stackHash: stack.identityHash,
+    components: stack.components.map(({ id }) => id),
+    files: stack.environmentFiles,
+    resources: stack.resources,
+    diagnostics,
+  };
+}

package/src/index/errors.js

@@ -0,0 +1,26 @@
+export class GenesisError extends Error {
+  constructor(code, message, details = undefined) {
+    super(message);
+    this.name = 'GenesisError';
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function fail(code, message, details = undefined) {
+  throw new GenesisError(code, message, details);
+}
+
+function diagnostic(code, message, line = undefined, details = undefined) {
+  const value = { code, message };
+  if (line !== undefined) value.line = line;
+  if (details !== undefined) value.details = details;
+  return value;
+}
+
+export function asDiagnostic(error) {
+  if (error && typeof error === 'object' && typeof error.code === 'string') {
+    return diagnostic(error.code, error.message || error.code, undefined, error.details);
+  }
+  return diagnostic('GENESIS_FAILED', error instanceof Error ? error.message : String(error));
+}

package/src/index/git.js

@@ -0,0 +1,26 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+import { fail } from './errors.js';
+import { runGitText } from './process.js';
+
+/** Resolve the caller's working directory and the one Git repository that contains it. */
+export async function gitContext(projectRoot = process.cwd()) {
+  let root;
+  try { root = await realpath(path.resolve(projectRoot)); } catch (error) {
+    fail('GIT_REPOSITORY_REQUIRED', `Project root does not exist: ${projectRoot}.`, {
+      cause: error.code || error.message,
+    });
+  }
+  let repositoryRoot;
+  try {
+    repositoryRoot = await realpath(path.resolve(await runGitText(root, ['rev-parse', '--show-toplevel'])));
+  } catch {
+    fail('GIT_REPOSITORY_REQUIRED', `Project root is not inside a Git worktree: ${projectRoot}.`);
+  }
+  const relative = path.relative(repositoryRoot, root);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`)) {
+    fail('GIT_REPOSITORY_REQUIRED', `Project root is outside its reported Git worktree: ${projectRoot}.`);
+  }
+  return { workingDirectory: root, repositoryRoot };
+}