dsh-tower 2.0.3 → 2.1.0-beta.1

package/domain/integration/gate.js

@@ -0,0 +1,176 @@
+// Pure preflight/gate blocker computation from state snapshots plus the Git
+// facts the app already read (tips, changed files, checkout branch). The app
+// performs every read and owns the result assembly.
+// @ts-check
+import { fileInScope } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Blocker} Blocker */
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} missionId
+ * @returns {object}
+ */
+export function missingMissionGateResult(missionId) {
+  return {
+    ok: false,
+    blockers: [{ code: 'mission-missing', detail: `unknown mission "${missionId}"` }],
+    missionId,
+    branchTip: null,
+    baseTip: null,
+    changedFiles: [],
+    review: null,
+  }
+}
+
+/**
+ * @param {{ missionId: string, startedAt?: number }} mergeIntent
+ * @returns {Blocker}
+ */
+export function mergeIntentPendingBlocker(mergeIntent) {
+  return {
+    code: 'merge-intent-pending',
+    detail: `a merge intent for ${mergeIntent.missionId} was recorded at ${new Date(Number(mergeIntent.startedAt) || 0).toISOString()}; run tower_merge to reconcile it`,
+  }
+}
+
+/**
+ * @param {string} missionId
+ * @returns {Blocker}
+ */
+export function noWorktreeBlocker(missionId) {
+  return { code: 'branch-missing', detail: `mission ${missionId} has no worktree or branch` }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.branch
+ * @param {string} input.base
+ * @param {string} input.baseTip
+ * @returns {Blocker}
+ */
+export function staleBaseBlocker({ branch, base, baseTip }) {
+  return {
+    code: 'stale-base',
+    detail: `${branch} does not contain base "${base}" tip ${baseTip.slice(0, 12)}; run tower_rebase first`,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.missionId
+ * @param {string[]} input.changedFiles
+ * @returns {Blocker | null}
+ */
+export function surveyChangedFilesBlocker({ missionId, changedFiles }) {
+  return changedFiles.length > 0
+    ? {
+        code: 'read-only-survey',
+        detail: `survey ${missionId} is read-only but ${changedFiles.length} file(s) changed: ${changedFiles.slice(0, 5).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @param {object} input
+ * @param {Mission} input.mission
+ * @param {string[]} input.changedFiles
+ * @returns {Blocker | null}
+ */
+export function outOfScopeBlocker({ mission, changedFiles }) {
+  const outOfScope = changedFiles.filter((file) => !fileInScope(mission.scope, file))
+  return outOfScope.length > 0
+    ? {
+        code: 'out-of-scope',
+        detail: `changed files outside scope (${mission.scope.join(', ')}): ${outOfScope.slice(0, 8).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {string[]} dirty
+ * @returns {string[]}
+ */
+export function overwrittenPaths(changedFiles, dirty) {
+  return changedFiles.filter((file) => dirty.includes(file))
+}
+
+/**
+ * @param {string[]} wouldOverwrite
+ * @returns {Blocker | null}
+ */
+export function baseDirtyBlocker(wouldOverwrite) {
+  return wouldOverwrite.length > 0
+    ? {
+        code: 'base-dirty',
+        detail: `main checkout has uncommitted changes this merge would overwrite: ${wouldOverwrite.slice(0, 8).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @param {object} input
+ * @param {string[]} input.deps
+ * @param {TowerState} input.state
+ * @returns {Blocker[]}
+ */
+export function dependencyBlockers({ deps = [], state }) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  for (const depId of deps) {
+    const dep = state.missions.find((entry) => entry.id === depId)
+    if (!dep || !['merged', 'abandoned'].includes(dep.status)) {
+      blockers.push({ code: 'deps-unmerged', detail: `${depId} is ${dep ? dep.status : 'missing'}` })
+    }
+  }
+  return blockers
+}
+
+/**
+ * @param {object} input
+ * @param {string | null} input.checkoutBranch
+ * @param {string} input.base
+ * @returns {Blocker | null}
+ */
+export function baseWrongBranchBlocker({ checkoutBranch, base }) {
+  return checkoutBranch !== base
+    ? { code: 'base-wrong-branch', detail: `main checkout is on ${checkoutBranch ?? 'detached HEAD'}, expected "${base}"` }
+    : null
+}
+
+/**
+ * Append every blocker produced by a decision helper.
+ * @param {Blocker[]} blockers
+ * @param {Blocker | null} blocker
+ * @returns {Blocker[]}
+ */
+export function pushBlocker(blockers, blocker) {
+  if (blocker) blockers.push(blocker)
+  return blockers
+}
+
+/**
+ * @param {object} input
+ * @param {object} input.mission full mission projection
+ * @param {object | null} input.worktree
+ * @param {string | null} input.branchTip
+ * @param {string | null} input.baseTip
+ * @param {string[]} input.changedFiles
+ * @param {object | null} input.review
+ * @param {Blocker[]} input.blockers
+ * @returns {object}
+ */
+export function gateResult({ mission, worktree, branchTip, baseTip, changedFiles, review, blockers }) {
+  return {
+    ok: blockers.length === 0,
+    blockers,
+    mission,
+    worktree,
+    branchTip,
+    baseTip,
+    changedFiles,
+    review,
+  }
+}

package/domain/integration/init.js

@@ -0,0 +1,225 @@
+// Pure init decisions: explicit/fallback base selection, ownership and reanchor
+// policy, snapshot decisions, and the initial/existing result projections. All
+// fs/git work and state persistence stay in app/init.js.
+// @ts-check
+import { SCHEMA_VERSION, TERMINAL_STATUSES } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+export const SNAPSHOT_REF_PREFIX = 'refs/tower/snapshot/'
+
+/**
+ * @param {string} commit
+ * @returns {string}
+ */
+export function snapshotRefFor(commit) {
+  return `${SNAPSHOT_REF_PREFIX}${commit}`
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function explicitBase(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+/**
+ * An explicit base must be a local branch name, never a raw ref or remote ref.
+ * @param {string} base
+ * @returns {string | null} the failure message, or null when valid
+ */
+export function invalidBaseMessage(base) {
+  return /^refs\//.test(base) || base.startsWith('origin/') ? `base must be a local branch name, not ${base}` : null
+}
+
+/**
+ * Without an explicit base, use the checked-out branch and fall back to `main`
+ * only for an unborn repository.
+ * @param {object} input
+ * @param {string | null} [input.branch]
+ * @param {boolean} input.committed
+ * @returns {{ base: string } | { error: string }}
+ */
+export function fallbackBase({ branch, committed }) {
+  let base = branch
+  if (!base && !committed) base = 'main'
+  if (!base) return { error: 'repository is in detached HEAD; pass an explicit local base branch' }
+  return { base }
+}
+
+/**
+ * @param {string | null} owner
+ * @param {string | null} caller
+ * @returns {boolean}
+ */
+export function ownedByOther(owner, caller) {
+  return Boolean(owner && caller && owner !== caller)
+}
+
+/**
+ * @param {string | null} owner
+ * @param {string | null} caller
+ * @returns {string | null} the caller that claims an unowned state
+ */
+export function claimCaller(owner, caller) {
+  return !owner && caller ? caller : null
+}
+
+/**
+ * @param {Mission[]} missions
+ * @returns {string | null} refusal message, or null when reanchor may proceed
+ */
+export function reanchorBlockedMessage(missions) {
+  const active = missions.filter((mission) => !TERMINAL_STATUSES.has(mission.status))
+  return active.length > 0 ? `cannot reanchor base while ${active.length} mission(s) are not merged or abandoned` : null
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} input.reanchor
+ * @param {string | null} input.reanchorBase
+ * @param {string} input.currentBase
+ * @returns {boolean}
+ */
+export function shouldReanchor({ reanchor, reanchorBase, currentBase }) {
+  return reanchor === true && reanchorBase !== currentBase
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} input.snapshotDirty
+ * @param {boolean} input.dirty
+ * @returns {boolean}
+ */
+export function shouldSnapshot({ snapshotDirty, dirty }) {
+  return snapshotDirty === true && dirty
+}
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {string} input.statePath
+ * @param {boolean} input.dirty
+ * @returns {object}
+ */
+export function existingInitResult({ state, statePath, dirty }) {
+  return {
+    created: false,
+    repoRoot: state.repoRoot,
+    commonDir: state.commonDir,
+    statePath,
+    base: state.base,
+    revision: state.revision,
+    missions: state.missions.length,
+    reanchored: false,
+    dirty,
+    snapshotCommit: state.snapshotCommit ?? null,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.commonDir
+ * @param {string} input.base
+ * @param {boolean} input.dirty
+ * @param {string | null} [input.towerAgentId]
+ * @param {string | null} [input.snapshotCommit]
+ * @param {string | null} [input.snapshotRef]
+ * @param {number} input.now
+ * @returns {TowerState}
+ */
+export function initialState({ repoRoot, commonDir, base, dirty, towerAgentId = null, snapshotCommit = null, snapshotRef = null, now }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    repoRoot,
+    commonDir,
+    base,
+    revision: 0,
+    createdAt: now,
+    updatedAt: now,
+    dirtyBase: dirty,
+    ...(towerAgentId ? { towerAgentId: String(towerAgentId) } : {}),
+    ...(snapshotCommit ? { snapshotCommit, snapshotRef } : {}),
+    missions: [],
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.commonDir
+ * @param {string} input.statePath
+ * @param {string} input.base
+ * @param {boolean} input.dirty
+ * @param {string | null} input.snapshotCommit
+ * @param {string | null} input.snapshotRef
+ * @returns {object}
+ */
+export function createdInitResult({ repoRoot, commonDir, statePath, base, dirty, snapshotCommit, snapshotRef }) {
+  return {
+    created: true,
+    repoRoot,
+    commonDir,
+    statePath,
+    base,
+    revision: 0,
+    missions: 0,
+    reanchored: false,
+    dirty,
+    snapshotCommit,
+    snapshotRef,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {string} input.statePath
+ * @param {boolean} input.dirty
+ * @param {boolean} input.reanchored
+ * @returns {object}
+ */
+export function existingInitWriteResult({ state, statePath, dirty, reanchored }) {
+  return {
+    created: false,
+    repoRoot: state.repoRoot,
+    commonDir: state.commonDir,
+    statePath,
+    base: state.base,
+    revision: state.revision,
+    missions: state.missions.length,
+    reanchored,
+    dirty,
+    snapshotCommit: state.snapshotCommit ?? null,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.base
+ * @param {string | null} [input.snapshotCommit]
+ * @param {boolean} input.dirty
+ * @returns {string}
+ */
+export function initActivityText({ base, snapshotCommit = null, dirty }) {
+  return `base ${base}${snapshotCommit ? ` snapshot ${snapshotCommit.slice(0, 12)}` : ''}${dirty ? ' (dirty base)' : ''}`
+}
+
+/**
+ * @param {string} caller
+ * @returns {string}
+ */
+export function ownerClaimActivityText(caller) {
+  return `tower owner claimed by ${caller}`
+}
+
+/**
+ * @param {string} base
+ * @returns {string}
+ */
+export function reanchorActivityText(base) {
+  return `base reanchored to ${base}`
+}

package/domain/integration/liveness.js

@@ -0,0 +1,31 @@
+// Pure roster-liveness decisions shared by rebase/teardown guards. A live
+// worker is a roster row for the mission that is neither inactive nor finished
+// and whose observed activity is "running".
+// @ts-check
+import { ROSTER_INACTIVE } from '../roster.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @param {Record<string, string | undefined>} activity
+ * @returns {RosterEntry | undefined}
+ */
+export function liveAgentFor(state, missionId, activity) {
+  return (state.roster ?? []).find(
+    (entry) =>
+      entry.missionId === missionId && !ROSTER_INACTIVE.has(entry.state) && activity[String(entry.agentId)] === 'running',
+  )
+}
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @param {Record<string, string | undefined>} activity
+ * @returns {boolean}
+ */
+export function hasLiveAgent(state, missionId, activity) {
+  return liveAgentFor(state, missionId, activity) !== undefined
+}