@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-dispatch-command.mjs

@@ -0,0 +1,484 @@
+import path from 'node:path';
+import process from 'node:process';
+import { createRuntimeDispatchReadonlyArtifacts } from './runtime-dispatch-readonly-artifacts.mjs';
+import { createRuntimeDispatchStateLifecycleModel } from './runtime-dispatch-state-lifecycle-model.mjs';
+
+export function createRuntimeDispatchCommand(deps) {
+  const {
+    jsonSchemaVersion,
+    stateDirectoryName,
+    workflowFileName,
+    dispatchesDirectoryName,
+    dispatchClaimsDirectoryName,
+    ensureRoot,
+    workflowPath,
+    dispatchesDirectory,
+    dispatchClaimsDirectory,
+    writeJsonEnvelope,
+    printList,
+    taskIdPattern,
+    taskIdRequirement,
+    windowsReservedTaskBasenames,
+    allowedTransitions,
+    adapterRuntimeBridge,
+    platformHints,
+    platformCapabilities,
+    forbiddenDispatchActions,
+    claimStaleAfterMs,
+    hasActualStopCondition,
+    tasksFromState,
+    readinessCounts,
+    reviewSummaryStatus,
+    jsonTaskSummaries,
+    parseIsoTimestamp,
+    optionalFileDigest,
+  } = deps;
+
+  const {
+    dispatchClaimFilePath,
+    dispatchEventFilePath,
+    dispatchEventSummary,
+    readDispatchEventFile,
+    dispatchEventDigest,
+    claimAudit,
+    claimAuditQuality,
+    listDispatchEvents,
+    verifyDispatchEvent,
+    dispatchClaimSafety,
+    readDispatchClaimFile,
+    listDispatchClaims,
+    claimSummary,
+    validateDispatchEventOrThrow,
+    dispatchPickupEnvelope,
+    dispatchAuditEnvelope,
+  } = createRuntimeDispatchReadonlyArtifacts({
+    jsonSchemaVersion,
+    stateDirectoryName,
+    workflowFileName,
+    dispatchesDirectoryName,
+    dispatchClaimsDirectoryName,
+    workflowPath,
+    dispatchesDirectory,
+    dispatchClaimsDirectory,
+    forbiddenDispatchActions,
+    claimStaleAfterMs,
+    parseIsoTimestamp,
+    optionalFileDigest,
+    platformHints,
+    platformCapabilities,
+  });
+
+  const {
+    validateDispatchActor,
+    writeDispatchEvent,
+    claimDispatchEvent,
+    ackDispatchClaim,
+    dispatchClaimEnvelope,
+  } = createRuntimeDispatchStateLifecycleModel({
+    jsonSchemaVersion,
+    workflowPath,
+    dispatchesDirectory,
+    dispatchClaimsDirectory,
+    taskIdPattern,
+    taskIdRequirement,
+    windowsReservedTaskBasenames,
+    dispatchClaimFilePath,
+    dispatchEventFilePath,
+    readDispatchEventFile,
+    dispatchEventDigest,
+    claimAuditQuality,
+    listDispatchClaims,
+    claimSummary,
+    validateDispatchEventOrThrow,
+    dispatchClaimSafety,
+    readDispatchClaimFile,
+  });
+
+  function transitionGate(fromSkill, toSkill) {
+    const from = String(fromSkill || 'none').trim() || 'none';
+    const to = String(toSkill || 'none').trim() || 'none';
+    const isTerminal = to.toLowerCase() === 'none';
+    const allowed = isTerminal || allowedTransitions.has(`${from}->${to}`);
+
+    return {
+      from_skill: from,
+      to_skill: to,
+      allowed,
+      source: 'runtime-contract',
+    };
+  }
+
+  function gatePreview(state, advice) {
+    if (!state) {
+      return {
+        transition: transitionGate('none', 'none'),
+        stop_condition: 'clear',
+        review: 'not_recorded',
+        task_readiness: 'not_recorded',
+        dispatchable: false,
+        blockers: ['workflow state is not recorded'],
+      };
+    }
+
+    const tasks = tasksFromState(state);
+    const readiness = readinessCounts(tasks);
+    const review = reviewSummaryStatus(tasks);
+    const transition = transitionGate(advice.currentSkill, advice.nextSkill);
+    const blockers = [];
+    const stopStatus = hasActualStopCondition(state.stop_condition) ? 'blocked' : 'clear';
+    const taskReadinessStatus = readiness.waiting > 0 || readiness.blocked > 0 ? 'blocked' : 'passed';
+    const reviewStatus = review === 'needs_fix' ? 'blocked' : 'passed';
+
+    if (!transition.allowed) blockers.push('transition is not listed in runtime-contract');
+    if (stopStatus === 'blocked') blockers.push('stop_condition is set');
+    if (reviewStatus === 'blocked') blockers.push('review_status needs_fix is present');
+    if (taskReadinessStatus === 'blocked') blockers.push('task readiness has waiting or blocked items');
+    if (!advice.nextSkill || advice.nextSkill === 'none') blockers.push('next_skill is none');
+
+    return {
+      transition,
+      stop_condition: stopStatus,
+      review: reviewStatus,
+      task_readiness: taskReadinessStatus,
+      task_readiness_counts: readiness,
+      review_status: review,
+      dispatchable: blockers.length === 0,
+      blockers,
+    };
+  }
+
+function dispatchIntentEnvelope(state, advice) {
+  const gates = gatePreview(state, advice);
+  const targetSkill = state && gates.dispatchable ? advice.nextSkill : 'none';
+
+  return {
+    mode: 'dispatch-intent',
+    ok: true,
+    state_present: Boolean(state),
+    intent: {
+      type: 'workflow_skill',
+      from_skill: advice.currentSkill,
+      target_skill: targetSkill,
+      reason: advice.reason || '',
+      status: advice.status,
+      adapter_ready: Boolean(state) && gates.dispatchable,
+      entry_hint: targetSkill === 'none'
+        ? 'No adapter-ready workflow skill target is available.'
+        : 'Load target skill manually and continue from Workflow Handoff.',
+    },
+    gates,
+    runtimeBridge: adapterRuntimeBridge,
+    adapter_bridge: adapterRuntimeBridge,
+    platform_hints: platformHints,
+    safety: {
+      dry_run: true,
+      writes: false,
+      dispatch_event: false,
+      auto_execution: false,
+      subagent: false,
+      mcp: false,
+      daemon: false,
+      git: false,
+      worktree: false,
+    },
+    summary: {
+      status: advice.status,
+      current_skill: advice.currentSkill,
+      next_skill: advice.nextSkill,
+      manual_action: advice.manualAction,
+    },
+    tasks: state ? jsonTaskSummaries(tasksFromState(state)) : [],
+    quality: [],
+    action: 'dispatch intent was previewed. No workflow state was changed. No skill was executed.',
+  };
+}
+
+
+function printDispatchIntent(intent) {
+  console.log('Vibecoding Runtime Dispatch Intent');
+  console.log('Mode: dry-run dispatch-intent');
+  console.log(`Status: ${intent.intent.status}`);
+  console.log(`Adapter ready: ${intent.intent.adapter_ready ? 'yes' : 'no'}`);
+  console.log(`Current skill: ${intent.intent.from_skill}`);
+  console.log(`Target skill: ${intent.intent.target_skill}`);
+  console.log(`Transition gate: ${intent.gates.transition.allowed ? 'allowed' : 'blocked'} (${intent.gates.transition.from_skill} -> ${intent.gates.transition.to_skill})`);
+  console.log(`Stop gate: ${intent.gates.stop_condition}`);
+  console.log(`Review gate: ${intent.gates.review}`);
+  console.log(`Task readiness gate: ${intent.gates.task_readiness}`);
+  if (intent.gates.blockers.length > 0) printList('Blockers', intent.gates.blockers);
+  console.log(`Entry hint: ${intent.intent.entry_hint}`);
+  console.log('Safety: dry_run=true; writes=false; dispatch_event=false; auto_execution=false; subagent=false; git=false; worktree=false.');
+  console.log('Action: dispatch intent was previewed. No workflow state was changed. No skill was executed.');
+}
+
+
+function confirmDispatchEnvelope(state, advice) {
+  const gates = gatePreview(state, advice);
+  if (!state) gates.blockers.push('workflow state is not recorded');
+  if (advice.status !== 'ready') gates.blockers.push(`next advice status is ${advice.status}`);
+
+  const uniqueBlockers = [...new Set(gates.blockers)];
+  if (uniqueBlockers.length > 0) {
+    throw new Error(`confirm-dispatch gate failed: ${uniqueBlockers.join('; ')}`);
+  }
+
+  return {
+    mode: 'confirm-dispatch',
+    ok: true,
+    state_present: true,
+    dispatch: {
+      type: 'workflow_skill',
+      from_skill: advice.currentSkill,
+      target_skill: advice.nextSkill,
+      reason: advice.reason || '',
+      adapter_ready: true,
+      entry_hint: 'Load the target workflow skill and continue from Workflow Handoff.',
+    },
+    gates,
+    runtimeBridge: adapterRuntimeBridge,
+    adapter_bridge: adapterRuntimeBridge,
+    platform_hints: platformHints,
+    safety: {
+      confirmed: true,
+      allowed_transition: gates.transition.allowed,
+      stop_condition_clear: gates.stop_condition === 'clear',
+      review_gate: gates.review,
+      task_readiness_gate: gates.task_readiness,
+      dry_run: false,
+      writes: true,
+      dispatch_event: true,
+      auto_execution: false,
+      subagent: false,
+      mcp: false,
+      daemon: false,
+      git: false,
+      worktree: false,
+      forbidden_actions: forbiddenDispatchActions,
+    },
+    summary: {
+      status: advice.status,
+      current_skill: advice.currentSkill,
+      next_skill: advice.nextSkill,
+      manual_action: 'adapter-readable dispatch envelope was created; load the target workflow skill manually.',
+    },
+    tasks: jsonTaskSummaries(tasksFromState(state)),
+    quality: [],
+    action: 'dispatch envelope was created after allowed transition, review gate, and task readiness gate passed. No git, worktree, subagent, daemon, MCP, or business source file was modified.',
+  };
+}
+
+
+function printConfirmDispatch(envelope, file) {
+  console.log('Vibecoding Runtime Confirm Dispatch');
+  console.log('Mode: confirm-dispatch');
+  console.log('Status: ready');
+  console.log(`Adapter ready: ${envelope.dispatch.adapter_ready ? 'yes' : 'no'}`);
+  console.log(`Current skill: ${envelope.dispatch.from_skill}`);
+  console.log(`Target skill: ${envelope.dispatch.target_skill}`);
+  console.log(`Transition gate: ${envelope.gates.transition.allowed ? 'allowed' : 'blocked'} (${envelope.gates.transition.from_skill} -> ${envelope.gates.transition.to_skill})`);
+  console.log(`Review gate: ${envelope.gates.review}`);
+  console.log(`Task readiness gate: ${envelope.gates.task_readiness}`);
+  console.log(`Dispatch event: ${path.relative(process.cwd(), file)}`);
+  console.log('Safety: confirmed=true; writes=true; dispatch_event=true; auto_execution=false; subagent=false; mcp=false; daemon=false; git=false; worktree=false.');
+  console.log('Action: dispatch envelope was created. No git, worktree, subagent, daemon, MCP, or business source file was modified.');
+}
+
+
+
+
+function printDispatchPickup(envelope) {
+  console.log('Vibecoding Runtime Dispatch Pickup');
+  console.log('Mode: pickup');
+  console.log(`Platform: ${envelope.pickup.platform}`);
+  console.log(`Entry file: ${envelope.pickup.entry_file}`);
+  console.log(`Event: ${envelope.pickup.event_file}`);
+  console.log(`Current skill: ${envelope.pickup.from_skill}`);
+  console.log(`Target skill: ${envelope.pickup.target_skill}`);
+  console.log(`Claim: ${envelope.claim ? `${envelope.claim.status} by ${envelope.claim.actor}` : 'not claimed'}`);
+  console.log(`Readiness: ready_for_adapter=${envelope.readiness.ready_for_adapter ? 'true' : 'false'}; event_valid=${envelope.readiness.event_valid ? 'true' : 'false'}; claim_picked=${envelope.readiness.claim_picked ? 'true' : 'false'}; target_skill_present=${envelope.readiness.target_skill_present ? 'true' : 'false'}; entry_file_present=${envelope.readiness.entry_file_present ? 'true' : 'false'}`);
+  console.log(`Digests: event=${envelope.digests.event_sha256 || 'none'}; claim=${envelope.digests.claim_sha256 || 'none'}; workflow=${envelope.digests.workflow_sha256 || 'none'}; handoff=${envelope.digests.handoff_sha256 || 'none'}`);
+  console.log(`Pickup verification: ${envelope.pickup_verification.ok ? 'passed' : 'failed'}`);
+  console.log(`Platform capability: mode=${envelope.platform_capability.mode}; session_create=${envelope.platform_capability.session_create ? 'true' : 'false'}; platform_api=${envelope.platform_capability.platform_api ? 'true' : 'false'}; stdin_automation=${envelope.platform_capability.stdin_automation ? 'true' : 'false'}`);
+  console.log(`Adapter dry-run: simulated=${envelope.adapter_dry_run.simulated ? 'true' : 'false'}; no_session=${envelope.adapter_dry_run.no_session ? 'true' : 'false'}; would_write=${envelope.adapter_dry_run.would_write ? 'true' : 'false'}`);
+  console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+  console.log(`Manual instruction: ${envelope.pickup.manual_instruction}`);
+  if (envelope.quality.length > 0) printList('Warnings', envelope.quality);
+  console.log('Safety: read_only=true; writes=false; auto_claim=false; auto_execution=false; platform_api=false; session_create=false; subagent=false; mcp=false; daemon=false; git=false; worktree=false.');
+  console.log('Action: dispatch pickup package was generated for manual use. No claim was created, no skill execution, platform API, session creation, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+}
+
+
+function printDispatchPickupVerify(envelope) {
+  console.log('Vibecoding Runtime Dispatch Pickup Verification');
+  console.log('Mode: pickup-verify');
+  console.log(`Status: ${envelope.pickup_verification.ok ? 'passed' : 'failed'}`);
+  console.log(`Platform: ${envelope.pickup.platform}`);
+  console.log(`Entry file: ${envelope.pickup.entry_file}`);
+  console.log(`Readiness: ready_for_adapter=${envelope.readiness.ready_for_adapter ? 'true' : 'false'}`);
+  console.log(`Digests: event=${envelope.digests.event_sha256 || 'none'}; claim=${envelope.digests.claim_sha256 || 'none'}; workflow=${envelope.digests.workflow_sha256 || 'none'}; handoff=${envelope.digests.handoff_sha256 || 'none'}`);
+  if (envelope.pickup_verification.failures.length > 0) printList('Verification failures', envelope.pickup_verification.failures);
+  console.log('Action: pickup package was verified read-only. No claim, session, adapter call, skill execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+}
+
+
+function printDispatchPickupDryRun(envelope) {
+  console.log('Vibecoding Runtime Adapter Pickup Dry Run');
+  console.log('Mode: pickup-dry-run');
+  console.log(`Platform: ${envelope.pickup.platform}`);
+  console.log(`Entry file: ${envelope.adapter_dry_run.would_load_entry_file}`);
+  console.log(`Simulated: ${envelope.adapter_dry_run.simulated ? 'true' : 'false'}`);
+  console.log(`No session: ${envelope.adapter_dry_run.no_session ? 'true' : 'false'}`);
+  console.log(`Would call platform API: ${envelope.adapter_dry_run.would_call_platform_api ? 'true' : 'false'}`);
+  console.log(`Would create session: ${envelope.adapter_dry_run.would_create_session ? 'true' : 'false'}`);
+  console.log(`Would write: ${envelope.adapter_dry_run.would_write ? 'true' : 'false'}`);
+  console.log(`Handoff digest: ${envelope.digests.handoff_sha256}`);
+  console.log('Action: adapter pickup was simulated without session creation. No claim, adapter call, skill execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+}
+
+
+
+function printDispatchClaim(envelope) {
+  if (envelope.mode === 'dispatch-claims-list') {
+    console.log('Vibecoding Runtime Dispatch Claims');
+    console.log('Mode: list');
+    console.log(`Claims: ${envelope.summary.count}`);
+    for (const claim of envelope.claims) {
+      const stale = claim.audit?.stale ? 'stale=true' : 'stale=false';
+      const digest = claim.audit?.event_digest_matches ? 'digest=matched' : 'digest=mismatch';
+      console.log(`- ${claim.event_file}: ${claim.status} by ${claim.actor} [${stale}; ${digest}; reassign_allowed=${claim.recovery?.reassign_allowed ? 'true' : 'false'}]`);
+    }
+    if (envelope.quality.length > 0) printList('Warnings', envelope.quality);
+    console.log('Action: dispatch claim state was listed with stale/recovery audit. No skill execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+    return;
+  }
+
+  console.log('Vibecoding Runtime Dispatch Claim');
+  console.log(`Mode: ${envelope.mode === 'dispatch-ack' ? 'ack' : 'claim'}`);
+  console.log(`Event: ${envelope.claim.event_file}`);
+  console.log(`Actor: ${envelope.claim.actor}`);
+  console.log(`Status: ${envelope.claim.status}`);
+  if (envelope.claim.ack?.reason) console.log(`Reason: ${envelope.claim.ack.reason}`);
+  console.log(envelope.action.replace('dispatch event was claimed for manual pickup. ', 'Action: ').replace('dispatch claim acknowledgement was recorded. ', 'Action: '));
+}
+
+
+
+function printDispatchAudit(envelope) {
+  if (envelope.mode === 'dispatch-audit-list') {
+    console.log('Vibecoding Runtime Dispatch Audit');
+    console.log('Mode: list');
+    console.log(`Dispatches: ${envelope.summary.count}`);
+    for (const item of envelope.dispatches) {
+      console.log(`- ${item.file}: ${item.from_skill || 'none'} -> ${item.target_skill || 'none'} [${item.mode}; adapter_ready=${item.adapter_ready ? 'true' : 'false'}]`);
+    }
+    console.log('Action: read-only dispatch audit listed dispatch events. No skill execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+    return;
+  }
+
+  console.log('Vibecoding Runtime Dispatch Audit');
+  console.log(`Mode: ${envelope.mode === 'dispatch-audit-verify' ? 'verify' : 'show'}`);
+  console.log(`File: ${envelope.summary.file}`);
+  console.log(`Event mode: ${envelope.summary.mode}`);
+  console.log(`Current skill: ${envelope.summary.from_skill}`);
+  console.log(`Target skill: ${envelope.summary.target_skill}`);
+  console.log(`Adapter ready: ${envelope.summary.adapter_ready ? 'yes' : 'no'}`);
+  console.log(`Review gate: ${envelope.summary.review_gate}`);
+  console.log(`Task readiness gate: ${envelope.summary.task_readiness_gate}`);
+  console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+  if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+  console.log('Action: read-only dispatch audit inspected a dispatch event. No skill execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.');
+}
+
+
+function runDispatches(options) {
+  if (options.write || options.dryRun || options.confirm || options.dispatch || options.dispatchIntent) {
+    throw new Error('dispatches supports audit and claim state only; --dry-run, --write, --confirm, --dispatch, and --dispatch-intent are not supported');
+  }
+  const modes = [
+    options.dispatchList,
+    options.dispatchShow,
+    options.dispatchVerify,
+    options.dispatchClaim,
+    options.dispatchAck,
+    options.dispatchClaims,
+    options.dispatchPickup,
+    options.dispatchPickupVerify,
+    options.dispatchPickupDryRun,
+  ].filter(Boolean);
+  if (modes.length !== 1) throw new Error('dispatches requires exactly one of --list, --show, --verify, --claim, --ack, --claims, --pickup, --pickup-verify, or --pickup-dry-run');
+  ensureRoot(options.root);
+
+  if (options.dispatchPickup || options.dispatchPickupVerify || options.dispatchPickupDryRun) {
+    const envelope = dispatchPickupEnvelope(options.root, options.dispatchEvent, options.platform);
+    if (options.dispatchPickupVerify) {
+      if (options.json) {
+        writeJsonEnvelope('dispatches', { ...envelope, mode: 'dispatch-pickup-verify', ok: envelope.pickup_verification.ok });
+        return;
+      }
+      printDispatchPickupVerify(envelope);
+      return;
+    }
+    if (options.dispatchPickupDryRun) {
+      if (options.json) {
+        writeJsonEnvelope('dispatches', { ...envelope, mode: 'dispatch-pickup-dry-run' });
+        return;
+      }
+      printDispatchPickupDryRun(envelope);
+      return;
+    }
+    if (options.json) {
+      writeJsonEnvelope('dispatches', envelope);
+      return;
+    }
+    printDispatchPickup(envelope);
+    return;
+  }
+
+  if (options.dispatchClaim || options.dispatchAck || options.dispatchClaims) {
+    const mode = options.dispatchClaims ? 'claims' : options.dispatchClaim ? 'claim' : 'ack';
+    const envelope = dispatchClaimEnvelope(options.root, mode, options);
+    if (options.json) {
+      writeJsonEnvelope('dispatches', envelope);
+      return;
+    }
+    printDispatchClaim(envelope);
+    return;
+  }
+
+  const mode = options.dispatchList ? 'list' : options.dispatchVerify ? 'verify' : 'show';
+  const envelope = dispatchAuditEnvelope(options.root, mode, options.dispatchEvent);
+  if (options.json) {
+    writeJsonEnvelope('dispatches', envelope);
+    return;
+  }
+  printDispatchAudit(envelope);
+}
+
+
+  return {
+    runDispatches,
+    validateDispatchActor,
+    dispatchClaimFilePath,
+    dispatchEventFilePath,
+    dispatchIntentEnvelope,
+    printDispatchIntent,
+    confirmDispatchEnvelope,
+    writeDispatchEvent,
+    printConfirmDispatch,
+    dispatchEventSummary,
+    readDispatchEventFile,
+    dispatchEventDigest,
+    claimAudit,
+    claimAuditQuality,
+    listDispatchEvents,
+    verifyDispatchEvent,
+    dispatchClaimSafety,
+    readDispatchClaimFile,
+    listDispatchClaims,
+    claimSummary,
+    validateDispatchEventOrThrow,
+    dispatchAuditEnvelope,
+    dispatchClaimEnvelope,
+    dispatchPickupEnvelope,
+  };
+}