dsh-tower 2.1.0-beta.1 → 2.3.0

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"
+    }
+  ]
+}