@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-stage-scriptlet.mjs

@@ -0,0 +1,430 @@
+import crypto from 'node:crypto';
+
+const stageScriptletStage = 'Stage 130';
+const stageScriptletKind = 'copy-ready-stage-execution-scriptlet';
+
+export function runtimeStageScriptlet({ runbook = {}, console: consoleInput = null, selectedStage = '', source = {} } = {}) {
+  const normalizedRunbook = normalizeRunbook(runbook);
+  const normalizedConsole = normalizeConsole(consoleInput);
+  const selected = selectStages(normalizedRunbook.stages, selectedStage);
+  const steps = scriptletStepsFor(selected, normalizedConsole);
+  const powershellCommands = powershellCommandsFor(steps);
+  const expectedMarkers = expectedMarkersFor(steps);
+  const evidenceTemplate = evidenceCaptureTemplateFor({ selected, steps, normalizedRunbook, normalizedConsole });
+  const stopIf = stopConditionsFor(selected, normalizedRunbook, normalizedConsole);
+  const core = {
+    version: 1,
+    stage: stageScriptletStage,
+    scriptlet_kind: stageScriptletKind,
+    source_bindings: sourceBindingSummary(source, normalizedRunbook, normalizedConsole),
+    target_stage: selectedStage || 'next-ready-stage',
+    selected_stage_count: selected.length,
+    runbook_summary: runbookSummary(normalizedRunbook),
+    console_summary: consoleSummary(normalizedConsole),
+    scriptlet_steps: steps,
+    powershell_commands: powershellCommands,
+    expected_markers: expectedMarkers,
+    evidence_capture_template: evidenceTemplate,
+    stop_if: stopIf,
+    copy_boundary: {
+      copy_ready: true,
+      preview_only: true,
+      execution_authorized: false,
+      commands_executed: false,
+      evidence_written: false,
+      git_write_authorized: false,
+      human_runs_manually: true,
+    },
+    allowed_followup: ['manual copy/paste execution by the user', 'Stage 119 execution evidence binding after manual execution', 'Stage 120 staged commit readiness after evidence binding'],
+    forbidden_actions: [
+      'scriptlet execution by runtime',
+      'smoke/check/test execution',
+      'evidence file write or sidecar write',
+      'source mutation or repair execution',
+      'git add/commit/push/PR/merge/tag',
+      'platform API, external network, model, MCP, or subagent invocation',
+    ],
+    boundary_assertions: runtimeStageScriptletBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeStageScriptletInvariants(core);
+  const scriptlet = {
+    ...core,
+    ok: invariants.pass,
+    stage_scriptlet_invariants: invariants,
+  };
+  return {
+    ...scriptlet,
+    scriptlet_digest: digestStageScriptlet(runtimeStageScriptletDigestPayload(scriptlet)),
+  };
+}
+
+export function runtimeStageScriptletDigestPayload(scriptlet) {
+  return {
+    stage: scriptlet.stage,
+    scriptlet_kind: scriptlet.scriptlet_kind,
+    source_bindings: scriptlet.source_bindings,
+    target_stage: scriptlet.target_stage,
+    selected_stage_count: scriptlet.selected_stage_count,
+    runbook_summary: scriptlet.runbook_summary,
+    console_summary: scriptlet.console_summary,
+    scriptlet_steps: scriptlet.scriptlet_steps,
+    powershell_commands: scriptlet.powershell_commands,
+    expected_markers: scriptlet.expected_markers,
+    evidence_capture_template: scriptlet.evidence_capture_template,
+    stop_if: scriptlet.stop_if,
+    copy_boundary: scriptlet.copy_boundary,
+    allowed_followup: scriptlet.allowed_followup,
+    forbidden_actions: scriptlet.forbidden_actions,
+    boundary_assertions: scriptlet.boundary_assertions,
+    stage_scriptlet_invariants: scriptlet.stage_scriptlet_invariants,
+  };
+}
+
+export function runtimeStageScriptletBoundaryAssertions() {
+  return {
+    stage_scriptlet_artifact: false,
+    scriptlet_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    evidence_write: false,
+    runbook_write: false,
+    console_write: false,
+    source_write: false,
+    command_execution: false,
+    check_execution: false,
+    smoke_execution: false,
+    test_execution: false,
+    validation_execution: false,
+    workflow_execution: false,
+    skill_execution: false,
+    runtime_action: false,
+    repair_execution: false,
+    formatting_execution: false,
+    auto_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    git_add: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeStageScriptletInvariants(scriptlet) {
+  const unsafeBoundaries = Object.entries(scriptlet.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = ['stage_scriptlet_artifact', 'sidecar_write', 'state_directory_created', 'evidence_write', 'source_write', 'command_execution', 'check_execution', 'smoke_execution', 'test_execution', 'validation_execution', 'workflow_execution', 'skill_execution', 'runtime_action', 'git', 'git_write', 'git_add', 'commit', 'pr', 'push', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => scriptlet.boundary_assertions?.[key] !== false);
+  const unsafeCopyBoundary = [
+    ...(scriptlet.copy_boundary?.preview_only === true ? [] : ['copy_boundary.preview_only must be true']),
+    ...(scriptlet.copy_boundary?.execution_authorized === false ? [] : ['copy_boundary.execution_authorized must be false']),
+    ...(scriptlet.copy_boundary?.commands_executed === false ? [] : ['copy_boundary.commands_executed must be false']),
+    ...(scriptlet.copy_boundary?.evidence_written === false ? [] : ['copy_boundary.evidence_written must be false']),
+    ...(scriptlet.copy_boundary?.git_write_authorized === false ? [] : ['copy_boundary.git_write_authorized must be false']),
+  ];
+  const unsafeCommands = (scriptlet.powershell_commands || [])
+    .filter((command) => /\b(git\s+(add|commit|push|merge|tag)|gh\s+pr|--confirm|--write|--dispatch|--auto-run|--run|--once)\b/i.test(command))
+    .map((command) => command.slice(0, 120));
+  const unsafeSteps = (scriptlet.scriptlet_steps || [])
+    .filter((step) => step.preview_only !== true || step.execution_authorized !== false || step.actions_executed !== false || step.evidence_written !== false)
+    .map((step) => step.id || 'unknown');
+  const findings = [
+    ...(scriptlet.stage === stageScriptletStage ? [] : [`stage must be ${stageScriptletStage}`]),
+    ...(scriptlet.scriptlet_kind === stageScriptletKind ? [] : [`scriptlet_kind must be ${stageScriptletKind}`]),
+    ...(scriptlet.source_bindings?.runbook_file ? [] : ['source runbook file is required']),
+    ...(scriptlet.source_bindings?.runbook_digest ? [] : ['source runbook digest is required']),
+    ...(Array.isArray(scriptlet.scriptlet_steps) && scriptlet.scriptlet_steps.length > 0 ? [] : ['scriptlet_steps must contain at least one preview step']),
+    ...(Array.isArray(scriptlet.powershell_commands) && scriptlet.powershell_commands.length > 0 ? [] : ['powershell_commands must contain at least one copy-ready command']),
+    ...(Array.isArray(scriptlet.expected_markers) && scriptlet.expected_markers.length > 0 ? [] : ['expected_markers must contain at least one marker']),
+    ...(scriptlet.evidence_capture_template?.schema_version ? [] : ['evidence_capture_template.schema_version is required']),
+    ...(Array.isArray(scriptlet.stop_if) && scriptlet.stop_if.length > 0 ? [] : ['stop_if must contain explicit stop conditions']),
+    ...unsafeCopyBoundary,
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+    ...unsafeCommands.map((command) => `powershell command must not include write/confirm/git mutation: ${command}`),
+    ...unsafeSteps.map((id) => `scriptlet step must remain preview-only and non-executing: ${id}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: ['runbook_binding', 'optional_console_binding', 'scriptlet_steps', 'powershell_commands', 'expected_markers', 'evidence_capture_template', 'stop_conditions', 'preview_only_boundary', 'read_only_boundary_assertions'],
+    findings,
+  };
+}
+
+export function digestStageScriptlet(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function normalizeRunbook(input) {
+  const runbook = objectValue(input.sequential_stage_runbook || input.stage_runbook || input);
+  const stages = listValue(runbook.stage_sequence || runbook.stages || runbook.runbook_stages || runbook.steps)
+    .map((stage, index) => ({
+      id: stringValue(stage.stage_id || stage.id || stage.stage || `stage-${index + 1}`),
+      title: stringValue(stage.title || stage.name || stage.stage || stage.stage_id || `Stage ${index + 1}`),
+      sequence_index: numberValue(stage.sequence_index || index + 1),
+      files_to_change: listValue(stage.files_to_change || stage.files).map(stringValue).filter(Boolean),
+      validation_commands: listValue(stage.validation_commands || stage.commands || stage.checks).map(stringValue).filter(Boolean),
+      evidence_required: listValue(stage.evidence_required || stage.evidence).map(stringValue).filter(Boolean),
+      stop_if: listValue(stage.stop_if || stage.stop_conditions).map(stringValue).filter(Boolean),
+      commit_subject: stringValue(stage.commit_subject),
+      execution_authorized: stage.execution_authorized === true,
+      actions_executed: stage.actions_executed === true,
+    }));
+  return {
+    provided: stages.length > 0,
+    stage: stringValue(runbook.stage || 'Stage 118'),
+    runbook_kind: stringValue(runbook.runbook_kind || runbook.kind || 'sequential-stage-runbook'),
+    ready_for_evidence_binding: runbook.ready_for_evidence_binding === true,
+    blocked_reasons: listValue(runbook.blocked_reasons).map(stringValue).filter(Boolean),
+    evidence_required: listValue(runbook.evidence_required).map(stringValue).filter(Boolean),
+    digest: stringValue(runbook.stage_runbook_digest || runbook.runbook_digest || runbook.sequential_stage_runbook_digest),
+    stages,
+  };
+}
+
+function normalizeConsole(input) {
+  if (!input) return { provided: false, digest: '', commands: [], evidence_needed: [], do_not_do_yet: [], recommended_next_action: {} };
+  const panel = objectValue(input.next_action_console || input.console || input);
+  return {
+    provided: true,
+    stage: stringValue(panel.stage || 'Stage 127'),
+    console_kind: stringValue(panel.console_kind || 'one-screen-next-action-console'),
+    digest: stringValue(panel.console_digest),
+    commands: listValue(panel.copy_ready_command_preview).map((item, index) => ({
+      id: stringValue(item.id || `console-command-${index + 1}`),
+      command: stringValue(item.command),
+      preview_only: item.preview_only !== false,
+    })).filter((item) => item.command),
+    evidence_needed: listValue(panel.evidence_needed_next).map((item) => ({
+      id: stringValue(item.id || item),
+      reason: stringValue(item.reason || item),
+    })).filter((item) => item.id || item.reason),
+    do_not_do_yet: listValue(panel.do_not_do_yet).map(stringValue).filter(Boolean),
+    recommended_next_action: objectValue(panel.recommended_next_action),
+  };
+}
+
+function selectStages(stages, selectedStage) {
+  const candidates = listValue(stages);
+  if (selectedStage) {
+    const matched = candidates.filter((stage) => [stage.id, stage.title, String(stage.sequence_index)].includes(selectedStage));
+    return matched.length > 0 ? matched : [];
+  }
+  return candidates.slice(0, 1);
+}
+
+function scriptletStepsFor(stages, normalizedConsole) {
+  const stageSteps = stages.flatMap((stage, stageIndex) => {
+    const commands = stage.validation_commands.length > 0 ? stage.validation_commands : ['node tools/vibe-runtime-check/index.mjs --root <project-root>'];
+    return commands.map((command, commandIndex) => ({
+      id: `stage130-step-${String(stageIndex + 1).padStart(2, '0')}-${String(commandIndex + 1).padStart(2, '0')}`,
+      stage_id: stage.id,
+      title: stage.title,
+      command,
+      powershell_command: toPowerShellCommand(command),
+      purpose: commandPurpose(command),
+      expected_marker: expectedMarkerFor(command),
+      evidence_key: evidenceKeyFor(stage, commandIndex),
+      preview_only: true,
+      execution_authorized: false,
+      actions_executed: false,
+      evidence_written: false,
+      git_write_authorized: false,
+    }));
+  });
+  const consoleSteps = normalizedConsole.commands
+    .filter((item) => item.preview_only)
+    .slice(0, 3)
+    .map((item, index) => ({
+      id: `stage130-console-preview-${String(index + 1).padStart(2, '0')}`,
+      stage_id: 'stage127-console-preview',
+      title: item.id,
+      command: item.command,
+      powershell_command: toPowerShellCommand(item.command),
+      purpose: 'console suggested preview command',
+      expected_marker: expectedMarkerFor(item.command),
+      evidence_key: `console_preview_${index + 1}`,
+      preview_only: true,
+      execution_authorized: false,
+      actions_executed: false,
+      evidence_written: false,
+      git_write_authorized: false,
+    }));
+  return dedupeBy([...stageSteps, ...consoleSteps], (item) => item.powershell_command).slice(0, 20);
+}
+
+function powershellCommandsFor(steps) {
+  return steps.map((step) => step.powershell_command).filter(Boolean);
+}
+
+function expectedMarkersFor(steps) {
+  return dedupe(steps.map((step) => step.expected_marker).filter(Boolean)).slice(0, 30);
+}
+
+function evidenceCaptureTemplateFor({ selected, steps, normalizedRunbook, normalizedConsole }) {
+  return {
+    schema_version: 1,
+    stage: stageScriptletStage,
+    template_kind: 'manual-execution-evidence-capture',
+    runbook_stage: normalizedRunbook.stage,
+    console_stage: normalizedConsole.provided ? normalizedConsole.stage : 'not_provided',
+    selected_stage_ids: selected.map((stage) => stage.id),
+    evidence_items: steps.map((step) => ({
+      key: step.evidence_key,
+      stage_id: step.stage_id,
+      command: step.command,
+      expected_marker: step.expected_marker,
+      exit_code: '<fill-after-manual-run>',
+      output_excerpt: '<paste-minimal-marker-output>',
+      ran_by: '<human-or-agent-after-explicit-request>',
+      ran_at: '<iso-timestamp>',
+    })),
+    next_contract: 'verification --execution-evidence --from-runbook <runbook-json> --from-file <filled-evidence-json> --stage <stage-id> --json',
+    writes_by_stage130: false,
+  };
+}
+
+function stopConditionsFor(stages, normalizedRunbook, normalizedConsole) {
+  return dedupe([
+    ...(stages.length > 0 ? [] : ['selected stage was not found in the local Stage 118 runbook']),
+    ...normalizedRunbook.blocked_reasons,
+    ...stages.flatMap((stage) => stage.stop_if),
+    ...normalizedConsole.do_not_do_yet,
+    'any command returns a non-zero exit code or missing expected marker',
+    'manual execution would require --confirm, --write, --dispatch, git add/commit/push/merge/tag, PR creation, platform API, model, MCP, or subagent access',
+    'evidence cannot be captured without mutating source or runtime state',
+  ]).slice(0, 30);
+}
+
+function sourceBindingSummary(source, runbook, normalizedConsole) {
+  return {
+    runbook_file: stringValue(source.runbook_file),
+    runbook_digest: stringValue(source.runbook_digest || runbook.digest),
+    console_file: stringValue(source.console_file),
+    console_digest: stringValue(source.console_digest || normalizedConsole.digest),
+  };
+}
+
+function runbookSummary(runbook) {
+  return {
+    provided: runbook.provided,
+    stage: runbook.stage,
+    runbook_kind: runbook.runbook_kind,
+    stage_count: runbook.stages.length,
+    ready_for_evidence_binding: runbook.ready_for_evidence_binding,
+    blocked_count: runbook.blocked_reasons.length,
+  };
+}
+
+function consoleSummary(normalizedConsole) {
+  return {
+    provided: normalizedConsole.provided,
+    stage: normalizedConsole.stage || '',
+    console_kind: normalizedConsole.console_kind || '',
+    command_preview_count: normalizedConsole.commands.length,
+    evidence_needed_count: normalizedConsole.evidence_needed.length,
+    recommended_next_action: stringValue(normalizedConsole.recommended_next_action?.id || normalizedConsole.recommended_next_action?.action),
+  };
+}
+
+function toPowerShellCommand(command) {
+  const text = stringValue(command).trim();
+  if (!text) return '';
+  if (/^powershell\s/i.test(text)) return text;
+  return `powershell -NoProfile -Command "${escapePowerShellDoubleQuoted(text)}"`;
+}
+
+function commandPurpose(command) {
+  const text = stringValue(command);
+  if (/runtime-check/i.test(text)) return 'runtime contract validation';
+  if (/release-check/i.test(text)) return 'full release validation';
+  if (/diff --check/i.test(text)) return 'whitespace and patch hygiene validation';
+  if (/node --check/i.test(text)) return 'syntax validation';
+  if (/test-path\s+\.vibecoding-state/i.test(text)) return 'state directory absence validation';
+  return 'manual stage validation command';
+}
+
+function expectedMarkerFor(command) {
+  const text = stringValue(command);
+  if (/runtime-check/i.test(text)) return 'Result: passed';
+  if (/release-check/i.test(text)) return 'Result: passed';
+  if (/diff --check/i.test(text)) return 'exit_code=0';
+  if (/node --check/i.test(text)) return 'exit_code=0';
+  if (/test-path\s+\.vibecoding-state/i.test(text)) return 'False';
+  return 'exit_code=0 and minimal success marker';
+}
+
+function evidenceKeyFor(stage, commandIndex) {
+  return `${slug(stage.id || stage.title || 'stage')}_command_${commandIndex + 1}`;
+}
+
+function escapePowerShellDoubleQuoted(value) {
+  return stringValue(value).replace(/`/g, '``').replace(/\$/g, '`$').replace(/"/g, '`"');
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value) {
+  return value === undefined || value === null ? '' : String(value);
+}
+
+function numberValue(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function dedupe(values) {
+  return [...new Set(values.map(stringValue).filter(Boolean))];
+}
+
+function dedupeBy(values, keyFn) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    const key = keyFn(value);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    result.push(value);
+  }
+  return result;
+}
+
+function slug(value) {
+  const text = stringValue(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return text || 'stage';
+}
+
+function stableStringify(value) {
+  return JSON.stringify(sortForJson(value));
+}
+
+function sortForJson(value) {
+  if (Array.isArray(value)) return value.map(sortForJson);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, sortForJson(nested)]));
+  }
+  return value;
+}