genesis-compiler 1.2.2 → 1.2.4

package/src/index/stack-city-presentation.js

@@ -0,0 +1,178 @@
+import { GenesisError } from './errors.js';
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const IGNORE_LINE = /^- Ignore `([^`]+)`[ \t]*$/u;
+const MATCH_LINE = /^- Match `([^`]+)` as `([^`]+)`: `([^`]+)\/\*\*`[ \t]*$/u;
+const FALLBACK_LINE = /^- Fallback `([^`]+)` as `([^`]+)`[ \t]*$/u;
+const REGEXP_SPECIAL = /[.+^${}()|[\]\\]/u;
+const compiledGlobPatterns = new Map();
+
+function invalid(piecePath, message) {
+  throw new GenesisError('STACK_PIECE_INVALID', message, { path: piecePath });
+}
+
+function normalizedPrefix(value, piecePath) {
+  const prefix = String(value || '').trim();
+  if (
+    !prefix
+    || prefix.startsWith('/')
+    || prefix.includes('\\')
+    || /[*?\[\]{}!]/u.test(prefix)
+    || prefix.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(piecePath, '## City regions match paths must be canonical project-relative prefixes.');
+  }
+  return prefix;
+}
+
+function normalizedGlob(value, piecePath) {
+  const pattern = String(value || '').trim();
+  if (
+    !pattern
+    || pattern.startsWith('/')
+    || pattern.includes('\\')
+    || pattern.includes('***')
+    || /[?\[\]{}!]/u.test(pattern)
+    || pattern.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(
+      piecePath,
+      '## City regions ignore patterns must be canonical project-relative globs using only * and ** wildcards.',
+    );
+  }
+  return pattern;
+}
+
+function regionIdentity(id, title, piecePath) {
+  if (!ID_PATTERN.test(id)) {
+    invalid(piecePath, '## City regions ids must use lowercase letters, digits, and single hyphens.');
+  }
+  if (!title.trim()) invalid(piecePath, '## City regions titles must not be empty.');
+  return { id, title: title.trim() };
+}
+
+function globExpression(pattern) {
+  if (compiledGlobPatterns.has(pattern)) return compiledGlobPatterns.get(pattern);
+  let expression = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === '*' && pattern[index + 1] === '*') {
+      if (pattern[index + 2] === '/') {
+        expression += '(?:[^/]+/)*';
+        index += 2;
+      } else {
+        expression += '.*';
+        index += 1;
+      }
+    } else if (character === '*') {
+      expression += '[^/]*';
+    } else {
+      expression += REGEXP_SPECIAL.test(character) ? `\\${character}` : character;
+    }
+  }
+  const compiled = new RegExp(`${expression}$`, 'u');
+  compiledGlobPatterns.set(pattern, compiled);
+  return compiled;
+}
+
+export function cityPathExcluded(filePath, exclusions = []) {
+  return exclusions.some((pattern) => globExpression(pattern).test(filePath));
+}
+
+/**
+ * A City presentation declaration is one complete, ordered contract. Ignore
+ * globs remove non-product files before Machine City is emitted. Matching
+ * prefixes are explicit Stack facts; one final fallback owns every remaining
+ * path. Genesis resolves both region and campus placement, so renderers never
+ * classify or filter repository paths.
+ */
+export function parseStackCityPresentationLines(lines, { path = 'stack piece' } = {}) {
+  if (lines === undefined) return { exclusions: [], regions: [] };
+  const content = lines.filter((line) => line.trim());
+  if (content.length === 0 || (content.length === 1 && content[0].trim() === '- Nothing.')) {
+    return { exclusions: [], regions: [] };
+  }
+  const exclusions = [];
+  const regions = [];
+  let regionDeclarationStarted = false;
+  content.forEach((line, index) => {
+    const ignore = line.match(IGNORE_LINE);
+    if (ignore) {
+      if (regionDeclarationStarted) {
+        invalid(path, '## City regions Ignore entries must precede Match and Fallback entries.');
+      }
+      exclusions.push(normalizedGlob(ignore[1], path));
+      return;
+    }
+    regionDeclarationStarted = true;
+    const match = line.match(MATCH_LINE);
+    if (match) {
+      const identity = regionIdentity(match[1], match[2], path);
+      regions.push({
+        ...identity,
+        fallback: false,
+        pathPrefix: normalizedPrefix(match[3], path),
+      });
+      return;
+    }
+    const fallback = line.match(FALLBACK_LINE);
+    if (fallback) {
+      if (index !== content.length - 1) {
+        invalid(path, '## City regions fallback must be the final declaration.');
+      }
+      regions.push({
+        ...regionIdentity(fallback[1], fallback[2], path),
+        fallback: true,
+        pathPrefix: null,
+      });
+      return;
+    }
+    invalid(
+      path,
+      '## City regions entries must use Ignore with a glob, Match with an id, title, and path/**, or one final Fallback.',
+    );
+  });
+  if (new Set(exclusions).size !== exclusions.length) {
+    invalid(path, '## City regions contains a duplicate ignore pattern.');
+  }
+  if (new Set(regions.map(({ id }) => id)).size !== regions.length) {
+    invalid(path, '## City regions contains a duplicate region id.');
+  }
+  const matches = regions.filter(({ fallback }) => !fallback);
+  if (new Set(matches.map(({ pathPrefix }) => pathPrefix)).size !== matches.length) {
+    invalid(path, '## City regions contains a duplicate path prefix.');
+  }
+  if (regions.filter(({ fallback }) => fallback).length !== 1) {
+    invalid(path, '## City regions requires exactly one final fallback.');
+  }
+  for (const [index, left] of matches.entries()) {
+    if (matches.slice(index + 1).some((right) => (
+      left.pathPrefix.startsWith(`${right.pathPrefix}/`)
+      || right.pathPrefix.startsWith(`${left.pathPrefix}/`)
+    ))) {
+      invalid(path, '## City regions match prefixes must not overlap.');
+    }
+  }
+  return { exclusions, regions };
+}
+
+export function composeStackCityPresentation(components = []) {
+  const owners = components.filter((component) => (
+    component.cityRegions.length > 0 || component.cityExclusions.length > 0
+  ));
+  if (owners.length === 0) return { exclusions: [], regions: [] };
+  if (owners.length > 1) {
+    throw new GenesisError(
+      'STACK_CITY_PRESENTATION_AMBIGUOUS',
+      `Stack components ${owners.map(({ id }) => id).join(', ')} declare competing City presentation contracts.`,
+      { components: owners.map(({ id }) => id) },
+    );
+  }
+  return {
+    exclusions: [...owners[0].cityExclusions],
+    regions: owners[0].cityRegions.map((region) => ({
+      ...region,
+      component: owners[0].id,
+    })),
+  };
+}

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

@@ -14,6 +14,8 @@ export function parseStackEnvironmentDefaultLines(lines, {
   path: defaultsPath = 'stack environment defaults',
 } = {}) {
   if (lines === undefined) return [];
+  const present = lines.map((line) => line.trim()).filter(Boolean);
+  if (present.length === 1 && present[0] === '- Nothing.') return [];
   const defaults = [];
   for (let index = 0; index < lines.length; index += 1) {
     const source = lines[index].trim();

package/src/index/stack-launch.js

@@ -7,9 +7,8 @@ import {
 
 const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const PLACEHOLDER = /\{([a-z][a-z0-9-]*)\}/gu;
-const PREVIEW_IDENTITY_COMMAND_PATH = /^\.vibe64\/bin\/[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 const PREVIEW_IDENTITY_ENVIRONMENT_NAME = /^[A-Z_][A-Z0-9_]*$/u;
-const PREVIEW_IDENTITY_PROTOCOL = 'vibe64.preview-identity.command.v1';
+const PREVIEW_IDENTITY_PROTOCOL = 'genesis.preview-identity.command.v1';
 const PREVIEW_IDENTITY_RESERVED_ENVIRONMENT_NAMES = new Set([
   'HOME',
   'LOGNAME',
@@ -17,8 +16,6 @@ const PREVIEW_IDENTITY_RESERVED_ENVIRONMENT_NAMES = new Set([
   'PATH',
   'TMPDIR',
   'USER',
-  'VIBE64_PREVIEW_IDENTITY_ENABLED',
-  'VIBE64_PREVIEW_IDENTITY_SECRET',
 ]);
 const PREVIEW_IDENTITY_TYPES = new Set(['email', 'login', 'user-id']);
 const PREVIEW_FIELDS = [
@@ -291,12 +288,14 @@ function normalizePreviewIdentity(draft, launchPath, targetId) {
   if (
     command.length > 64
     || command.some((entry) => !entry.trim() || entry.length > 4096 || /[\r\n]/u.test(entry))
-    || !PREVIEW_IDENTITY_COMMAND_PATH.test(command[0])
+    || !command[0].includes('/')
+    || command[0].includes('\\')
+    || command[0].split('/').some((part) => !part || ['.', '..'].includes(part))
     || command.some((entry) => /\{(?:host|port)\}/u.test(entry))
   ) {
     invalid(
       launchPath,
-      'Preview identity command must use an app-owned executable under .vibe64/bin and contain at most 64 literal arguments.',
+      'Preview identity command must use a committed app-owned project-relative executable and contain at most 64 literal arguments.',
       draft.line,
     );
   }

package/src/index/stack-piece.js

@@ -1,5 +1,6 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { parseStackCityPresentationLines } from './stack-city-presentation.js';
 import { parseStackDeploymentLines } from './stack-deployment.js';
 import { parseStackEnvironmentDefaultLines } from './stack-environment-defaults.js';
 import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
@@ -9,7 +10,7 @@ import { normalizeSource } from './utils.js';
 
 const STACK_PIECE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const STACK_CUSTOMIZATION_TITLE = /^# Stack customization: ([a-z0-9]+(?:-[a-z0-9]+)*)\s*$/u;
-const STACK_CUSTOMIZATION_FIELDS = new Set(['Description', 'Guidance', 'Deslop']);
+const STACK_CUSTOMIZATION_FIELDS = new Set(['Description', 'Guidance', 'Adoption', 'Deslop']);
 
 export function normalizeStackPieceId(value, {
   code = 'STACK_PIECE_INVALID',
@@ -92,12 +93,12 @@ function customizationSections(source, piecePath) {
     if (/^#{1,3}\s+/u.test(line)) invalid(piecePath, `Unknown customization heading: ${line.trim()}.`);
     if (field) content.push(line);
     else if (line.trim()) {
-      invalid(piecePath, 'Customization content must be below Description, Guidance, or Deslop.');
+      invalid(piecePath, 'Customization content must be below Description, Guidance, Adoption, or Deslop.');
     }
   }
   finishField();
   if (Object.values(result).every((values) => Object.keys(values).length === 0)) {
-    invalid(piecePath, 'Stack customization must add or override Description, Guidance, or Deslop.');
+    invalid(piecePath, 'Stack customization must add or override Description, Guidance, Adoption, or Deslop.');
   }
   return result;
 }
@@ -150,18 +151,22 @@ function skill(all, piecePath) {
   };
 }
 
-function resources(all, piecePath) {
-  const source = textSection(all, 'Resources');
+export function parseStackResourceLines(lines, {
+  path: resourcePath = 'stack resources',
+} = {}) {
+  if (lines === undefined) return [];
+  const source = lines.join('\n').trim();
   if (!source) return [];
+  if (source === '- Nothing.') return [];
   const blocks = [...source.matchAll(/```json genesis-resource\s*\n([\s\S]*?)\n```/gu)];
   const outside = source.replace(/```json genesis-resource\s*\n[\s\S]*?\n```/gu, '').trim();
   if (outside || blocks.length === 0) {
-    invalid(piecePath, '## Resources may contain only `json genesis-resource` fenced objects.');
+    invalid(resourcePath, '## Resources may contain only `json genesis-resource` fenced objects.');
   }
   const parsed = blocks.map((match) => {
     let resource;
     try { resource = JSON.parse(match[1]); } catch (error) {
-      invalid(piecePath, `A Stack resource is invalid JSON: ${error.message}`);
+      invalid(resourcePath, `A Stack resource is invalid JSON: ${error.message}`);
     }
     if (
       !resource
@@ -172,7 +177,7 @@ function resources(all, piecePath) {
       || !Array.isArray(resource.environmentAlternatives)
       || resource.environmentAlternatives.length === 0
     ) {
-      invalid(piecePath, 'A Stack resource needs an id, kind, and at least one environment alternative.');
+      invalid(resourcePath, 'A Stack resource needs an id, kind, and at least one environment alternative.');
     }
     const environmentAlternatives = resource.environmentAlternatives.map((alternative) => {
       const required = alternative?.required;
@@ -181,7 +186,7 @@ function resources(all, piecePath) {
         !Array.isArray(required)
         || !Array.isArray(allowEmpty)
       ) {
-        invalid(piecePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+        invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
       }
       const names = [...required, ...allowEmpty];
       if (
@@ -190,17 +195,23 @@ function resources(all, piecePath) {
         || allowEmpty.some((name) => !required.includes(name))
         || new Set(required).size !== required.length
         || new Set(allowEmpty).size !== allowEmpty.length
-      ) invalid(piecePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
+      ) invalid(resourcePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
       return { required: [...required], allowEmpty: [...allowEmpty] };
     });
     return { id: resource.id, kind: resource.kind, environmentAlternatives };
   });
   if (new Set(parsed.map(({ id }) => id)).size !== parsed.length) {
-    invalid(piecePath, '## Resources contains a duplicate resource id.');
+    invalid(resourcePath, '## Resources contains a duplicate resource id.');
   }
   return parsed;
 }
 
+function resources(all, piecePath) {
+  return parseStackResourceLines(all.has('Resources') ? all.get('Resources') : undefined, {
+    path: piecePath,
+  });
+}
+
 /**
  * Stack pieces are guidance, not a second programming language. Genesis reads
  * only the few sections it uses and deliberately ignores explanatory sections.
@@ -217,9 +228,14 @@ export function parseStackPieceSource(value, {
   const all = sections(source);
   const description = textSection(all, 'Description');
   const guidance = textSection(all, 'Guidance');
+  const adoption = textSection(all, 'Adoption');
   const deslop = textSection(all, 'Deslop');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const cityPresentation = parseStackCityPresentationLines(
+    all.has('City regions') ? all.get('City regions') : undefined,
+    { path: piecePath },
+  );
   const environmentDefaults = parseStackEnvironmentDefaultLines(
     all.has('Environment defaults') ? all.get('Environment defaults') : undefined,
     { path: piecePath },
@@ -243,12 +259,15 @@ export function parseStackPieceSource(value, {
     id,
     description,
     guidance,
+    adoption,
     requires: idList(all, 'Requires', piecePath, { required: true }),
     conflicts: idList(all, 'Conflicts', piecePath),
     indexers: idList(all, 'Indexers', piecePath),
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
     environmentDefaults,
     environmentFiles: environmentFiles || [],
     launchTargets: launch?.targets || [],
@@ -292,6 +311,11 @@ export function applyStackPieceCustomization(piece, customization) {
       customization.override.guidance,
       customization.add.guidance,
     ),
+    adoption: customizedText(
+      piece.adoption,
+      customization.override.adoption,
+      customization.add.adoption,
+    ),
     deslop: customizedText(piece.deslop, customization.override.deslop, customization.add.deslop),
   };
 }

package/src/index/stack.js

@@ -5,10 +5,12 @@ import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { composeStackCityPresentation } from './stack-city-presentation.js';
 import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
 import { resolveStackPieces } from './stack-composition.js';
 import {
   composeStackEnvironmentDefaults,
+  parseStackEnvironmentDefaultLines,
 } from './stack-environment-defaults.js';
 import {
   composeStackEnvironmentFiles,
@@ -23,6 +25,7 @@ import {
   applyStackPieceCustomization,
   normalizeStackPieceId,
   parseStackPieceCustomizationSource,
+  parseStackResourceLines,
 } from './stack-piece.js';
 import { STACK_PATH } from './paths.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
@@ -31,6 +34,8 @@ const COMPONENT_LINE = /^- `([a-z0-9]+(?:-[a-z0-9]+)*)`$/u;
 export const EMPTY_STACK_SOURCE = '# Stack\n\n## Components\n';
 const STACK_SECTIONS = new Set([
   'Components',
+  'Resources',
+  'Environment defaults',
   'Environment files',
   'Workspace setup',
   'Commands',
@@ -103,8 +108,10 @@ function renderStack({
   commandLines = [],
   componentIds: componentIdsValue,
   deploymentLines = null,
+  environmentDefaultLines = null,
   environmentFileLines = null,
   launchLines = null,
+  resourceLines = null,
   workspaceSetupLines = null,
 }) {
   return [
@@ -112,6 +119,12 @@ function renderStack({
     '',
     '## Components',
     ...componentIdsValue.map((id) => `- \`${id}\``),
+    ...(resourceLines === null
+      ? []
+      : ['', '## Resources', '', ...withoutOuterBlankLines(resourceLines)]),
+    ...(environmentDefaultLines === null
+      ? []
+      : ['', '## Environment defaults', '', ...withoutOuterBlankLines(environmentDefaultLines)]),
     ...(environmentFileLines === null
       ? []
       : ['', '## Environment files', '', ...withoutOuterBlankLines(environmentFileLines)]),
@@ -152,6 +165,15 @@ export async function addStackPieces({ pieces, projectRoot }) {
   )).map(({ id }) => id);
   const commandLines = parseStackCommandLines(sections.get('Commands') || [], { path: STACK_PATH })
     .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
+  const resourceLines = sections.has('Resources') ? sections.get('Resources') : null;
+  parseStackResourceLines(resourceLines === null ? undefined : resourceLines, { path: STACK_PATH });
+  const environmentDefaultLines = sections.has('Environment defaults')
+    ? sections.get('Environment defaults')
+    : null;
+  parseStackEnvironmentDefaultLines(
+    environmentDefaultLines === null ? undefined : environmentDefaultLines,
+    { path: STACK_PATH },
+  );
   const environmentFileLines = sections.has('Environment files')
     ? sections.get('Environment files')
     : null;
@@ -177,8 +199,10 @@ export async function addStackPieces({ pieces, projectRoot }) {
     commandLines,
     componentIds: selected,
     deploymentLines,
+    environmentDefaultLines,
     environmentFileLines,
     launchLines,
+    resourceLines,
     workspaceSetupLines,
   });
   const stackChanged = rendered !== source;
@@ -264,8 +288,20 @@ export async function readStack(projectRoot) {
   ).map(({ line: _line, ...command }) => command);
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
-  const resources = resourceDeclarations(components);
-  const environmentDefaults = composeStackEnvironmentDefaults(components);
+  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 projectEnvironmentDefaults = parseStackEnvironmentDefaultLines(
+    sections.has('Environment defaults') ? sections.get('Environment defaults') : undefined,
+    { path: STACK_PATH },
+  );
+  const environmentDefaults = sections.has('Environment defaults')
+    ? projectEnvironmentDefaults.map((entry) => ({ ...entry, sources: ['project'] }))
+    : composeStackEnvironmentDefaults(components);
   const projectEnvironmentFiles = parseStackEnvironmentFileLines(
     sections.has('Environment files') ? sections.get('Environment files') : undefined,
     { path: STACK_PATH },
@@ -290,6 +326,8 @@ export async function readStack(projectRoot) {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
+      cityExclusions: cityPresentation.exclusions,
+      cityRegions: cityPresentation.regions,
       commands: commands.map(({ label, argv }) => ({ label, argv })),
       environmentDefaults,
       environmentFiles,
@@ -299,6 +337,8 @@ export async function readStack(projectRoot) {
       workspaceSetup,
     })),
     components,
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
     commands,
     environmentDefaults,
     environmentFiles,
@@ -307,6 +347,7 @@ export async function readStack(projectRoot) {
     workspaceSetup,
     resources,
     guidance: composedProse(components, 'guidance'),
+    adoption: composedProse(components, 'adoption'),
     deslop: composedProse(components, 'deslop'),
   };
 }
@@ -317,10 +358,14 @@ export function stackPromptContext(stack) {
       id: piece.id,
       description: piece.description,
       ...(piece.guidance ? { guidance: piece.guidance } : {}),
+      ...(piece.adoption ? { adoption: piece.adoption } : {}),
       requires: piece.requires,
     })),
+    cityExclusions: stack.cityExclusions,
+    cityRegions: stack.cityRegions,
     verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
     environmentDefaults: stack.environmentDefaults,
+    resources: stack.resources,
     environmentFiles: stack.environmentFiles,
     launchTargets: stack.launchTargets,
     deployment: stack.deployment,

package/src/index/utils.js

@@ -29,7 +29,7 @@ export function uniqueSorted(values = []) {
   return [...new Set(values)].sort();
 }
 
-export async function writeFileAtomic(filePath, source, { mode = 0o644 } = {}) {
+export async function writeFileAtomic(filePath, source, { mode = 0o666 } = {}) {
   const temporary = `${filePath}.${randomUUID()}.tmp`;
   await mkdir(path.dirname(filePath), { recursive: true });
   try {

package/src/index/workspace-setup.js

@@ -1,10 +1,17 @@
 import { access } from 'node:fs/promises';
 import path from 'node:path';
 
+import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
+import { runProcess } from './process.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
 
+async function emit(onEvent, event) {
+  try { await onEvent?.(event); } catch { /* Progress observers do not control preparation. */ }
+}
+
 export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }) {
   const diagnostics = [...stack.workspaceSetup.diagnostics];
   const applicableSteps = [];
@@ -68,3 +75,72 @@ export async function inspectProjectWorkspaceSetup({
   const stack = await readStack(root);
   return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
 }
+
+/** Execute the selected Stack's exact workspace recipe with the caller's environment. */
+export async function prepareProjectWorkspace({
+  environment = process.env,
+  onEvent,
+  processRunner = runProcess,
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const setup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+  if (setup.status !== 'ready') {
+    const summary = setup.diagnostics.map(({ message }) => message).join(' ')
+      || 'The selected Stack declares no applicable workspace preparation commands.';
+    return {
+      ...setup,
+      summary,
+      commands: [],
+    };
+  }
+
+  const resolvedEnvironment = withStackEnvironmentDefaults(
+    environment,
+    stack.environmentDefaults,
+  );
+  const commands = [];
+  try {
+    for (const step of setup.steps) {
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_STARTED',
+        message: `Preparing: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+      await processRunner(step.argv[0], step.argv.slice(1), {
+        cwd: path.resolve(root, step.workdir),
+        env: resolvedEnvironment,
+        maxBytes: 32 * 1024 * 1024,
+        code: 'WORKSPACE_PREPARATION_FAILED',
+      });
+      commands.push({
+        label: step.label,
+        argv: step.argv,
+        workdir: step.workdir,
+      });
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_COMPLETED',
+        message: `Prepared: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+    }
+    return {
+      ...setup,
+      status: 'passed',
+      summary: `Prepared the workspace with ${commands.length} command${commands.length === 1 ? '' : 's'}.`,
+      commands,
+      diagnostics: [],
+    };
+  } catch (error) {
+    return {
+      ...setup,
+      status: 'failed',
+      summary: error.message,
+      commands,
+      diagnostics: [asDiagnostic(error)],
+    };
+  }
+}

package/src/index.js

@@ -12,7 +12,10 @@ import { inspectProjectLaunch } from './index/launch.js';
 import { listBuiltinStackPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
 import { verifyProject } from './index/verification.js';
-import { inspectProjectWorkspaceSetup } from './index/workspace-setup.js';
+import {
+  inspectProjectWorkspaceSetup,
+  prepareProjectWorkspace,
+} from './index/workspace-setup.js';
 
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
@@ -41,7 +44,7 @@ export async function adoptProject({ projectRoot = process.cwd(), request = '' }
   const description = await generateProjectPrompt({
     projectRoot,
     request,
-    task: 'describe',
+    task: 'adopt',
   });
   return {
     status: 'ready',
@@ -51,7 +54,7 @@ export async function adoptProject({ projectRoot = process.cwd(), request = '' }
     changedFiles: initialized.changedFiles,
     prompt: description.prompt,
     warnings: description.warnings,
-    guidance: 'Follow the generated description prompt now. Genesis does not start another agent.',
+    guidance: 'Follow the generated adoption prompt now. Genesis does not start another agent.',
   };
 }
 
@@ -86,6 +89,10 @@ export function inspectWorkspaceSetup(options) {
   return inspectProjectWorkspaceSetup(options);
 }
 
+export function prepareWorkspace(options) {
+  return prepareProjectWorkspace(options);
+}
+
 export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }

package/stacks/pieces/cpp.md

@@ -12,6 +12,18 @@ C and C++ translation-unit, header, callable, ownership, build, and test convent
 
 - `cpp`
 
+## Adoption
+
+- Identify the actual build system and presets, compiler and language level,
+  package/runtime dependencies, generated-source steps, and supported build
+  configurations without substituting a preferred CMake or Meson layout.
+- Record exact configure/build/test commands and the executable argv, workdir,
+  host/port handling, HTTP readiness predicate, and signal/shutdown contract for
+  every web-service target.
+- Preserve public headers, ABI and platform assumptions. Treat databases,
+  queues, TLS material, and external service credentials as explicit Resources,
+  not implicit properties of the native binary.
+
 ## Deslop
 
 - Preserve public header boundaries, ABI expectations, build configuration,