opencode-session-port 0.0.0-stage → 0.1.0

package/src/tui/orchestration/checkpoint.ts

@@ -0,0 +1,160 @@
+/**
+ * Injected checkpoint flow (Phase 4, bounded orchestration; `fix-57`).
+ *
+ * `runCheckpointFlow` wires the completed Phase 2/3 core and Phase 4 adapters
+ * into one testable sequence and returns only low-level structured facts:
+ *
+ *   collectCheckpointPayload(port, { projectID, policy })
+ *     → zero sessions ⇒ `no-sessions` outcome (P-04), before the password
+ *       prompt, path resolution, crypto creation, and any filesystem write
+ *     → requestPassword("checkpoint")
+ *       → cancel ⇒ `canceled` outcome, before path resolution and write
+ *     → resolveCheckpointOutputPath({ projectDirectory, explicitPath? }) (P-15)
+ *     → cryptoFactory.create(cryptoPolicy) (explicit injected policy only)
+ *     → crypto.seal(asOneShotByteSource(serializeCheckpointPayload(payload)), password)
+ *     → writeEncryptedArtifact(path, sealedSource)
+ *
+ * Password handling: the resolved `Uint8Array` is treated as flow-owned and is
+ * held until `writeEncryptedArtifact` has consumed the sealed iterable (the
+ * real container's KDF/framing may pull the plaintext lazily), then
+ * best-effort zeroed in `finally` on success and every failure path. There is
+ * no plaintext fallback, no plaintext temp file (A-03), and no secure-deletion
+ * promise (A-07).
+ *
+ * Truthful outcomes: only `no-sessions`, `canceled`, and `written` are
+ * returned. Collection, path, crypto, and write failures propagate unchanged
+ * (for example `SessionCollectionError`, `CryptoContainerError`, `EEXIST`,
+ * `ArtifactFileError`) so an error, cancel, or empty collection can never be
+ * reported as a created artifact. No O-15 report/UX format is produced here —
+ * the caller owns the final report.
+ *
+ * Policy boundaries (all still OPEN; nothing inferred):
+ * - O-01/O-02/O-03: no production numeric policy, format, or cap exists in
+ *   this module. `CryptoPolicy` and the `CheckpointCryptoFactory` are injected
+ *   by the caller; tests use clearly test-only fakes.
+ * - O-10: this flow uses the existing collector's project-scoped enumeration
+ *   and adds no child/subagent enumeration of its own; child-association
+ *   semantics remain OPEN and the collector includes exactly what the
+ *   explicit project scope returns.
+ * - O-15: report formats remain OPEN; only path/session-count/encrypted-byte
+ *   facts cross this boundary.
+ * - P-15/O-08: the path itself comes from the injected
+ *   `resolveCheckpointOutputPath`; this module never invents a path and never
+ *   overwrites an existing artifact.
+ *
+ * Evidence boundary: exercised only by fake ports, fake password providers,
+ * fake crypto factories, and fake store functions. No real host call,
+ * filesystem write, KDF, or import is performed by this lane, and no runtime
+ * or compatibility claim follows.
+ */
+
+import {
+	collectCheckpointPayload,
+	serializeCheckpointPayload,
+	type SessionCollectionPolicy,
+	type SessionReadPort,
+} from "../../core/sessions/index.ts";
+import type { ByteSource, CheckpointCryptoFactory, CryptoPolicy } from "../../core/contracts/index.ts";
+import type { ResolveCheckpointOutputPathOptions } from "../artifacts/files.ts";
+import {
+	asOneShotByteSource,
+	isRecordValue,
+	requireCallable,
+	requireNonEmptyString,
+	zeroPasswordBestEffort,
+	type PasswordProvider,
+} from "./shared.ts";
+
+/** Explicit, fully injected checkpoint dependencies. Every field is required; no defaults exist. */
+export interface CheckpointFlowInput {
+	/** Explicit project scope for collection; the collector re-validates it and never resolves "current". */
+	readonly projectID: string;
+	/** Current project directory used by the P-15 path policy (default `.sessionport/` location). */
+	readonly projectDirectory: string;
+	/** Explicit collection bounds; no defaults are applied (O-03). */
+	readonly policy: SessionCollectionPolicy;
+	/** Caller-supplied crypto factory; no production factory or profile is created here. */
+	readonly cryptoFactory: CheckpointCryptoFactory;
+	/** Explicit allow-listed policy for `factory.create`; never taken from an artifact. */
+	readonly cryptoPolicy: CryptoPolicy;
+	/** Injected `resolveCheckpointOutputPath` (P-15); the real function is passed by the product wiring. */
+	readonly resolveCheckpointOutputPath: (options: ResolveCheckpointOutputPathOptions) => Promise<string>;
+	/** Injected `writeEncryptedArtifact`; receives already-sealed ciphertext bytes only. */
+	readonly writeEncryptedArtifact: (targetPath: string, source: ByteSource) => Promise<number>;
+	/** Interactive password provider; called once per run, `undefined` means canceled. */
+	readonly requestPassword: PasswordProvider;
+	/** Optional explicit output-path override (P-15); omitted uses the default location. */
+	readonly explicitOutputPath?: string;
+}
+
+/** Low-level checkpoint outcome. No O-15 report format is implied. */
+export type CheckpointOutcome =
+	/** P-04: the explicit project scope returned zero sessions; nothing was prompted, resolved, or written. */
+	| { readonly status: "no-sessions" }
+	/** The user canceled the password prompt; nothing was resolved, encrypted, or written. */
+	| { readonly status: "canceled" }
+	/** The sealed artifact was written; the facts below are raw observations, not a UX report. */
+	| {
+			readonly status: "written";
+			readonly artifactPath: string;
+			readonly sessionCount: number;
+			readonly encryptedBytes: number;
+	  };
+
+/**
+ * Runs one checkpoint to a completed encrypted artifact or to a clear
+ * no-sessions/canceled outcome. Errors propagate unchanged; see the module
+ * comment for the exact sequence and policy boundaries.
+ */
+export async function runCheckpointFlow(
+	port: SessionReadPort,
+	input: CheckpointFlowInput,
+): Promise<CheckpointOutcome> {
+	if (!isRecordValue(input)) {
+		throw new TypeError(
+			"runCheckpointFlow requires an input object with explicit projectID, projectDirectory, policy, cryptoFactory, cryptoPolicy, resolveCheckpointOutputPath, writeEncryptedArtifact, and requestPassword",
+		);
+	}
+	requireCallable(input.requestPassword, "requestPassword");
+	requireCallable(input.resolveCheckpointOutputPath, "resolveCheckpointOutputPath");
+	requireCallable(input.writeEncryptedArtifact, "writeEncryptedArtifact");
+	if (!isRecordValue(input.cryptoFactory) || typeof input.cryptoFactory.create !== "function") {
+		throw new TypeError("runCheckpointFlow requires a CheckpointCryptoFactory with a create(policy) function");
+	}
+	const projectID = requireNonEmptyString(input.projectID, "projectID");
+	requireNonEmptyString(input.projectDirectory, "projectDirectory");
+
+	const payload = await collectCheckpointPayload(port, { projectID, policy: input.policy });
+	if (payload.sessions.length === 0) {
+		// P-04: no empty checkpoints. Nothing is prompted, resolved, encrypted, or written.
+		return { status: "no-sessions" };
+	}
+
+	const password = await input.requestPassword("checkpoint");
+	if (password === undefined) {
+		return { status: "canceled" };
+	}
+	if (!(password instanceof Uint8Array)) {
+		throw new TypeError("The checkpoint password provider must resolve with Uint8Array bytes or undefined");
+	}
+
+	try {
+		const artifactPath = await input.resolveCheckpointOutputPath({
+			projectDirectory: input.projectDirectory,
+			...(input.explicitOutputPath !== undefined ? { explicitPath: input.explicitOutputPath } : {}),
+		});
+		const crypto = await input.cryptoFactory.create(input.cryptoPolicy);
+		// `serializeCheckpointPayload` returns bytes; `seal` consumes a ByteSource,
+		// so the serialized payload is handed over as a one-shot borrowed chunk.
+		const sealed = await crypto.seal(asOneShotByteSource(serializeCheckpointPayload(payload)), password);
+		const encryptedBytes = await input.writeEncryptedArtifact(artifactPath, sealed);
+		if (typeof encryptedBytes !== "number" || !Number.isSafeInteger(encryptedBytes) || encryptedBytes < 0) {
+			throw new TypeError("writeEncryptedArtifact must resolve with the exact non-negative integer byte count written");
+		}
+		return { status: "written", artifactPath, sessionCount: payload.sessions.length, encryptedBytes };
+	} finally {
+		// Best-effort only (A-07): the password is zeroed after the sealed
+		// iterable has been consumed (or the write failed), never before.
+		zeroPasswordBestEffort(password);
+	}
+}

package/src/tui/orchestration/index.ts

@@ -0,0 +1,55 @@
+/**
+ * SessionPort V1 TUI orchestration (Phase 4, bounded non-visual lane; `fix-57`).
+ *
+ * Public surface:
+ * - `runCheckpointFlow(port, input)` → collect, prompt, resolve the P-15 path,
+ *   seal, and write one encrypted artifact; returns only `no-sessions` /
+ *   `canceled` / `written` low-level facts.
+ * - `runRestorePreflight(client, input)` → O-12 capability probe, one password
+ *   attempt, authenticated strict-parse of the artifact, destination snapshot,
+ *   the required bounded metadata-only cross-project session-ID occupancy
+ *   inventory (owner-approved 2026-10-14 amendment; after auth/parse and the
+ *   destination read, before planning), and a completed `planRestore`; returns
+ *   the plan plus the caller's explicit target directory.
+ * - `runRestorePreflightWithPasswordAttempts(client, input)` → the
+ *   owner-decided three-attempt restore password loop around
+ *   `runRestorePreflight`; retries only the stable `authentication-failed`
+ *   code and returns a terminal `authentication-failed` outcome after the
+ *   permitted attempts instead of rethrowing the raw crypto error.
+ * - `runRestoreExecution(input)` → sequential parent-first execution of one
+ *   completed `RestorePlan` through the injected `SessionImportAdapter` with
+ *   truthful per-session outcomes (imported / skipped / failed / blocked /
+ *   not-attempted), no retries, independent-branch continuation, blocked
+ *   descendants of a failed/blocked/unattempted parent, and the caller's
+ *   explicit target on every import (O-06 handling policy; the final report
+ *   format stays OPEN as O-15).
+ *
+ * This lane performs no command registration, no real host calls, and no
+ * production crypto configuration. All effects are injected; tests use fake
+ * ports, fake clients, fake importers, fake crypto, and fake store functions
+ * only.
+ *
+ * OPEN decision boundaries preserved here: O-01/O-02/O-03 (no production
+ * profile, format, or numeric cap), O-06 (owner handling policy implemented;
+ * runtime partial-import behavior remains unvalidated), O-10 (child-session
+ * enumeration: the checkpoint flow adds none), O-11 (damage policy), O-15
+ * (final error taxonomy/report format: none is produced here), O-16 (the
+ * restore caller supplies an explicit target). No runtime, compatibility, or
+ * security claim follows from this module.
+ */
+
+export { runCheckpointFlow } from "./checkpoint.ts";
+export type { CheckpointFlowInput, CheckpointOutcome } from "./checkpoint.ts";
+export { runRestorePreflight } from "./restore-preflight.ts";
+export type { RestorePreflightInput, RestorePreflightOutcome } from "./restore-preflight.ts";
+export { isAuthenticationFailure, RESTORE_PASSWORD_ATTEMPT_LIMIT, runRestorePreflightWithPasswordAttempts } from "./restore-auth.ts";
+export type { RestoreAuthenticatedPreflightOutcome } from "./restore-auth.ts";
+export { runRestoreExecution } from "./restore-execution.ts";
+export type {
+	RestoreExecutionInput,
+	RestoreExecutionResult,
+	RestoreExecutionSummary,
+	RestoreSessionExecutionStatus,
+	RestoreSessionOutcome,
+} from "./restore-execution.ts";
+export type { PasswordProvider, PasswordPurpose } from "./shared.ts";

package/src/tui/orchestration/restore-auth.ts

@@ -0,0 +1,94 @@
+/**
+ * Owner-decided restore password-attempt loop (Phase 2 experimental wiring).
+ *
+ * `runRestorePreflightWithPasswordAttempts` wraps the injected
+ * `runRestorePreflight` (Phase 4 orchestration) with the owner decision
+ * recorded in O-07/P-13 (2026-10-10): a restore permits **three failed
+ * password attempts per command run**.
+ *
+ * Exact semantics:
+ * - Each attempt calls `runRestorePreflight` exactly once, which prompts for
+ *   the password through the injected provider and performs the full
+ *   capability probe, lazy artifact read, authentication, strict parse,
+ *   destination snapshot, the required bounded metadata-only cross-project
+ *   session-ID occupancy inventory (owner-approved 2026-10-14 amendment), and
+ *   the `planRestore` preflight.
+ * - Only an error carrying the stable crypto code `"authentication-failed"` is
+ *   retried. The classification is structural (`error.code`), never based on
+ *   message text, so no raw exception detail is inspected, exposed, or logged.
+ * - After the final permitted attempt, the outcome is a truthful
+ *   `{ status: "authentication-failed" }`; the raw error is not rethrown, so
+ *   the caller reports generic copy. This deliberately does not distinguish a
+ *   wrong password from a damaged artifact.
+ * - Every other error (truncated/tampered artifact, invalid UTF-8/JSON,
+ *   destination/planner failure, missing capability, provider failure)
+ *   propagates unchanged on its first occurrence; nothing is retried.
+ * - `canceled` and `capability-unavailable` outcomes pass through unchanged and
+ *   are never retried.
+ *
+ * Password ownership stays with `runRestorePreflight`: each attempt's resolved
+ * bytes are best-effort zeroed in its `finally` block; this wrapper never
+ * retains a password. No import is performed here; the caller owns any later
+ * `runRestoreExecution`.
+ *
+ * Evidence boundary: fake clients, fake crypto, fake artifact sources, fake
+ * destination callbacks, and a fake cross-project inventory callback only. No
+ * real host call, artifact read, KDF, or import is performed by this lane, and
+ * no runtime or compatibility claim follows.
+ */
+
+import {
+	runRestorePreflight,
+	type RestorePreflightInput,
+	type RestorePreflightOutcome,
+} from "./restore-preflight.ts";
+import { isRecordValue } from "./shared.ts";
+
+/**
+ * Owner-decided per-command-run restore attempt limit (O-07/P-13,
+ * 2026-10-10): three failed password attempts, then stop.
+ */
+export const RESTORE_PASSWORD_ATTEMPT_LIMIT = 3;
+
+/**
+ * Restore-preflight outcome including the terminal three-attempt
+ * authentication failure. The final case is returned instead of rethrowing the
+ * raw crypto error so callers can report generic copy.
+ */
+export type RestoreAuthenticatedPreflightOutcome =
+	| RestorePreflightOutcome
+	| { readonly status: "authentication-failed" };
+
+/** True only for the stable crypto `authentication-failed` code; never inspects message text. */
+export function isAuthenticationFailure(error: unknown): boolean {
+	return isRecordValue(error) && error["code"] === "authentication-failed";
+}
+
+/**
+ * Runs the restore preflight with up to `maxAttempts` password attempts
+ * (default: the owner-decided three). See the module comment for the exact
+ * retry/classification policy.
+ */
+export async function runRestorePreflightWithPasswordAttempts(
+	client: unknown,
+	input: RestorePreflightInput,
+	maxAttempts: number = RESTORE_PASSWORD_ATTEMPT_LIMIT,
+): Promise<RestoreAuthenticatedPreflightOutcome> {
+	if (typeof maxAttempts !== "number" || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
+		throw new TypeError("maxAttempts must be an explicit positive safe integer");
+	}
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		try {
+			return await runRestorePreflight(client, input);
+		} catch (error) {
+			if (!isAuthenticationFailure(error)) throw error;
+			if (attempt === maxAttempts) {
+				// Give up after the permitted attempts without disclosing the raw
+				// crypto error; the caller reports generic copy.
+				return { status: "authentication-failed" };
+			}
+		}
+	}
+	// Unreachable: the loop returns or throws on every iteration.
+	return { status: "authentication-failed" };
+}