genesis-compiler 1.0.0 → 1.2.0

package/src/index/init.js

@@ -0,0 +1,48 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { syncProjectSkills } from './agent-skills.js';
+import { BLUEPRINT_SKELETON_SOURCE } from './blueprint.js';
+import { installCodexHooks } from './codex-hooks.js';
+import { gitContext } from './git.js';
+import { BLUEPRINT_PATH, PROGRAM_ROOT, STACK_PATH } from './paths.js';
+import { EMPTY_STACK_SOURCE, readStack } from './stack.js';
+
+async function createIfMissing(projectRoot, relativePath, source) {
+  const location = path.join(projectRoot, relativePath);
+  await mkdir(path.dirname(location), { recursive: true });
+  try {
+    await writeFile(location, source, { flag: 'wx', mode: 0o644 });
+    return relativePath;
+  } catch (error) {
+    if (error?.code === 'EEXIST') return null;
+    throw error;
+  }
+}
+
+export async function initializeProject({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const created = (await Promise.all([
+    createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
+    createIfMissing(root, STACK_PATH, EMPTY_STACK_SOURCE),
+  ])).filter(Boolean);
+  await mkdir(path.join(root, PROGRAM_ROOT), { recursive: true });
+  const stack = await readStack(root);
+  const skills = await syncProjectSkills({ projectRoot: root, stack });
+  const hooks = await installCodexHooks({ projectRoot: root });
+  const changedFiles = [...created, ...hooks.changedFiles, ...skills.changedFiles].sort();
+  return {
+    status: changedFiles.length > 0 ? 'updated' : 'unchanged',
+    summary: changedFiles.length > 0
+      ? 'Initialized Genesis, Agent Skills, and project Codex hooks.'
+      : 'Genesis, its Agent Skills, and project Codex hooks are already initialized.',
+    changedFiles,
+    diagnostics: skills.diagnostics,
+    guidance: [
+      'Open Codex and use /hooks to review and trust the project hooks.',
+      'Genesis workflow skills are available in .agents/skills/.',
+      'Describe product intent in genesis/blueprint.md.',
+      'Stack components are optional; add them with genesis stack add <piece...>.',
+    ].join(' '),
+  };
+}

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,89 @@
+import { execFile } from 'node:child_process';
+
+import { GenesisError } from './errors.js';
+
+const MAX_DIAGNOSTIC_OUTPUT = 16_384;
+
+function executeFile(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, options, (error, stdout, stderr) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+    child.stdin?.end();
+  });
+}
+
+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;
+}