dsh-tower 2.0.3 → 2.1.0-beta.1

package/domain/scope.js

@@ -0,0 +1,105 @@
+import { TowerToolError } from './errors.js'
+// Pure scope helpers shared by planning and gates.
+// @ts-check
+const GLOB_META = /[*?[{]/
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function globToRegExp(pattern) {
+  let out = '^'
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*') {
+      if (pattern[index + 1] === '*') {
+        out += '.*'
+        index += 1
+      } else {
+        out += '[^/]*'
+      }
+    } else if (char === '?') {
+      out += '[^/]'
+    } else {
+      out += char.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  return new RegExp(`${out}$`)
+}
+
+/**
+ * @param {string[] | null | undefined} scope
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function fileInScope(scope, file) {
+  return (scope ?? []).some((pattern) => globToRegExp(pattern).test(file))
+}
+
+/**
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function validateTitle(title) {
+  if (typeof title !== 'string' || title.trim().length === 0) fail('mission title is required')
+  if (!/^[\x20-\x7E]+$/.test(title)) fail(`mission title must be printable ASCII: ${JSON.stringify(title)}`)
+  return title.trim()
+}
+
+/**
+ * @param {unknown} scope
+ * @param {{ allowEmpty?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function normalizeScope(scope, { allowEmpty = false } = {}) {
+  if (!Array.isArray(scope)) fail('mission scope must be an array of relative globs')
+  if (scope.length === 0 && !allowEmpty) fail('mission scope must not be empty for a build mission')
+  /** @type {string[]} */
+  const out = []
+  for (const raw of scope) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) fail('scope entries must be non-empty strings')
+    const value = raw.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '').trim()
+    if (value.length === 0) fail('scope entries must be non-empty strings')
+    if (value.startsWith('/') || /^[A-Za-z]:/.test(value)) fail(`scope must be relative: ${raw}`)
+    if (value.split('/').some((part) => part === '..')) fail(`scope must not contain "..": ${raw}`)
+    if (!out.includes(value)) out.push(value)
+  }
+  return out
+}
+
+/**
+ * @param {string} pattern
+ * @returns {string}
+ */
+function scopePrefix(pattern) {
+  const index = pattern.search(GLOB_META)
+  const literal = index < 0 ? pattern : pattern.slice(0, index)
+  return literal.replace(/\/+$/, '')
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {boolean}
+ */
+export function scopesOverlap(a, b) {
+  for (const pa of a) {
+    for (const pb of b) {
+      if (pa === pb) return true
+      const x = scopePrefix(pa)
+      const y = scopePrefix(pb)
+      if (!x || !y) return true
+      if (x === y) return true
+      if (x.startsWith(`${y}/`) || y.startsWith(`${x}/`)) return true
+    }
+  }
+  return false
+}

package/domain/state/schema.js

@@ -0,0 +1,233 @@
+// Declarative state-file schema (#56 P4).
+//
+// `StateSchema` describes the structural contract of
+// `<git-common-dir>/dsh-tower/state.json`. Object schemas allow additional
+// properties on purpose: state files are forward/backward compatible and legacy
+// rows carry extra fields. Semantic policy (uniqueness, status/verdict
+// vocabularies, review exemption, worktree records and the revision counter)
+// lives in `./semantics.js`, so this module remains a pure declaration.
+// @ts-check
+import { Type } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+import { SCHEMA_VERSION } from '../mission.js'
+
+const optional = { additionalProperties: true }
+
+const NonNegativeInteger = Type.Integer({ minimum: 0 })
+
+const WorktreeSchema = Type.Object({}, optional)
+
+const MissionSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+    tasks: Type.Array(Type.Unknown()),
+    deps: Type.Array(Type.Unknown()),
+    references: Type.Optional(Type.Array(Type.Unknown())),
+    reviewPolicy: Type.Optional(Type.String()),
+    testRuns: Type.Optional(Type.Array(Type.Unknown())),
+    worktree: Type.Optional(Type.Union([WorktreeSchema, Type.Null()])),
+  },
+  optional,
+)
+
+const RosterEntrySchema = Type.Object(
+  {
+    name: Type.String(),
+    agentId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  },
+  optional,
+)
+
+const ReviewSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+    mergeVerdict: Type.Optional(Type.String()),
+  },
+  optional,
+)
+
+const FindingSchema = Type.Object(
+  {
+    id: Type.String(),
+    status: Type.Optional(Type.String()),
+  },
+  optional,
+)
+
+const MessageSchema = Type.Object(
+  {
+    id: Type.String(),
+    to: Type.String(),
+    readBy: Type.Array(Type.Unknown()),
+  },
+  optional,
+)
+
+/** Structural contract for one persisted Tower state document. */
+export const StateSchema = Type.Object(
+  {
+    schemaVersion: Type.Literal(SCHEMA_VERSION),
+    revision: Type.Optional(Type.Number()),
+    base: Type.Optional(Type.String()),
+    repoRoot: Type.Optional(Type.String()),
+    commonDir: Type.Optional(Type.String()),
+    createdAt: Type.Optional(Type.Number()),
+    updatedAt: Type.Optional(Type.Number()),
+    dirtyBase: Type.Optional(Type.Boolean()),
+    towerAgentId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    snapshotCommit: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    snapshotRef: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    missions: Type.Array(MissionSchema),
+    roster: Type.Optional(Type.Array(RosterEntrySchema)),
+    reviews: Type.Optional(Type.Array(ReviewSchema)),
+    findings: Type.Optional(Type.Array(FindingSchema)),
+    messages: Type.Optional(Type.Array(MessageSchema)),
+    batches: Type.Optional(Type.Array(Type.Unknown())),
+    legacySnapshots: Type.Optional(Type.Array(Type.Unknown())),
+    legacyMaps: Type.Optional(Type.Array(Type.Unknown())),
+    deliveries: Type.Optional(Type.Array(Type.Unknown())),
+    mergeIntent: Type.Optional(Type.Union([Type.Object({}, optional), Type.Null()])),
+    rebaseIntent: Type.Optional(Type.Union([Type.Object({}, optional), Type.Null()])),
+    messageSeq: Type.Optional(NonNegativeInteger),
+    reviewSeq: Type.Optional(NonNegativeInteger),
+    findingSeq: Type.Optional(NonNegativeInteger),
+    batchSeq: Type.Optional(NonNegativeInteger),
+    deliverySeq: Type.Optional(NonNegativeInteger),
+  },
+  optional,
+)
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** @type {readonly string[]} */
+const ARRAY_KEYS = ['batches', 'legacySnapshots', 'legacyMaps', 'deliveries']
+/** @type {readonly string[]} */
+const SEQUENCE_KEYS = ['messageSeq', 'reviewSeq', 'findingSeq', 'batchSeq', 'deliverySeq']
+
+/**
+ * Reproduce the historical `[tower:state-corrupt]` diagnostics for the
+ * structural failures the schema rejects. Keeping them in the state vocabulary
+ * (rather than exposing TypeBox paths) keeps operator-facing messages stable.
+ * @param {Record<string, any>} state
+ * @param {string} where
+ * @returns {string | null}
+ */
+function firstShapeMessage(state, where) {
+  if (state.schemaVersion !== SCHEMA_VERSION) {
+    return `unsupported tower state schemaVersion ${state.schemaVersion}${where}`
+  }
+  if (!Array.isArray(state.missions)) return `tower state has no missions array${where}`
+  for (const mission of state.missions) {
+    if (!isPlainObject(mission) || typeof mission.id !== 'string') return `mission entry without id${where}`
+    const id = mission.id
+    if (!Array.isArray(mission.tasks)) return `mission ${id} has no tasks array${where}`
+    if (!Array.isArray(mission.deps)) return `mission ${id} has no deps array${where}`
+    if (mission.references !== undefined && !Array.isArray(mission.references)) {
+      return `mission ${id} has no references array${where}`
+    }
+    if (mission.reviewPolicy !== undefined && typeof mission.reviewPolicy !== 'string') {
+      return `mission ${id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`
+    }
+    if (mission.testRuns !== undefined && !Array.isArray(mission.testRuns)) {
+      return `mission ${id} has no testRuns array${where}`
+    }
+    if (mission.worktree !== undefined && mission.worktree !== null && !isPlainObject(mission.worktree)) {
+      return `mission ${id} has an invalid worktree record${where}`
+    }
+  }
+  for (const key of ['base', 'repoRoot', 'commonDir']) {
+    if (state[key] !== undefined && typeof state[key] !== 'string') return `tower state ${key} is not a string${where}`
+  }
+  for (const key of ['createdAt', 'updatedAt']) {
+    if (state[key] !== undefined && typeof state[key] !== 'number') {
+      return `tower state ${key} is not a number${where}`
+    }
+  }
+  if (state.dirtyBase !== undefined && typeof state.dirtyBase !== 'boolean') {
+    return `tower state dirtyBase is not a boolean${where}`
+  }
+  for (const key of ['towerAgentId', 'snapshotCommit', 'snapshotRef']) {
+    if (state[key] !== undefined && state[key] !== null && typeof state[key] !== 'string') {
+      return `tower state ${key} is not a string or null${where}`
+    }
+  }
+  if (state.revision !== undefined && typeof state.revision !== 'number') {
+    return `tower state revision is not a non-negative integer${where}`
+  }
+  for (const key of ARRAY_KEYS) {
+    if (state[key] !== undefined && !Array.isArray(state[key])) return `tower state ${key} is not an array${where}`
+  }
+  for (const key of SEQUENCE_KEYS) {
+    if (state[key] !== undefined && !(Number.isInteger(state[key]) && state[key] >= 0)) {
+      return `tower state ${key} is not a non-negative integer${where}`
+    }
+  }
+  if (state.mergeIntent !== undefined && state.mergeIntent !== null && !isPlainObject(state.mergeIntent)) {
+    return `tower state mergeIntent is not an object${where}`
+  }
+  if (state.rebaseIntent !== undefined && state.rebaseIntent !== null && !isPlainObject(state.rebaseIntent)) {
+    return `tower state rebaseIntent is not an object${where}`
+  }
+  if (state.roster !== undefined) {
+    if (!Array.isArray(state.roster)) return `tower state roster is not an array${where}`
+    for (const entry of state.roster) {
+      if (!isPlainObject(entry) || typeof entry.name !== 'string') return `invalid roster entry${where}`
+      if (entry.agentId !== undefined && entry.agentId !== null && typeof entry.agentId !== 'string') {
+        return `invalid roster entry${where}`
+      }
+    }
+  }
+  if (state.messages !== undefined) {
+    if (!Array.isArray(state.messages)) return `tower state messages is not an array${where}`
+    for (const message of state.messages) {
+      if (!isPlainObject(message) || typeof message.id !== 'string' || typeof message.to !== 'string') {
+        return `invalid message entry${where}`
+      }
+      if (!Array.isArray(message.readBy)) return `message ${message.id} has no readBy array${where}`
+    }
+  }
+  if (state.findings !== undefined) {
+    if (!Array.isArray(state.findings)) return `tower state findings is not an array${where}`
+    for (const finding of state.findings) {
+      if (!isPlainObject(finding) || typeof finding.id !== 'string') return `invalid finding entry${where}`
+      if (finding.status !== undefined && typeof finding.status !== 'string') {
+        return `finding ${finding.id} has unknown status ${finding.status}${where}`
+      }
+    }
+  }
+  if (state.reviews !== undefined) {
+    if (!Array.isArray(state.reviews)) return `tower state reviews is not an array${where}`
+    for (const review of state.reviews) {
+      if (!isPlainObject(review) || typeof review.id !== 'string') return `invalid review entry${where}`
+      if (review.status !== undefined && typeof review.status !== 'string') {
+        return `review ${review.id} has unknown status ${review.status}${where}`
+      }
+      if (review.mergeVerdict !== undefined && typeof review.mergeVerdict !== 'string') {
+        return `review ${review.id} has unknown merge verdict ${review.mergeVerdict}${where}`
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Pure structural check. Returns the legacy diagnostic, or null when the state
+ * satisfies `StateSchema`. `where` is the already-formatted " at <path>" suffix.
+ * @param {unknown} state
+ * @param {string} [where]
+ * @returns {string | null}
+ */
+export function stateShapeError(state, where = '') {
+  if (!isPlainObject(state)) return `tower state is not an object${where}`
+  if (Value.Check(StateSchema, state)) return null
+  const record = /** @type {Record<string, any>} */ (state)
+  return firstShapeMessage(record, where) ?? `tower state does not match the state schema${where}`
+}

package/domain/state/semantics.js

@@ -0,0 +1,117 @@
+// Semantic state-file checks (#56 P4).
+//
+// `stateShapeError` proves the structural contract; this module owns the policy
+// the shape cannot express: unique ids, status/verdict vocabularies, the review
+// exemption, roster/agent uniqueness, worktree records and the revision
+// counter. Messages keep the historical `[tower:state-corrupt]` wording.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { FINDING_STATUSES, MERGE_VERDICTS, MISSION_STATUSES, REVIEW_STATUS_RE } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('state-corrupt', message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * A worktree record may omit legacy fields, but every field it carries must
+ * keep its documented type.
+ * @param {Record<string, any>} mission
+ * @param {string} where
+ * @returns {void}
+ */
+function assertWorktreeRecord(mission, where) {
+  const worktree = mission.worktree
+  if (worktree === undefined || worktree === null) return
+  const invalid = !isPlainObject(worktree) || ['path', 'branch', 'baseCommit', 'realPath'].some(
+    (key) => worktree[key] !== undefined && typeof worktree[key] !== 'string',
+  ) || (worktree.createdAt !== undefined && typeof worktree.createdAt !== 'number')
+  if (invalid) fail(`mission ${mission.id} has an invalid worktree record${where}`)
+}
+
+/**
+ * @param {unknown} state
+ * @param {string} where
+ * @returns {TowerState}
+ */
+export function assertStateSemantics(state, where) {
+  const record = /** @type {Record<string, any>} */ (state)
+  if (record.revision !== undefined && (!Number.isInteger(record.revision) || record.revision < 0)) {
+    fail(`tower state revision is not a non-negative integer${where}`)
+  }
+  const missionIds = new Set()
+  for (const mission of record.missions) {
+    if (missionIds.has(mission.id)) fail(`duplicate mission id ${mission.id}${where}`)
+    missionIds.add(mission.id)
+    if (!MISSION_STATUSES.includes(mission.status)) {
+      fail(`mission ${mission.id} has unknown status ${mission.status}${where}`)
+    }
+    if (mission.reviewPolicy !== undefined && !['required-clean', 'none'].includes(mission.reviewPolicy)) {
+      fail(`mission ${mission.id} has unknown reviewPolicy ${mission.reviewPolicy}${where}`)
+    }
+    if (mission.reviewPolicy === 'none' && !String(mission.reviewExemptionReason ?? '').trim()) {
+      fail(`mission ${mission.id} has reviewPolicy none without a reason${where}`)
+    }
+    assertWorktreeRecord(mission, where)
+  }
+  if (record.roster !== undefined) {
+    const names = new Set()
+    const agents = new Set()
+    for (const entry of record.roster) {
+      const reserved = entry?.state === 'reserved'
+      if (!entry || typeof entry.name !== 'string' || (!reserved && typeof entry.agentId !== 'string')) {
+        fail(`invalid roster entry${where}`)
+      }
+      if (names.has(entry.name)) fail(`duplicate roster name ${entry.name}${where}`)
+      if (typeof entry.agentId === 'string') {
+        if (agents.has(entry.agentId)) fail(`duplicate roster agent ${entry.agentId}${where}`)
+        agents.add(entry.agentId)
+      }
+      names.add(entry.name)
+    }
+  }
+  if (record.messages !== undefined) {
+    const ids = new Set()
+    for (const message of record.messages) {
+      if (ids.has(message.id)) fail(`duplicate message id ${message.id}${where}`)
+      ids.add(message.id)
+    }
+  }
+  if (record.findings !== undefined) {
+    const ids = new Set()
+    for (const finding of record.findings) {
+      if (ids.has(finding.id)) fail(`duplicate finding id ${finding.id}${where}`)
+      ids.add(finding.id)
+      if (finding.status !== undefined && !FINDING_STATUSES.includes(finding.status)) {
+        fail(`finding ${finding.id} has unknown status ${finding.status}${where}`)
+      }
+    }
+  }
+  if (record.reviews !== undefined) {
+    const ids = new Set()
+    for (const review of record.reviews) {
+      if (ids.has(review.id)) fail(`duplicate review id ${review.id}${where}`)
+      ids.add(review.id)
+      if (!REVIEW_STATUS_RE.test(String(review.status))) {
+        fail(`review ${review.id} has unknown status ${review.status}${where}`)
+      }
+      if (!MERGE_VERDICTS.includes(review.mergeVerdict)) {
+        fail(`review ${review.id} has unknown merge verdict ${review.mergeVerdict}${where}`)
+      }
+    }
+  }
+  return /** @type {TowerState} */ (record)
+}

package/domain/state.js

@@ -0,0 +1,33 @@
+// Pure state-file validation (#56 P4).
+//
+// The structural contract lives in `state/schema.js` (TypeBox) and the policy
+// checks in `state/semantics.js`. This module stays the public entry point so
+// every app/tool import of `domain/state.js` is unchanged.
+// @ts-check
+import { TowerToolError } from './errors.js'
+import { stateShapeError } from './state/schema.js'
+import { assertStateSemantics } from './state/semantics.js'
+
+/** @typedef {import('../types/index.js').TowerState} TowerState */
+
+export { StateSchema, stateShapeError } from './state/schema.js'
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('state-corrupt', message)
+}
+
+/**
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @returns {TowerState}
+ */
+export function validateState(state, statePath) {
+  const where = statePath ? ` at ${statePath}` : ''
+  const shapeError = stateShapeError(state, where)
+  if (shapeError) fail(shapeError)
+  return assertStateSemantics(state, where)
+}

package/domain/summary.js

@@ -0,0 +1,114 @@
+// Pure mission/finding summaries.
+// @ts-check
+import { FINDING_STATUSES } from './mission.js'
+
+/** @typedef {import('../types/index.js').Finding} Finding */
+/** @typedef {import('../types/index.js').FindingSummary} FindingSummary */
+/** @typedef {import('../types/index.js').Mission} Mission */
+/** @typedef {import('../types/index.js').MissionDetail} MissionDetail */
+/** @typedef {import('../types/index.js').MissionSummary} MissionSummary */
+/** @typedef {import('../types/index.js').MissionTask} MissionTask */
+/** @typedef {import('../types/index.js').TaskCounts} TaskCounts */
+
+/**
+ * @param {MissionTask[]} tasks
+ * @returns {TaskCounts}
+ */
+function taskCounts(tasks) {
+  /** @type {TaskCounts} */
+  const counts = { total: tasks.length, done: 0, open: 0, dropped: 0 }
+  for (const task of tasks) {
+    if (task.status === 'done') counts.done += 1
+    else if (task.status === 'dropped') counts.dropped += 1
+    else counts.open += 1
+  }
+  return counts
+}
+
+/**
+ * @param {Mission} mission
+ * @returns {MissionSummary}
+ */
+export function missionSummary(mission) {
+  return {
+    id: mission.id,
+    title: mission.title,
+    kind: mission.kind,
+    status: mission.status,
+    scope: mission.scope,
+    deps: mission.deps,
+    owner: mission.owner ?? null,
+    worktree: mission.worktree
+      ? {
+          path: mission.worktree.path,
+          branch: mission.worktree.branch,
+          baseCommit: mission.worktree.baseCommit,
+        }
+      : null,
+    blockers: mission.blockers ?? [],
+    tasks: taskCounts(mission.tasks ?? []),
+    scopeGeneration: mission.scopeGeneration ?? 1,
+    ownerGeneration: mission.ownerGeneration ?? 0,
+    pauseCause: mission.pauseCause ?? null,
+    reviewPolicy: mission.reviewPolicy ?? 'required-clean',
+    mergedCommit: mission.mergedCommit ?? null,
+    mergedAt: mission.mergedAt ?? null,
+    updatedAt: mission.updatedAt,
+  }
+}
+
+/**
+ * @param {Mission} mission
+ * @returns {MissionDetail}
+ */
+function fullMission(mission) {
+  return {
+    ...missionSummary(mission),
+    tasks: (mission.tasks ?? []).map((task) => ({ ...task })),
+    notes: mission.notes ?? [],
+    completionReport: mission.completionReport ?? null,
+    authorizationRef: mission.authorizationRef ?? null,
+    references: mission.references ?? [],
+    reviewPolicy: mission.reviewPolicy ?? 'required-clean',
+    reviewExemptionReason: mission.reviewExemptionReason ?? '',
+    testRuns: mission.testRuns ?? [],
+  }
+}
+
+/**
+ * @param {Finding} finding
+ * @returns {FindingSummary}
+ */
+function findingSummary(finding) {
+  return {
+    id: finding.id,
+    seq: finding.seq ?? null,
+    type: finding.type,
+    title: finding.title,
+    severity: finding.severity ?? null,
+    status: finding.status ?? 'open',
+    missionId: finding.missionId ?? null,
+    branch: finding.branch ?? null,
+    reportedBy: finding.reportedBy ?? null,
+    at: finding.at ?? null,
+    updatedAt: finding.updatedAt ?? null,
+    closedAt: finding.closedAt ?? null,
+  }
+}
+
+/**
+ * @param {Finding[]} findings
+ * @returns {Record<string, number>}
+ */
+function countFindings(findings) {
+  /** @type {Record<string, number>} */
+  const counts = {}
+  for (const status of FINDING_STATUSES) counts[status] = 0
+  for (const finding of findings) {
+    const status = finding.status ?? 'open'
+    counts[status] = (counts[status] ?? 0) + 1
+  }
+  return counts
+}
+
+export { taskCounts, fullMission, findingSummary, countFindings }