dsh-tower 2.1.0-beta.1 → 2.1.0

package/domain/state.js

@@ -1,17 +1,123 @@
-// Pure state-file validation (#56 P4).
+// Pure state-file validation and migration decisions (#56 P4, #72).
 //
-// 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.
+// The structural contract lives in `state/schema.js` (TypeBox), the policy
+// checks in `state/semantics.js`, and the version registry in
+// `state/migrations.js`. This module stays the public entry point so every
+// app/tool import of `domain/state.js` is unchanged.
+//
+// `validateState` proves a document matches the *current* schema.
+// `prepareState` is the load-path decision: it inspects the version, applies the
+// ordered migration registry, then validates the target schema. Both are pure;
+// the side effects (backup, write, activity) live in `lib/stateFile.js`.
 // @ts-check
 import { TowerToolError } from './errors.js'
+import { SCHEMA_VERSION } from './mission.js'
+import { migrationChain, migrateState } from './state/migrations.js'
 import { stateShapeError } from './state/schema.js'
 import { assertStateSemantics } from './state/semantics.js'
 
 /** @typedef {import('../types/index.js').TowerState} TowerState */
+/** @typedef {{ from: number, to: number }} MigrationStep */
+/** @typedef {import('./state/migrations.js').StateMigration} StateMigration */
 
 export { StateSchema, stateShapeError } from './state/schema.js'
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Classify a document's `schemaVersion` without throwing. This is the read path
+ * doctor uses, so it must stay usable on a repository that cannot load.
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {readonly StateMigration[]} [migrations] registry to classify against
+ * @returns {{
+ *   status: 'current'|'migratable'|'newer'|'unmigratable'|'invalid',
+ *   currentVersion: number|null,
+ *   supportedVersion: number,
+ *   migrations: MigrationStep[],
+ *   message?: string,
+ * }}
+ */
+export function inspectStateVersion(state, statePath, migrations) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (!isPlainObject(state)) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state is not an object${where}`,
+    }
+  }
+  const version = /** @type {Record<string, any>} */ (state).schemaVersion
+  if (!Number.isInteger(version) || version < 1) {
+    return {
+      status: 'invalid',
+      currentVersion: null,
+      supportedVersion: SCHEMA_VERSION,
+      migrations: [],
+      message: `tower state has no usable schemaVersion (${JSON.stringify(version)})${where}`,
+    }
+  }
+  if (version === SCHEMA_VERSION) {
+    return { status: 'current', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  if (version > SCHEMA_VERSION) {
+    return { status: 'newer', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  const chain = migrationChain(version, SCHEMA_VERSION, migrations)
+  if (!chain) {
+    return { status: 'unmigratable', currentVersion: version, supportedVersion: SCHEMA_VERSION, migrations: [] }
+  }
+  return {
+    status: 'migratable',
+    currentVersion: version,
+    supportedVersion: SCHEMA_VERSION,
+    migrations: chain.map((step) => ({ from: step.from, to: step.to })),
+  }
+}
+
+/**
+ * @param {{ status: string, currentVersion: number|null, supportedVersion: number, message?: string }} info
+ * @param {string} [statePath]
+ * @returns {TowerToolError}
+ */
+function versionError(info, statePath) {
+  const where = statePath ? ` at ${statePath}` : ''
+  if (info.status === 'newer') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, but this build supports ${info.supportedVersion}: it was written by a newer dsh-tower and will not be downgraded`,
+      {
+        nextAction: `upgrade dsh-tower to a release that supports state schemaVersion ${info.currentVersion}; the file was left untouched`,
+      },
+    )
+  }
+  if (info.status === 'migratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}; load it through the state loader to migrate it to ${info.supportedVersion}`,
+      { nextAction: 'call any tower tool; mutations apply the migration under the state lock' },
+    )
+  }
+  if (info.status === 'unmigratable') {
+    return new TowerToolError(
+      'state-version-unsupported',
+      `tower state${where} has schemaVersion ${info.currentVersion}, which has no migration to ${info.supportedVersion}`,
+      {
+        nextAction: `restore a state.json written by dsh-tower ${info.supportedVersion}; this build will not guess at an unknown schema`,
+      },
+    )
+  }
+  return new TowerToolError('state-corrupt', info.message ?? `tower state is not usable${where}`)
+}
+
 /**
  * @param {string} message
  * @returns {never}
@@ -21,13 +127,57 @@ function fail(message) {
 }
 
 /**
+ * Prove a document matches the current schema. Any other version is rejected
+ * with a version error rather than corruption; the load path migrates first.
  * @param {unknown} state
  * @param {string} [statePath]
  * @returns {TowerState}
  */
 export function validateState(state, statePath) {
+  const info = inspectStateVersion(state, statePath)
+  if (info.status !== 'current') throw versionError(info, statePath)
   const where = statePath ? ` at ${statePath}` : ''
   const shapeError = stateShapeError(state, where)
   if (shapeError) fail(shapeError)
   return assertStateSemantics(state, where)
 }
+
+/**
+ * The pure load-path decision: migrate an older document through the registry,
+ * validate the result against the target schema, then report what happened. The
+ * returned state is the validated migrated document; the caller decides whether
+ * to persist it (only while holding the state lock).
+ *
+ * @param {unknown} state
+ * @param {string} [statePath]
+ * @param {{ migrations?: readonly StateMigration[] }} [options]
+ * @returns {{ state: TowerState, from: number, to: number, migrated: MigrationStep[], changed: boolean }}
+ */
+export function prepareState(state, statePath, options = {}) {
+  const info = inspectStateVersion(state, statePath, options.migrations)
+  if (info.status === 'current') {
+    return {
+      state: validateState(state, statePath),
+      from: SCHEMA_VERSION,
+      to: SCHEMA_VERSION,
+      migrated: [],
+      changed: false,
+    }
+  }
+  if (info.status !== 'migratable') throw versionError(info, statePath)
+  const outcome = migrateState(/** @type {Record<string, any>} */ (state), {
+    statePath,
+    to: info.supportedVersion,
+    migrations: options.migrations,
+  })
+  // Validation runs on the *target* document: a shape that was invalid under
+  // the old schema (a missing `tasks` array, say) may be valid after a backfill,
+  // and validating the target is what proves the migration did its job.
+  return {
+    state: validateState(outcome.state, statePath),
+    from: outcome.from,
+    to: outcome.to,
+    migrated: outcome.steps,
+    changed: true,
+  }
+}

package/domain/summary.js

@@ -1,6 +1,7 @@
 // Pure mission/finding summaries.
 // @ts-check
 import { FINDING_STATUSES } from './mission.js'
+import { completionReportBytes } from './missions/completion.js'
 
 /** @typedef {import('../types/index.js').Finding} Finding */
 /** @typedef {import('../types/index.js').FindingSummary} FindingSummary */
@@ -53,6 +54,7 @@ export function missionSummary(mission) {
     reviewPolicy: mission.reviewPolicy ?? 'required-clean',
     mergedCommit: mission.mergedCommit ?? null,
     mergedAt: mission.mergedAt ?? null,
+    reportBytes: completionReportBytes(mission.completionReport),
     updatedAt: mission.updatedAt,
   }
 }

package/lib/archive.js

@@ -0,0 +1,279 @@
+// Terminal-mission archive storage (#73).
+//
+// Layout, under the Tower state directory:
+//
+//   archive/index.json      compact entries; tower_status pages from here
+//   archive/<year>.json     full missions plus their linked reviews/findings
+//
+// Both files carry `archiveVersion` (independent of the state SCHEMA_VERSION).
+// Reads are deliberately tolerant: a truncated or foreign archive returns a
+// diagnostic result and never throws, so `tower_status` still renders the hot
+// state. Writes happen before the state document is compacted, and dedupe by
+// mission id, so a crash between the two files is recoverable on the next
+// mutation instead of losing a mission.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+import {
+  ARCHIVE_VERSION,
+  archiveDocumentError,
+  dedupeById,
+  indexEntryFromArchived,
+} from '../domain/state/archive.js'
+
+/** @typedef {import('../types/index.js').Mission} Mission */
+
+/**
+ * @param {{ dir: string }} paths
+ * @returns {{ dir: string, index: string, year: (year: number) => string }}
+ */
+export function archivePaths(paths) {
+  const dir = path.join(paths.dir, 'archive')
+  return { dir, index: path.join(dir, 'index.json'), year: (year) => path.join(dir, `${year}.json`) }
+}
+
+/**
+ * @param {any} error
+ * @returns {boolean}
+ */
+function isMissing(error) {
+  return error?.code === 'ENOENT'
+}
+
+/**
+ * @param {string} where
+ * @param {string} message
+ * @returns {string}
+ */
+function diagnostic(where, message) {
+  return `tower archive is unreadable at ${where}: ${message}`
+}
+
+/**
+ * Read `archive/index.json` without throwing. A missing index means "no
+ * archive yet"; a corrupt one is reported as `ok:false` with the diagnostic.
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @returns {Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>}
+ */
+export async function readArchiveIndex(store, paths) {
+  const file = archivePaths(paths).index
+  let document
+  try {
+    document = await store.readJson(file)
+  } catch (error) {
+    if (isMissing(error)) return { ok: true, file, missions: [], exists: false }
+    return { ok: false, file, missions: [], error: diagnostic(file, String(error?.message ?? error)), exists: true }
+  }
+  const error = archiveDocumentError(document, 'index', ` at ${file}`)
+  if (error) return { ok: false, file, missions: [], error, exists: true }
+  return { ok: true, file, missions: document.missions, exists: true }
+}
+
+/**
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @param {number} year
+ * @returns {Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>}
+ */
+export async function readArchiveYear(store, paths, year) {
+  const file = archivePaths(paths).year(year)
+  let document
+  try {
+    document = await store.readJson(file)
+  } catch (error) {
+    if (isMissing(error)) return { ok: true, file, missions: [], exists: false }
+    return { ok: false, file, missions: [], error: diagnostic(file, String(error?.message ?? error)), exists: true }
+  }
+  const error = archiveDocumentError(document, 'year', ` at ${file}`)
+  if (error) return { ok: false, file, missions: [], error, exists: true }
+  return { ok: true, file, missions: document.missions, exists: true }
+}
+
+/**
+ * Append full entries to their year files, then to the index. Returns
+ * `ok:false` (and writes nothing for the index) when an existing archive file
+ * is unreadable, so a corrupt archive is never silently replaced.
+ * @param {{ readJson: (file: string) => Promise<any>, writeJsonAtomic: (file: string, value: unknown) => Promise<void>, ensureDir: (dir: string) => Promise<void> }} store
+ * @param {{ dir: string }} paths
+ * @param {{ entries: Array<Record<string, any>>, now: number }} input
+ * @returns {Promise<{ ok: boolean, count: number, files: string[], error?: string }>}
+ */
+export async function writeArchiveEntries(store, paths, { entries, now }) {
+  if (entries.length === 0) return { ok: true, count: 0, files: [] }
+  const target = archivePaths(paths)
+
+  // Read the index first: if it is corrupt, refusing to write keeps the old
+  // history byte-identical and leaves the state missions intact for a retry.
+  const index = await readArchiveIndex(store, paths)
+  if (!index.ok) return { ok: false, count: 0, files: [], error: index.error }
+
+  /** @type {Map<number, Array<Record<string, any>>>} */
+  const byYear = new Map()
+  for (const entry of entries) {
+    const year = entry.archivedYear
+    if (!Number.isInteger(year)) return { ok: false, count: 0, files: [], error: `archive entry ${entry.id} has no archivedYear` }
+    const bucket = byYear.get(year) ?? []
+    bucket.push(entry)
+    byYear.set(year, bucket)
+  }
+
+  /** @type {Array<{ year: number, file: string, missions: any[] }>} */
+  const yearDocuments = []
+  for (const [year, batch] of [...byYear.entries()].sort((left, right) => left[0] - right[0])) {
+    const existing = await readArchiveYear(store, paths, year)
+    if (!existing.ok) return { ok: false, count: 0, files: [], error: existing.error }
+    yearDocuments.push({
+      year,
+      file: existing.file,
+      missions: dedupeById([...existing.missions, ...batch]),
+    })
+  }
+
+  await store.ensureDir(target.dir)
+  for (const document of yearDocuments) {
+    await store.writeJsonAtomic(document.file, {
+      archiveVersion: ARCHIVE_VERSION,
+      year: document.year,
+      updatedAt: now,
+      missions: document.missions,
+    })
+  }
+
+  const indexed = dedupeById([...index.missions, ...entries.map(indexEntryFromArchived)])
+  await store.writeJsonAtomic(target.index, {
+    archiveVersion: ARCHIVE_VERSION,
+    updatedAt: now,
+    missions: indexed,
+  })
+
+  return {
+    ok: true,
+    count: entries.length,
+    files: [...yearDocuments.map((document) => document.file), target.index],
+  }
+}
+
+/**
+ * Load one archived mission with its linked reviews/findings.
+ * @param {{ readJson: (file: string) => Promise<any> }} store
+ * @param {{ dir: string }} paths
+ * @param {string} missionId
+ * @returns {Promise<{ ok: boolean, entry?: Record<string, any>, unreadable?: boolean, missing?: boolean, error?: string }>}
+ */
+export async function readArchivedEntry(store, paths, missionId) {
+  const index = await readArchiveIndex(store, paths)
+  if (!index.ok) return { ok: false, unreadable: true, error: index.error }
+  const indexEntry = index.missions.find((entry) => entry.id === missionId)
+  if (!indexEntry) return { ok: false, missing: true }
+  const year = await readArchiveYear(store, paths, indexEntry.archivedYear)
+  if (!year.ok) return { ok: false, unreadable: true, error: year.error }
+  const entry = year.missions.find((candidate) => candidate.id === missionId)
+  if (!entry) {
+    return {
+      ok: false,
+      unreadable: true,
+      error: `tower archive index lists ${missionId} in ${year.file}, but the year file has no such entry`,
+    }
+  }
+  return { ok: true, entry }
+}
+
+/**
+ * @param {string} file
+ * @param {string} kind
+ * @returns {Promise<{ file: string, kind: string, ok: boolean, bytes: number, missions: number, error?: string, document?: any }>}
+ */
+async function inspectFile(file, kind) {
+  let text
+  try {
+    text = await fsp.readFile(file, 'utf8')
+  } catch (error) {
+    return { file, kind, ok: false, bytes: 0, missions: 0, error: diagnostic(file, String(error?.message ?? error)) }
+  }
+  const bytes = Buffer.byteLength(text)
+  let document
+  try {
+    document = JSON.parse(text)
+  } catch (error) {
+    return { file, kind, ok: false, bytes, missions: 0, error: diagnostic(file, `invalid JSON (${error.message})`) }
+  }
+  const error = archiveDocumentError(document, /** @type {'index'|'year'} */ (kind), ` at ${file}`)
+  if (error) return { file, kind, ok: false, bytes, missions: 0, error, document }
+  return { file, kind, ok: true, bytes, missions: document.missions.length, document }
+}
+
+/**
+ * Read-only inventory for `tower_doctor`: file sizes, mission counts, year
+ * files and every unreadable file's diagnostic. A missing archive directory is
+ * a healthy empty archive, not an error.
+ * @param {{ dir: string, state?: string }} paths
+ * @returns {Promise<{
+ *   dir: string, exists: boolean, bytes: number, missions: number, years: number[],
+ *   files: Array<Record<string, any>>, unreadable: string[],
+ *   index: { ok: boolean, count: number, error?: string } | null,
+ * }>}
+ */
+export async function inspectArchive(paths) {
+  const target = archivePaths(/** @type {{ dir: string }} */ (paths))
+  let names
+  try {
+    names = await fsp.readdir(target.dir)
+  } catch (error) {
+    if (isMissing(error)) {
+      return { dir: target.dir, exists: false, bytes: 0, missions: 0, years: [], files: [], unreadable: [], index: null }
+    }
+    return {
+      dir: target.dir,
+      exists: true,
+      bytes: 0,
+      missions: 0,
+      years: [],
+      files: [],
+      unreadable: [diagnostic(target.dir, String(error?.message ?? error))],
+      index: null,
+    }
+  }
+
+  const jsonFiles = names.filter((name) => name.endsWith('.json')).sort()
+  const files = []
+  let bytes = 0
+  let index = null
+  const yearIds = new Set()
+  for (const name of jsonFiles) {
+    const file = path.join(target.dir, name)
+    const kind = name === 'index.json' ? 'index' : 'year'
+    const inspected = await inspectFile(file, kind)
+    files.push({
+      file,
+      kind,
+      ok: inspected.ok,
+      bytes: inspected.bytes,
+      missions: inspected.missions,
+      ...(inspected.error ? { error: inspected.error } : {}),
+    })
+    bytes += inspected.bytes
+    if (kind === 'index') {
+      index = { ok: inspected.ok, count: inspected.missions, ...(inspected.error ? { error: inspected.error } : {}) }
+    } else if (inspected.ok) {
+      for (const entry of inspected.document.missions) yearIds.add(entry.id)
+    }
+  }
+  const unreadable = files
+    .filter((file) => !file.ok && typeof file.error === 'string')
+    .map((file) => /** @type {string} */ (file.error))
+  const years = files
+    .filter((file) => file.kind === 'year' && file.ok)
+    .map((file) => Number(path.basename(file.file, '.json')))
+    .filter((year) => Number.isInteger(year))
+    .sort((left, right) => left - right)
+  return {
+    dir: target.dir,
+    exists: true,
+    bytes,
+    missions: index?.ok ? index.count : yearIds.size,
+    years,
+    files,
+    unreadable,
+    index,
+  }
+}

package/lib/caseSensitivity.js

@@ -0,0 +1,66 @@
+// Case-insensitive-filesystem detection (#90).
+//
+// On Windows and macOS the checkout's filesystem folds case, while Git reports
+// the casing stored in the index. Scope matching has to know which world it is
+// in, so `tower_init` probes once and records the answer in state.
+//
+// The probe creates one uniquely-named mixed-case file in the checkout root
+// (the filesystem scope matching actually compares) and looks its lower-cased
+// name up. It returns:
+//   true   the lookup found the file: the filesystem folds case;
+//   false  the lookup was ENOENT: the filesystem is case-sensitive;
+//   null   the probe could not run (read-only checkout, EPERM, an unexpected
+//          stat failure). "Unknown" is deliberately not "case-sensitive": init
+//          keeps working and `tower_doctor` reports the safe default.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+
+/** Prefix is public so tests and support code can recognise a leaked probe. */
+export const CASE_PROBE_PREFIX = '.tower-case-probe-'
+
+/**
+ * A name that is guaranteed to differ from its lower-cased form, so the lookup
+ * actually distinguishes the two filesystem behaviours.
+ * @param {() => number} random
+ * @returns {string}
+ */
+function probeName(random) {
+  return `${CASE_PROBE_PREFIX}Z${random().toString(36).slice(2, 10)}`
+}
+
+/**
+ * @param {string} dir directory on the filesystem under test
+ * @param {{ fs?: typeof fsp, name?: string, random?: () => number }} [options]
+ *   `fs` is a seam for the failure branches, which cannot be produced portably
+ *   by permissions on every OS (Windows does not honour chmod the way POSIX does).
+ * @returns {Promise<boolean | null>}
+ */
+export async function detectCaseSensitivity(dir, options = {}) {
+  const fs = options.fs ?? fsp
+  const name = options.name ?? probeName(options.random ?? Math.random)
+  const probePath = path.join(dir, name)
+  const lowerPath = path.join(dir, name.toLowerCase())
+  if (lowerPath === probePath) return null
+
+  try {
+    await fs.writeFile(probePath, '')
+  } catch {
+    return null
+  }
+
+  try {
+    await fs.stat(lowerPath)
+    return true
+  } catch (error) {
+    const code = /** @type {{ code?: string }} */ (error)?.code
+    return code === 'ENOENT' ? false : null
+  } finally {
+    // Best effort: a leaked probe would dirty `git status` of the state dir and
+    // the detection result is already known.
+    try {
+      await fs.unlink(probePath)
+    } catch {
+      // the probe file may already be gone (or the failure branch never wrote it)
+    }
+  }
+}