@ran-sh/dsh-crew 0.3.0

package/src/workflow.mjs

@@ -0,0 +1,160 @@
+// Unified job workflow: the shared state machine + structured outcome that
+// every worker job goes through, whether it was started with dsh_run_worker
+// (blocking) or dsh_spawn_worker (async). run and spawn differ only in whether
+// the caller awaits the job; the business steps — created → running →
+// verifying → (escalating | reviewing) → ready/completed/failed — are the
+// same, driven by evidence rather than by which transport started the job.
+//
+// Everything in this module is a pure function (no DSH, hub or worker runtime,
+// no I/O), so the workflow rules are unit-testable in isolation. The runtime
+// layers stamp phase + outcome through these helpers so server.mjs stays a
+// transport adapter.
+
+import { evaluateAttempt } from './policy.mjs';
+import { parseDeliveryReport } from './delivery.mjs';
+
+export const JOB_PHASES = Object.freeze({
+  CREATED: 'created',
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  VERIFYING: 'verifying',
+  ESCALATING: 'escalating',
+  REVIEWING: 'reviewing',
+  READY: 'ready',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+  INTERRUPTED: 'interrupted',
+});
+
+const TERMINAL_PHASES = new Set([JOB_PHASES.COMPLETED, JOB_PHASES.FAILED, JOB_PHASES.CANCELLED, JOB_PHASES.INTERRUPTED]);
+
+export function isTerminalPhase(phase) {
+  return TERMINAL_PHASES.has(phase);
+}
+
+// Legal phase transitions (pure guard — the runtime never just assigns a phase).
+const ALLOWED_TRANSITIONS = {
+  [JOB_PHASES.CREATED]: [JOB_PHASES.QUEUED, JOB_PHASES.RUNNING, JOB_PHASES.CANCELLED, JOB_PHASES.FAILED],
+  [JOB_PHASES.QUEUED]: [JOB_PHASES.RUNNING, JOB_PHASES.CANCELLED],
+  [JOB_PHASES.RUNNING]: [JOB_PHASES.VERIFYING, JOB_PHASES.REVIEWING, JOB_PHASES.CANCELLED, JOB_PHASES.FAILED],
+  [JOB_PHASES.VERIFYING]: [JOB_PHASES.ESCALATING, JOB_PHASES.REVIEWING, JOB_PHASES.READY, JOB_PHASES.FAILED, JOB_PHASES.CANCELLED],
+  [JOB_PHASES.ESCALATING]: [JOB_PHASES.RUNNING, JOB_PHASES.CANCELLED, JOB_PHASES.FAILED],
+  [JOB_PHASES.REVIEWING]: [JOB_PHASES.READY, JOB_PHASES.FAILED, JOB_PHASES.CANCELLED],
+  [JOB_PHASES.READY]: [JOB_PHASES.COMPLETED, JOB_PHASES.FAILED, JOB_PHASES.CANCELLED],
+};
+
+/**
+ * May a workflow transition from one phase to another? Terminal phases never
+ * leave. A terminal destination is allowed only from a non-terminal phase;
+ * every non-terminal transition must be listed above.
+ */
+export function canTransition(from, to) {
+  const fromKey = from ?? JOB_PHASES.CREATED;
+  if (isTerminalPhase(fromKey)) return false;
+  if (isTerminalPhase(to)) return true;
+  const allowed = ALLOWED_TRANSITIONS[fromKey];
+  if (!allowed) return false;
+  return allowed.includes(to);
+}
+
+function splitSection(value) {
+  if (typeof value !== 'string' || value.trim() === '') return [];
+  return value.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+}
+
+function parseTests(section) {
+  return splitSection(section).map((line) => {
+    const m = line.match(/^(?:[-*+]\s+)?(PASS|FAIL|NOT RUN)\s+—\s+(.+?)\s+—\s+(.+)$/);
+    if (!m) return { line };
+    const [, status, command, summary] = m;
+    return { status, command: command.trim(), summary: summary.trim() };
+  });
+}
+
+/**
+ * Classify a worker run into a canonical task status. Completion of the
+ * process is not success: FAIL/not-run tests and missing delivery all downgrade
+ * the verdict. Returns 'success' | 'partial' | 'blocked' | 'failed'.
+ */
+export function classifyTaskStatus({ executionStatus = 'completed', testsStatus, deliveryComplete = true, deliveryMissing = [] } = {}) {
+  void deliveryMissing;
+  if (executionStatus !== 'completed') return 'failed';
+  if (testsStatus === 'FAIL') return 'partial';
+  if (!deliveryComplete) return 'blocked';
+  if (testsStatus === 'NOT RUN') return 'partial';
+  return 'success';
+}
+
+/**
+ * Normalize a worker's final message (+ delivery metadata) into the canonical
+ * structured outcome the workflow consumes. The Markdown Delivery Report stays
+ * the human-readable layer; this is the runtime's internal standard.
+ */
+export function buildOutcome({ result = '', deliveryMeta, executionStatus, stopReason, deliveryMissing } = {}) {
+  const parsed = parseDeliveryReport(result);
+  const testsStatus = parsed.tests_status ?? deliveryMeta?.tests_status;
+  const tests = parseTests(parsed.sections.Tests);
+  const execStatus = executionStatus ?? (stopReason === 'completed' ? 'completed' : 'failed');
+  return {
+    execution_status: execStatus,
+    task_status: classifyTaskStatus({
+      executionStatus: execStatus,
+      testsStatus,
+      deliveryComplete: parsed.complete,
+      deliveryMissing: deliveryMissing ?? parsed.missing,
+    }),
+    confidence: null,
+    needs_escalation: false,
+    changes: splitSection(parsed.sections.Diff),
+    tests,
+    tests_status: testsStatus ?? null,
+    risks: splitSection(parsed.sections.Risks),
+    unverified: splitSection(parsed.sections.Unverified),
+    delivery: {
+      complete: parsed.complete,
+      missing: [...(parsed.missing ?? [])],
+      format: parsed.format,
+      sections: [...(parsed.present ?? [])],
+    },
+  };
+}
+
+/**
+ * Decide what happens next after a worker attempt completes. Pure: consumes
+ * the canonical outcome + the role's model policy + the attempt number, and
+ * returns the workflow step (accept / escalate / review / fail) with a reason.
+ * This is the single rule for blocking AND async jobs — server.mjs only
+ * transports the result.
+ */
+export function decideNextStep({ outcome, policy, attempt = 0, reviewRequested = false, reviewerAuto = false } = {}) {
+  const o = outcome ?? {};
+  const evaluation = evaluateAttempt({
+    execution: o.execution_status,
+    taskStatus: o.task_status,
+    testsStatus: o.tests_status,
+    deliveryComplete: o.delivery?.complete,
+    workspaceEvidenceOK: o.workspace_evidence_ok !== false,
+    policy,
+    attempt,
+  });
+  if (evaluation.decision === 'escalate') {
+    return { step: 'escalate', phase: JOB_PHASES.ESCALATING, reason: evaluation.reason, evaluation };
+  }
+  if (reviewRequested && reviewerAuto && evaluation.decision === 'accept') {
+    return { step: 'review', phase: JOB_PHASES.REVIEWING, reason: 'review requested', evaluation };
+  }
+  if (evaluation.decision === 'accept') {
+    return { step: 'accept', phase: JOB_PHASES.READY, reason: 'verified', evaluation };
+  }
+  return { step: 'fail', phase: JOB_PHASES.FAILED, reason: evaluation.reason ?? 'no accept path', evaluation };
+}
+
+/**
+ * Pure run/spawn parity check helper: given the same spec + outcome, blocking
+ * and async jobs must reach the same next step. Exported for tests so the
+ * "run and spawn share one workflow" guarantee is asserted directly.
+ */
+export function parityStep(spec) {
+  return decideNextStep(spec).step;
+}

package/src/workspace-audit.mjs

@@ -0,0 +1,231 @@
+// Read-only workspace auditing for the auditable-delivery flow. Captures a
+// before/after snapshot of a git working tree (status / stat / name-status)
+// plus a bounded, redacted patch, so an orchestrator can review exactly what a
+// worker changed before accepting the result.
+//
+// Discipline: strictly read-only. Only git porcelain reads are issued — never
+// reset / stash / clean / checkout, and nothing here writes to disk. A
+// non-git directory degrades to { kind: 'no-git' } instead of failing, and a
+// pre-dirty workspace is flagged (dirtyBaseline) rather than hidden.
+//
+// The default `git` runner is replaceable with an injected runner in tests:
+// it receives (argsArray, { cwd }) and resolves { code, stdout, stderr }.
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { win32 } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export const DIFF_LIMIT = 64 * 1024;
+export const NOT_A_GIT_REPOSITORY = 'NOT_A_GIT_REPOSITORY';
+export const GIT_NOT_FOUND = 'GIT_NOT_FOUND';
+export const GIT_TIMEOUT = 'GIT_TIMEOUT';
+export const GIT_TIMEOUT_MS = 8000;
+
+const SENSITIVE_SUFFIXES = ['.pem', '.key'];
+const SENSITIVE_PREFIXES = ['credentials', 'secret'];
+const ENV_BASENAME = '.env';
+
+/**
+ * True when a path looks like a credential/secret file whose patch content
+ * must be redacted: .env / .env.*, credentials*, secrets*, *.pem, *.key.
+ * The file's name-status entry stays visible — only the patch is hidden.
+ */
+export function isSensitivePath(relPath) {
+  const segments = String(relPath ?? '').replace(/\\/g, '/').split('/');
+  return segments.some((raw) => {
+    const seg = raw.toLowerCase();
+    if (seg === ENV_BASENAME || seg.startsWith(`${ENV_BASENAME}.`)) return true;
+    if (SENSITIVE_PREFIXES.some((p) => seg.startsWith(p))) return true;
+    return SENSITIVE_SUFFIXES.some((s) => seg.endsWith(s));
+  });
+}
+
+let resolvedGitExecutable = 'git';
+
+export async function resolveWindowsGit({ exec = execFileAsync, env = process.env, exists = existsSync } = {}) {
+  try {
+    const located = await exec('where.exe', ['git'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+    const first = String(located.stdout ?? '').split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+    if (first) return first;
+  } catch {}
+  // Always compose candidate paths with Windows semantics. This helper is
+  // unit-tested on non-Windows hosts too, and host-native path.join() would
+  // otherwise turn C:\\... inputs into mixed/invalid paths on POSIX.
+  const candidates = [
+    env.ProgramFiles && win32.join(env.ProgramFiles, 'Git', 'cmd', 'git.exe'),
+    env.ProgramFiles && win32.join(env.ProgramFiles, 'Git', 'bin', 'git.exe'),
+    env.LOCALAPPDATA && win32.join(env.LOCALAPPDATA, 'Programs', 'Git', 'cmd', 'git.exe'),
+  ].filter(Boolean);
+  return candidates.find((candidate) => exists(candidate));
+}
+
+async function defaultRunner(args, { cwd }) {
+  let out;
+  try {
+    out = await execFileAsync(resolvedGitExecutable, args, { cwd, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
+  } catch (error) {
+    const missing = error?.code === 'ENOENT' || /spawn git ENOENT/i.test(error?.message ?? '');
+    if (!missing || process.platform !== 'win32' || resolvedGitExecutable !== 'git') throw error;
+    const fallback = await resolveWindowsGit();
+    if (!fallback) throw error;
+    resolvedGitExecutable = fallback;
+    out = await execFileAsync(resolvedGitExecutable, args, { cwd, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
+  }
+  return { code: 0, stdout: out.stdout ?? '', stderr: out.stderr ?? '' };
+}
+
+/** Run one git read; normalize failure into a no-git reason, never throws. */
+async function runGit(runner, args, opts) {
+  try {
+    const r = await runner(args, opts);
+    const stderr = r.stderr ?? '';
+    if (/not a git repository/i.test(stderr)) {
+      return { ok: false, reason: NOT_A_GIT_REPOSITORY, error: stderr.trim() };
+    }
+    return { ok: true, code: r.code ?? 0, stdout: r.stdout ?? '', stderr };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    if (err?.code === 'ETIMEDOUT' || err?.killed === true || /timed out|timeout/i.test(msg)) return { ok: false, reason: GIT_TIMEOUT, error: 'git audit timed out' };
+    if (/ENOENT|spawn git/i.test(msg)) return { ok: false, reason: GIT_NOT_FOUND, error: msg };
+    return { ok: false, reason: NOT_A_GIT_REPOSITORY, error: msg };
+  }
+}
+
+function splitFirstTab(line) {
+  const i = line.indexOf('\t');
+  return i === -1 ? [line, ''] : [line.slice(0, i), line.slice(i + 1)];
+}
+
+/**
+ * Parse `git diff --name-status` + `git status --porcelain` into structured
+ * change lists used by the patch builder. Renames/copies fold onto their
+ * destination path (the diff shows them there); untracked `??` rows are listed
+ * separately because git does not diff them read-only.
+ */
+export function parseChanges(nameStatus, statusPorcelain) {
+  const modified = [];
+  const deleted = [];
+  const renamed = [];
+  for (const line of String(nameStatus ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const [code, rest] = splitFirstTab(trimmed);
+    const paths = rest.split('\t').filter(Boolean);
+    if (paths.length === 0) continue;
+    const x = code[0] ?? '';
+    const y = code[1] ?? '';
+    if (y === 'D' || x === 'D') { deleted.push(paths[paths.length - 1]); continue; }
+    if (x === 'R' || x === 'C') { renamed.push(paths[0]); modified.push(paths[paths.length - 1]); continue; }
+    modified.push(paths[paths.length - 1]);
+  }
+  const untracked = String(statusPorcelain ?? '').split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith('??'))
+    .map((l) => l.slice(2).trim())
+    .filter(Boolean);
+  return {
+    modified: [...new Set(modified)],
+    deleted: [...new Set(deleted)],
+    renamed: [...new Set(renamed)],
+    untracked: [...new Set(untracked)],
+  };
+}
+
+/**
+ * Read-only pre-run snapshot of a workspace. Returns a git snapshot
+ * { kind:'git', status, nameStatus, stat, dirty, changes } or a degraded
+ * { kind:'no-git', reason, error } for non-repos / missing git. Never throws.
+ */
+export async function captureWorkspaceBaseline({ cwd, git } = {}) {
+  const runner = git ?? defaultRunner;
+  if (!cwd) return { kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace cwd is required' };
+  const [status, nameStatus, stat] = await Promise.all([
+    runGit(runner, ['status', '--porcelain'], { cwd }),
+    runGit(runner, ['diff', '--name-status'], { cwd }),
+    runGit(runner, ['diff', '--stat'], { cwd }),
+  ]);
+  for (const r of [status, nameStatus, stat]) {
+    if (!r.ok) return { kind: 'no-git', reason: r.reason, error: r.error };
+  }
+  const changes = parseChanges(nameStatus.stdout, status.stdout);
+  return {
+    kind: 'git',
+    status: status.stdout,
+    nameStatus: nameStatus.stdout,
+    stat: stat.stdout,
+    dirty: changes.modified.length + changes.deleted.length + changes.renamed.length + changes.untracked.length > 0,
+    changes,
+  };
+}
+
+/** Build the bounded, redacted patch for the changed (tracked) paths. */
+async function buildPatch(runner, { cwd, changes, limit }) {
+  const { modified, deleted, untracked } = changes;
+  const nonSensitive = [...new Set([...modified, ...deleted])].filter((p) => !isSensitivePath(p));
+  const sensitive = [...new Set([...modified, ...deleted])].filter((p) => isSensitivePath(p));
+  const redacted = [];
+  let patch = '';
+  if (nonSensitive.length > 0) {
+    const r = await runGit(runner, ['diff', '--binary', '--', ...nonSensitive], { cwd });
+    if (!r.ok) return { failed: true, reason: r.reason, error: r.error };
+    patch += r.stdout;
+  }
+  for (const p of sensitive) {
+    redacted.push(p);
+    patch += `diff --git a/${p} b/${p}\n[REDACTED SENSITIVE FILE]\n`;
+  }
+  for (const p of untracked) {
+    if (isSensitivePath(p)) {
+      redacted.push(p);
+      patch += `[REDACTED SENSITIVE FILE: ${p} (untracked)]\n`;
+    } else {
+      patch += `[UNTRACKED FILE: ${p} (content not diffed read-only)]\n`;
+    }
+  }
+  let truncated = false;
+  if (Buffer.byteLength(patch, 'utf8') > limit) {
+    patch = Buffer.from(patch, 'utf8').subarray(0, limit).toString('utf8');
+    truncated = true;
+  }
+  return { failed: false, patch, truncated, redacted };
+}
+
+/**
+ * Read-only post-run snapshot: the after-state (status / stat / name-status)
+ * plus the bounded, redacted patch of everything the worker changed.
+ * `dirtyBaseline` records whether the workspace was already dirty before the
+ * worker started (the diff may then include pre-existing changes). Never
+ * throws; degrades to { kind:'no-git' } like captureWorkspaceBaseline.
+ */
+export async function captureWorkspaceDiff({ cwd, baseline, git, limit = DIFF_LIMIT } = {}) {
+  const runner = git ?? defaultRunner;
+  if (!cwd) return { kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace cwd is required' };
+  if (!baseline || baseline.kind !== 'git') {
+    return { kind: 'no-git', reason: baseline?.reason ?? NOT_A_GIT_REPOSITORY, error: baseline?.error };
+  }
+  const [status, nameStatus, stat] = await Promise.all([
+    runGit(runner, ['status', '--porcelain'], { cwd }),
+    runGit(runner, ['diff', '--name-status'], { cwd }),
+    runGit(runner, ['diff', '--stat'], { cwd }),
+  ]);
+  for (const r of [status, nameStatus, stat]) {
+    if (!r.ok) return { kind: 'no-git', reason: r.reason, error: r.error };
+  }
+  const changes = parseChanges(nameStatus.stdout, status.stdout);
+  const patch = await buildPatch(runner, { cwd, changes, limit });
+  if (patch.failed) return { kind: 'no-git', reason: patch.reason, error: patch.error };
+  return {
+    kind: 'git',
+    status: status.stdout,
+    nameStatus: nameStatus.stdout,
+    stat: stat.stdout,
+    patch: patch.patch,
+    truncated: patch.truncated,
+    redacted: patch.redacted,
+    dirtyBaseline: baseline.dirty === true,
+    changes,
+  };
+}