genesis-compiler 1.2.0 → 1.2.2

package/src/index/stack-deployment.js

@@ -0,0 +1,204 @@
+import { GenesisError } from './errors.js';
+import {
+  isCanonicalProjectWorkdir,
+  isSafeProcessExecutable,
+  parseBacktickedArguments,
+} from './stack-process.js';
+
+const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const STEP_LINE = /^- (Prepare|Build|Migrate|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u;
+const STEP_ROLE_ORDER = Object.freeze({
+  prepare: 0,
+  build: 1,
+  migrate: 2,
+  serve: 3,
+});
+
+function invalid(deploymentPath, message, line, details = {}) {
+  throw new GenesisError('STACK_DEPLOYMENT_INVALID', message, {
+    path: deploymentPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function oneToken(source, prefix, deploymentPath, label, line) {
+  const values = parseBacktickedArguments(source.slice(prefix.length));
+  if (!values || values.length !== 1) {
+    invalid(deploymentPath, `${label} accepts exactly one backticked value.`, line);
+  }
+  return values[0];
+}
+
+function parseRuntimes(source, deploymentPath, line) {
+  const values = parseBacktickedArguments(source.slice('- Runtimes: '.length));
+  if (!values || values.some((value) => !RUNTIME_ID.test(value))) {
+    invalid(
+      deploymentPath,
+      'Deployment runtimes must be separate backticked technology ids.',
+      line,
+    );
+  }
+  if (new Set(values).size !== values.length) {
+    invalid(deploymentPath, 'Deployment contains a duplicate runtime.', line);
+  }
+  return values;
+}
+
+function parseUrlPath(value, deploymentPath, line) {
+  const normalized = String(value || '').trim();
+  if (!normalized.startsWith('/') || normalized.startsWith('//') || /[\\?#]/u.test(normalized)) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness path must begin with one slash and contain no query or fragment.',
+      line,
+    );
+  }
+  return normalized;
+}
+
+function parseReadiness(source, deploymentPath, line) {
+  const match = source.match(/^- Ready when: `GET` `([^`\r\n]+)` returns `([0-9]{3})`$/u);
+  if (!match) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness must use `- Ready when: `GET` `/path` returns `200``.',
+      line,
+    );
+  }
+  const status = Number(match[2]);
+  if (!Number.isInteger(status) || status < 200 || status > 399) {
+    invalid(deploymentPath, 'Deployment readiness status must be from 200 through 399.', line);
+  }
+  return {
+    kind: 'http',
+    method: 'GET',
+    path: parseUrlPath(match[1], deploymentPath, line),
+    status,
+  };
+}
+
+function parseStep(match, deploymentPath, line) {
+  const label = match[2].trim();
+  const argv = parseBacktickedArguments(match[3]);
+  if (!label || /[\0\r\n]/u.test(label)) {
+    invalid(deploymentPath, 'Deployment step labels must be non-empty single lines.', line);
+  }
+  if (!argv || argv.some((value) => value.includes('\0')) || !isSafeProcessExecutable(argv[0])) {
+    invalid(
+      deploymentPath,
+      'Deployment command and arguments must be separate non-empty backticked values with a safe executable.',
+      line,
+    );
+  }
+  return {
+    label,
+    argv,
+    role: match[1].toLowerCase(),
+  };
+}
+
+export function parseStackDeploymentLines(lines, {
+  path: deploymentPath = 'stack deployment',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return { version: 1, steps: [] };
+
+  const result = {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+  };
+  const seen = new Set();
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const line = index + 1;
+    if (source.startsWith('- Workdir: ')) {
+      if (seen.has('workdir')) invalid(deploymentPath, 'Duplicate Deployment Workdir.', line);
+      seen.add('workdir');
+      const workdir = oneToken(source, '- Workdir: ', deploymentPath, 'Deployment Workdir', line);
+      if (!isCanonicalProjectWorkdir(workdir)) {
+        invalid(deploymentPath, 'Deployment workdir must be a canonical project-relative directory.', line);
+      }
+      result.workdir = workdir;
+      continue;
+    }
+    if (source.startsWith('- Runtimes: ')) {
+      if (seen.has('runtimes')) invalid(deploymentPath, 'Duplicate Deployment Runtimes.', line);
+      seen.add('runtimes');
+      result.runtimeRequirements = parseRuntimes(source, deploymentPath, line);
+      continue;
+    }
+    if (source.startsWith('- Ready when: ')) {
+      if (seen.has('readiness')) invalid(deploymentPath, 'Duplicate Deployment Ready when.', line);
+      seen.add('readiness');
+      result.readiness = parseReadiness(source, deploymentPath, line);
+      continue;
+    }
+    const step = source.match(STEP_LINE);
+    if (step) {
+      result.steps.push(parseStep(step, deploymentPath, line));
+      continue;
+    }
+    invalid(deploymentPath, `Unknown Deployment entry: ${source}.`, line);
+  }
+  if (result.steps.length === 0) {
+    invalid(deploymentPath, '## Deployment needs at least one command or exactly `- Nothing.`.');
+  }
+  const serveSteps = result.steps.filter(({ role }) => role === 'serve');
+  if (serveSteps.length !== 1 || result.steps.at(-1).role !== 'serve') {
+    invalid(deploymentPath, 'Deployment needs exactly one final Serve step.');
+  }
+  for (let index = 1; index < result.steps.length; index += 1) {
+    if (STEP_ROLE_ORDER[result.steps[index].role] < STEP_ROLE_ORDER[result.steps[index - 1].role]) {
+      invalid(
+        deploymentPath,
+        'Deployment steps must be ordered Prepare, Build, Migrate, then Serve.',
+      );
+    }
+  }
+  if (!result.readiness) {
+    invalid(deploymentPath, 'Deployment needs one Ready when entry.');
+  }
+  return result;
+}
+
+export function composeStackDeployment(components, projectDeployment) {
+  if (projectDeployment) return { ...projectDeployment, source: 'project', diagnostics: [] };
+  const declarations = components
+    .filter((component) => component.deployment?.steps?.length > 0)
+    .map((component) => ({
+      ...component.deployment,
+      source: `component:${component.id}`,
+    }));
+  if (declarations.length === 0) {
+    return {
+      version: 1,
+      workdir: '.',
+      runtimeRequirements: [],
+      readiness: null,
+      steps: [],
+      source: null,
+      diagnostics: [],
+    };
+  }
+  if (declarations.length === 1) return { ...declarations[0], diagnostics: [] };
+  const sources = declarations.map(({ source }) => source).sort();
+  return {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+    source: null,
+    diagnostics: [{
+      code: 'STACK_DEPLOYMENT_AMBIGUOUS',
+      message: `Selected Stack components provide competing Deployment recipes: ${sources.join(', ')}. Add one project ## Deployment section to choose the exact recipe.`,
+      details: { sources },
+    }],
+  };
+}

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

@@ -0,0 +1,79 @@
+import { GenesisError } from './errors.js';
+
+const DEFAULT_LINE = /^- Default `([A-Za-z_][A-Za-z0-9_]*)`: `([^`\r\n]+)`[ \t]*$/u;
+
+function invalid(defaultsPath, message, line, details = {}) {
+  throw new GenesisError('STACK_ENVIRONMENT_DEFAULTS_INVALID', message, {
+    path: defaultsPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+export function parseStackEnvironmentDefaultLines(lines, {
+  path: defaultsPath = 'stack environment defaults',
+} = {}) {
+  if (lines === undefined) return [];
+  const defaults = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const entry = source.match(DEFAULT_LINE);
+    if (!entry) {
+      invalid(
+        defaultsPath,
+        'Every Environment defaults entry must be a Default bullet with a backticked name and value.',
+        index + 1,
+        { observed: source },
+      );
+    }
+    defaults.push({ name: entry[1], value: entry[2] });
+  }
+  if (defaults.length === 0) {
+    invalid(defaultsPath, '## Environment defaults needs at least one Default entry.');
+  }
+  if (new Set(defaults.map(({ name }) => name)).size !== defaults.length) {
+    invalid(defaultsPath, '## Environment defaults contains a duplicate name.');
+  }
+  return defaults;
+}
+
+export function composeStackEnvironmentDefaults(components) {
+  const defaults = new Map();
+  for (const component of components) {
+    for (const declaration of component.environmentDefaults) {
+      const existing = defaults.get(declaration.name);
+      if (existing && existing.value !== declaration.value) {
+        invalid(
+          `component:${component.id}`,
+          `Stack components declare incompatible defaults for ${declaration.name}.`,
+          undefined,
+          {
+            name: declaration.name,
+            sources: [...existing.sources, `component:${component.id}`],
+          },
+        );
+      }
+      if (existing) {
+        existing.sources.push(`component:${component.id}`);
+      } else {
+        defaults.set(declaration.name, {
+          ...declaration,
+          sources: [`component:${component.id}`],
+        });
+      }
+    }
+  }
+  return [...defaults.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/** Apply public Stack constants beneath explicit host or user environment. */
+export function withStackEnvironmentDefaults(environment, defaults = []) {
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)) {
+    throw new TypeError('Stack environment resolution requires an environment object.');
+  }
+  return {
+    ...Object.fromEntries(defaults.map(({ name, value }) => [name, value])),
+    ...environment,
+  };
+}

package/src/index/stack-launch.js

@@ -118,6 +118,7 @@ function targetDraft(match, launchPath, line) {
     workdir: '.',
     preferredPort: null,
     urlPath: '/',
+    readiness: null,
     runtimeRequirements: [],
     steps: [],
     previewIdentity: null,
@@ -126,6 +127,27 @@ function targetDraft(match, launchPath, line) {
   };
 }
 
+function parseReadiness(source, launchPath, line) {
+  const match = source.match(/^- Ready when: `GET` `([^`\r\n]+)` returns `([0-9]{3})`$/u);
+  if (!match) {
+    invalid(
+      launchPath,
+      'Launch target readiness must use `- Ready when: `GET` `/path` returns `200``.',
+      line,
+    );
+  }
+  const status = Number(match[2]);
+  if (!Number.isInteger(status) || status < 200 || status > 399) {
+    invalid(launchPath, 'Launch target readiness status must be from 200 through 399.', line);
+  }
+  return {
+    kind: 'http',
+    method: 'GET',
+    path: parseUrlPath(match[1], launchPath, line),
+    status,
+  };
+}
+
 function parsePreferredPort(value, launchPath, line) {
   if (!/^[0-9]+$/u.test(value)) {
     invalid(launchPath, 'Launch target preferred port must be an integer from 1024 through 65535.', line);
@@ -204,6 +226,17 @@ function parseTargetLine(draft, source, launchPath, line) {
     );
     return;
   }
+  if (source.startsWith('- Ready when: ')) {
+    setOnce(
+      draft,
+      'readiness',
+      parseReadiness(source, launchPath, line),
+      launchPath,
+      line,
+      'Launch target Ready when entry',
+    );
+    return;
+  }
   const step = source.match(/^- (Prepare|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u);
   if (step) {
     draft.steps.push({
@@ -336,6 +369,9 @@ function normalizeTarget(draft, launchPath) {
   if (serverSteps.length !== 1 || draft.steps.at(-1).role !== 'server') {
     invalid(launchPath, `Launch target ${draft.id} needs exactly one final Serve step.`, draft.line);
   }
+  if (!draft.readiness) {
+    invalid(launchPath, `Launch target ${draft.id} needs one Ready when entry.`, draft.line);
+  }
   return {
     id: draft.id,
     label: draft.label,
@@ -343,6 +379,7 @@ function normalizeTarget(draft, launchPath) {
     workdir: draft.workdir,
     preferredPort: draft.preferredPort,
     urlPath: draft.urlPath,
+    readiness: draft.readiness,
     runtimeRequirements: draft.runtimeRequirements,
     steps: draft.steps,
     ...(draft.previewIdentity

package/src/index/stack-piece.js

@@ -1,5 +1,7 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { parseStackDeploymentLines } from './stack-deployment.js';
+import { parseStackEnvironmentDefaultLines } from './stack-environment-defaults.js';
 import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
 import { parseStackLaunchLines } from './stack-launch.js';
 import { parseStackWorkspaceSetupLines } from './stack-workspace-setup.js';
@@ -165,10 +167,12 @@ function resources(all, piecePath) {
       !resource
       || typeof resource.id !== 'string'
       || !STACK_PIECE_ID_PATTERN.test(resource.id)
+      || typeof resource.kind !== 'string'
+      || !STACK_PIECE_ID_PATTERN.test(resource.kind)
       || !Array.isArray(resource.environmentAlternatives)
       || resource.environmentAlternatives.length === 0
     ) {
-      invalid(piecePath, 'A Stack resource needs an id and at least one environment alternative.');
+      invalid(piecePath, 'A Stack resource needs an id, kind, and at least one environment alternative.');
     }
     const environmentAlternatives = resource.environmentAlternatives.map((alternative) => {
       const required = alternative?.required;
@@ -189,7 +193,7 @@ function resources(all, piecePath) {
       ) invalid(piecePath, `Stack resource ${resource.id} has an invalid environment alternative.`);
       return { required: [...required], allowEmpty: [...allowEmpty] };
     });
-    return { id: resource.id, environmentAlternatives };
+    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.');
@@ -216,6 +220,10 @@ export function parseStackPieceSource(value, {
   const deslop = textSection(all, 'Deslop');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const environmentDefaults = parseStackEnvironmentDefaultLines(
+    all.has('Environment defaults') ? all.get('Environment defaults') : undefined,
+    { path: piecePath },
+  );
   const environmentFiles = parseStackEnvironmentFileLines(
     all.has('Environment files') ? all.get('Environment files') : undefined,
     { path: piecePath },
@@ -223,6 +231,10 @@ export function parseStackPieceSource(value, {
   const launch = parseStackLaunchLines(all.has('Launch') ? all.get('Launch') : undefined, {
     path: piecePath,
   });
+  const deployment = parseStackDeploymentLines(
+    all.has('Deployment') ? all.get('Deployment') : undefined,
+    { path: piecePath },
+  );
   const workspaceSetup = parseStackWorkspaceSetupLines(
     all.has('Workspace setup') ? all.get('Workspace setup') : undefined,
     { path: piecePath },
@@ -237,8 +249,10 @@ export function parseStackPieceSource(value, {
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    environmentDefaults,
     environmentFiles: environmentFiles || [],
     launchTargets: launch?.targets || [],
+    deployment,
     workspaceSetupSteps: workspaceSetup || [],
     deslop,
   };

package/src/index/stack-workspace-setup.js

@@ -8,6 +8,7 @@ import {
 const PREPARE_LINE = /^- Prepare `([^`\r\n]+)` with (.+?):[ \t]+(.+)$/u;
 const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const READY_WHEN_SUFFIX = /^(.*?)[ \t]+when `([^`\r\n]+)` exists$/u;
+const OPTIONAL_WHEN_SUFFIX = /^(.*?)[ \t]+if `([^`\r\n]+)` exists$/u;
 const WORKDIR_SUFFIX = /^(.*?)[ \t]+in `([^`\r\n]+)`$/u;
 
 function invalid(setupPath, message, line, details = {}) {
@@ -59,7 +60,7 @@ export function parseStackWorkspaceSetupLines(lines, {
     if (!entry) {
       invalid(
         setupPath,
-        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when `path` exists]: `command` `argument`...`.',
+        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when|if `path` exists]: `command` `argument`...`.',
         line,
         { observed: source },
       );
@@ -69,9 +70,11 @@ export function parseStackWorkspaceSetupLines(lines, {
       invalid(setupPath, 'Workspace setup labels must be non-empty single lines.', line);
     }
     const readyEntry = entry[2].match(READY_WHEN_SUFFIX);
-    const setupSource = readyEntry ? readyEntry[1] : entry[2];
+    const optionalEntry = readyEntry ? null : entry[2].match(OPTIONAL_WHEN_SUFFIX);
+    const setupSource = readyEntry ? readyEntry[1] : optionalEntry ? optionalEntry[1] : entry[2];
     const readyWhen = readyEntry ? readyEntry[2] : '';
-    if (readyWhen && (readyWhen === '.' || !isCanonicalProjectWorkdir(readyWhen))) {
+    const runWhen = optionalEntry ? optionalEntry[2] : '';
+    if ((readyWhen || runWhen) && ((readyWhen || runWhen) === '.' || !isCanonicalProjectWorkdir(readyWhen || runWhen))) {
       invalid(
         setupPath,
         'Workspace setup readiness paths must be canonical project-relative paths.',
@@ -98,6 +101,7 @@ export function parseStackWorkspaceSetupLines(lines, {
       runtimeRequirements: parseRuntimeRequirements(runtimeSource, setupPath, line),
       workdir,
       ...(readyWhen ? { readyWhen } : {}),
+      ...(runWhen ? { runWhen } : {}),
     });
   }
   if (steps.length === 0) {

package/src/index/stack.js

@@ -5,7 +5,11 @@ import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
 import { resolveStackPieces } from './stack-composition.js';
+import {
+  composeStackEnvironmentDefaults,
+} from './stack-environment-defaults.js';
 import {
   composeStackEnvironmentFiles,
   parseStackEnvironmentFileLines,
@@ -30,6 +34,7 @@ const STACK_SECTIONS = new Set([
   'Environment files',
   'Workspace setup',
   'Commands',
+  'Deployment',
   'Launch',
 ]);
 const STACK_CUSTOMIZATION_ROOT = 'genesis/stack';
@@ -97,6 +102,7 @@ function withoutOuterBlankLines(lines = []) {
 function renderStack({
   commandLines = [],
   componentIds: componentIdsValue,
+  deploymentLines = null,
   environmentFileLines = null,
   launchLines = null,
   workspaceSetupLines = null,
@@ -114,6 +120,9 @@ function renderStack({
       : ['', '## Workspace setup', '', ...withoutOuterBlankLines(workspaceSetupLines)]),
     ...(commandLines.length > 0 ? ['', '## Commands', ...commandLines] : []),
     ...(launchLines === null ? [] : ['', '## Launch', '', ...withoutOuterBlankLines(launchLines)]),
+    ...(deploymentLines === null
+      ? []
+      : ['', '## Deployment', '', ...withoutOuterBlankLines(deploymentLines)]),
     '',
   ].join('\n');
 }
@@ -152,6 +161,11 @@ export async function addStackPieces({ pieces, projectRoot }) {
   );
   const launchLines = sections.has('Launch') ? sections.get('Launch') : null;
   parseStackLaunchLines(launchLines === null ? undefined : launchLines, { path: STACK_PATH });
+  const deploymentLines = sections.has('Deployment') ? sections.get('Deployment') : null;
+  parseStackDeploymentLines(
+    deploymentLines === null ? undefined : deploymentLines,
+    { path: STACK_PATH },
+  );
   const workspaceSetupLines = sections.has('Workspace setup')
     ? sections.get('Workspace setup')
     : null;
@@ -162,6 +176,7 @@ export async function addStackPieces({ pieces, projectRoot }) {
   const rendered = renderStack({
     commandLines,
     componentIds: selected,
+    deploymentLines,
     environmentFileLines,
     launchLines,
     workspaceSetupLines,
@@ -250,6 +265,7 @@ export async function readStack(projectRoot) {
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
   const resources = resourceDeclarations(components);
+  const environmentDefaults = composeStackEnvironmentDefaults(components);
   const projectEnvironmentFiles = parseStackEnvironmentFileLines(
     sections.has('Environment files') ? sections.get('Environment files') : undefined,
     { path: STACK_PATH },
@@ -260,6 +276,11 @@ export async function readStack(projectRoot) {
     { path: STACK_PATH },
   );
   const launchTargets = composeStackLaunchTargets(components, projectLaunch);
+  const projectDeployment = parseStackDeploymentLines(
+    sections.has('Deployment') ? sections.get('Deployment') : undefined,
+    { path: STACK_PATH },
+  );
+  const deployment = composeStackDeployment(components, projectDeployment);
   const projectWorkspaceSetup = parseStackWorkspaceSetupLines(
     sections.has('Workspace setup') ? sections.get('Workspace setup') : undefined,
     { path: STACK_PATH },
@@ -270,15 +291,19 @@ export async function readStack(projectRoot) {
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
       commands: commands.map(({ label, argv }) => ({ label, argv })),
+      environmentDefaults,
       environmentFiles,
       launchTargets,
+      deployment,
       resources,
       workspaceSetup,
     })),
     components,
     commands,
+    environmentDefaults,
     environmentFiles,
     launchTargets,
+    deployment,
     workspaceSetup,
     resources,
     guidance: composedProse(components, 'guidance'),
@@ -295,8 +320,10 @@ export function stackPromptContext(stack) {
       requires: piece.requires,
     })),
     verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    environmentDefaults: stack.environmentDefaults,
     environmentFiles: stack.environmentFiles,
     launchTargets: stack.launchTargets,
+    deployment: stack.deployment,
     workspaceSetup: stack.workspaceSetup,
   };
 }

package/src/index/verification.js

@@ -2,8 +2,10 @@ import { runProcess } from './process.js';
 import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
 import { clearVerification, writeVerification } from './project-state.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 import { readStack } from './stack.js';
+import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control verification. */ }
@@ -17,7 +19,34 @@ export async function verifyProject({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const missing = missingStackResources({ environment, resources: stack.resources });
+  const workspaceSetup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+  if (workspaceSetup.status === 'blocked') {
+    return {
+      status: 'blocked',
+      summary: workspaceSetup.diagnostics.map(({ message }) => message).join(' '),
+      commands: [],
+      diagnostics: workspaceSetup.diagnostics,
+    };
+  }
+  const waiting = workspaceSetup.diagnostics.filter(
+    ({ code }) => code === 'STACK_WORKSPACE_SETUP_WAITING',
+  );
+  if (waiting.length > 0) {
+    return {
+      status: 'unconfigured',
+      summary: waiting.map(({ message }) => message).join(' '),
+      commands: [],
+      diagnostics: waiting,
+    };
+  }
+  const resolvedEnvironment = withStackEnvironmentDefaults(
+    environment,
+    stack.environmentDefaults,
+  );
+  const missing = missingStackResources({
+    environment: resolvedEnvironment,
+    resources: stack.resources,
+  });
   if (missing.length > 0) {
     return {
       status: 'blocked',
@@ -47,6 +76,7 @@ export async function verifyProject({
       });
       await processRunner(command.argv[0], command.argv.slice(1), {
         cwd: root,
+        env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'VERIFICATION_FAILED',
       });

package/src/index/workspace-setup.js

@@ -5,16 +5,22 @@ import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
 
-/** Read the Stack's workspace preparation recipe without executing it. */
-export async function inspectProjectWorkspaceSetup({
-  projectRoot,
-} = {}) {
-  const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }) {
   const diagnostics = [...stack.workspaceSetup.diagnostics];
+  const applicableSteps = [];
   if (diagnostics.length === 0) {
     const waitingFor = [];
     for (const step of stack.workspaceSetup.steps) {
+      if (step.runWhen) {
+        try {
+          await access(path.join(root, step.runWhen));
+          applicableSteps.push(step);
+        } catch (error) {
+          if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+        }
+        continue;
+      }
+      applicableSteps.push(step);
       if (!step.readyWhen) continue;
       try {
         await access(path.join(root, step.readyWhen));
@@ -36,9 +42,9 @@ export async function inspectProjectWorkspaceSetup({
   const blocked = diagnostics.some(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING');
   let status = 'unconfigured';
   if (blocked) status = 'blocked';
-  else if (!waiting && stack.workspaceSetup.steps.length > 0) status = 'ready';
+  else if (!waiting && applicableSteps.length > 0) status = 'ready';
   const recipeHash = status === 'ready'
-    ? sha256(stableJson({ version: 1, steps: stack.workspaceSetup.steps }))
+    ? sha256(stableJson({ version: 1, steps: applicableSteps }))
     : '';
   return {
     status,
@@ -47,9 +53,18 @@ export async function inspectProjectWorkspaceSetup({
     components: stack.components.map(({ id }) => id),
     source: stack.workspaceSetup.source,
     runtimeRequirements: uniqueSorted(
-      stack.workspaceSetup.steps.flatMap((step) => step.runtimeRequirements),
+      applicableSteps.flatMap((step) => step.runtimeRequirements),
     ),
-    steps: stack.workspaceSetup.steps,
+    steps: applicableSteps,
     diagnostics,
   };
 }
+
+/** Read the Stack's workspace preparation recipe without executing it. */
+export async function inspectProjectWorkspaceSetup({
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+}