@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/bootstrap/transaction/executor.ts

@@ -0,0 +1,112 @@
+// The per-action executor interface. The engine (engine.ts) owns everything transactional: the lock, preview
+// revalidation, consent, path resolution and symlink refusal, the journal, backups, staging, atomic replacement,
+// rollback and resume. An executor only says, for one action kind:
+//
+//   plan     which journal class the step is and which path it changes (pure, from the action alone);
+//   check    whether the step may run on this host now (read-only: preconditions, pins, versions);
+//   change   what the target should become (read-only: bytes for a file, a symlink target, a directory tree,
+//            or an `effect` for steps with no file of their own to stage: enrollment, verification, activation,
+//            launch). Large content (a harness, hubctl) is never passed as bytes: it is streamed into the step's
+//            StagingArea (stream.ts) and named as a StagedFile, which the engine moves or copies into place;
+//   undo     how to reverse a done effect that has no backup (clear a stored credential, unload a service).
+//
+// Executors never write files themselves (except an effect, through its own typed client such as the
+// CredentialStore), never receive a shell, and never see the journal's internals. Adapter tasks supply the
+// harness, MCP-registration, service-activation, enrollment and verification executors through this interface.
+import type { Action, ActionKind, EntryClass, EvidenceResult, ExecutionContext, FileState, PathRef, RootMapping } from "../contracts/index.ts"
+import type { TxFs } from "./fs.ts"
+import type { StagedFile, StagingArea } from "./stream.ts"
+import type { ResolveOptions } from "./resolve.ts"
+import type { TxResult } from "./result.ts"
+
+export type ActionOf<K extends ActionKind> = Extract<Action, { kind: K }>
+
+/** The host apply runs on (computed fresh by the caller: hostFingerprint() and targetOf()). */
+export interface HostInfo {
+  readonly fingerprint: string
+  readonly target: string
+}
+
+/**
+ * One file of a directory tree an executor wants staged (a harness unpacked from its verified archive): small
+ * content as bytes, large content as a file of the step's staging area.
+ */
+export type TreeFile = {
+  /** Relative, "/"-separated, inside the tree (isSafeRel). */
+  readonly rel: string
+  readonly mode: number
+} & ({ readonly bytes: Uint8Array } | { readonly staged: StagedFile })
+
+export type Change =
+  /**
+   * Write these bytes (or this staged file: one the step's staging area wrote is moved, any other is copied, its
+   * digest checked while it is copied). `refuse`: an existing different file is a conflict. `backup`: it is backed
+   * up and replaced.
+   */
+  | ({ readonly type: "file"; readonly mode: number; readonly replace: "refuse" | "backup" } & ({ readonly bytes: Uint8Array } | { readonly staged: StagedFile }))
+  | { readonly type: "directory"; readonly mode: number }
+  | { readonly type: "symlink"; readonly target: string; readonly replace: "refuse" | "backup" }
+  /** A fresh, immutable tree (a versioned install root). An existing different tree is a conflict. */
+  | { readonly type: "tree"; readonly files: readonly TreeFile[]; readonly mode: number }
+  /**
+   * v1.1: remove the target file (a service unit of a removed component). The engine backs it up, journals it and
+   * unlinks it; a rollback restores the backup. A missing target is skipped.
+   */
+  | { readonly type: "remove" }
+  /** A step without a file to stage. The engine journals the target's state before and after `perform`. */
+  | { readonly type: "effect"; readonly perform: () => Promise<TxResult<void>> }
+  /** Already exactly as wanted: journaled as skipped. */
+  | { readonly type: "none"; readonly reason: string }
+
+export interface StepPlan {
+  readonly class: EntryClass
+  /** The path the step changes; required for every class except external. */
+  readonly path?: PathRef
+  readonly resolve?: ResolveOptions
+}
+
+export interface StepContext {
+  readonly fs: TxFs
+  readonly roots: readonly RootMapping[]
+  /** v1.1: where apply runs; paths resolve for it. */
+  readonly context: ExecutionContext
+  readonly host: HostInfo
+  readonly now: () => number
+  /** The resolved, symlink-checked absolute path of the step's target (when it has one). */
+  readonly target?: string
+  /** The target's state now. */
+  readonly current: FileState
+  /**
+   * The target's state before this transaction touched it: `current`, unless an earlier step of this transaction
+   * changed the same path and left it exactly so. Preconditions are checked against this.
+   */
+  readonly original: FileState
+  /** Resolves another PathRef with the same symlink rules. */
+  readonly resolve: (ref: PathRef, options?: ResolveOptions) => TxResult<string>
+  /** Records upstream evidence for the apply report (never into the journal). */
+  readonly recordEvidence: (results: readonly EvidenceResult[]) => void
+  /** The step's private scratch space for large downloads and what they unpack to (removed after the step). */
+  readonly staging: StagingArea
+}
+
+export interface UndoContext {
+  readonly fs: TxFs
+  readonly roots: readonly RootMapping[]
+  readonly context: ExecutionContext
+  readonly host: HostInfo
+  readonly now: () => number
+  readonly target?: string
+  /** Why the engine undoes: a credential to clear, or a done external step to reverse. */
+  readonly reason: "clear-credential" | "revert-external"
+}
+
+export interface ActionExecutor<K extends ActionKind = ActionKind> {
+  readonly kind: K
+  plan(action: ActionOf<K>): StepPlan
+  check?(action: ActionOf<K>, ctx: StepContext): Promise<TxResult<void>>
+  change(action: ActionOf<K>, ctx: StepContext): Promise<TxResult<Change>>
+  /** Required for class credential (clear it; a stale credential is never restored). Optional for external. */
+  undo?(action: ActionOf<K>, ctx: UndoContext): Promise<TxResult<void>>
+}
+
+export type ExecutorMap = { readonly [K in ActionKind]?: ActionExecutor<K> }

package/packages/cli/src/bootstrap/transaction/fs.ts

@@ -0,0 +1,194 @@
+// The filesystem operations the applier uses, and nothing more: no exec, no spawn, no network. Everything the
+// transaction layer does to disk goes through a TxFs, so tests can inject faults (ENOSPC, a kill at any step
+// boundary) and the engine stays a pure function of what this interface reports.
+//
+// Writes are only ever "create a new file exclusively" (O_CREAT|O_EXCL|O_NOFOLLOW, then fsync); replacing a file is
+// always stage-then-rename, so a reader (or a crash) sees the old file or the new one, never a torn mix. Large files
+// (a harness binary, hubctl itself) are written and read in chunks (createExclusive, readRange), never whole.
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fchmodSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  readSync,
+  renameSync,
+  rmdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs"
+import type { EntryKind } from "../contracts/index.ts"
+
+export interface EntryInfo {
+  readonly kind: EntryKind
+  /** Permission bits (0..0o7777). */
+  readonly mode: number
+  readonly size: number
+}
+
+/** A file being created exclusively, written in chunks (createExclusive). */
+export interface TxWriter {
+  write(chunk: Uint8Array): void
+  /** Sets the mode, fsyncs and closes: the file is complete. */
+  close(): void
+  /** Closes and removes the incomplete file. */
+  abort(): void
+}
+
+export interface TxFs {
+  /** Does not follow symlinks; undefined when nothing is there. */
+  lstat(path: string): EntryInfo | undefined
+  readFile(path: string): Uint8Array
+  /** At most `length` bytes from `offset` (fewer at the end of the file). Does not follow a final symlink. */
+  readRange(path: string, offset: number, length: number): Uint8Array
+  readlink(path: string): string
+  readdir(path: string): string[]
+  /** Creates a new file (fails if anything exists there, a symlink included), writes it fully, sets `mode`, fsyncs. */
+  writeExclusive(path: string, data: Uint8Array | string, mode: number): void
+  /** Like writeExclusive, for content that arrives in chunks: the file is created now and completed by close(). */
+  createExclusive(path: string, mode: number): TxWriter
+  /** Atomic replace of `to`'s directory entry. */
+  rename(from: string, to: string): void
+  /** Hard link; fails if `to` exists (an atomic create-if-absent of complete content). */
+  link(from: string, to: string): void
+  unlink(path: string): void
+  /** One level; fails if it exists. */
+  mkdir(path: string, mode: number): void
+  /** Creates every missing level with `mode`. */
+  mkdirp(path: string, mode: number): void
+  /** Fails if not empty. */
+  rmdir(path: string): void
+  symlink(target: string, path: string): void
+  chmod(path: string, mode: number): void
+  /** Best effort: makes a rename in `path` durable. */
+  fsyncDir(path: string): void
+}
+
+function kindOf(mode: number): EntryKind {
+  switch (mode & constants.S_IFMT) {
+    case constants.S_IFREG:
+      return "file"
+    case constants.S_IFDIR:
+      return "directory"
+    case constants.S_IFLNK:
+      return "symlink"
+    default:
+      return "other"
+  }
+}
+
+const errno = (error: unknown) => (error as NodeJS.ErrnoException | undefined)?.code
+
+export const nodeFs: TxFs = {
+  lstat(path) {
+    try {
+      const s = lstatSync(path)
+      return { kind: kindOf(s.mode), mode: s.mode & 0o7777, size: s.size }
+    } catch (error) {
+      if (errno(error) === "ENOENT" || errno(error) === "ENOTDIR") return undefined
+      throw error
+    }
+  },
+  readFile: (path) => new Uint8Array(readFileSync(path)),
+  readRange(path, offset, length) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+    try {
+      const out = new Uint8Array(length)
+      let got = 0
+      while (got < length) {
+        const n = readSync(fd, out, got, length - got, offset + got)
+        if (n === 0) break
+        got += n
+      }
+      return got === length ? out : out.subarray(0, got)
+    } finally {
+      closeSync(fd)
+    }
+  },
+  readlink: (path) => readlinkSync(path),
+  readdir: (path) => readdirSync(path),
+  writeExclusive(path, data, mode) {
+    const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, mode)
+    let ok = false
+    try {
+      const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data
+      let offset = 0
+      while (offset < bytes.byteLength) offset += writeSync(fd, bytes, offset, bytes.byteLength - offset)
+      fchmodSync(fd, mode)
+      fsyncSync(fd)
+      ok = true
+    } finally {
+      closeSync(fd)
+      if (!ok) {
+        try {
+          unlinkSync(path)
+        } catch {}
+      }
+    }
+  },
+  createExclusive(path, mode) {
+    const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, mode)
+    let open = true
+    const finish = (complete: boolean) => {
+      if (!open) return
+      open = false
+      try {
+        if (complete) {
+          fchmodSync(fd, mode)
+          fsyncSync(fd)
+        }
+      } finally {
+        closeSync(fd)
+        if (!complete) {
+          try {
+            unlinkSync(path)
+          } catch {}
+        }
+      }
+    }
+    return {
+      write(chunk) {
+        if (!open) throw new Error(`${path} is already closed`)
+        let offset = 0
+        while (offset < chunk.byteLength) offset += writeSync(fd, chunk, offset, chunk.byteLength - offset)
+      },
+      close() {
+        try {
+          finish(true)
+        } catch (error) {
+          try {
+            unlinkSync(path)
+          } catch {}
+          throw error
+        }
+      },
+      abort: () => finish(false),
+    }
+  },
+  rename: (from, to) => renameSync(from, to),
+  link: (from, to) => linkSync(from, to),
+  unlink: (path) => unlinkSync(path),
+  mkdir: (path, mode) => mkdirSync(path, { mode }),
+  mkdirp: (path, mode) => void mkdirSync(path, { recursive: true, mode }),
+  rmdir: (path) => rmdirSync(path),
+  symlink: (target, path) => symlinkSync(target, path),
+  chmod: (path, mode) => chmodSync(path, mode),
+  fsyncDir(path) {
+    try {
+      const fd = openSync(path, constants.O_RDONLY)
+      try {
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+    } catch {}
+  },
+}

package/packages/cli/src/bootstrap/transaction/index.ts

@@ -0,0 +1,12 @@
+// The transactional local applier for bootstrap setup plans (see engine.ts for the guarantees and executor.ts for
+// the per-action executor interface adapters implement). Built on the frozen v1 contracts in ../contracts.
+export * from "./result.ts"
+export * from "./fs.ts"
+export * from "./state.ts"
+export * from "./resolve.ts"
+export * from "./lock.ts"
+export * from "./store.ts"
+export * from "./json-merge.ts"
+export * from "./executor.ts"
+export * from "./builtin.ts"
+export * from "./engine.ts"