dsh-tower 2.1.0-beta.1 → 2.3.0

package/adapters/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 './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/adapters/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 './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)
+    }
+  }
+}

package/adapters/default.js

@@ -1,10 +1,53 @@
-// Default composition root for Tower dependencies (#50).
-import * as store from '../lib/store.js'
-import * as vcs from '../lib/git.js'
+// Default composition root for the Tower ports (#50, #69).
+//
+// This module is the one place where the concrete adapters (node:fs,
+// node:child_process) are turned into the plain deps object the app layer
+// takes. `createDefaultDeps()` is called once by the host entry (index.js); the
+// app never imports an adapter. Tests and embedders use the memoised
+// `defaultDeps` (or host/tower.js) so the process has exactly one adapter set.
+import crypto from 'node:crypto'
+import * as archive from './archive.js'
+import * as caseSensitivity from './caseSensitivity.js'
+import * as config from '../host/config.js'
+import { loadStateFile } from './stateFile.js'
+import * as ownership from './worktreeOwnership.js'
+import { createStorePort } from './store-fs.js'
+import { createVcsPort } from './vcs-git.js'
+import { NOOP_EVENT_PORT } from '../ports/events.js'
 
-export const defaultDeps = {
-  store,
-  vcs,
-  clock: { now: () => Date.now() },
-  ids: { uuid: () => crypto.randomUUID() },
+/**
+ * Assemble a dependency object implementing every port in ports/.
+ * @param {Partial<Record<'store'|'vcs'|'config'|'state'|'archive'|'ownership'|'caseSensitivity'|'clock'|'ids'|'events', any>>} [overrides]
+ * @returns {Record<string, any>}
+ */
+export function createDefaultDeps(overrides = {}) {
+  const store = createStorePort()
+  return {
+    store,
+    vcs: createVcsPort(),
+    config: {
+      runtimeConfig: config.runtimeConfig,
+      resolveRepoConfig: config.resolveRepoConfig,
+    },
+    state: { loadStateFile },
+    archive: {
+      readIndex: archive.readArchiveIndex,
+      readEntry: archive.readArchivedEntry,
+      writeEntries: archive.writeArchiveEntries,
+    },
+    ownership: {
+      assertOwnership: ownership.assertOwnership,
+      canonicalPath: ownership.canonicalPath,
+    },
+    caseSensitivity: { detect: caseSensitivity.detectCaseSensitivity },
+    clock: { now: () => Date.now() },
+    ids: { uuid: () => crypto.randomUUID(), shortHash: store.shortHash },
+    // The host entry replaces this with the Cordis emitter; default deps (and
+    // tests/embedders) keep the no-op channel so events never fail a tool.
+    events: NOOP_EVENT_PORT,
+    ...overrides,
+  }
 }
+
+/** The single process-wide default adapter set. */
+export const defaultDeps = createDefaultDeps()

package/{lib → adapters}/git.js

@@ -1,6 +1,6 @@
 import { TowerToolError } from '../domain/errors.js'
 // Minimal git port: array arguments only, bounded output, no shell.
-import { execFile } from '../adapters/vcs-git.js'
+import { execFile } from './vcs-git.js'
 import path from 'node:path'
 
 const GIT_TIMEOUT_MS = 15000

package/{lib → adapters}/leases.js

@@ -11,7 +11,7 @@
 // Fail-closed protocol: a held, expired, or token-mismatched lease is reported,
 // never silently taken over. Only the token holder may release a lease, and
 // releasing an expired lease requires an explicit `force: true`.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
@@ -27,6 +27,11 @@ const LOCK_STALE_MS = 10000
 const LOCK_POLL_MS = 20
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
 
+// Exported with the retry loop so a test can assert the budget and the exact
+// transient set instead of copying them (#86).
+export const UNLINK_ATTEMPTS = 12
+export const TRANSIENT_UNLINK_ERRORS = new Set(['EPERM', 'EBUSY', 'EACCES'])
+
 function fail(code, message) {
   /** @type {Error & {code?: string}} */
   const error = new Error(message)
@@ -57,17 +62,21 @@ export function leasesLockPath(commonDir) {
 /**
  * Windows can reject unlink while an indexer, antivirus, or a concurrent
  * reader still holds the file; retry briefly instead of failing the mutation.
+ *
+ * `options.unlink` and `options.sleep` inject the syscall and the backoff so
+ * both outcomes are testable on any OS (#86); production callers omit them.
  */
-async function unlinkWithRetry(file) {
+export async function unlinkWithRetry(file, options = {}) {
+  const unlink = options.unlink ?? fsp.unlink
+  const wait = options.sleep ?? sleep
   for (let attempt = 0; ; attempt += 1) {
     try {
-      await fsp.unlink(file)
+      await unlink(file)
       return true
     } catch (error) {
       if (error?.code === 'ENOENT') return false
-      const transient = error?.code === 'EPERM' || error?.code === 'EBUSY' || error?.code === 'EACCES'
-      if (!transient || attempt >= 12) throw error
-      await sleep(10 + attempt * 15)
+      if (!TRANSIENT_UNLINK_ERRORS.has(error?.code) || attempt >= UNLINK_ATTEMPTS) throw error
+      await wait(10 + attempt * 15)
     }
   }
 }

package/{lib → adapters}/legacy.js

@@ -9,7 +9,7 @@
 //
 // `validateLegacyMap` is the audit-only mapping check: a map is a record that
 // legacy id X corresponds to DSH mission Y. It never adopts or restores work.
-import { fsp } from '../adapters/store-fs.js'
+import { fsp } from './store-fs.js'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
@@ -41,13 +41,27 @@ function sha256(buffer) {
   return crypto.createHash('sha256').update(buffer).digest('hex')
 }
 
-function win32Lower(value) {
-  return process.platform === 'win32' ? value.toLowerCase() : value
+// Path semantics are selected from an injected platform so both branches are
+// testable on any OS (#86). On the real platform this is exactly `path`.
+function pathFor(platform) {
+  return platform === 'win32' ? path.win32 : path.posix
 }
 
-function isInside(parent, child) {
-  const relative = path.relative(win32Lower(path.resolve(parent)), win32Lower(path.resolve(child)))
-  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+export function win32Lower(value, platform = process.platform) {
+  return platform === 'win32' ? value.toLowerCase() : value
+}
+
+/**
+ * Is `child` inside `parent` (or the same path)? Windows reconciles case
+ * because NTFS is case-insensitive; the POSIX branch stays case-sensitive.
+ */
+export function isInside(parent, child, platform = process.platform) {
+  const pathImpl = pathFor(platform)
+  const relative = pathImpl.relative(
+    win32Lower(pathImpl.resolve(parent), platform),
+    win32Lower(pathImpl.resolve(child), platform),
+  )
+  return relative === '' || (!relative.startsWith('..') && !pathImpl.isAbsolute(relative))
 }
 
 async function realpathOrResolve(target) {