genesis-compiler 1.2.26 → 1.2.28

package/src/index/stack-catalog.js

@@ -10,6 +10,7 @@ import {
 
 const require = createRequire(import.meta.url);
 const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
+const FIRST_PARTY_STACK_PACKAGE = 'genesis-stack';
 
 export function normalizeStackPackageName(value) {
   const name = String(value ?? '').trim();
@@ -50,6 +51,16 @@ async function packageDirectory(packageName, projectRoot) {
   );
 }
 
+export async function installedFirstPartyStackPackages({ projectRoot } = {}) {
+  try {
+    await packageDirectory(FIRST_PARTY_STACK_PACKAGE, projectRoot);
+    return [FIRST_PARTY_STACK_PACKAGE];
+  } catch (error) {
+    if (error?.code === 'STACK_PACKAGE_UNAVAILABLE') return [];
+    throw error;
+  }
+}
+
 async function readPieceDirectory(
   directory,
   sourcePrefix,

package/src/index/stack-project-contracts.js

@@ -0,0 +1,205 @@
+import { GenesisError } from './errors.js';
+import { composeStackEnvironmentDefaults } from './stack-environment-defaults.js';
+import { composeStackEnvironmentFiles } from './stack-environment-files.js';
+import {
+  composeStackSections,
+  opaqueStackSections,
+  trimStackSectionLines,
+} from './stack-section.js';
+
+const PROJECT_CONTRACT_NAMES = [
+  'Resources',
+  'Environment defaults',
+  'Environment files',
+  'Verification',
+];
+
+function distinctVerificationCommands(components) {
+  const seen = new Set();
+  return components.flatMap(({ verificationCommands }) => verificationCommands)
+    .filter(({ label, argv }) => {
+      const key = JSON.stringify([label, argv]);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+function projectResource(resource) {
+  return {
+    id: resource.id,
+    kind: resource.kind,
+    environmentAlternatives: resource.environmentAlternatives.map((alternative) => ({
+      bindings: alternative.bindings,
+      ...(alternative.allowEmpty.length > 0 ? { allowEmpty: alternative.allowEmpty } : {}),
+      ...(alternative.preferred ? { preferred: true } : {}),
+    })),
+    ...(Object.keys(resource.optionalBindings).length > 0
+      ? { optionalBindings: resource.optionalBindings }
+      : {}),
+  };
+}
+
+function resourceLines(components) {
+  const resources = components.flatMap(({ resources }) => resources);
+  if (resources.length === 0) return null;
+  return resources.flatMap((resource, index) => [
+    ...(index > 0 ? [''] : []),
+    '```json genesis-resource',
+    JSON.stringify(projectResource(resource), null, 2),
+    '```',
+  ]);
+}
+
+function environmentDefaultLines(components) {
+  const defaults = composeStackEnvironmentDefaults(components);
+  if (defaults.length === 0) return null;
+  return defaults.map(({ name, value }) => `- Default \`${name}\`: \`${value}\``);
+}
+
+function environmentFileLines(components) {
+  const files = composeStackEnvironmentFiles(components, null);
+  if (files.length === 0) return null;
+  return files.map(({ path }) => `- Dotenv \`${path}\``);
+}
+
+function verificationLines(components) {
+  const commands = distinctVerificationCommands(components);
+  if (commands.length === 0) return null;
+  return commands.map(({ label, argv }) => (
+    `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`
+  ));
+}
+
+function componentGenesisContracts(components, sections) {
+  return new Map([
+    ['Resources', sections.has('Resources') ? null : resourceLines(components)],
+    ['Environment defaults', sections.has('Environment defaults')
+      ? null
+      : environmentDefaultLines(components)],
+    ['Environment files', sections.has('Environment files')
+      ? null
+      : environmentFileLines(components)],
+    ['Verification', sections.has('Verification') ? null : verificationLines(components)],
+  ].filter(([, lines]) => lines !== null));
+}
+
+export function stackPieceContractNames(piece) {
+  return [
+    ...(piece.resources.length > 0 ? ['Resources'] : []),
+    ...(piece.environmentDefaults.length > 0 ? ['Environment defaults'] : []),
+    ...(piece.environmentFiles.length > 0 ? ['Environment files'] : []),
+    ...(piece.verificationCommands.length > 0 ? ['Verification'] : []),
+    ...piece.extensions.map(({ name }) => name),
+  ];
+}
+
+function contractSections({ components, knownSectionNames, sections }) {
+  const genesisContracts = componentGenesisContracts(components, sections);
+  const materializedSections = [];
+  const projectLines = new Map();
+
+  for (const name of PROJECT_CONTRACT_NAMES) {
+    if (sections.has(name)) {
+      projectLines.set(name, trimStackSectionLines(sections.get(name)));
+    } else if (genesisContracts.has(name)) {
+      projectLines.set(name, genesisContracts.get(name));
+      materializedSections.push(name);
+    }
+  }
+
+  const extensions = composeStackSections(
+    components,
+    opaqueStackSections(sections, knownSectionNames),
+  );
+  for (const extension of extensions) {
+    const [diagnostic] = extension.diagnostics;
+    if (diagnostic) {
+      throw new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+    }
+    projectLines.set(extension.name, trimStackSectionLines(extension.lines));
+    if (!sections.has(extension.name)) materializedSections.push(extension.name);
+  }
+
+  return {
+    environmentDefaultLines: projectLines.get('Environment defaults') ?? null,
+    environmentFileLines: projectLines.get('Environment files') ?? null,
+    extensionSections: [...projectLines.entries()]
+      .filter(([name]) => !PROJECT_CONTRACT_NAMES.includes(name))
+      .map(([name, lines]) => ({ name, lines })),
+    materializedSections,
+    projectContracts: [...projectLines].map(([name, lines]) => ({ name, lines })),
+    resourceLines: projectLines.get('Resources') ?? null,
+    verificationLines: projectLines.get('Verification') ?? null,
+  };
+}
+
+export function materializeStackProjectContracts(options) {
+  return contractSections(options);
+}
+
+export function requireMaterializedStackProjectContracts(options) {
+  const result = contractSections(options);
+  if (result.materializedSections.length > 0) {
+    const headings = result.materializedSections.map((name) => `\`## ${name}\``);
+    throw new GenesisError(
+      'STACK_PROJECT_CONTRACTS_INCOMPLETE',
+      `Selected Stack components require project-owned contracts missing from genesis/stack.md: ${headings.join(', ')}. Run \`genesis migrate\` for an older project or re-run the confirmed \`genesis stack add\` operation for a current project.`,
+      { sections: result.materializedSections },
+    );
+  }
+  return result;
+}
+
+function contractBlocks(projectContracts) {
+  if (projectContracts.length === 0) {
+    return [
+      'No operation contract was proposed by these components. Inspect the application you are creating and declare only its real setup, verification, output, and other consumer operations before calling it ready.',
+    ];
+  }
+  return projectContracts.flatMap(({ name, lines }) => [
+    `### \`## ${name}\``,
+    '',
+    '~~~markdown',
+    ...lines,
+    '~~~',
+    '',
+  ]);
+}
+
+export function renderStackPreparationPrompt({
+  components,
+  materializedSections = [],
+  newlySelected = [],
+  projectContracts = [],
+  reviewSections = [],
+} = {}) {
+  if (newlySelected.length === 0 && materializedSections.length === 0) return '';
+  const selected = components.map(({ id }) => `\`${id}\``).join(', ');
+  return [
+    '# Prepare the selected Stack',
+    '',
+    `Genesis selected ${selected} and made its concrete operation proposals project-owned in \`genesis/stack.md\`. That file is now the durable contract for this application; future catalog releases must not silently change it.`,
+    ...(materializedSections.length > 0 ? [
+      '',
+      `Materialized contract headings: ${materializedSections.map((name) => `\`## ${name}\``).join(', ')}.`,
+    ] : []),
+    ...(reviewSections.length > 0 ? [
+      '',
+      `These existing project contracts remained authoritative while the new components were added: ${reviewSections.map((name) => `\`## ${name}\``).join(', ')}. Reconcile them against the newly selected technology using source evidence; Genesis deliberately did not overwrite them.`,
+    ] : []),
+    '',
+    'Continue this same task now:',
+    '',
+    '1. Read `genesis/blueprint.md`, `genesis/engineering.md`, and the complete `genesis/stack.md`, then run `genesis context .` (or the relevant source paths).',
+    '2. Load every applicable installed Agent Skill and follow the selected technology’s authoritative guidance before creating dependencies or source.',
+    '3. For a new project, implement the source and commands so every project contract below is true. For existing source, inspect reality first and change a complete project section when the inherited proposal is not already true; do not add compatibility code merely to imitate a proposal.',
+    '4. Keep each consumer-owned section opaque to Genesis. Validate it with the consumer or framework that owns its grammar and behavior.',
+    '5. Establish or update the non-technical Blueprint and affected Program explanations as the product becomes concrete.',
+    '6. Run `genesis check`, resolve structural or incomplete-contract diagnostics, and run `genesis verify` only after the declared verification commands exist. Passing verification is evidence for those commands, not proof of every consumer operation.',
+    '',
+    '## Project contracts to satisfy',
+    '',
+    ...contractBlocks(projectContracts),
+  ].join('\n').trimEnd();
+}

package/src/index/stack-section.js

@@ -31,8 +31,8 @@ export function opaqueStackSections(sections, knownNames) {
 
 /**
  * Compose consumer-owned Stack sections without interpreting their contents.
- * A project declaration replaces component defaults; otherwise exactly one
- * selected component may provide a section with a given name.
+ * An existing project declaration wins; otherwise exactly one selected
+ * component may propose a section for materialization under a given name.
  */
 export function composeStackSections(components = [], projectSections = []) {
   const projectByName = new Map(projectSections.map((section) => [section.name, section]));

package/src/index/stack.js

@@ -10,18 +10,21 @@ import {
 import { composeStackCityPresentation } from './stack-city-presentation.js';
 import { resolveStackPieces } from './stack-composition.js';
 import {
-  composeStackEnvironmentDefaults,
   parseStackEnvironmentDefaultLines,
 } from './stack-environment-defaults.js';
 import {
-  composeStackEnvironmentFiles,
   parseStackEnvironmentFileLines,
 } from './stack-environment-files.js';
 import {
-  composeStackSections,
   opaqueStackSections,
   trimStackSectionLines,
 } from './stack-section.js';
+import {
+  materializeStackProjectContracts,
+  renderStackPreparationPrompt,
+  requireMaterializedStackProjectContracts,
+  stackPieceContractNames,
+} from './stack-project-contracts.js';
 import { parseStackVerificationLines } from './stack-verification.js';
 import {
   applyStackPieceCustomization,
@@ -129,7 +132,7 @@ function renderStack({
   resourceLines = null,
   extensionSections = [],
   stackPackages = [],
-  verificationLines = [],
+  verificationLines = null,
 }) {
   return [
     '# Stack',
@@ -148,7 +151,9 @@ function renderStack({
     ...(environmentFileLines === null
       ? []
       : ['', '## Environment files', '', ...trimStackSectionLines(environmentFileLines)]),
-    ...(verificationLines.length > 0 ? ['', '## Verification', ...verificationLines] : []),
+    ...(verificationLines === null
+      ? []
+      : ['', '## Verification', '', ...trimStackSectionLines(verificationLines)]),
     ...extensionSections.flatMap(({ name, lines }) => (
       ['', `## ${name}`, '', ...trimStackSectionLines(lines)]
     )),
@@ -185,46 +190,48 @@ export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }
       .map((piece) => customizePiece(projectRoot, piece)),
   );
   const selected = selectedPieces.map(({ id }) => id);
+  const newlySelectedPieces = selectedPieces.filter(({ id }) => !existing.includes(id));
   const selectedPackages = [...new Set([
     ...declaredPackages,
     ...selectedPieces.map(({ stackPackage }) => stackPackage).filter(Boolean),
   ])].sort();
-  const verificationLines = parseStackVerificationLines(
-    sections.get('Verification') || [],
+  const projectContracts = materializeStackProjectContracts({
+    components: selectedPieces,
+    knownSectionNames: STACK_SECTIONS,
+    sections,
+  });
+  const verificationLines = projectContracts.verificationLines === null ? null : parseStackVerificationLines(
+    projectContracts.verificationLines,
     { path: STACK_PATH },
   )
     .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
-  const resourceLines = sections.has('Resources') ? sections.get('Resources') : null;
+  const resourceLines = projectContracts.resourceLines;
   parseStackResourceLines(resourceLines === null ? undefined : resourceLines, { path: STACK_PATH });
-  const environmentDefaultLines = sections.has('Environment defaults')
-    ? sections.get('Environment defaults')
-    : null;
+  const environmentDefaultLines = projectContracts.environmentDefaultLines;
   parseStackEnvironmentDefaultLines(
     environmentDefaultLines === null ? undefined : environmentDefaultLines,
     { path: STACK_PATH },
   );
-  const environmentFileLines = sections.has('Environment files')
-    ? sections.get('Environment files')
-    : null;
+  const environmentFileLines = projectContracts.environmentFileLines;
   parseStackEnvironmentFileLines(
     environmentFileLines === null ? undefined : environmentFileLines,
     { path: STACK_PATH },
   );
-  const extensionSections = opaqueStackSections(sections, STACK_SECTIONS);
   const rendered = renderStack({
     componentIds: selected,
     environmentDefaultLines,
     environmentFileLines,
     resourceLines,
-    extensionSections,
+    extensionSections: projectContracts.extensionSections,
     stackPackages: selectedPackages,
     verificationLines,
   });
   const stackChanged = rendered !== source;
   if (stackChanged) await writeFileAtomic(location, rendered);
+  const stack = await readStack(projectRoot, { stackPackages: availablePackages });
   const skills = await syncProjectSkills({
     projectRoot,
-    stack: await readStack(projectRoot, { stackPackages: availablePackages }),
+    stack,
   });
   const changedFiles = [
     ...(stackChanged ? [STACK_PATH] : []),
@@ -238,24 +245,28 @@ export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }
     components: selected,
     changedFiles,
     diagnostics: skills.diagnostics,
+    prompt: renderStackPreparationPrompt({
+      components: stack.components,
+      materializedSections: projectContracts.materializedSections,
+      newlySelected: newlySelectedPieces.map(({ id }) => id),
+      projectContracts: stack.projectContracts,
+      reviewSections: [...new Set(newlySelectedPieces.flatMap(stackPieceContractNames))]
+        .filter((name) => sections.has(name)),
+    }),
   };
 }
 
-function distinctVerificationCommands(commands) {
-  const seen = new Set();
-  return commands.filter((command) => {
-    const key = JSON.stringify([command.label, command.argv]);
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
-function resourceDeclarations(components) {
-  return components.flatMap((piece) => piece.resources.map((resource) => ({
-    component: piece.id,
-    resource,
-  })));
+export async function materializeProjectStackContracts({ projectRoot, stackPackages = [] }) {
+  const source = await readFile(path.join(projectRoot, STACK_PATH), 'utf8');
+  const selected = componentIds(parseSections(source));
+  if (selected.length === 0) {
+    return { changedFiles: [], diagnostics: [], materializedSections: [] };
+  }
+  const result = await addStackPieces({ pieces: selected, projectRoot, stackPackages });
+  return {
+    changedFiles: result.changedFiles,
+    diagnostics: result.diagnostics,
+  };
 }
 
 function composedProse(components, field) {
@@ -280,7 +291,10 @@ async function customizePiece(projectRoot, piece) {
   }));
 }
 
-export async function readStack(projectRoot, { stackPackages = [] } = {}) {
+async function readStackWithContractMode(projectRoot, {
+  allowComponentContracts,
+  stackPackages = [],
+}) {
   const location = path.join(projectRoot, STACK_PATH);
   let source;
   try {
@@ -305,39 +319,45 @@ export async function readStack(projectRoot, { stackPackages = [] } = {}) {
     catalog,
     requested: componentIds(sections),
   })).map((piece) => customizePiece(projectRoot, piece)));
+  const projectContracts = (allowComponentContracts
+    ? materializeStackProjectContracts
+    : requireMaterializedStackProjectContracts)({
+    components,
+    knownSectionNames: STACK_SECTIONS,
+    sections,
+  });
   const projectVerificationCommands = parseStackVerificationLines(
-    sections.get('Verification') || [],
+    projectContracts.verificationLines || [],
     { path: STACK_PATH },
   ).map(({ line: _line, ...command }) => command);
-  const componentVerificationCommands = components.flatMap((piece) => piece.verificationCommands);
-  const verificationCommands = distinctVerificationCommands(
-    projectVerificationCommands.length > 0
-      ? projectVerificationCommands
-      : componentVerificationCommands,
-  );
+  const verificationCommands = projectVerificationCommands;
   const cityPresentation = composeStackCityPresentation(components);
-  const projectResources = sections.has('Resources')
-    ? parseStackResourceLines(sections.get('Resources'), { path: STACK_PATH })
-    : null;
-  const resources = projectResources === null
-    ? resourceDeclarations(components)
-    : projectResources.map((resource) => ({ component: 'project', resource }));
+  const resources = parseStackResourceLines(
+    projectContracts.resourceLines === null ? undefined : projectContracts.resourceLines,
+    { path: STACK_PATH },
+  ).map((resource) => ({ component: 'project', resource }));
   const projectEnvironmentDefaults = parseStackEnvironmentDefaultLines(
-    sections.has('Environment defaults') ? sections.get('Environment defaults') : undefined,
+    projectContracts.environmentDefaultLines === null
+      ? undefined
+      : projectContracts.environmentDefaultLines,
     { path: STACK_PATH },
   );
-  const environmentDefaults = sections.has('Environment defaults')
-    ? projectEnvironmentDefaults.map((entry) => ({ ...entry, sources: ['project'] }))
-    : composeStackEnvironmentDefaults(components);
+  const environmentDefaults = projectEnvironmentDefaults
+    .map((entry) => ({ ...entry, sources: ['project'] }));
   const projectEnvironmentFiles = parseStackEnvironmentFileLines(
-    sections.has('Environment files') ? sections.get('Environment files') : undefined,
+    projectContracts.environmentFileLines === null
+      ? undefined
+      : projectContracts.environmentFileLines,
     { path: STACK_PATH },
   );
-  const environmentFiles = composeStackEnvironmentFiles(components, projectEnvironmentFiles);
-  const extensions = composeStackSections(
-    components,
-    opaqueStackSections(sections, STACK_SECTIONS),
-  );
+  const environmentFiles = (projectEnvironmentFiles || [])
+    .map((file) => ({ ...file, source: 'project' }));
+  const extensions = projectContracts.extensionSections.map(({ name, lines }) => ({
+    name,
+    lines,
+    source: 'project',
+    diagnostics: [],
+  }));
   return {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
@@ -359,6 +379,7 @@ export async function readStack(projectRoot, { stackPackages = [] } = {}) {
     environmentDefaults,
     environmentFiles,
     extensions,
+    projectContracts: projectContracts.projectContracts,
     resources,
     guidance: composedProse(components, 'guidance'),
     adoption: composedProse(components, 'adoption'),
@@ -367,9 +388,22 @@ export async function readStack(projectRoot, { stackPackages = [] } = {}) {
   };
 }
 
+export function readStack(projectRoot, { stackPackages = [] } = {}) {
+  return readStackWithContractMode(projectRoot, {
+    allowComponentContracts: false,
+    stackPackages,
+  });
+}
+
+export function readLegacyStack(projectRoot, { stackPackages = [] } = {}) {
+  return readStackWithContractMode(projectRoot, {
+    allowComponentContracts: true,
+    stackPackages,
+  });
+}
+
 export function stackPromptContext(stack) {
   return {
-    stackPackages: stack.stackPackages,
     components: stack.components.map((piece) => ({
       id: piece.id,
       description: piece.description,