genesis-compiler 1.0.0 → 1.2.0

package/src/index/prompt.js

@@ -0,0 +1,347 @@
+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 { listBuiltinStackPieces } from './stack-catalog.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';
+import { gitVisibleFileStates } from './project-files.js';
+import { isProjectContentPath } from './paths.js';
+
+const TASKS = new Set(['start', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
+const DEFAULT_REQUEST = {
+  start: 'Start a conversation about this project.',
+  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 stackCatalogContext(pieces = []) {
+  return pieces.map(({ id, description, requires, conflicts }) => ({
+    id,
+    description,
+    requires,
+    conflicts,
+  }));
+}
+
+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: [],
+  };
+}
+
+async function generateStartPrompt({ instructions, program, request, root }) {
+  let blueprint;
+  try {
+    blueprint = await readBlueprint(root, { required: true });
+  } catch (error) {
+    if (error?.code !== 'BLUEPRINT_REQUIRED') throw error;
+    const files = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
+    const existing = [...files.values()].some((state) => state.exists);
+    if (!existing) throw error;
+    return {
+      status: 'ready',
+      task: 'start',
+      prompt: renderPrompt({
+        instructions,
+        request,
+        context: {
+          task: 'start',
+          projectRoot: root,
+          projectKind: 'existing-uninitialized',
+          genesis: { initialized: false },
+          program: programContext(program),
+        },
+      }),
+      warnings: program.diagnostic ? [program.diagnostic] : [],
+      verificationCommands: [],
+    };
+  }
+  const [stack, index, catalog] = await Promise.all([
+    readStack(root),
+    buildProjectIndex({ projectRoot: root, write: false }),
+    listBuiltinStackPieces(),
+  ]);
+  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
+  const newProject = stack.components.length === 0 && index.fileCount === 0;
+  return {
+    status: 'ready',
+    task: 'start',
+    prompt: renderPrompt({
+      instructions,
+      request,
+      context: {
+        task: 'start',
+        projectRoot: root,
+        projectKind: newProject ? 'new' : 'existing',
+        blueprint: {
+          path: blueprint.path,
+          description: blueprint.description,
+        },
+        stack: stackPromptContext(stack),
+        availableStackPieces: stackCatalogContext(catalog),
+        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 (task === 'start') {
+    return generateStartPrompt({
+      instructions,
+      program,
+      request: userRequest,
+      root,
+    });
+  }
+  let stack;
+  if (task === 'work') {
+    try {
+      stack = await readStack(root);
+    } catch (error) {
+      if (error?.code !== 'STACK_REQUIRED') throw error;
+      return generateStartPrompt({
+        instructions: await readInstalledAsset('start'),
+        program,
+        request: userRequest,
+        root,
+      });
+    }
+    if (stack.components.length === 0) {
+      return generateStartPrompt({
+        instructions: await readInstalledAsset('start'),
+        program,
+        request: userRequest,
+        root,
+      });
+    }
+  }
+  if (['describe', 'program'].includes(task)) {
+    return generateExplanationPrompt({
+      instructions,
+      program,
+      request: userRequest,
+      root,
+      task,
+    });
+  }
+
+  const blueprint = await readBlueprint(root, { required: true, requireDescription: true });
+  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,
+  };
+}

package/src/index/stack-catalog.js

@@ -0,0 +1,72 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { GenesisError } from './errors.js';
+import {
+  normalizeStackPieceId,
+  parseStackPieceSource,
+} from './stack-piece.js';
+
+const catalogRoot = fileURLToPath(new URL('../../stacks/pieces/', import.meta.url));
+function builtinStackPiecePath(id) {
+  return path.join(catalogRoot, `${id}.md`);
+}
+
+export async function readBuiltinStackCatalog() {
+  let entries;
+  try {
+    entries = await readdir(catalogRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+      throw new GenesisError(
+        'STACK_CATALOG_INVALID',
+        'The installed Genesis package is missing its built-in stack catalog.',
+        { catalogRoot },
+      );
+    }
+    throw error;
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name)
+    .sort();
+  const pieces = await Promise.all(files.map(async (file) => {
+    const id = normalizeStackPieceId(file.slice(0, -3));
+    const source = await readFile(builtinStackPiecePath(id), 'utf8');
+    return parseStackPieceSource(source, {
+      expectedId: id,
+      path: `builtin:${id}`,
+    });
+  }));
+  const catalog = new Map();
+  for (const piece of pieces) {
+    if (catalog.has(piece.id)) {
+      throw new GenesisError(
+        'STACK_CATALOG_INVALID',
+        `The built-in stack catalog contains duplicate piece ${piece.id}.`,
+        { piece: piece.id },
+      );
+    }
+    catalog.set(piece.id, piece);
+  }
+  return catalog;
+}
+
+export async function listBuiltinStackPieces() {
+  return [...(await readBuiltinStackCatalog()).values()]
+    .sort((left, right) => left.id.localeCompare(right.id))
+    .map((piece) => ({
+      id: piece.id,
+      description: piece.description,
+      guidance: piece.guidance,
+      requires: piece.requires,
+      conflicts: piece.conflicts,
+      indexers: piece.indexers,
+      launchTargets: piece.launchTargets.map(({ id }) => id),
+      workspaceSetup: piece.workspaceSetupSteps,
+      skill: piece.skill === null ? null : piece.skill.path,
+      resources: piece.resources.map(({ id }) => id),
+    }));
+}

package/src/index/stack-command.js

@@ -0,0 +1,65 @@
+import { GenesisError } from './errors.js';
+import { isSafeProcessExecutable, parseBacktickedArguments } from './stack-process.js';
+
+function commandDiagnostic(stackPath, message, line, details = {}) {
+  throw new GenesisError(
+    'STACK_COMMANDS_INVALID',
+    message,
+    {
+      path: stackPath,
+      ...(line === undefined ? {} : { line }),
+      ...details,
+    },
+  );
+}
+
+export function parseStackCommandLines(lines, { path: stackPath } = {}) {
+  const commands = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index];
+    const line = index + 1;
+    if (!source.trim()) continue;
+    const entry = source.match(/^- Verify `([^`\r\n]+)`:[ \t]+(.+)$/u);
+    if (!entry) {
+      commandDiagnostic(
+        stackPath,
+        'Every Commands entry must use `- Verify `label`: `command` `argument`...`.',
+        line,
+        { observed: source },
+      );
+    }
+
+    const tokenSource = entry[2].trim();
+    const argv = parseBacktickedArguments(tokenSource);
+    if (!argv) {
+      commandDiagnostic(
+        stackPath,
+        'Every command and argument must be one separate non-empty backticked value.',
+        line,
+        { observed: source },
+      );
+    }
+
+    const command = argv[0];
+    if (
+      argv.some((value) => value.includes('\0'))
+      || !isSafeProcessExecutable(command)
+    ) {
+      commandDiagnostic(
+        stackPath,
+        'A stack command executable must be a PATH name or project-relative path without traversal.',
+        line,
+        { command },
+      );
+    }
+
+    commands.push({
+      label: entry[1],
+      argv,
+      line,
+    });
+  }
+
+  return commands;
+}

package/src/index/stack-composition.js

@@ -0,0 +1,38 @@
+import { GenesisError } from './errors.js';
+
+function orderedClosure(catalog, selected, unknown, visiting, ordered) {
+  for (const id of selected) {
+    if (ordered.some((piece) => piece.id === id)) continue;
+    const piece = catalog.get(id);
+    if (!piece) {
+      unknown.add(id);
+      continue;
+    }
+    if (visiting.has(id)) {
+      throw new GenesisError('STACK_DEPENDENCY_CYCLE', `Stack component dependency cycle includes ${id}.`);
+    }
+    visiting.add(id);
+    orderedClosure(catalog, piece.requires, unknown, visiting, ordered);
+    visiting.delete(id);
+    ordered.push(piece);
+  }
+}
+
+/** Adds dependency closure and rejects only real unknown or conflicting pieces. */
+export function resolveStackPieces({ catalog, existing = [], requested = [] } = {}) {
+  const unknown = new Set();
+  const pieces = [];
+  orderedClosure(catalog, [...new Set([...existing, ...requested])], unknown, new Set(), pieces);
+  const installed = new Set(pieces.map(({ id }) => id));
+  for (const piece of pieces) {
+    const conflict = piece.conflicts.find((id) => installed.has(id));
+    if (conflict) {
+      throw new GenesisError(
+        'STACK_PIECE_CONFLICT',
+        `Stack components ${piece.id} and ${conflict} conflict.`,
+        { component: piece.id, conflict },
+      );
+    }
+  }
+  return { pieces, unknown: [...unknown].sort() };
+}

package/src/index/stack-environment-files.js

@@ -0,0 +1,83 @@
+import { GenesisError } from './errors.js';
+import { isCanonicalProjectWorkdir } from './stack-process.js';
+
+const DOTENV_LINE = /^- Dotenv `([^`\r\n]+)`[ \t]*$/u;
+
+function invalid(environmentPath, message, line, details = {}) {
+  throw new GenesisError('STACK_ENVIRONMENT_FILES_INVALID', message, {
+    path: environmentPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function environmentFilePath(value, environmentPath, line) {
+  if (value === '.' || !isCanonicalProjectWorkdir(value)) {
+    invalid(
+      environmentPath,
+      'Environment file paths must be canonical project-relative file paths.',
+      line,
+      { observed: value },
+    );
+  }
+  return value;
+}
+
+export function parseStackEnvironmentFileLines(lines, {
+  path: environmentPath = 'stack environment files',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return [];
+  const files = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const entry = source.match(DOTENV_LINE);
+    if (!entry) {
+      invalid(
+        environmentPath,
+        'Every Environment files entry must use `- Dotenv `project-relative-path``.',
+        index + 1,
+        { observed: source },
+      );
+    }
+    files.push({
+      format: 'dotenv',
+      path: environmentFilePath(entry[1], environmentPath, index + 1),
+    });
+  }
+  if (files.length === 0) {
+    invalid(environmentPath, '## Environment files needs at least one Dotenv entry.');
+  }
+  const paths = files.map((file) => file.path);
+  if (new Set(paths).size !== paths.length) {
+    invalid(environmentPath, '## Environment files contains a duplicate path.');
+  }
+  return files;
+}
+
+export function composeStackEnvironmentFiles(components, projectFiles) {
+  if (projectFiles !== null) {
+    return projectFiles.map((file) => ({ ...file, source: 'project' }));
+  }
+  const files = new Map();
+  for (const component of components) {
+    for (const file of component.environmentFiles) {
+      const existing = files.get(file.path);
+      if (existing && existing.format !== file.format) {
+        invalid(
+          `component:${component.id}`,
+          `Stack components declare incompatible environment file formats for ${file.path}.`,
+        );
+      }
+      if (!existing) {
+        files.set(file.path, {
+          ...file,
+          source: `component:${component.id}`,
+        });
+      }
+    }
+  }
+  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
+}