dsh-tower 2.0.3 → 2.1.0-beta.1

package/domain/missions/findings.js

@@ -0,0 +1,201 @@
+// Pure finding normalization, filtering, and transition policy.
+//
+// app/findings.js owns loading state, the writer lock, sequence assignment,
+// persistence, and the activity entry.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { FINDING_SEVERITIES, FINDING_STATUSES, FINDING_TRANSITIONS, FINDING_TYPES } from '../mission.js'
+import { countFindings, findingSummary } from '../summary.js'
+
+/** @typedef {import('../../types/index.js').Finding} Finding */
+/** @typedef {import('../../types/index.js').Mission} Mission */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isNonEmpty(value) {
+  return value !== undefined && value !== null && value !== ''
+}
+
+/**
+ * Validate and project the user-supplied fields of a new finding.
+ * @param {any} input
+ * @param {Mission[]} missions
+ * @returns {any}
+ */
+export function normalizeFindingInput(input, missions) {
+  if (!FINDING_TYPES.includes(input.type)) {
+    fail(`finding type must be one of ${FINDING_TYPES.join('|')}`)
+  }
+  const title = String(input.title ?? '').trim()
+  if (!title) fail('finding title is required')
+  const summary = String(input.summary ?? '').trim()
+  if (!summary) fail('finding summary is required')
+  const details = String(input.details ?? '').trim()
+  if (!details) fail('finding details are required')
+  const suggestedFix = String(input.suggested_fix ?? '').trim()
+  if (!suggestedFix) fail('finding suggested_fix is required')
+  const severity = input.severity ?? null
+  if (severity !== null && !FINDING_SEVERITIES.includes(severity)) {
+    fail(`finding severity must be one of ${FINDING_SEVERITIES.join('|')}`)
+  }
+  let mission = null
+  if (isNonEmpty(input.missionId)) {
+    mission = missions.find((entry) => entry.id === input.missionId) ?? null
+    if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  }
+  return {
+    type: input.type,
+    title,
+    severity,
+    summary,
+    location: typeof input.location === 'string' && input.location.trim() ? input.location.trim() : null,
+    details,
+    suggested_fix: suggestedFix,
+    missionId: mission ? mission.id : null,
+    branch: mission && mission.worktree ? mission.worktree.branch : null,
+  }
+}
+
+/**
+ * Project the complete finding record that gets persisted.
+ * @param {any} fields
+ * @param {{ seq: number, now: number, reportedBy: unknown }} params
+ * @returns {Finding}
+ */
+export function newFinding(fields, { seq, now, reportedBy }) {
+  return {
+    id: `F${seq}`,
+    seq,
+    ...fields,
+    reportedBy,
+    at: now,
+    status: 'open',
+  }
+}
+
+/**
+ * @param {any} actor
+ * @returns {{ name: string, role: string }}
+ */
+export function normalizeFindingActor(actor) {
+  const resolved = actor ?? { name: 'tower', role: 'tower' }
+  if (typeof resolved.role !== 'string') fail('finding actor role must be a string')
+  return resolved
+}
+
+/**
+ * @param {any} input
+ * @returns {boolean}
+ */
+export function wantsFindingUpdate(input) {
+  const hasId = isNonEmpty(input.id)
+  return hasId && (input.status !== undefined || input.note !== undefined)
+}
+
+/**
+ * Pure read/list projection. Throws on an unknown id or an invalid filter.
+ * @param {Finding[]} findings
+ * @param {any} input
+ * @returns {any}
+ */
+export function readFindingsView(findings, input) {
+  const counts = countFindings(findings)
+  if (isNonEmpty(input.id)) {
+    const finding = findings.find((entry) => entry.id === input.id)
+    if (!finding) fail(`unknown finding "${input.id}"`, 'finding-not-found')
+    return { finding: { ...finding }, counts, total: findings.length, filtered: 1, action: 'read' }
+  }
+  if (input.status !== undefined && input.status !== 'all') {
+    if (!FINDING_STATUSES.includes(input.status)) {
+      fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+    }
+  }
+  let visible = findings
+  if (input.status !== undefined && input.status !== 'all') {
+    visible = visible.filter((finding) => (finding.status ?? 'open') === input.status)
+  }
+  if (input.type !== undefined) {
+    if (!FINDING_TYPES.includes(input.type)) fail(`finding type must be one of ${FINDING_TYPES.join('|')}`)
+    visible = visible.filter((finding) => finding.type === input.type)
+  }
+  if (input.severity !== undefined) {
+    if (!FINDING_SEVERITIES.includes(input.severity)) {
+      fail(`finding severity must be one of ${FINDING_SEVERITIES.join('|')}`)
+    }
+    visible = visible.filter((finding) => finding.severity === input.severity)
+  }
+  if (isNonEmpty(input.missionId)) {
+    visible = visible.filter((finding) => finding.missionId === input.missionId)
+  }
+  if (input.open === true) {
+    visible = visible.filter((finding) => !['fixed', 'wontfix'].includes(finding.status ?? 'open'))
+  }
+  const limit = Math.max(1, Math.min(200, Number.isInteger(input.limit) ? input.limit : 50))
+  const page = visible.slice(-limit).reverse()
+  return {
+    findings: page.map((finding) => findingSummary(finding)),
+    counts,
+    total: findings.length,
+    filtered: visible.length,
+    action: 'list',
+  }
+}
+
+/**
+ * Apply one finding lifecycle transition to the draft finding.
+ * @param {{ finding: Finding, input: any, actor: { name: string, role: string }, now: number }} params
+ * @returns {{ noteAdded: boolean }}
+ */
+export function applyFindingUpdate({ finding, input, actor, now }) {
+  if (actor.role === 'reviewer') {
+    fail('reviewers may list and read findings, but only the tower or a worker may change finding status', 'not-authorized')
+  }
+  let noteAdded = false
+  if (input.status !== undefined) {
+    if (input.status === 'all') {
+      fail('finding status "all" is only a list filter; pass a concrete status when updating')
+    }
+    if (!FINDING_STATUSES.includes(input.status)) {
+      fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+    }
+    const current = finding.status ?? 'open'
+    const allowed = FINDING_TRANSITIONS[current] ?? []
+    if (!allowed.includes(input.status)) {
+      fail(`finding ${finding.id} cannot move from ${current} to ${input.status}`, 'invalid-transition')
+    }
+    finding.status = input.status
+    if (input.status === 'fixed' || input.status === 'wontfix') finding.closedAt = now
+    else delete finding.closedAt
+  }
+  if (input.note !== undefined) {
+    if (typeof input.note !== 'string' || input.note.trim().length === 0) {
+      fail('finding note must be a non-empty string')
+    }
+    const record = /** @type {any} */ (finding)
+    if (!Array.isArray(record.notes)) record.notes = []
+    record.notes.push({ by: actor.name, at: now, text: input.note.trim() })
+    noteAdded = true
+  }
+  finding.updatedAt = now
+  return { noteAdded }
+}
+
+/**
+ * @param {Finding} finding
+ * @param {Finding[]} all
+ * @returns {any}
+ */
+export function findingUpdateView(finding, all) {
+  return { finding: { ...finding }, counts: countFindings(all), total: all.length, filtered: 1, action: 'updated' }
+}

package/domain/missions/lifecycle.js

@@ -0,0 +1,185 @@
+// Pure mission lifecycle transition policy.
+//
+// app/mission.js supplies the loaded mission/state and persists the result;
+// this module owns the authorization and transition rules and mutates only the
+// in-memory mission draft it is given.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { MISSION_STATUSES, TERMINAL_STATUSES, canTransition, pauseCauseError } from '../mission.js'
+import { normalizeScope, scopesOverlap } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+const TERMINAL = TERMINAL_STATUSES
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizePauseCause(value) {
+  const error = pauseCauseError(/** @type {string | null | undefined} */ (value))
+  if (error) fail(error)
+  return value === undefined || value === null || value === '' ? 'user' : /** @type {string} */ (value)
+}
+
+/**
+ * Reject actor/input combinations a worker may not perform. The tower owns
+ * status, scope, blockers, and pause metadata; a worker only reports work.
+ * @param {Mission} mission
+ * @param {{ name?: string, role?: string }} actor
+ * @param {any} input
+ * @returns {void}
+ */
+export function assertMissionActor(mission, actor, input) {
+  const workerRequest = actor.role === 'worker'
+  if (actor.role === 'reviewer') {
+    fail('only the tower or a worker may update a mission; reviewers submit tower_review', 'not-authorized')
+  }
+  if (workerRequest && mission.owner && mission.owner !== actor.name) {
+    fail(`worker ${actor.name} does not own mission ${mission.id} (owner: ${mission.owner})`, 'not-authorized')
+  }
+  if (workerRequest) {
+    if (input.status !== undefined) {
+      fail('only the tower can change mission status directly; workers report completion with tower_complete', 'not-authorized')
+    }
+    if (input.scope !== undefined) fail('only the tower can change mission scope', 'not-authorized')
+    if (input.clear_blockers === true) fail('only the tower can clear blockers', 'not-authorized')
+    if (input.pause_cause !== undefined || input.authorization !== undefined) {
+      fail('only the tower can record pause/authorization metadata', 'not-authorized')
+    }
+  }
+}
+
+/**
+ * Apply one validated `tower_mission` patch to the mission draft and return
+ * the human-readable change list used by the activity log.
+ * @param {{ mission: Mission, state: TowerState, input: any, config: any }} params
+ * @returns {{ changes: string[] }}
+ */
+export function applyMissionUpdate({ mission, state, input, config }) {
+  const actor = input.actor ?? { name: 'tower', role: 'tower' }
+  assertMissionActor(mission, actor, input)
+  if (input.pause_cause !== undefined && input.status !== 'paused') {
+    fail('pause_cause is only valid together with status "paused"')
+  }
+  if (input.status === 'abandoned' && (typeof input.note !== 'string' || input.note.trim().length === 0)) {
+    fail('abandoning a mission requires a non-empty note (reason)')
+  }
+  /** @type {string[]} */
+  const changes = []
+
+  if (input.status !== undefined) {
+    if (typeof input.status !== 'string' || !MISSION_STATUSES.includes(input.status)) {
+      fail(`unknown mission status "${input.status}"`)
+    }
+    if (input.status === 'merged') {
+      fail('merged is recorded only by tower_merge, not by a generic mission patch', 'invalid-transition')
+    }
+    if (!canTransition(mission.status, input.status)) {
+      fail(`mission ${mission.id} cannot move from ${mission.status} to ${input.status}`, 'invalid-transition')
+    }
+    if (input.status === 'paused') {
+      mission.pauseCause = normalizePauseCause(input.pause_cause)
+    }
+    if (mission.status === 'paused' && input.status === 'active') {
+      const requireAuthorization = config.mode.requireResumeAuthorization === true
+      if (requireAuthorization && (mission.pauseCause ?? 'user') === 'user') {
+        if (typeof input.authorization !== 'string' || input.authorization.trim().length === 0) {
+          fail('resuming a user-paused mission requires a non-empty authorization reference')
+        }
+      }
+      if (typeof input.authorization === 'string' && input.authorization.trim()) {
+        mission.authorizationRef = input.authorization.trim()
+      }
+    }
+    mission.status = input.status
+    changes.push(`status=${input.status}`)
+  }
+
+  if (input.task_done !== undefined) {
+    const needle = String(input.task_done)
+    const tasks = /** @type {any[]} */ (mission.tasks)
+    const task = tasks.find(
+      (entry) => entry.status === 'open' && entry.text.toLowerCase().includes(needle.toLowerCase()),
+    )
+    if (!task) fail(`no open task matching "${needle}" in mission ${mission.id}`)
+    task.status = 'done'
+    changes.push(`task_done="${task.text}"`)
+  }
+
+  if (input.task_drop !== undefined) {
+    if (typeof input.task_drop_reason !== 'string' || input.task_drop_reason.trim().length === 0) {
+      fail('task_drop requires task_drop_reason')
+    }
+    const needle = String(input.task_drop)
+    const tasks = /** @type {any[]} */ (mission.tasks)
+    const task = tasks.find(
+      (entry) => entry.status === 'open' && entry.text.toLowerCase().includes(needle.toLowerCase()),
+    )
+    if (!task) fail(`no open task matching "${needle}" in mission ${mission.id}`)
+    task.status = 'dropped'
+    task.note = input.task_drop_reason.trim()
+    const notes = /** @type {string[]} */ (mission.notes)
+    notes.push(`task dropped: ${task.text} — ${task.note}`)
+    changes.push(`task_drop="${task.text}"`)
+  }
+
+  if (input.blocker !== undefined) {
+    if (typeof input.blocker !== 'string' || input.blocker.trim().length === 0) {
+      fail('blocker must be a non-empty string')
+    }
+    if (TERMINAL.has(mission.status)) {
+      fail(`mission ${mission.id} is ${mission.status}; a blocker cannot reopen a terminal mission`)
+    }
+    const blockers = /** @type {string[]} */ (mission.blockers)
+    blockers.push(input.blocker.trim())
+    mission.status = 'blocked'
+    changes.push('blocker added')
+  }
+
+  if (input.clear_blockers === true) {
+    mission.blockers = []
+    changes.push('blockers cleared')
+  }
+
+  if (input.note !== undefined) {
+    if (typeof input.note !== 'string' || input.note.trim().length === 0) {
+      fail('note must be a non-empty string')
+    }
+    const notes = /** @type {string[]} */ (mission.notes)
+    notes.push(input.note.trim())
+    changes.push('note added')
+  }
+
+  if (input.scope !== undefined) {
+    if (!['active', 'completed'].includes(mission.status)) {
+      fail(`scope can only be widened for active or completed missions, not ${mission.status}`)
+    }
+    const scope = normalizeScope(input.scope, { allowEmpty: mission.kind === 'survey' })
+    const others = state.missions.filter(
+      (entry) => entry.id !== mission.id && !TERMINAL.has(entry.status) && entry.kind !== 'survey',
+    )
+    for (const other of others) {
+      if (mission.kind !== 'survey' && scopesOverlap(scope, other.scope)) {
+        fail(`widened scope overlaps mission ${other.id}; retire it or add an explicit ordering`)
+      }
+    }
+    mission.scope = scope
+    mission.scopeGeneration = (mission.scopeGeneration ?? 1) + 1
+    mission.status = 'active'
+    changes.push('scope widened')
+  }
+
+  if (changes.length === 0) fail('tower_mission requires at least one change')
+  return { changes }
+}

package/domain/missions/plan.js

@@ -0,0 +1,149 @@
+// Pure mission planning input normalization and projections.
+//
+// The use case in app/plan.js owns the state lock, load, persistence, and the
+// activity entry; everything here is deterministic and repository-free.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { normalizeScope, validateTitle } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Validate and normalize one `tower_plan` mission entry.
+ * @param {any} input
+ * @param {number} index
+ * @returns {any}
+ */
+export function normalizeMissionInput(input, index) {
+  if (!isPlainObject(input)) fail(`missions[${index}] must be an object`)
+  const title = validateTitle(input.title)
+  const kind = input.kind === 'survey' ? 'survey' : 'build'
+  const scope = normalizeScope(input.scope ?? [], { allowEmpty: kind === 'survey' })
+  /** @type {Array<{ text: string, status: string }>} */
+  const tasks = []
+  if (input.tasks !== undefined) {
+    if (!Array.isArray(input.tasks)) fail(`missions[${index}].tasks must be an array of strings`)
+    for (const task of input.tasks) {
+      if (typeof task !== 'string' || task.trim().length === 0) {
+        fail(`missions[${index}].tasks entries must be non-empty strings`)
+      }
+      tasks.push({ text: task.trim(), status: 'open' })
+    }
+  }
+  /** @type {string[]} */
+  const deps = []
+  if (input.deps !== undefined) {
+    if (!Array.isArray(input.deps)) fail(`missions[${index}].deps must be an array of mission ids`)
+    for (const dep of input.deps) {
+      if (typeof dep !== 'string' || dep.trim().length === 0) {
+        fail(`missions[${index}].deps entries must be non-empty mission ids`)
+      }
+      if (!deps.includes(dep.trim())) deps.push(dep.trim())
+    }
+  }
+  const context = typeof input.context === 'string' ? input.context.slice(0, 4096) : ''
+  /** @type {string[]} */
+  const references = []
+  if (input.references !== undefined) {
+    if (!Array.isArray(input.references)) fail(`missions[${index}].references must be an array of pointers`)
+    if (input.references.length > 20) fail(`missions[${index}].references supports at most 20 pointers`)
+    for (const reference of input.references) {
+      if (typeof reference !== 'string' || reference.trim().length === 0) {
+        fail(`missions[${index}].references entries must be non-empty strings`)
+      }
+      if (!references.includes(reference.trim())) references.push(reference.trim())
+    }
+  }
+  const reviewPolicy = input.reviewPolicy === undefined ? 'required-clean' : input.reviewPolicy
+  if (!['required-clean', 'none'].includes(reviewPolicy)) {
+    fail(`missions[${index}].reviewPolicy must be "required-clean" or "none"`)
+  }
+  const reviewExemptionReason = typeof input.reviewExemptionReason === 'string' ? input.reviewExemptionReason.trim() : ''
+  if (reviewPolicy === 'none' && reviewExemptionReason.length === 0) {
+    fail(`missions[${index}].reviewPolicy "none" requires a non-empty reviewExemptionReason`)
+  }
+  return { title, kind, scope, tasks, deps, context, references, reviewPolicy, reviewExemptionReason }
+}
+
+/**
+ * Validate the plan envelope and normalize every mission entry.
+ * @param {any} input
+ * @returns {any[]}
+ */
+export function normalizePlanMissions(input) {
+  if (!Array.isArray(input.missions) || input.missions.length === 0) {
+    fail('tower_plan needs at least one mission')
+  }
+  return input.missions.map((mission, index) => normalizeMissionInput(mission, index))
+}
+
+/**
+ * Assign the next contiguous mission ids without mutating the input.
+ * @param {any[]} prepared
+ * @param {number} start
+ * @returns {any[]}
+ */
+export function assignMissionIds(prepared, start) {
+  return prepared.map((mission, index) => ({ ...mission, id: `M${start + index}` }))
+}
+
+/**
+ * Every explicit dependency must name an existing or newly assigned mission.
+ * @param {any[]} assigned
+ * @param {Mission[]} existingMissions
+ * @returns {void}
+ */
+export function assertKnownDependencies(assigned, existingMissions) {
+  const known = new Set([...existingMissions.map((mission) => mission.id), ...assigned.map((mission) => mission.id)])
+  for (const mission of assigned) {
+    for (const dep of mission.deps) {
+      if (!known.has(dep)) fail(`mission ${mission.id} depends on unknown mission "${dep}"`)
+    }
+  }
+}
+
+/**
+ * Project a normalized, id-assigned input into a fresh mission record.
+ * @param {string} id
+ * @param {any} input
+ * @param {number} now
+ * @returns {Mission}
+ */
+export function newMission(id, input, now) {
+  return /** @type {Mission} */ (/** @type {any} */ ({
+    id,
+    title: input.title,
+    kind: input.kind,
+    scope: input.scope,
+    tasks: input.tasks,
+    deps: input.deps,
+    context: input.context,
+    references: input.references ?? [],
+    reviewPolicy: input.reviewPolicy ?? 'required-clean',
+    reviewExemptionReason: input.reviewExemptionReason ?? '',
+    status: 'planned',
+    owner: null,
+    blockers: [],
+    notes: [],
+    reviews: [],
+    scopeGeneration: 1,
+    createdAt: now,
+    updatedAt: now,
+  }))
+}