genesis-compiler 1.0.0 → 1.1.0

package/src/index/launch.js

@@ -0,0 +1,34 @@
+import { gitContext } from './git.js';
+import { missingStackResources } from './stack-preflight.js';
+import { readStack } from './stack.js';
+import { uniqueSorted } from './utils.js';
+
+/** Read the Stack's launch declaration without choosing or starting a runtime. */
+export async function inspectProjectLaunch({
+  environment = process.env,
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = missingStackResources({ environment, resources: stack.resources });
+  const disabledReason = diagnostics.length === 0
+    ? null
+    : diagnostics.map(({ message }) => message).join(' ');
+  const targets = stack.launchTargets.map((target) => ({
+    ...target,
+    available: diagnostics.length === 0,
+    disabledReason,
+  }));
+  let status = 'ready';
+  if (targets.length === 0) status = 'unconfigured';
+  else if (diagnostics.length > 0) status = 'blocked';
+  return {
+    status,
+    stackHash: stack.identityHash,
+    components: stack.components.map(({ id }) => id),
+    runtimeRequirements: uniqueSorted(targets.flatMap((target) => target.runtimeRequirements)),
+    resources: stack.resources,
+    targets,
+    diagnostics,
+  };
+}

package/src/index/paths.js

@@ -0,0 +1,10 @@
+export const BLUEPRINT_PATH = 'genesis/blueprint.md';
+export const STACK_PATH = 'genesis/stack.md';
+export const PROGRAM_ROOT = 'genesis/program';
+export const VERIFICATION_PATH = '.genesis/verification.json';
+
+export function isProjectContentPath(file) {
+  const first = file.split('/')[0];
+  if (file === '.agents/skills' || file.startsWith('.agents/skills/')) return false;
+  return !['.codex', '.genesis', 'genesis'].includes(first);
+}

package/src/index/process.js

@@ -0,0 +1,78 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { GenesisError } from './errors.js';
+
+const MAX_DIAGNOSTIC_OUTPUT = 16_384;
+const executeFile = promisify(execFile);
+
+function boundedDiagnosticOutput(buffer) {
+  const source = buffer.toString('utf8');
+  if (source.length <= MAX_DIAGNOSTIC_OUTPUT) return source;
+  const marker = '\n... diagnostic output omitted ...\n';
+  const available = MAX_DIAGNOSTIC_OUTPUT - marker.length;
+  const head = Math.floor(available / 2);
+  return `${source.slice(0, head)}${marker}${source.slice(-(available - head))}`;
+}
+
+function cleanGitEnvironment(overrides = {}) {
+  const environment = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) environment[key] = value;
+  }
+  return { ...environment, ...overrides };
+}
+
+export async function runProcess(command, args, {
+  cwd,
+  env = process.env,
+  maxBytes = 32 * 1024 * 1024,
+  code = 'PROCESS_EXEC_FAILED',
+} = {}) {
+  try {
+    const { stdout, stderr } = await executeFile(command, args, {
+      cwd,
+      env,
+      encoding: 'buffer',
+      maxBuffer: maxBytes,
+      shell: false,
+      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}`, {
+      command,
+      args,
+      status: typeof error.code === 'number' ? error.code : null,
+      signal: error.signal || null,
+      cause: typeof error.code === 'string' ? error.code : undefined,
+      stdout: boundedDiagnosticOutput(stdout),
+      stderr: boundedDiagnosticOutput(stderr),
+    });
+  }
+}
+
+export async function runGit(cwd, args, options = {}) {
+  return runProcess('git', [
+    '-c', 'core.hooksPath=/dev/null',
+    '-c', 'commit.gpgSign=false',
+    '-c', 'core.fsmonitor=false',
+    ...args,
+  ], {
+    cwd,
+    env: cleanGitEnvironment({
+      GIT_CONFIG_NOSYSTEM: '1',
+      GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+      ...options.env,
+    }),
+    maxBytes: options.maxBytes,
+    code: options.code || 'GIT_EXEC_FAILED',
+  });
+}
+
+export async function runGitText(cwd, args, options = {}) {
+  const result = await runGit(cwd, args, options);
+  return result.stdout.toString('utf8').trimEnd();
+}

package/src/index/program.js

@@ -0,0 +1,181 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GenesisError } from './errors.js';
+import { isProjectContentPath, PROGRAM_ROOT } from './paths.js';
+import { normalizeRelative } from './utils.js';
+
+const SOURCE_LINE = /^- `([^`]+)`$/u;
+const CONCEPT_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+async function markdownFiles(projectRoot) {
+  const root = path.join(projectRoot, PROGRAM_ROOT);
+  const files = [];
+  let found = true;
+
+  async function visit(directory, relative = '') {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (['ENOENT', 'ENOTDIR'].includes(error?.code) && directory === root) {
+        found = false;
+        return;
+      }
+      throw error;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const child = path.join(directory, entry.name);
+      const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await visit(child, childRelative);
+      else if (entry.isFile() && entry.name.endsWith('.md')) files.push(`${PROGRAM_ROOT}/${childRelative}`);
+      else {
+        throw new GenesisError(
+          'PROGRAM_INVALID',
+          `Program may contain only directories and Markdown modules: ${PROGRAM_ROOT}/${childRelative}.`,
+        );
+      }
+    }
+  }
+
+  await visit(root);
+  return { files, found };
+}
+
+async function sourceExists(projectRoot, sourcePath) {
+  try {
+    return (await stat(path.join(projectRoot, sourcePath))).isFile();
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+function moduleIdentity(programPath) {
+  const relative = programPath.slice(`${PROGRAM_ROOT}/`.length, -3);
+  const normalized = normalizeRelative(relative);
+  const segments = normalized.split('/');
+  if (segments.length < 2 || segments.some((segment) => !CONCEPT_NAME.test(segment))) {
+    throw new GenesisError(
+      'PROGRAM_INVALID',
+      `Program module needs lowercase conceptual subsystem and operation names: ${programPath}.`,
+      { path: programPath },
+    );
+  }
+  return {
+    name: segments.at(-1),
+    subsystem: segments.slice(0, -1).join('/'),
+  };
+}
+
+function moduleContents(source, programPath) {
+  const lines = source.replace(/\r\n?/gu, '\n').split('\n');
+  const title = lines.find((line) => /^#\s+\S/u.test(line))?.replace(/^#\s+/u, '').trim() || '';
+  const headings = lines
+    .map((line, index) => ({ line, index }))
+    .filter(({ line }) => /^##\s+/u.test(line));
+  const sourcesHeading = headings.filter(({ line }) => line === '## Sources');
+  const contractHeading = headings.filter(({ line }) => line === '## Public contract');
+  if (
+    sourcesHeading.length !== 1
+    || contractHeading.length !== 1
+    || sourcesHeading[0].index >= contractHeading[0].index
+  ) {
+    throw new GenesisError(
+      'PROGRAM_INVALID',
+      `Program module needs one Sources section before one Public contract: ${programPath}.`,
+      { path: programPath },
+    );
+  }
+  const sourceLines = lines
+    .slice(sourcesHeading[0].index + 1, contractHeading[0].index)
+    .filter((line) => line.trim());
+  const sources = sourceLines.map((line) => line.match(SOURCE_LINE)?.[1]);
+  const nextHeading = headings.find(({ index }) => index > contractHeading[0].index);
+  const contractLines = lines
+    .slice(contractHeading[0].index + 1, nextHeading?.index ?? lines.length)
+    .filter((line) => line.trim());
+  if (
+    sources.length === 0
+    || sources.some((sourcePath) => sourcePath === undefined)
+    || new Set(sources).size !== sources.length
+    || contractLines.length === 0
+  ) {
+    throw new GenesisError(
+      'PROGRAM_INVALID',
+      `Program module needs distinct backticked source bullets and a non-empty public contract: ${programPath}.`,
+      { path: programPath },
+    );
+  }
+  const implementationHeading = headings.filter(({ line }) => line === '## Implementation map');
+  if (implementationHeading.length > 1) {
+    throw new GenesisError(
+      'PROGRAM_INVALID',
+      `Program module has duplicate Implementation maps: ${programPath}.`,
+      { path: programPath },
+    );
+  }
+  const description = lines
+    .slice(lines.findIndex((line) => /^#\s+\S/u.test(line)) + 1, sourcesHeading[0].index)
+    .join('\n')
+    .trim();
+  let implementationMap = '';
+  if (implementationHeading.length === 1) {
+    const heading = implementationHeading[0];
+    const following = headings.find(({ index }) => index > heading.index);
+    implementationMap = lines.slice(heading.index + 1, following?.index ?? lines.length).join('\n').trim();
+  }
+  return {
+    title,
+    description,
+    sources: sources.map((sourcePath) => normalizeRelative(sourcePath)),
+    publicContract: contractLines.join('\n').trim(),
+    implementationMap,
+  };
+}
+
+export async function inspectProgram(projectRoot) {
+  const { files, found } = await markdownFiles(projectRoot);
+  if (!found || files.length === 0) {
+    return { status: 'missing', files: [], modules: [], subsystems: [] };
+  }
+
+  const modules = [];
+  for (const programPath of files) {
+    const source = await readFile(path.join(projectRoot, programPath), 'utf8');
+    if ((source.match(/^#\s+\S.*$/gmu) || []).length !== 1) {
+      throw new GenesisError('PROGRAM_INVALID', `Program module has an invalid explanatory format: ${programPath}.`, {
+        path: programPath,
+      });
+    }
+    const identity = moduleIdentity(programPath);
+    const contents = moduleContents(source, programPath);
+    const { sources } = contents;
+    for (const sourcePath of sources) {
+      if (!sourcePath || !isProjectContentPath(sourcePath) || !await sourceExists(projectRoot, sourcePath)) {
+        throw new GenesisError(
+          'PROGRAM_SOURCE_MISSING',
+          `Program module cites a missing or ineligible source file: ${sourcePath}.`,
+          { path: programPath, sourcePath },
+        );
+      }
+    }
+    modules.push({
+      path: programPath,
+      name: identity.name,
+      sources,
+      subsystem: identity.subsystem,
+      title: contents.title,
+      description: contents.description,
+      publicContract: contents.publicContract,
+      implementationMap: contents.implementationMap,
+    });
+  }
+
+  return {
+    status: 'valid',
+    files,
+    modules,
+    subsystems: [...new Set(modules.map(({ subsystem }) => subsystem))].sort(),
+  };
+}

package/src/index/project-files.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+import { runGit } from './process.js';
+import { pathState } from './utils.js';
+
+async function visiblePaths(projectRoot) {
+  const [visible, deleted] = await Promise.all([
+    runGit(projectRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.']),
+    runGit(projectRoot, ['ls-files', '-z', '--deleted', '--', '.']),
+  ]);
+  const absent = new Set(deleted.stdout.toString('utf8').split('\0').filter(Boolean));
+  return [...new Set(visible.stdout.toString('utf8').split('\0').filter(Boolean))]
+    .filter((file) => !absent.has(file) && file !== '.git' && !file.startsWith('.git/'))
+    .sort();
+}
+
+/** Hashable states for ordinary Git-visible files, excluding ignored output. */
+export async function gitVisibleFileStates(projectRoot, { includePath = () => true } = {}) {
+  const states = new Map();
+  for (const file of (await visiblePaths(projectRoot)).filter(includePath)) {
+    states.set(file, await pathState(path.join(projectRoot, file)));
+  }
+  return states;
+}

package/src/index/project-state.js

@@ -0,0 +1,87 @@
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { isProjectContentPath, VERIFICATION_PATH } from './paths.js';
+import { gitVisibleFileStates } from './project-files.js';
+import { sha256, stableJson, writeFileAtomic } from './utils.js';
+
+const SCHEMA_VERSION = 1;
+const HASH = /^sha256:[0-9a-f]{64}$/u;
+
+function commandRecords(stack) {
+  return stack.commands.map(({ label, argv }) => ({ label, argv }));
+}
+
+async function codebaseHash(projectRoot) {
+  const states = await gitVisibleFileStates(projectRoot, { includePath: isProjectContentPath });
+  return sha256(stableJson([...states].map(([file, state]) => ({
+    path: file,
+    hash: state.hash,
+    mode: state.mode,
+  }))));
+}
+
+async function readEvidence(projectRoot) {
+  try {
+    const value = JSON.parse(await readFile(path.join(projectRoot, VERIFICATION_PATH), 'utf8'));
+    const exactFields = value && typeof value === 'object'
+      && Object.keys(value).sort().join(',') === 'codeHash,commands,schemaVersion,stackHash';
+    const validCommands = Array.isArray(value?.commands) && value.commands.every((command) => (
+      command
+      && typeof command === 'object'
+      && Object.keys(command).sort().join(',') === 'argv,label'
+      && typeof command.label === 'string'
+      && command.label.length > 0
+      && Array.isArray(command.argv)
+      && command.argv.length > 0
+      && command.argv.every((argument) => typeof argument === 'string' && argument.length > 0)
+    ));
+    if (
+      !exactFields
+      || value.schemaVersion !== SCHEMA_VERSION
+      || !HASH.test(value.codeHash)
+      || !HASH.test(value.stackHash)
+      || !validCommands
+    ) return { status: 'invalid', evidence: null };
+    return { status: 'recorded', evidence: value };
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return { status: 'missing', evidence: null };
+    if (error instanceof SyntaxError) return { status: 'invalid', evidence: null };
+    throw error;
+  }
+}
+
+export async function inspectVerification({ projectRoot, stack }) {
+  if (stack.commands.length === 0) return { status: 'unconfigured', evidence: null };
+  const saved = await readEvidence(projectRoot);
+  if (saved.status !== 'recorded') return saved;
+  const expected = {
+    codeHash: await codebaseHash(projectRoot),
+    stackHash: stack.identityHash,
+    commands: commandRecords(stack),
+  };
+  return {
+    status: stableJson({
+      codeHash: saved.evidence.codeHash,
+      stackHash: saved.evidence.stackHash,
+      commands: saved.evidence.commands,
+    }) === stableJson(expected) ? 'current' : 'stale',
+    evidence: saved.evidence,
+  };
+}
+
+export async function clearVerification(projectRoot) {
+  await rm(path.join(projectRoot, VERIFICATION_PATH), { force: true });
+}
+
+export async function writeVerification({ projectRoot, stack }) {
+  const location = path.join(projectRoot, VERIFICATION_PATH);
+  const evidence = {
+    schemaVersion: SCHEMA_VERSION,
+    codeHash: await codebaseHash(projectRoot),
+    stackHash: stack.identityHash,
+    commands: commandRecords(stack),
+  };
+  await writeFileAtomic(location, stableJson(evidence));
+  return evidence;
+}

package/src/index/prompt.js

@@ -0,0 +1,239 @@
+import { readInstalledAsset } from './assets.js';
+import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
+import { buildProjectIndex, MACHINE_CITY_PATH, PROGRAM_CITY_PATH } from './code-index.js';
+import { BLUEPRINT_SKELETON_SOURCE, readBlueprint } from './blueprint.js';
+import { readStack, stackPromptContext } from './stack.js';
+import { GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { inspectProgram } from './program.js';
+import { inspectVerification } from './project-state.js';
+import { missingStackResources } from './stack-preflight.js';
+import { stableJson } from './utils.js';
+
+const TASKS = new Set(['work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
+const DEFAULT_REQUEST = {
+  work: 'Implement the product intent expressed by the current Blueprint.',
+  deslop: 'Simplify the current Git-visible work without making unrelated changes.',
+  program: 'Refresh the complete useful Program for the code that exists now.',
+  describe: 'Create or refresh the complete Blueprint and useful Program for the codebase that exists now.',
+  review: 'Review the complete useful relationship between Blueprint, code, Program, and tests.',
+};
+
+function requestText(value, task) {
+  const request = String(value ?? '').trim();
+  if (Buffer.byteLength(request, 'utf8') > 64 * 1024) {
+    throw new GenesisError('PROMPT_REQUEST_INVALID', 'Prompt request exceeds 64 KiB.');
+  }
+  if (task === 'blueprint' && !request) {
+    throw new GenesisError('PROMPT_REQUEST_REQUIRED', 'Blueprint prompt generation requires explicit user intent.');
+  }
+  return request || DEFAULT_REQUEST[task];
+}
+
+async function observeProgram(projectRoot) {
+  try {
+    return await inspectProgram(projectRoot);
+  } catch (error) {
+    return {
+      status: 'invalid',
+      files: [],
+      modules: [],
+      subsystems: [],
+      diagnostic: { code: error.code || 'PROGRAM_INVALID', message: error.message },
+    };
+  }
+}
+
+function programContext(program) {
+  return {
+    status: program.status,
+    files: program.files,
+    subsystems: program.subsystems,
+    modules: program.modules.map(({ path, name, sources, subsystem }) => ({
+      path,
+      name,
+      sources,
+      subsystem,
+    })),
+    ...(program.diagnostic ? { diagnostic: program.diagnostic } : {}),
+  };
+}
+
+function codeIndexContext(index) {
+  return {
+    machineCity: {
+      path: MACHINE_CITY_PATH,
+      status: index.machine.status,
+      files: index.fileCount,
+      functions: index.functionCount,
+    },
+    programCity: {
+      path: PROGRAM_CITY_PATH,
+      status: index.program.status,
+      operations: index.operationCount,
+    },
+    query: 'genesis index <function-or-path...>',
+  };
+}
+
+function renderPrompt({
+  instructions,
+  request,
+  context,
+  skills = '',
+  guidance = '',
+  cleanup = '',
+}) {
+  return [
+    instructions.trim(),
+    '',
+    'USER REQUEST',
+    '',
+    request,
+    '',
+    'GENESIS CONTEXT',
+    '',
+    '```json',
+    stableJson(context).trimEnd(),
+    '```',
+    ...(guidance ? ['', 'SELECTED STACK GUIDANCE', '', guidance] : []),
+    ...(skills ? ['', 'AVAILABLE AGENT SKILLS', '', skills] : []),
+    ...(cleanup ? ['', 'SELECTED STACK CLEANUP GUIDANCE', '', cleanup] : []),
+    '',
+  ].join('\n');
+}
+
+async function generateExplanationPrompt({ instructions, program, request, root, task }) {
+  const blueprint = await readBlueprint(root, {
+    required: true,
+    requireDescription: task === 'program',
+  });
+  const [stack, index] = await Promise.all([
+    readStack(root),
+    buildProjectIndex({ projectRoot: root, write: false }),
+  ]);
+  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
+  const blueprintContext = task === 'describe'
+    ? { path: blueprint.path, source: blueprint.source }
+    : { path: blueprint.path, description: blueprint.description };
+  return {
+    status: 'ready',
+    task,
+    prompt: renderPrompt({
+      instructions,
+      request,
+      context: {
+        task,
+        projectRoot: root,
+        blueprint: blueprintContext,
+        stack: stackPromptContext(stack),
+        program: programContext(program),
+        codeIndex: codeIndexContext(index),
+      },
+      guidance: stack.guidance,
+      skills: renderAgentSkillCatalog(projectSkills.skills),
+    }),
+    warnings: [
+      ...(program.diagnostic ? [program.diagnostic] : []),
+      ...projectSkills.diagnostics,
+      ...index.diagnostics,
+    ],
+    verificationCommands: [],
+  };
+}
+
+export async function generateProjectPrompt({
+  environment = process.env,
+  projectRoot,
+  request = '',
+  task = 'work',
+} = {}) {
+  if (!TASKS.has(task)) {
+    throw new GenesisError('PROMPT_TASK_INVALID', `Prompt task must be one of: ${[...TASKS].join(', ')}.`);
+  }
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const userRequest = requestText(request, task);
+  const instructions = await readInstalledAsset(task);
+
+  if (task === 'blueprint') {
+    const blueprint = await readBlueprint(root);
+    const projectSkills = await inspectProjectSkills({ projectRoot: root, stack: null });
+    const prompt = renderPrompt({
+      instructions,
+      request: userRequest,
+      context: {
+        task,
+        projectRoot: root,
+        blueprint: {
+          path: 'genesis/blueprint.md',
+          source: blueprint?.source || BLUEPRINT_SKELETON_SOURCE,
+        },
+      },
+      skills: renderAgentSkillCatalog(projectSkills.skills),
+    });
+    return {
+      status: 'ready',
+      task,
+      prompt,
+      warnings: projectSkills.diagnostics,
+      verificationCommands: [],
+    };
+  }
+
+  const program = await observeProgram(root);
+  if (['describe', 'program'].includes(task)) {
+    return generateExplanationPrompt({
+      instructions,
+      program,
+      request: userRequest,
+      root,
+      task,
+    });
+  }
+
+  const blueprint = await readBlueprint(root, { required: true, requireDescription: true });
+  const stack = await readStack(root);
+  const [index, projectSkills] = await Promise.all([
+    buildProjectIndex({ projectRoot: root, write: false }),
+    inspectProjectSkills({ projectRoot: root, stack }),
+  ]);
+  const missing = missingStackResources({ environment, resources: stack.resources });
+  const warnings = [
+    ...(program.diagnostic ? [program.diagnostic] : []),
+    ...missing,
+    ...projectSkills.diagnostics,
+    ...index.diagnostics,
+  ];
+  const context = {
+    task,
+    projectRoot: root,
+    blueprint: { path: blueprint.path, description: blueprint.description },
+    stack: stackPromptContext(stack),
+    program: programContext(program),
+    resourceInputs: missing.length > 0
+      ? { status: 'missing', diagnostics: missing }
+      : { status: 'present' },
+    verificationCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    agentSkills: { status: projectSkills.status },
+    codeIndex: codeIndexContext(index),
+  };
+  if (task === 'review') {
+    const verification = await inspectVerification({ projectRoot: root, stack });
+    context.verificationEvidence = { status: verification.status };
+  }
+  const prompt = renderPrompt({
+    instructions,
+    request: userRequest,
+    context,
+    guidance: stack.guidance,
+    skills: renderAgentSkillCatalog(projectSkills.skills),
+    cleanup: task === 'deslop' ? stack.deslop : '',
+  });
+  return {
+    status: 'ready',
+    task,
+    prompt,
+    warnings,
+    verificationCommands: context.verificationCommands,
+  };
+}