dsh-tower 2.0.4 → 2.1.0

package/domain/integration/provision.js

@@ -0,0 +1,124 @@
+// Pure provision decisions: branch slug, base-commit choice, worktree root and
+// path resolution, and result/activity projections. Git worktree creation and
+// state persistence stay in app/provision.js.
+// @ts-check
+import path from 'node:path'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').MissionWorktree} MissionWorktree */
+
+/**
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function slugify(title) {
+  const slug = String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 24)
+  return slug || 'mission'
+}
+
+/**
+ * @param {Mission} mission
+ * @returns {string}
+ */
+export function worktreeBranch(mission) {
+  return `tower/${mission.id.toLowerCase()}-${slugify(mission.title)}`
+}
+
+/**
+ * Pick the base commit from the explicit argument, the requested base ref, or
+ * the recorded dirty snapshot. `source: 'base'` means the caller must rev-parse
+ * the configured base (the only I/O in the choice).
+ * @param {object} input
+ * @param {unknown} [input.baseCommit]
+ * @param {unknown} [input.includeDirtyBase]
+ * @param {string | null} [input.snapshotCommit]
+ * @param {boolean} [input.snapshotCommitValid]
+ * @returns {{ source: 'explicit' | 'snapshot', commit: string } | { source: 'base' }}
+ */
+export function baseCommitChoice({ baseCommit, includeDirtyBase, snapshotCommit = null, snapshotCommitValid = false }) {
+  if (baseCommit) return { source: 'explicit', commit: String(baseCommit) }
+  if (includeDirtyBase === false) return { source: 'base' }
+  if (snapshotCommit && snapshotCommitValid) return { source: 'snapshot', commit: snapshotCommit }
+  return { source: 'base' }
+}
+
+/**
+ * @param {object} input
+ * @param {string | null} [input.worktreeRoot]
+ * @param {string | null} [input.configuredRoot]
+ * @param {string} input.repoRoot
+ * @param {string} input.commonDirHash
+ * @returns {string}
+ */
+export function worktreeRoot({ worktreeRoot = null, configuredRoot = null, repoRoot, commonDirHash }) {
+  if (worktreeRoot) return path.resolve(worktreeRoot)
+  if (configuredRoot) return path.resolve(configuredRoot)
+  return path.join(path.dirname(repoRoot), '.dsh-tower-worktrees', commonDirHash)
+}
+
+/**
+ * @param {string} root
+ * @param {string} missionId
+ * @returns {string}
+ */
+export function worktreePath(root, missionId) {
+  return path.join(root, missionId)
+}
+
+/**
+ * @param {unknown} missionId
+ * @returns {boolean}
+ */
+export function hasMissionId(missionId) {
+  return typeof missionId === 'string' && missionId.trim().length > 0
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.path
+ * @param {string} input.branch
+ * @param {string} input.baseCommit
+ * @param {number} input.createdAt
+ * @param {string | null} [input.realPath]
+ * @returns {MissionWorktree}
+ */
+export function worktreeRecord({ path: wtPath, branch, baseCommit, createdAt, realPath = null }) {
+  return /** @type {MissionWorktree} */ ({
+    path: wtPath,
+    branch,
+    baseCommit,
+    createdAt,
+    ...(realPath === null ? {} : { realPath }),
+  })
+}
+
+/**
+ * @param {Mission} mission
+ * @param {MissionWorktree} worktree
+ * @returns {{ mission: Mission, worktree: MissionWorktree, created: false }}
+ */
+export function existingWorktreeResult(mission, worktree) {
+  return { mission, worktree, created: false }
+}
+
+/**
+ * @param {Mission} mission
+ * @param {MissionWorktree} worktree
+ * @returns {{ mission: Mission, worktree: MissionWorktree, created: true }}
+ */
+export function createdWorktreeResult(mission, worktree) {
+  return { mission, worktree, created: true }
+}
+
+/**
+ * @param {string} branch
+ * @param {string} wtPath
+ * @returns {string}
+ */
+export function provisionActivityText(branch, wtPath) {
+  return `${branch} at ${wtPath}`
+}

package/domain/integration/rebase.js

@@ -0,0 +1,236 @@
+// Pure rebase decisions: the prepared snapshot, durable-intent classification,
+// replay/conflict outcomes, and the strings recorded for reconciliation.
+// Git reads/writes and persistence stay in app/rebase.js.
+// @ts-check
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+export const STALE_PREPARE = 'tower state changed while the rebase was being prepared; retry'
+export const STALE_ACT =
+  'tower state changed while the rebase was running; the rebase intent is retained so the next tower_rebase can reconcile it; retry'
+
+/**
+ * @param {string | null | undefined} tip
+ * @returns {string}
+ */
+export function shortTip(tip) {
+  return String(tip ?? '').slice(0, 7)
+}
+
+/**
+ * @param {RosterEntry} agent
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function workerBusyResult(agent) {
+  return { ok: false, blockers: [{ code: 'worker-busy', detail: `agent ${agent.name} is running; rebase refused` }] }
+}
+
+/**
+ * @param {string} path
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function dirtyWorktreeResult(path) {
+  return { ok: false, blockers: [{ code: 'worktree-dirty', detail: `${path} has uncommitted changes` }] }
+}
+
+/**
+ * Rewriting an already-landed branch would destroy the reviewed tip.
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.base
+ * @returns {object}
+ */
+export function alreadyMergedRebaseResult({ oldTip, baseTip, base }) {
+  return {
+    ok: true,
+    alreadyMerged: true,
+    skipped: true,
+    oldTip,
+    newTip: oldTip,
+    baseTip,
+    note: `${oldTip.slice(0, 7)} is already contained in ${base} ${baseTip.slice(0, 7)}; branch left untouched — call tower_merge to record the landed merge`,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @returns {object}
+ */
+export function alreadyUpToDateResult({ oldTip, baseTip }) {
+  return { ok: true, alreadyUpToDate: true, oldTip, newTip: oldTip, baseTip }
+}
+
+/**
+ * Both tips must still match the prepared snapshot before the branch rewrite.
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.currentTip
+ * @param {string} input.currentBase
+ * @returns {boolean}
+ */
+export function rebaseTipsMoved({ oldTip, baseTip, currentTip, currentBase }) {
+  return currentTip !== oldTip || currentBase !== baseTip
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.currentTip
+ * @param {string} input.currentBase
+ * @returns {string}
+ */
+export function rebaseTipsMovedDetail({ oldTip, baseTip, currentTip, currentBase }) {
+  return `tips moved after preparation (${shortTip(oldTip)}/${shortTip(baseTip)} -> ${shortTip(currentTip)}/${shortTip(currentBase)}), so nothing was rebased`
+}
+
+/**
+ * Malformed durable intents are refused rather than guessed.
+ * @param {unknown} intent
+ * @returns {boolean}
+ */
+export function malformedRebaseIntent(intent) {
+  const record = /** @type {Record<string, unknown> | null} */ (intent)
+  return (
+    typeof record !== 'object' ||
+    record === null ||
+    typeof record.missionId !== 'string' ||
+    typeof record.token !== 'string'
+  )
+}
+
+/**
+ * Classify the durable intent from the observed worktree tip. Only the two
+ * unambiguous outcomes are recordable; anything else stays pending.
+ * @param {object} input
+ * @param {{ oldTip: string, baseTip: string, commits?: number | null }} input.intent
+ * @param {Mission | undefined} input.mission
+ * @param {string} [input.tip]
+ * @param {boolean} input.tipReadable
+ * @param {boolean} input.baseIsAncestor
+ * @param {number | null} [input.actualCommits]
+ * @returns {{ action: 'clear' | 'ambiguous' | 'record', reason?: string, tip?: string }}
+ */
+export function classifyRebaseIntent({ intent, mission, tip, tipReadable, baseIsAncestor, actualCommits = null }) {
+  if (!mission || !mission.worktree || typeof mission.worktree.path !== 'string') {
+    return { action: 'clear', reason: 'the mission has no worktree' }
+  }
+  if (!tipReadable) return { action: 'clear', reason: 'the worktree is not readable' }
+  if (tip === intent.oldTip) {
+    return { action: 'clear', reason: 'the branch tip is unchanged (the rebase never ran)' }
+  }
+  if (!baseIsAncestor) return { action: 'ambiguous', tip }
+  if (intent.commits !== null && intent.commits !== undefined) {
+    if (actualCommits !== Number(intent.commits)) return { action: 'ambiguous', tip }
+  }
+  return { action: 'record', tip }
+}
+
+/**
+ * @param {{ missionId: string, startedAt?: number }} intent
+ * @param {string | undefined} tip
+ * @returns {string}
+ */
+export function ambiguousRebaseIntentMessage(intent, tip) {
+  return `a rebase intent for ${intent.missionId} from ${new Date(Number(intent.startedAt) || 0).toISOString()} is pending and cannot be reconciled automatically (tip ${shortTip(tip)} does not match the prepared snapshot); finish or abort the rebase in that worktree, then retry`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.token
+ * @param {string} input.missionId
+ * @param {string} input.base
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {number | null} input.commits
+ * @param {number} input.startedAt
+ * @returns {object}
+ */
+export function buildRebaseIntent({ token, missionId, base, oldTip, baseTip, commits, startedAt }) {
+  return { token, missionId, base, oldTip, baseTip, commits, startedAt }
+}
+
+/**
+ * @param {string} base
+ * @param {string} baseTip
+ * @returns {string}
+ */
+export function rebaseConflictNote(base, baseTip) {
+  return `rebase conflict onto ${base} @ ${baseTip.slice(0, 12)}`
+}
+
+/**
+ * @param {string} detail
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function rebaseConflictResult(detail) {
+  return { ok: false, blockers: [{ code: 'rebase-conflict', detail }] }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {{ ok: true, oldTip: string, newTip: string, baseTip: string, reviewWaived: true }}
+ */
+export function rebaseSuccessResult({ oldTip, newTip, baseTip }) {
+  return { ok: true, oldTip, newTip, baseTip, reviewWaived: true }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseSuccessNote({ oldTip, newTip, baseTip }) {
+  return `rebased ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}; conflict-free rebase waives re-review`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseReconcileNote({ oldTip, newTip, baseTip }) {
+  return `reconciled interrupted rebase ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}; the clean rebase waiver is preserved`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseActivityText({ oldTip, newTip, baseTip }) {
+  return `${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseReconcileActivityText({ oldTip, newTip, baseTip }) {
+  return `reconciled ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}`
+}
+
+/**
+ * @param {string | undefined} reason
+ * @returns {string}
+ */
+export function clearedRebaseIntentActivityText(reason) {
+  return `cleared a stale rebase intent (${reason})`
+}

package/domain/integration/review.js

@@ -0,0 +1,52 @@
+// Pure review-selection and exemption decisions shared by the merge/gate/read
+// projections. No repository I/O.
+// @ts-check
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Review} Review */
+/** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
+
+/**
+ * Reviews are branch-scoped; a missing branch has no reviews.
+ * @param {Review[] | null | undefined} reviews
+ * @param {string | null} branch
+ * @returns {Review[]}
+ */
+export function reviewsForBranch(reviews, branch) {
+  return branch ? (reviews ?? []).filter((review) => review.branch === branch) : []
+}
+
+/**
+ * The latest review round, or null when the branch has no reviews.
+ * @param {Review[]} reviews
+ * @returns {Review | null}
+ */
+export function latestReview(reviews) {
+  return reviews.length > 0 ? reviews.reduce((left, right) => (left.round >= right.round ? left : right)) : null
+}
+
+/**
+ * A mission may skip review only with both the exemption gate and a reason.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {boolean}
+ */
+export function isReviewExempt(mission, config = {}) {
+  return (
+    config.review?.requireReview === false ||
+    (mission.reviewPolicy === 'none' &&
+      config.gates?.allowReviewExemption === true &&
+      String(mission.reviewExemptionReason ?? '').trim().length > 0)
+  )
+}
+
+/**
+ * `reviewPolicy: none` is invalid when the reviewer gate does not allow it.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {boolean}
+ */
+export function reviewExemptionInvalid(mission, config = {}) {
+  const requireReview = config.review?.requireReview !== false
+  return requireReview && mission.reviewPolicy === 'none' && config.gates?.allowReviewExemption !== true
+}

package/domain/integration/teardown.js

@@ -0,0 +1,118 @@
+// Pure teardown decisions: keep/remove eligibility and the revalidation of a
+// prepared candidate. Worktree ownership checks and git removals stay in
+// app/teardown.js.
+// @ts-check
+import { hasLiveAgent } from './liveness.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+export const STALE_TEARDOWN = 'tower state changed while teardown was being prepared; retry'
+
+/** @typedef {{ missionId: string, action: string, reason?: string, forced?: boolean }} Decision */
+
+/**
+ * Replace a decision object in place so mission order is preserved.
+ * @param {Decision} decision
+ * @param {Record<string, unknown>} value
+ * @returns {void}
+ */
+export function replaceDecision(decision, value) {
+  const missionId = decision.missionId
+  for (const key of Object.keys(decision)) delete /** @type {Record<string, unknown>} */ (decision)[key]
+  Object.assign(decision, { missionId, ...value })
+}
+
+/**
+ * Snapshot-only eligibility before ownership/dirty diagnostics run.
+ * `skip` means the mission has no removable worktree; `decision` is a keep
+ * outcome; `proceed` means the caller must run the ownership/dirty checks.
+ * @param {Mission} mission
+ * @param {object} input
+ * @param {boolean} [input.excluded]
+ * @param {boolean} [input.hasLiveAgent]
+ * @returns {{ skip: true } | { decision: Decision } | { proceed: true }}
+ */
+export function teardownPrecheck(mission, { excluded = false, hasLiveAgent = false } = {}) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  if (!record.worktree || record.worktreeRemovedAt) return { skip: true }
+  if (excluded) return { decision: { missionId: mission.id, action: 'keep', reason: 'excluded' } }
+  if (hasLiveAgent) return { decision: { missionId: mission.id, action: 'keep', reason: 'live agent' } }
+  if (!['merged', 'abandoned'].includes(mission.status)) {
+    return { decision: { missionId: mission.id, action: 'keep', reason: `mission is ${mission.status}` } }
+  }
+  return { proceed: true }
+}
+
+/**
+ * @param {string} missionId
+ * @param {unknown} error
+ * @returns {Decision}
+ */
+export function ownershipUnverifiedDecision(missionId, error) {
+  return {
+    missionId,
+    action: 'keep',
+    reason: `worktree ownership/registration unverified: ${String(/** @type {{ message?: unknown }} */ (error)?.message ?? error).slice(0, 240)}`,
+  }
+}
+
+/**
+ * @param {boolean} dirty
+ * @param {boolean} [force]
+ * @returns {{ action: 'keep', reason: string } | null}
+ */
+export function teardownDirtyDecision(dirty, force) {
+  return dirty && force !== true ? { action: 'keep', reason: 'uncommitted changes' } : null
+}
+
+/**
+ * @param {boolean} dirty
+ * @returns {{ action: 'remove', reason: 'eligible', forced: boolean }}
+ */
+export function teardownRemoveDecision(dirty) {
+  return { action: 'remove', reason: 'eligible', forced: dirty }
+}
+
+/**
+ * Revalidate a prepared candidate against the current state. Used both before
+ * the git lock and again after re-reading state inside it.
+ * @param {TowerState} state
+ * @param {{ missionId: string, worktree: { path: string } }} candidate
+ * @param {Record<string, string | undefined>} [activity]
+ * @returns {{ ok: true, mission: Mission } | { ok: false, reason: string }}
+ */
+export function revalidateTeardownCandidate(state, candidate, activity = {}) {
+  const mission = state.missions.find((entry) => entry.id === candidate.missionId)
+  const record = mission ? /** @type {Record<string, any>} */ (mission) : null
+  if (!record || !record.worktree || record.worktreeRemovedAt) return { ok: false, reason: 'worktree is already gone' }
+  if (record.worktree.path !== candidate.worktree.path) {
+    return { ok: false, reason: 'worktree path changed during teardown' }
+  }
+  if (!['merged', 'abandoned'].includes(record.status)) return { ok: false, reason: `mission is ${record.status}` }
+  if (hasLiveAgent(state, record.id, activity)) return { ok: false, reason: 'live agent' }
+  return { ok: true, mission: /** @type {Mission} */ (mission) }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.branch
+ * @param {string | null} [input.branchDeleteError]
+ * @returns {{ action: 'removed', branch: string, branchRetained?: true, branchDeleteError?: string }}
+ */
+export function teardownRemovedDecision({ branch, branchDeleteError = null }) {
+  return {
+    action: 'removed',
+    branch,
+    ...(branchDeleteError ? { branchRetained: true, branchDeleteError } : {}),
+  }
+}
+
+/**
+ * @param {string} branch
+ * @param {string | null} [branchDeleteError]
+ * @returns {string}
+ */
+export function teardownActivityText(branch, branchDeleteError = null) {
+  return `${branch}${branchDeleteError ? ' (branch retained)' : ''}`
+}

package/domain/mission.js

@@ -0,0 +1,68 @@
+// Pure mission vocabulary and transition rules (#49). No fs, git, or config.
+// @ts-check
+
+/** @typedef {import('../types/index.js').FindingSeverity} FindingSeverity */
+/** @typedef {import('../types/index.js').FindingStatus} FindingStatus */
+/** @typedef {import('../types/index.js').FindingType} FindingType */
+/** @typedef {import('../types/index.js').MergeVerdict} MergeVerdict */
+/** @typedef {import('../types/index.js').MissionStatus} MissionStatus */
+
+/** @type {readonly MissionStatus[]} */
+export const MISSION_STATUSES = ['planned', 'active', 'completed', 'blocked', 'paused', 'merged', 'abandoned']
+export const SCHEMA_VERSION = 3
+/** @type {readonly MergeVerdict[]} */
+export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
+export const REVIEW_STATUS_RE = /^(clean|p1-\d+items|p2-\d+items)$/
+/** @type {ReadonlySet<string>} */
+export const TERMINAL_STATUSES = new Set(['merged', 'abandoned'])
+/** @type {readonly FindingType[]} */
+export const FINDING_TYPES = ['bug', 'improve', 'vuln', 'idea']
+/** @type {readonly FindingSeverity[]} */
+export const FINDING_SEVERITIES = ['low', 'medium', 'high', 'critical']
+/** @type {readonly FindingStatus[]} */
+export const FINDING_STATUSES = ['open', 'triaged', 'fixed', 'wontfix']
+/** @type {Record<string, readonly string[]>} */
+export const FINDING_TRANSITIONS = {
+  open: ['triaged', 'fixed', 'wontfix'],
+  triaged: ['open', 'fixed', 'wontfix'],
+  fixed: ['open'],
+  wontfix: ['open'],
+}
+/** @type {readonly string[]} */
+export const PAUSE_CAUSES = ['user', 'failure', 'resource', 'dependency']
+/** @type {Record<string, readonly string[] | undefined>} */
+export const TRANSITIONS = {
+  planned: ['active', 'abandoned'],
+  active: ['completed', 'blocked', 'paused', 'abandoned'],
+  blocked: ['active', 'paused', 'completed', 'abandoned'],
+  paused: ['active', 'abandoned'],
+  completed: ['active', 'abandoned'],
+  merged: [],
+  abandoned: [],
+}
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status)
+}
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return (TRANSITIONS[from] ?? []).includes(to)
+}
+
+/**
+ * @param {string | null | undefined} [value]
+ * @returns {string | null}
+ */
+export function pauseCauseError(value) {
+  if (value === undefined || value === null || value === '') return null
+  return PAUSE_CAUSES.includes(value) ? null : `pause_cause must be one of ${PAUSE_CAUSES.join('|')}`
+}