dsh-tower 2.1.0 → 2.3.0

package/ports/contract.js

@@ -0,0 +1,38 @@
+// Port contract primitives (#69).
+//
+// A port is a runtime-checkable contract, not only a JSDoc typedef: the
+// contract object is importable, and `assertPort` rejects a dependency object
+// that does not implement it. That is what makes the seam substitutable at
+// runtime instead of merely documented.
+export function definePort(name, methods) {
+  return Object.freeze({ name, methods: Object.freeze([...methods]) })
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ * @param {string} [label]
+ */
+export function assertPort(impl, contract, label = contract.name) {
+  if (!impl || typeof impl !== 'object') {
+    throw new TypeError(`${label}: expected an object implementing ${contract.name}`)
+  }
+  const missing = contract.methods.filter((method) => typeof (/** @type {any} */ (impl))[method] !== 'function')
+  if (missing.length > 0) {
+    throw new TypeError(`${label} does not implement ${contract.name}; missing: ${missing.join(', ')}`)
+  }
+  return impl
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ */
+export function implementsPort(impl, contract) {
+  try {
+    assertPort(impl, contract)
+    return true
+  } catch {
+    return false
+  }
+}

package/ports/events.js

@@ -0,0 +1,24 @@
+// Domain-event port (#75).
+//
+// The app layer persists a transition and then emits the domain events it
+// described through this port. The host binds it to Cordis `ctx.emit`; tests
+// bind it to a recorder. `emit` is best effort by contract: a listener (or a
+// missing service) must never fail the tool that produced the fact.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} EventPort
+ * @property {(name: string, payload: Record<string, any>) => void} emit
+ */
+
+export const EVENT_PORT = definePort('EventPort', ['emit'])
+
+/** @param {unknown} impl */
+export function assertEventPort(impl) {
+  return /** @type {EventPort} */ (assertPort(impl, EVENT_PORT, 'events'))
+}
+
+/** The no-op default: embedders without an event channel still get a Tower. */
+export const NOOP_EVENT_PORT = Object.freeze({
+  emit() {},
+})

package/ports/ids.js

@@ -1,7 +1,15 @@
-// Ids port (#56).
+// Ids port (#69).
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} IdsPort
  * @property {() => string} uuid
  * @property {(text: string) => string} shortHash
  */
-export {}
+
+export const IDS_PORT = definePort('IdsPort', ['uuid', 'shortHash'])
+
+/** @param {unknown} impl */
+export function assertIdsPort(impl) {
+  return /** @type {IdsPort} */ (assertPort(impl, IDS_PORT, 'ids'))
+}

package/ports/index.js

@@ -1,2 +1,54 @@
-// Explicit ports consumed by app use cases (#56).
-export {}
+// Explicit ports consumed by app use cases (#69).
+//
+// `assertPorts` is the injection check the app layer runs on the dependency
+// object it receives: a composition root that forgets a port fails at
+// construction, not in the middle of a mission.
+import { assertPort } from './contract.js'
+import { STORE_PORT, assertStorePort } from './store.js'
+import { VCS_PORT, assertVcsPort } from './vcs.js'
+import { CLOCK_PORT, assertClockPort } from './clock.js'
+import { IDS_PORT, assertIdsPort } from './ids.js'
+import { CONFIG_PORT, assertConfigPort } from './config.js'
+import { STATE_PORT, assertStatePort } from './state.js'
+import { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+import { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+import { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+import { EVENT_PORT, assertEventPort } from './events.js'
+
+/** Every port the Tower app layer depends on, keyed by deps member. */
+export const PORTS = Object.freeze({
+  store: { contract: STORE_PORT, assert: assertStorePort },
+  vcs: { contract: VCS_PORT, assert: assertVcsPort },
+  clock: { contract: CLOCK_PORT, assert: assertClockPort },
+  ids: { contract: IDS_PORT, assert: assertIdsPort },
+  config: { contract: CONFIG_PORT, assert: assertConfigPort },
+  state: { contract: STATE_PORT, assert: assertStatePort },
+  ownership: { contract: OWNERSHIP_PORT, assert: assertOwnershipPort },
+  caseSensitivity: { contract: CASE_SENSITIVITY_PORT, assert: assertCaseSensitivityPort },
+  archive: { contract: ARCHIVE_PORT, assert: assertArchivePort },
+  events: { contract: EVENT_PORT, assert: assertEventPort },
+})
+
+/** @param {unknown} deps */
+export function assertPorts(deps) {
+  if (!deps || typeof deps !== 'object') {
+    throw new TypeError('Tower requires an injected deps object assembled by the composition root (see adapters/default.js)')
+  }
+  for (const [name, port] of Object.entries(PORTS)) {
+    if (typeof port.assert === 'function') port.assert(deps[name])
+    else assertPort(deps[name], port.contract, name)
+  }
+  return deps
+}
+
+export { STORE_PORT, assertStorePort } from './store.js'
+export { VCS_PORT, assertVcsPort } from './vcs.js'
+export { CLOCK_PORT, assertClockPort } from './clock.js'
+export { IDS_PORT, assertIdsPort } from './ids.js'
+export { CONFIG_PORT, assertConfigPort } from './config.js'
+export { STATE_PORT, assertStatePort } from './state.js'
+export { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+export { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+export { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+export { EVENT_PORT, assertEventPort, NOOP_EVENT_PORT } from './events.js'
+export { definePort, assertPort, implementsPort } from './contract.js'

package/ports/ownership.js

@@ -0,0 +1,17 @@
+// Worktree-ownership port (#69). The default implementation verifies a stored
+// worktree against the real filesystem and Git; an in-memory composition can
+// substitute a verifier that matches its own virtual paths.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} OwnershipPort
+ * @property {(input: { storedPath: string, storedRealPath?: string, branch: string, commonDir: string, missionId?: string }) => Promise<{ path: string, realPath: string }>} assertOwnership
+ * @property {(target: string) => Promise<string>} canonicalPath
+ */
+
+export const OWNERSHIP_PORT = definePort('OwnershipPort', ['assertOwnership', 'canonicalPath'])
+
+/** @param {unknown} impl */
+export function assertOwnershipPort(impl) {
+  return /** @type {OwnershipPort} */ (assertPort(impl, OWNERSHIP_PORT, 'ownership'))
+}

package/ports/state.js

@@ -0,0 +1,16 @@
+// State-load port (#69): schema inspection, migration, and the one persisted
+// migration result. The implementation is store-agnostic and receives the
+// store port, so an in-memory store can drive the same load path.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} StatePort
+ * @property {(input: { store: unknown, paths: unknown, now?: number, persist?: boolean, migrations?: readonly unknown[] }) => Promise<any>} loadStateFile
+ */
+
+export const STATE_PORT = definePort('StatePort', ['loadStateFile'])
+
+/** @param {unknown} impl */
+export function assertStatePort(impl) {
+  return /** @type {StatePort} */ (assertPort(impl, STATE_PORT, 'state'))
+}

package/ports/store.js

@@ -1,11 +1,60 @@
-// Store port (#56). Implementation: adapters/store-fs.js.
+// Store port (#69). Implementation: adapters/store-fs.js.
+//
+// App use cases depend on this contract, not on adapters/store.js: they receive the
+// implementation through the composition root and never import the adapter.
+// The contract lists every method app/** and tools/** call, so an implementation
+// that is missing one fails `assertPorts` at construction instead of mid-mission.
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} StorePort
+ * @property {(commonDir: string) => { dir: string, state: string, lock: string, gitLock: string, activity: string }} pathsFor
  * @property {(file: string) => Promise<boolean>} exists
  * @property {(dir: string) => Promise<void>} ensureDir
  * @property {(file: string) => Promise<any>} readJson
  * @property {(file: string, value: unknown) => Promise<void>} writeJsonAtomic
  * @property {(file: string, value: unknown) => Promise<void>} appendJsonl
- * @property {(paths: object, fn: () => Promise<any>, options?: object) => Promise<any>} withLock
+ * @property {(paths: object, fn: (paths: object) => Promise<any>, options?: object) => Promise<any>} withLock
+ * @property {(paths: object, fn: (paths: object) => Promise<any>, options?: object) => Promise<any>} withGitLock
+ * @property {(file: string, limit?: number) => Promise<any[]>} readActivityTail
+ * @property {(file: string) => Promise<string>} readText
+ * @property {(file: string, text: string, encoding?: string) => Promise<void>} writeText
+ * @property {(file: string, text: string, encoding?: string) => Promise<void>} appendText
+ * @property {(from: string, to: string) => Promise<void>} rename
+ * @property {(from: string, to: string) => Promise<void>} renameWithRetry
+ * @property {(file: string) => Promise<{ mtimeMs: number }>} stat
+ * @property {(file: string) => Promise<void>} unlink
+ * @property {(paths: object, options?: object) => Promise<{ record: any, raw: string | null }>} readGitLock
+ * @property {(lock: { record: any } | null, options?: object) => { held: boolean, pid?: number | null, phase?: string | null, heldMs?: number }} gitLockView
  */
-export {}
+
+// `rename` and `renameWithRetry` are both declared because they are not
+// interchangeable: `renameWithRetry` has temp-file semantics and on a terminal
+// failure it unlinks its source, which is right for a disposable temp file but
+// would delete the bytes `tower_recover` must keep auditable. The audit rename
+// therefore uses the plain `rename` primitive (see tools/recover.js).
+export const STORE_PORT = definePort('StorePort', [
+  'pathsFor',
+  'exists',
+  'ensureDir',
+  'readJson',
+  'writeJsonAtomic',
+  'appendJsonl',
+  'withLock',
+  'withGitLock',
+  'readActivityTail',
+  'readText',
+  'writeText',
+  'appendText',
+  'rename',
+  'renameWithRetry',
+  'stat',
+  'unlink',
+  'readGitLock',
+  'gitLockView',
+])
+
+/** @param {unknown} impl */
+export function assertStorePort(impl) {
+  return /** @type {StorePort} */ (assertPort(impl, STORE_PORT, 'store'))
+}

package/ports/vcs.js

@@ -1,11 +1,32 @@
-// Vcs port (#56). Implementation: adapters/vcs-git.js.
+// Vcs port (#69). Implementation: adapters/vcs-git.js.
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} VcsPort
  * @property {(cwd: string, args: string[], options?: object) => Promise<string>} git
  * @property {(cwd: string, args: string[], options?: object) => Promise<string|null>} tryGit
  * @property {(cwd: string, ref: string) => Promise<string>} revParse
  * @property {(cwd: string) => Promise<boolean>} isClean
- * @property {(cwd: string, a: string, b: string) => Promise<boolean>} isAncestor
- * @property {(repoRoot: string) => Promise<{root:string, commonDir:string, branch:string|null}>} resolveRepo
+ * @property {(cwd: string, ancestor: string, descendant: string) => Promise<boolean>} isAncestor
+ * @property {(repoRoot: string) => Promise<{ root: string, commonDir: string, branch: string|null }>} resolveRepo
+ * @property {(cwd: string) => Promise<string|null>} currentBranch
+ * @property {(cwd: string, fromRef: string) => Promise<number>} countCommits
+ * @property {(cwd: string) => Promise<Array<{ path: string, branch?: string, head?: string }>>} listWorktrees
  */
-export {}
+
+export const VCS_PORT = definePort('VcsPort', [
+  'git',
+  'tryGit',
+  'revParse',
+  'isClean',
+  'isAncestor',
+  'resolveRepo',
+  'currentBranch',
+  'countCommits',
+  'listWorktrees',
+])
+
+/** @param {unknown} impl */
+export function assertVcsPort(impl) {
+  return /** @type {VcsPort} */ (assertPort(impl, VCS_PORT, 'vcs'))
+}

package/scripts/architecture-waivers.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "Justified architecture-gate exemptions (#80). Every entry needs rule, path, reason, and owner or ref. Scripts/architecture.mjs fails with waiver-contract when an entry is not justified. domain-pure, host-scope and no-lib-from-core cannot be waived at all, and domain/** accepts no waiver. Since #70 the retired lib/ layer has no waivers: host/** owns ambient state by rule, and only the two I/O adapters below are exempt.",
+  "waivers": [
+    {
+      "rule": "child-process-surface",
+      "path": "adapters/vcs-git.js",
+      "reason": "The git adapter is the single process-spawning boundary; no other module implements VcsPort with a child process.",
+      "owner": "louifinn",
+      "ref": "#50"
+    },
+    {
+      "rule": "fs-surface",
+      "path": "adapters/store-fs.js",
+      "reason": "The filesystem adapter is the single node:fs boundary; the store port needs atomic writes, lock files, and raw store reads.",
+      "owner": "louifinn",
+      "ref": "#50"
+    }
+  ]
+}