genesis-compiler 1.0.0 → 1.2.0

package/src/index/agent-skills.js

@@ -0,0 +1,425 @@
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import {
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+import { GenesisError } from './errors.js';
+import { sha256, stableJson, writeFileAtomic } from './utils.js';
+
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+const require = createRequire(import.meta.url);
+const SKILLS_ROOT = '.agents/skills';
+const MANIFEST_PATH = `${SKILLS_ROOT}/.genesis-managed.json`;
+const MANIFEST_VERSION = 1;
+const HASH = /^sha256:[0-9a-f]{64}$/u;
+const SKILL_FIELDS = new Set([
+  'name',
+  'description',
+  'license',
+  'compatibility',
+  'metadata',
+  'allowed-tools',
+]);
+
+const CORE_SKILLS = [
+  'genesis-project',
+  'genesis-program',
+  'genesis-deslop',
+].map((name) => ({
+  component: null,
+  package: null,
+  path: `skills/${name}`,
+  source: `genesis:skills/${name}`,
+}));
+
+function invalidSkill(message, details = {}) {
+  throw new GenesisError('AGENT_SKILL_INVALID', message, details);
+}
+
+function validSkillName(value) {
+  if (typeof value !== 'string') return false;
+  const name = value.normalize('NFKC');
+  return name.length > 0
+    && name.length <= 64
+    && name === name.toLowerCase()
+    && !name.startsWith('-')
+    && !name.endsWith('-')
+    && !name.includes('--')
+    && [...name].every((character) => character === '-' || /[\p{L}\p{N}]/u.test(character));
+}
+
+function frontmatter(source, location) {
+  const normalized = source.replace(/\r\n?/gu, '\n');
+  if (!normalized.startsWith('---\n')) invalidSkill(`Agent Skill is missing YAML frontmatter: ${location}.`);
+  const end = normalized.indexOf('\n---\n', 4);
+  if (end === -1) invalidSkill(`Agent Skill frontmatter is not closed: ${location}.`);
+  let metadata;
+  try {
+    metadata = parseYaml(normalized.slice(4, end));
+  } catch (error) {
+    invalidSkill(`Agent Skill frontmatter is invalid YAML: ${location}.`, { cause: error.message });
+  }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    invalidSkill(`Agent Skill frontmatter must be a mapping: ${location}.`);
+  }
+  return metadata;
+}
+
+async function skillTree(directory, relative = '') {
+  const entries = await readdir(path.join(directory, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) invalidSkill(`Agent Skill contains a symbolic link: ${child}.`);
+    if (entry.isDirectory()) {
+      files.push(...await skillTree(directory, child));
+      continue;
+    }
+    if (!entry.isFile()) invalidSkill(`Agent Skill contains a non-file entry: ${child}.`);
+    const location = path.join(directory, child);
+    const [content, info] = await Promise.all([readFile(location), lstat(location)]);
+    files.push({
+      path: child,
+      hash: sha256(content),
+      mode: (info.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+    });
+  }
+  return files;
+}
+
+async function describeSkill(directory, source) {
+  let info;
+  try { info = await lstat(directory); } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return null;
+    throw error;
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    invalidSkill(`Agent Skill must be an ordinary directory: ${directory}.`);
+  }
+  const skillFile = path.join(directory, 'SKILL.md');
+  let skillSource;
+  try { skillSource = await readFile(skillFile, 'utf8'); } catch (error) {
+    invalidSkill(`Agent Skill is missing SKILL.md: ${directory}.`, { cause: error.code || error.message });
+  }
+  const metadata = frontmatter(skillSource, skillFile);
+  const unexpected = Object.keys(metadata).filter((field) => !SKILL_FIELDS.has(field));
+  if (unexpected.length > 0) {
+    invalidSkill(`Agent Skill frontmatter contains unsupported fields: ${unexpected.sort().join(', ')}.`);
+  }
+  const { name } = metadata;
+  const description = typeof metadata.description === 'string' ? metadata.description.trim() : '';
+  if (
+    !validSkillName(name)
+    || name.normalize('NFKC') !== path.basename(directory).normalize('NFKC')
+  ) invalidSkill(`Agent Skill name must match its directory and use the standard lowercase format: ${directory}.`);
+  if (!description || description.length > 1024) {
+    invalidSkill(`Agent Skill description must contain 1-1024 characters: ${skillFile}.`);
+  }
+  if (
+    metadata.compatibility !== undefined
+    && (typeof metadata.compatibility !== 'string' || metadata.compatibility.length > 500)
+  ) invalidSkill(`Agent Skill compatibility must be a string of at most 500 characters: ${skillFile}.`);
+  if (metadata.license !== undefined && typeof metadata.license !== 'string') {
+    invalidSkill(`Agent Skill license must be a string: ${skillFile}.`);
+  }
+  if (metadata['allowed-tools'] !== undefined && typeof metadata['allowed-tools'] !== 'string') {
+    invalidSkill(`Agent Skill allowed-tools must be a string: ${skillFile}.`);
+  }
+  if (
+    metadata.metadata !== undefined
+    && (
+      !metadata.metadata
+      || typeof metadata.metadata !== 'object'
+      || Array.isArray(metadata.metadata)
+      || Object.values(metadata.metadata).some((value) => typeof value !== 'string')
+    )
+  ) invalidSkill(`Agent Skill metadata must map strings to strings: ${skillFile}.`);
+  const files = await skillTree(directory);
+  return {
+    name,
+    description,
+    directory,
+    source,
+    files,
+    hash: sha256(stableJson(files)),
+  };
+}
+
+async function packageDirectory(packageName) {
+  for (const modulesRoot of require.resolve.paths(packageName) || []) {
+    const manifest = path.join(modulesRoot, packageName, 'package.json');
+    try {
+      const value = JSON.parse(await readFile(manifest, 'utf8'));
+      if (value?.name === packageName) return path.dirname(manifest);
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+        throw new GenesisError(
+          'AGENT_SKILL_UNAVAILABLE',
+          `Cannot read selected Agent Skill package ${packageName}: ${error.message}.`,
+          { package: packageName },
+        );
+      }
+    }
+  }
+  throw new GenesisError(
+    'AGENT_SKILL_UNAVAILABLE',
+    `Selected Agent Skill package is unavailable: ${packageName}.`,
+    { package: packageName },
+  );
+}
+
+async function resolveLocator(locator) {
+  const root = locator.package ? await packageDirectory(locator.package) : packageRoot;
+  const directory = path.join(root, locator.path);
+  const source = locator.source || (
+    locator.package
+      ? `npm:${locator.package}/${locator.path}`
+      : `genesis:${locator.path}`
+  );
+  const skill = await describeSkill(directory, source);
+  if (!skill) invalidSkill(`Selected Agent Skill is unavailable: ${directory}.`);
+  return { ...skill, component: locator.component };
+}
+
+/** Resolves the three Genesis workflow skills plus authoritative selected Stack skills. */
+export async function projectSkillPlan(stack) {
+  const locators = [
+    ...CORE_SKILLS,
+    ...(stack?.components || []).flatMap((component) => (
+      component.skill ? [{ ...component.skill, component: component.id }] : []
+    )),
+  ];
+  const resolved = await Promise.all(locators.map(resolveLocator));
+  const skills = new Map();
+  for (const skill of resolved) {
+    const previous = skills.get(skill.name);
+    if (previous && previous.hash !== skill.hash) {
+      throw new GenesisError(
+        'AGENT_SKILL_COLLISION',
+        `Selected Stack sources provide different Agent Skills named ${skill.name}.`,
+        { name: skill.name, sources: [previous.source, skill.source] },
+      );
+    }
+    if (!previous) skills.set(skill.name, skill);
+  }
+  return [...skills.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function readManifest(projectRoot) {
+  const location = path.join(projectRoot, MANIFEST_PATH);
+  let value;
+  try { value = JSON.parse(await readFile(location, 'utf8')); } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      return { location, value: { schemaVersion: MANIFEST_VERSION, skills: {} } };
+    }
+    throw new GenesisError('AGENT_SKILLS_MANIFEST_INVALID', `${MANIFEST_PATH} is invalid: ${error.message}.`);
+  }
+  const valid = value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && value.schemaVersion === MANIFEST_VERSION
+    && value.skills
+    && typeof value.skills === 'object'
+    && !Array.isArray(value.skills)
+    && Object.entries(value.skills).every(([name, record]) => (
+      validSkillName(name)
+      && record
+      && typeof record === 'object'
+      && Object.keys(record).sort().join(',') === 'hash,source'
+      && HASH.test(record.hash)
+      && typeof record.source === 'string'
+      && record.source.length > 0
+    ));
+  if (!valid) throw new GenesisError('AGENT_SKILLS_MANIFEST_INVALID', `${MANIFEST_PATH} has an invalid shape.`);
+  return { location, value };
+}
+
+async function replaceSkill(source, target) {
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  const backup = `${target}.${randomUUID()}.backup`;
+  await mkdir(path.dirname(target), { recursive: true });
+  let replaced = false;
+  try {
+    await cp(source, temporary, { recursive: true, errorOnExist: true });
+    try {
+      await rename(target, backup);
+      replaced = true;
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    }
+    await rename(temporary, target);
+  } catch (error) {
+    if (replaced) {
+      await rm(target, { recursive: true, force: true }).catch(() => {});
+      await rename(backup, target).catch(() => {});
+    }
+    throw error;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+    await rm(backup, { recursive: true, force: true });
+  }
+}
+
+function targetFiles(skill) {
+  return skill.files.map(({ path: file }) => `${SKILLS_ROOT}/${skill.name}/${file}`);
+}
+
+/** Installs only Genesis-owned or authoritative Stack-declared skills. */
+export async function syncProjectSkills({ projectRoot, stack } = {}) {
+  const desired = await projectSkillPlan(stack);
+  const desiredNames = new Set(desired.map(({ name }) => name));
+  const manifest = await readManifest(projectRoot);
+  const changedFiles = [];
+  const diagnostics = [];
+
+  for (const skill of desired) {
+    const target = path.join(projectRoot, SKILLS_ROOT, skill.name);
+    const installed = await describeSkill(target, `project:${skill.name}`);
+    const managed = Object.hasOwn(manifest.value.skills, skill.name)
+      ? manifest.value.skills[skill.name]
+      : null;
+    if (!installed) {
+      await replaceSkill(skill.directory, target);
+      manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+      changedFiles.push(...targetFiles(skill));
+      continue;
+    }
+    if (!managed) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_EXTERNAL',
+        message: `Preserved existing project Agent Skill ${skill.name}; Genesis does not own it.`,
+        details: { name: skill.name, path: `${SKILLS_ROOT}/${skill.name}/SKILL.md` },
+      });
+      continue;
+    }
+    if (installed.hash !== managed.hash) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_CUSTOMIZED',
+        message: `Preserved locally modified Agent Skill ${skill.name}.`,
+        details: { name: skill.name, path: `${SKILLS_ROOT}/${skill.name}/SKILL.md` },
+      });
+      continue;
+    }
+    if (installed.hash !== skill.hash || managed.source !== skill.source) {
+      await replaceSkill(skill.directory, target);
+      manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+      changedFiles.push(...new Set([...targetFiles(installed), ...targetFiles(skill)]));
+    }
+  }
+
+  for (const [name, record] of Object.entries(manifest.value.skills)) {
+    if (desiredNames.has(name)) continue;
+    const target = path.join(projectRoot, SKILLS_ROOT, name);
+    const installed = await describeSkill(target, `project:${name}`);
+    if (installed?.hash === record.hash) {
+      await rm(target, { recursive: true, force: true });
+      changedFiles.push(...targetFiles(installed));
+    } else if (installed) {
+      diagnostics.push({
+        code: 'AGENT_SKILL_PRESERVED',
+        message: `Preserved modified deselected Agent Skill ${name} and released Genesis ownership.`,
+        details: { name, path: `${SKILLS_ROOT}/${name}/SKILL.md` },
+      });
+    }
+    delete manifest.value.skills[name];
+  }
+
+  const rendered = stableJson(manifest.value);
+  let previous = null;
+  try { previous = await readFile(manifest.location, 'utf8'); } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+  }
+  if (rendered !== previous) {
+    await writeFileAtomic(manifest.location, rendered);
+    changedFiles.push(MANIFEST_PATH);
+  }
+  return {
+    status: changedFiles.length > 0 ? 'updated' : 'unchanged',
+    changedFiles: [...new Set(changedFiles)].sort(),
+    diagnostics,
+    skills: desired.map(({ name }) => name),
+  };
+}
+
+/** Inspects the exact project copies without changing them. */
+export async function inspectProjectSkills({ projectRoot, stack } = {}) {
+  const desired = await projectSkillPlan(stack);
+  const manifest = await readManifest(projectRoot);
+  const diagnostics = [];
+  const skills = [];
+  let customized = false;
+  let invalid = false;
+  let missing = false;
+  for (const expected of desired) {
+    const target = path.join(projectRoot, SKILLS_ROOT, expected.name);
+    let installed;
+    try { installed = await describeSkill(target, `project:${expected.name}`); } catch (error) {
+      invalid = true;
+      diagnostics.push({ code: error.code || 'AGENT_SKILL_INVALID', message: error.message });
+      continue;
+    }
+    if (!installed) {
+      missing = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_MISSING',
+        message: `Project Agent Skill is missing: ${SKILLS_ROOT}/${expected.name}/SKILL.md.`,
+        details: { name: expected.name },
+      });
+      continue;
+    }
+    const managed = Object.hasOwn(manifest.value.skills, expected.name)
+      ? manifest.value.skills[expected.name]
+      : null;
+    if (!managed) {
+      customized = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_EXTERNAL',
+        message: `Project Agent Skill ${expected.name} is externally managed; Genesis preserved it.`,
+        details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
+      });
+    } else if (installed.hash !== managed.hash) {
+      customized = true;
+      diagnostics.push({
+        code: 'AGENT_SKILL_CUSTOMIZED',
+        message: `Project Agent Skill ${expected.name} differs from its Genesis-managed source.`,
+        details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
+      });
+    }
+    skills.push({
+      name: installed.name,
+      description: installed.description,
+      path: `${SKILLS_ROOT}/${installed.name}/SKILL.md`,
+      component: expected.component,
+    });
+  }
+  return {
+    status: invalid ? 'invalid' : missing ? 'missing' : customized ? 'customized' : 'current',
+    diagnostics,
+    skills,
+  };
+}
+
+export function renderAgentSkillCatalog(skills) {
+  if (!skills.length) return '';
+  return [
+    'The following Agent Skills are available for progressive loading. Read a matching',
+    '`SKILL.md` completely before acting, and resolve its relative references from the',
+    'skill directory. Load scripts, references, and assets only when needed.',
+    '',
+    ...skills.flatMap(({ name, description, path: skillPath }) => [
+      `- \`${name}\` — ${description}`,
+      `  Path: \`${skillPath}\``,
+    ]),
+  ].join('\n');
+}

package/src/index/assets.js

@@ -0,0 +1,19 @@
+import { readFile } from 'node:fs/promises';
+
+const root = new URL('../../', import.meta.url);
+const assets = {
+  start: new URL('prompts/start.txt', root),
+  work: new URL('prompts/work.txt', root),
+  describe: new URL('prompts/describe.txt', root),
+  reconcile: new URL('prompts/reconcile.txt', root),
+  deslop: new URL('prompts/deslop.txt', root),
+  program: new URL('prompts/program.txt', root),
+  blueprint: new URL('prompts/blueprint.txt', root),
+  review: new URL('prompts/review.txt', root),
+};
+
+export async function readInstalledAsset(name) {
+  const location = assets[name];
+  if (!location) throw new TypeError(`Unknown Genesis asset: ${name}.`);
+  return readFile(location, 'utf8');
+}

package/src/index/blueprint.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GenesisError } from './errors.js';
+import { BLUEPRINT_PATH } from './paths.js';
+import { normalizeSource } from './utils.js';
+
+export const BLUEPRINT_SKELETON_SOURCE = '# Blueprint\n\n';
+
+export function parseBlueprintSource(value, { requireDescription = false } = {}) {
+  const source = normalizeSource(value);
+  if (!/^# Blueprint[ \t]*$/mu.test(source)) {
+    throw new GenesisError('BLUEPRINT_INVALID', 'Blueprint needs one `# Blueprint` title.', {
+      path: BLUEPRINT_PATH,
+    });
+  }
+  const description = source.replace(/^# Blueprint[ \t]*\n?/mu, '').trim();
+  if (requireDescription && !description) {
+    throw new GenesisError('BLUEPRINT_INVALID', 'Blueprint needs a product description.', {
+      path: BLUEPRINT_PATH,
+    });
+  }
+  return { path: BLUEPRINT_PATH, source, description };
+}
+
+export async function readBlueprint(projectRoot, { required = false, requireDescription = false } = {}) {
+  try {
+    return parseBlueprintSource(await readFile(path.join(projectRoot, BLUEPRINT_PATH), 'utf8'), {
+      requireDescription,
+    });
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code) && !required) return null;
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      throw new GenesisError('BLUEPRINT_REQUIRED', `Blueprint does not exist: ${BLUEPRINT_PATH}.`);
+    }
+    throw error;
+  }
+}

package/src/index/check.js

@@ -0,0 +1,102 @@
+import { readBlueprint } from './blueprint.js';
+import { inspectProjectSkills } from './agent-skills.js';
+import { readStack } from './stack.js';
+import { asDiagnostic } 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';
+
+function invalidResult(area, error) {
+  return {
+    status: 'invalid',
+    blueprint: area === 'blueprint' ? 'invalid' : 'valid',
+    stack: area === 'stack' ? 'invalid' : 'unknown',
+    skills: area === 'skills' ? 'invalid' : 'unknown',
+    program: 'unknown',
+    resources: 'unknown',
+    verification: 'unknown',
+    programFiles: [],
+    subsystems: [],
+    diagnostics: [asDiagnostic(error)],
+    guidance: error.message,
+  };
+}
+
+export async function checkProject({ environment = process.env, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  try {
+    await readBlueprint(root, { required: true, requireDescription: true });
+  } catch (error) {
+    return invalidResult('blueprint', error);
+  }
+
+  let stack;
+  try {
+    stack = await readStack(root);
+  } catch (error) {
+    return invalidResult('stack', error);
+  }
+
+  let program;
+  try {
+    program = await inspectProgram(root);
+  } catch (error) {
+    program = {
+      status: 'invalid',
+      files: [],
+      subsystems: [],
+      diagnostic: asDiagnostic(error),
+    };
+  }
+  let skills;
+  try {
+    skills = await inspectProjectSkills({ projectRoot: root, stack });
+  } catch (error) {
+    skills = { status: 'invalid', diagnostics: [asDiagnostic(error)], skills: [] };
+  }
+  const missingResources = missingStackResources({ environment, resources: stack.resources });
+  const verification = await inspectVerification({ projectRoot: root, stack });
+  const diagnostics = [
+    ...(program.diagnostic ? [program.diagnostic] : []),
+    ...skills.diagnostics,
+    ...missingResources,
+    ...(verification.status === 'invalid' ? [{
+      code: 'VERIFICATION_EVIDENCE_INVALID',
+      message: 'Saved verification evidence is malformed.',
+    }] : []),
+  ];
+
+  const guidance = [];
+  if (program.status === 'missing') guidance.push('Generate an explanatory Program prompt with genesis prompt --task program.');
+  if (program.status === 'invalid') guidance.push('Repair the Program with genesis prompt --task program.');
+  if (skills.status === 'missing') guidance.push('Run genesis init to install selected project Agent Skills.');
+  if (skills.status === 'invalid') guidance.push('Repair the reported Agent Skill or managed-skill manifest.');
+  if (missingResources.length > 0) {
+    guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
+  }
+  if (['missing', 'stale'].includes(verification.status)) guidance.push('Run genesis verify to refresh concrete evidence.');
+  if (verification.status === 'unconfigured') guidance.push('Add project verification commands to genesis/stack.md.');
+  guidance.push('Use genesis prompt --task review for a semantic, evidence-based comparison.');
+
+  const needsAttention = program.status === 'missing'
+    || skills.status === 'missing'
+    || missingResources.length > 0
+    || ['missing', 'stale', 'unconfigured'].includes(verification.status);
+
+  return {
+    status: program.status === 'invalid' || skills.status === 'invalid' || verification.status === 'invalid'
+      ? 'invalid'
+      : needsAttention ? 'attention' : 'ok',
+    blueprint: 'valid',
+    stack: 'valid',
+    skills: skills.status,
+    program: program.status,
+    resources: missingResources.length > 0 ? 'missing' : 'inputs-present',
+    verification: verification.status,
+    programFiles: program.files,
+    subsystems: program.subsystems,
+    diagnostics,
+    guidance: guidance.join(' '),
+  };
+}