@hypit/hypit 0.0.1 → 0.1.0

package/packages/runtime/src/types.ts

@@ -0,0 +1,157 @@
+import type {
+  BlobRef,
+  BuildDefinition,
+  BuildFact,
+  BuildState,
+  CommandResult,
+  CoreCommand,
+  ResourceId,
+} from "@hypit/protocol";
+import type { OperationSnapshot } from "./operations.js";
+
+export type RuntimeBlockedCommand = {
+  readonly command: string;
+  readonly reason: string;
+  readonly subject: string;
+};
+
+export type RuntimeRunnableCommand = {
+  readonly command: CoreCommand;
+  /** Every resource is acquired atomically before the command can cause a side effect. */
+  readonly resources: readonly RuntimeResourceClaim[];
+  /** Asynchronous work retains one shared in-flight reservation while polling. */
+  readonly capacityMode?: "active" | "asynchronous";
+};
+
+export type RuntimeResourceClaim = import("./capacity.js").CapacityResourceClaim;
+
+export type RuntimeWorkerRunOptions = {
+  readonly idlePollMs: number;
+  readonly signal?: AbortSignal;
+  /** Called after abandoned work is claimable and immediately before the claim loop starts. */
+  readonly ready?: () => void | Promise<void>;
+};
+
+export type RuntimePreparation = {
+  readonly state: BuildState;
+  readonly runnable: readonly RuntimeRunnableCommand[];
+  readonly blocked: readonly RuntimeBlockedCommand[];
+};
+
+export type RuntimeExecutionContext = {
+  /** Stable Run-local identity; two identical BuildRequests may still be distinct Builds. */
+  readonly build: string;
+  /** Release only the asynchronous Operation's occupancy after its remote end is confirmed. */
+  readonly releaseOperationCapacity?: () => Promise<void>;
+};
+
+export type RuntimeActionResult<T> =
+  | { readonly status: "completed"; readonly value: T }
+  | Extract<RuntimeExecutionResult, { readonly status: "deferred" }>;
+
+/** One short action; occupancy ends with the call, while rate consumption remains. */
+export type RuntimeActionExecutor = {
+  run<T>(request: { readonly build: string; readonly command: string; readonly action: string;
+    readonly resources: readonly RuntimeResourceClaim[] }, execute: () => Promise<T>): Promise<RuntimeActionResult<T>>;
+};
+
+export type RuntimeExecutionResult =
+  | { readonly status: "completed"; readonly event: CommandResult }
+  | { readonly status: "pending"; readonly operation: string; readonly wakeAt?: number }
+  | { readonly status: "deferred"; readonly wakeAt?: number; readonly reason: string };
+
+/** Minimal execution port used by a Scheduler. `prepare` is the sole command-generation boundary. */
+export type RuntimeCommandExecutor = {
+  prepare(state: BuildState): RuntimePreparation;
+  executeCommand(
+    state: BuildState,
+    command: RuntimeRunnableCommand,
+    context: RuntimeExecutionContext,
+  ): Promise<RuntimeExecutionResult>;
+  cancelOperation?(
+    state: BuildState,
+    operation: OperationSnapshot,
+  ): Promise<OperationSnapshot>;
+  advanceOperation?(operation: OperationSnapshot): Promise<OperationSnapshot>;
+  /** Validate an already received result without invoking a Producer or contacting an Endpoint. */
+  acceptOperation?(state: BuildState, operation: OperationSnapshot): Promise<CommandResult | undefined>;
+};
+
+/** Build-local byte resources. Location, retention and transport are Runtime policy. */
+export type ResourceIOOptions = {
+  /** Cancel the transfer, close its streams and discard unfinished writes before rejecting.
+   * Stream producers supplied by the caller must observe the same signal while producing chunks.
+   */
+  readonly signal?: AbortSignal;
+};
+
+export type ResourceStore = {
+  /** Store one new resource instance. Equal bytes remain independent resources. */
+  put(bytes: Uint8Array, mediaType: string, options?: ResourceIOOptions): Promise<BlobRef>;
+  /** Write bytes for an already-declared source or historical resource. */
+  write(resource: BlobRef, bytes: Uint8Array, options?: ResourceIOOptions): Promise<void>;
+  /** Read bytes previously stored under this execution identity. */
+  get(resource: ResourceId, options?: ResourceIOOptions): Promise<Uint8Array | undefined>;
+  /** Cheap presence query. */
+  has(resource: ResourceId, options?: ResourceIOOptions): Promise<boolean>;
+};
+
+/** Optional transfer capability. Core and components never require storage to expose it. */
+export type StreamingResourceStore = ResourceStore & {
+  putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string, options?: ResourceIOOptions): Promise<BlobRef>;
+  writeStream(resource: BlobRef, chunks: AsyncIterable<Uint8Array>, options?: ResourceIOOptions): Promise<void>;
+  /** Stream bytes previously stored under this resource identity. */
+  open(resource: ResourceId, options?: ResourceIOOptions): Promise<AsyncIterable<Uint8Array> | undefined>;
+};
+
+export function isStreamingResourceStore(value: ResourceStore): value is StreamingResourceStore {
+  return "putStream" in value && typeof value.putStream === "function"
+    && "writeStream" in value && typeof value.writeStream === "function"
+    && "open" in value && typeof value.open === "function";
+}
+
+export type BuildSnapshot = {
+  readonly build: string;
+  readonly definition: BuildDefinition;
+  readonly facts: readonly BuildFact[];
+  /** Materialized read view reconstructed from Definition + Facts; never stored as authority. */
+  readonly state: BuildState;
+};
+
+/** Stores one Definition and the Core Facts accepted for it in order. */
+export type BuildStore = {
+  create(build: string, definition: BuildDefinition): Promise<BuildSnapshot>;
+  read(build: string): Promise<BuildSnapshot | undefined>;
+  append(build: string, fact: BuildFact): Promise<void>;
+  /** Drop execution material after the project Build Result has become authoritative. */
+  remove?(build: string): Promise<void>;
+};
+
+export type ScheduledBuild =
+  | { readonly id: string; readonly state: BuildState; readonly snapshot?: never }
+  | { readonly id: string; readonly snapshot: BuildSnapshot; readonly state?: never };
+
+export type SchedulerExecutionOutcome = {
+  readonly command: string;
+  readonly kind: CoreCommand["kind"];
+  readonly resources: readonly string[];
+  readonly status: "completed" | "pending" | "deferred" | "error";
+  readonly operation?: string;
+  readonly wakeAt?: number;
+  readonly message?: string;
+};
+
+export type ScheduledBuildResult = {
+  readonly id: string;
+  readonly status: "complete" | "paused" | "failed";
+  readonly state: BuildState;
+  readonly outcomes: readonly SchedulerExecutionOutcome[];
+  readonly blocked: readonly RuntimeBlockedCommand[];
+};
+
+export type BuildSchedulerOptions = {
+  /** Optional durable authority. When present, every admitted Core Fact is appended. */
+  readonly buildStore?: BuildStore;
+  /** Called after an accepted event changes the materialized Build view. */
+  readonly onStateChange?: (build: string, state: BuildState) => Promise<void>;
+};

package/packages/runtime-host-node/README.md

@@ -0,0 +1,25 @@
+# `@hypit/runtime-host-node`
+
+Node.js Runtime port shared by the generic CLI and an application's chosen Runtime implementation,
+plus environment helpers for Endpoint adapters.
+
+The package keeps Node-specific process control out of the host-neutral Runtime contracts. It provides:
+
+- project-root resolution for configured relative executable paths;
+- executable availability diagnostics for absolute, relative and `PATH` commands;
+- explicit environment-credential diagnostics.
+
+These functions produce `RuntimeDoctorDiagnostic` values only. They do not construct Endpoints,
+read secret values, execute commands or choose fallback Providers.
+
+The generic CLI depends only on this port. The official video application selects
+`@hypit/runtime-local` directly; Runtime Profiles vary credentials, Endpoints and their services
+rather than replacing the Runtime itself or selecting Build history storage. A second application
+may supply another `NodeRuntimeHost` at its Distribution assembly boundary; no unused Host plugin
+registry or selector is exposed in a local Profile.
+
+The same port lets an authoring application open a disposable transient execution. The caller hands
+over a graph state, deterministic Producers, validators and temporary Resources; the Runtime keeps
+Endpoint selection, handlers and concurrency for that disposable session private and returns the evaluated
+state. This is an execution boundary, not a second Runtime Profile, Build type, cross-Build scheduler or
+preview registry.

package/packages/runtime-host-node/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hypit/runtime-host-node",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/build-result": "workspace:*",
+    "@hypit/build-result-kit": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/workspace": "workspace:*"
+  }
+}

package/packages/runtime-host-node/src/index.ts

@@ -0,0 +1,421 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import type { ArtifactAttachment } from "@hypit/workspace";
+import type { BuildResultForward } from "@hypit/build-result";
+import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
+import type { DriverRunResult, NodeDriverOptions, ProducerRegistry } from "@hypit/driver-node";
+import type { BuildDefinition, BuildState, CanonicalValue, CapabilityRef, Need, StoredValue } from "@hypit/protocol";
+import type {
+  BuildCatalogDescriptor,
+  BuildCompletion,
+  BuildExecutionStop,
+  CapacityReservation,
+  CredentialAcquisition,
+  CredentialRef,
+  OperationSnapshot,
+  ResourceStore,
+  RuntimeWorkerRunOptions,
+} from "@hypit/runtime";
+import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";
+
+export type RuntimeHostActiveBuildSubmission = {
+  readonly id: string;
+  readonly state: BuildState;
+  readonly view: BuildView;
+};
+
+export type RuntimeHostFinishedBuildSubmission = {
+  readonly id: string;
+  readonly state: BuildState;
+  readonly completion: BuildCompletion;
+};
+
+export type RuntimeHostBuildSubmission = RuntimeHostActiveBuildSubmission | RuntimeHostFinishedBuildSubmission;
+
+export type BuildActivity = "submitting" | "ready" | "running" | "waiting" | "saving-result";
+
+export type BuildOperationView = {
+  readonly id?: string;
+  readonly receipt?: import("@hypit/runtime").OperationReceipt;
+  readonly wakeAt?: number;
+  readonly endpoint: string;
+  readonly status: OperationSnapshot["status"];
+  readonly progress?: OperationSnapshot["progress"];
+  readonly failure?: OperationSnapshot["failure"];
+};
+
+/** Stable Host view. Runtime persistence records never cross this boundary. */
+export type BuildView = {
+  readonly id: string;
+  readonly createdAt: number;
+  readonly activity: BuildActivity;
+  readonly outcome?: BuildCompletion["outcome"];
+  readonly issue?: { readonly scope: "result" | "cleanup"; readonly message: string };
+  readonly cancellationRequested: boolean;
+  readonly stop?: BuildExecutionStop;
+  readonly source?: { readonly path: string };
+  readonly run?: { readonly path: string };
+  readonly targets: readonly string[];
+  /** External Needs in the frozen Build Plan and the subset already accepted by Core. */
+  readonly requests?: { readonly total: number; readonly completed: number };
+  readonly acceptedRecords: number;
+  readonly outstandingCommands: number;
+  readonly operations: readonly BuildOperationView[];
+};
+
+export type RuntimeHostCredentialStatus = {
+  readonly endpoint: string;
+  readonly slot: string;
+  readonly label: string;
+  readonly kind: "secret" | "json";
+  readonly ref: CredentialRef;
+  readonly acquisition?: CredentialAcquisition;
+  readonly configured: boolean;
+  readonly writable: boolean;
+};
+
+export type RuntimeHostControl = {
+  inspect(build: string): Promise<BuildView | undefined>;
+  activity(): Promise<{
+    readonly builds: readonly BuildView[];
+    readonly capacity: readonly CapacityReservation[];
+  }>;
+  cancel(build: string, reason?: string): Promise<BuildView | undefined>;
+  close(): void | Promise<void>;
+};
+
+/** One-shot Result write or incomplete-submission cleanup with no execution Providers. */
+export type RuntimeHostResultControl = {
+  finishResult(build: string): Promise<{
+    readonly id: string;
+    readonly outcome: BuildCompletion["outcome"];
+    readonly issue?: { readonly scope: "result" | "cleanup"; readonly message: string };
+  } | undefined>;
+  discardSubmission(build: string): Promise<boolean>;
+  close(): void | Promise<void>;
+};
+
+export type RuntimeHostCredentialControl = {
+  credentials(endpoint?: string): Promise<readonly RuntimeHostCredentialStatus[]>;
+  putCredential(endpoint: string, slot: string, secret: string): Promise<RuntimeHostCredentialStatus>;
+  deleteCredential(endpoint: string, slot: string): Promise<{
+    readonly deleted: boolean;
+    readonly credential: RuntimeHostCredentialStatus;
+  }>;
+  close(): void | Promise<void>;
+};
+
+export type RuntimeHostExecution = RuntimeHostControl & RuntimeHostCredentialControl & RuntimeHostResultControl & {
+  build(request: {
+    readonly id: string;
+    readonly definition: BuildDefinition;
+    readonly componentPackages?: readonly string[];
+    readonly catalog: BuildCatalogDescriptor;
+    readonly attachments?: readonly ArtifactAttachment[];
+    /** Project-owned Result destination, fixed before this Build becomes active. */
+    readonly result: {
+      readonly repository: BuildResultRepositoryLocation;
+      readonly title?: string;
+      readonly forwards?: readonly BuildResultForward[];
+    };
+  }, options?: {
+    readonly follow?: boolean;
+    readonly pollIntervalMs?: number;
+    readonly maxWaitMs?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<RuntimeHostBuildSubmission>;
+  work(options: RuntimeWorkerRunOptions): Promise<void>;
+};
+
+export type RuntimeHostDoctorResult = {
+  readonly dataRoot: string;
+  readonly diagnostics: readonly RuntimeDoctorDiagnostic[];
+};
+
+/**
+ * Disposable graph evaluation through capabilities that their Providers explicitly allow outside
+ * a Build. The Host owns Endpoint selection, credentials, invocation and session-local concurrency;
+ * callers contribute only deterministic domain Producers, validation and an ephemeral ResourceStore.
+ */
+export type RuntimeHostTransientExecution = {
+  evaluate(input: {
+    readonly state: BuildState;
+    readonly producers: ProducerRegistry;
+    readonly validators: NonNullable<NodeDriverOptions["validators"]>;
+    readonly resources: ResourceStore;
+  }): Promise<DriverRunResult>;
+  close(): void | Promise<void>;
+};
+
+/** The selected Endpoint behind one demanded capability, read from the Profile alone. */
+export type RuntimeHostCapabilityProvider = {
+  /** Caller-owned identity for this planned request. */
+  readonly request: string;
+  readonly capability: CapabilityRef;
+  readonly status: "resolved" | "unresolved" | "unsupported" | "ambiguous";
+  /** Configured Endpoint instance selected for this request, when exactly one is identifiable. */
+  readonly endpoint?: string;
+  /** Provider package the Runtime Profile selected for that Endpoint. */
+  readonly use?: string;
+  /** Where that Provider publishes its prices, as the Provider package declares it. */
+  readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };
+  /** Every matching Endpoint instance when the selection is ambiguous. */
+  readonly endpoints?: readonly string[];
+  /** Provider-owned reasons from Endpoints that offer the capability but reject this request. */
+  readonly rejections?: readonly { readonly endpoint: string; readonly message: string }[];
+  /** The Endpoint instance the Profile's `bindings` name for this capability, when it names one. */
+  readonly binding?: string;
+};
+
+export type RuntimeHostCapabilityPricing = RuntimeHostCapabilityProvider & {
+  /** Provider-owned current pricing material relevant to this request. */
+  readonly pricingDocuments?: readonly {
+    readonly source: string;
+    readonly data: CanonicalValue;
+    readonly summary?: string;
+  }[];
+  /** A failed pricing-source read. The Provider's static price page remains available. */
+  readonly pricingError?: string;
+};
+
+export type RuntimeHostProviderQuery = {
+  readonly request: string;
+  readonly capability: CapabilityRef;
+  readonly returns: import("@hypit/protocol").TypeRef;
+  /** Complete support-relevant parameters available before the Build. */
+  readonly constraints: import("@hypit/protocol").CanonicalValue;
+  /** Future graph inputs described by the package that owns this request. */
+  readonly pendingInputs?: readonly {
+    readonly input: string;
+    readonly role?: string;
+  }[];
+};
+
+export type ManagedProgramProgress = {
+  readonly id: string;
+  readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+};
+
+export type ManagedProgramReport = {
+  readonly id: string;
+  readonly endpoint: string;
+  readonly action?: "already-running" | "installed" | "started" | "stopped" | "not-ours" | "nothing-to-stop" | "unchanged";
+  readonly state:
+    | { readonly state: "ready" }
+    | { readonly state: "down"; readonly detail: string }
+    | { readonly state: "mismatch"; readonly detail: string };
+  readonly detail?: string;
+  readonly logPath?: string;
+  readonly pid?: number;
+};
+
+export type RuntimeWorkerState = {
+  readonly state: "running" | "stopped";
+  readonly configuration?: "current" | "changed";
+  readonly profile: string;
+  readonly pid?: number;
+  readonly startedAt?: number;
+  readonly logPath: string;
+};
+
+export type RuntimeController = {
+  readonly profile: string;
+  readonly dataRoot: string;
+  readonly worker: {
+    up(options?: { readonly maxWaitMs?: number }): Promise<RuntimeWorkerState>;
+    status(): Promise<RuntimeWorkerState>;
+    logs(): Promise<{ readonly path: string; readonly text: string }>;
+    down(options?: { readonly maxWaitMs?: number }): Promise<RuntimeWorkerState>;
+  };
+  readonly programs: {
+    up(options: {
+      readonly maxWaitMs?: number;
+      readonly onProgress?: (event: ManagedProgramProgress) => void;
+      readonly capabilities?: readonly CapabilityRef[];
+    }): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }>;
+    down(): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }>;
+    report(): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }>;
+  };
+};
+
+export type RuntimeWorkerLaunch = {
+  readonly command: string;
+  readonly args: readonly string[];
+};
+
+export type NodeRuntimeHost = {
+  readonly profile: string;
+  resolvePaths(): Promise<{
+    readonly packageRoot?: string;
+    readonly runtimeDataRoot?: string;
+  }>;
+  controller(options?: {
+    readonly packageRoot?: string;
+  }): Promise<RuntimeController>;
+  createRuntime(): Promise<RuntimeHostExecution>;
+  openControl(options?: { readonly readOnly?: boolean }): Promise<RuntimeHostControl>;
+  /** Open only Result-writing dependencies; never construct execution Providers. */
+  openResultControl(): Promise<RuntimeHostResultControl>;
+  openCredentials(endpoint: string): Promise<RuntimeHostCredentialControl>;
+  /** Explicitly prepare upstream packages selected by this Runtime Profile. */
+  prepare(options?: {
+    readonly onProgress?: (event: import("./packages.js").HostPackageProgress) => void;
+  }): Promise<readonly import("./packages.js").HostPackageReport[]>;
+  /**
+   * Read-only, bounded deployment validation for one demanded Build slice.
+   * It may inspect local files, credentials and loopback program state, but it
+   * never installs, starts or contacts a remote Provider or Artifact Store.
+   */
+  preflight(options?: {
+    readonly capabilities?: readonly CapabilityRef[];
+  }): Promise<RuntimeHostDoctorResult>;
+  /** Active deployment diagnosis. Unlike preflight, adapters may contact their configured services. */
+  doctor(options?: {
+    readonly capabilities?: readonly CapabilityRef[];
+  }): Promise<RuntimeHostDoctorResult>;
+  /**
+   * Which selected Endpoint would serve each capability and where its Provider publishes prices.
+   * Reads the Profile and Endpoint declarations only; never resolves a credential or contacts a service.
+   */
+  providers(requests: readonly RuntimeHostProviderQuery[]): Promise<readonly RuntimeHostCapabilityProvider[]>;
+  /** Read current Provider-owned pricing material relevant to these requests. */
+  pricing(requests: readonly RuntimeHostProviderQuery[]): Promise<readonly RuntimeHostCapabilityPricing[]>;
+  /**
+   * Execute one immediate Need through the selected Endpoint and its credentials, outside any Build.
+   * The creation-time boundary for observation, transcription and other quick capabilities; it
+   * creates no Build, Result or state, and refuses asynchronous capabilities.
+   */
+  invoke(need: Need, resources: ResourceStore): Promise<{ readonly value: StoredValue }>;
+  /** Open one disposable authoring execution. It creates no Build, Result or recoverable Operation. */
+  openTransientExecution(): Promise<RuntimeHostTransientExecution>;
+  runWorker(readyFile: string, owner: string): Promise<void>;
+};
+
+/**
+ * Persistent state owned by the installed Hypit Host, never by an author project
+ * or a replaceable source checkout.
+ */
+export function hypitHostStateRoot(options: {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly platform?: NodeJS.Platform;
+  readonly home?: string;
+} = {}): string {
+  const env = options.env ?? process.env;
+  const override = env.HYPIT_STATE_HOME;
+  if (override !== undefined && override.trim().length > 0) return resolve(override);
+  const platform = options.platform ?? process.platform;
+  const home = options.home ?? homedir();
+  if (platform === "darwin") return join(home, "Library", "Application Support", "Hypit");
+  if (platform === "win32") {
+    const local = env.LOCALAPPDATA;
+    return join(local === undefined || local.trim().length === 0
+      ? join(home, "AppData", "Local")
+      : local, "Hypit");
+  }
+  const state = env.XDG_STATE_HOME;
+  return join(state === undefined || state.trim().length === 0
+    ? join(home, ".local", "state")
+    : state, "hypit");
+}
+
+/** Upstream npm packages shared by every Hypit project and future session on this machine. */
+export function hypitHostPackageRoot(hostStateRoot = hypitHostStateRoot()): string {
+  return join(resolve(hostStateRoot), "packages");
+}
+
+function pathLike(value: string): boolean {
+  return isAbsolute(value) || value.includes("/") || value.includes("\\");
+}
+
+/** Bare command names remain PATH-resolved; configured relative paths are rooted at the Runtime Profile root. */
+export function resolveRuntimeExecutable(root: string, value: string): string {
+  return pathLike(value) && !isAbsolute(value) ? resolve(root, value) : value;
+}
+
+async function executableExists(value: string): Promise<boolean> {
+  const unavailable = (error: unknown) => error instanceof Error && "code" in error
+    && ["ENOENT", "ENOTDIR", "EACCES"].includes(String(error.code));
+  const extensions = process.platform === "win32" && !/\.[^\\/]+$/u.test(value)
+    ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+    : [];
+  // A configured path names one file, and on Windows this asks only whether that file is there, so
+  // it is tried as written before any PATHEXT extension. A bare command name is resolved the way a
+  // shell would resolve it, where an extensionless entry is not something Windows can run.
+  const candidates = (base: string, suffixes: readonly string[]) =>
+    (suffixes.length === 0 ? [""] : suffixes).map((suffix) => `${base}${suffix}`);
+  const available = async (candidate: string): Promise<boolean> => {
+    try {
+      await access(candidate, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+      return true;
+    } catch (error) {
+      if (unavailable(error)) return false;
+      throw error;
+    }
+  };
+  if (pathLike(value)) {
+    for (const candidate of candidates(value, ["", ...extensions])) if (await available(candidate)) return true;
+    return false;
+  }
+  for (const directory of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    for (const candidate of candidates(resolve(directory, value), extensions)) {
+      if (await available(candidate)) return true;
+    }
+  }
+  return false;
+}
+
+export async function diagnoseRuntimeExecutable(options: {
+  readonly root: string;
+  readonly configured: string | undefined;
+  readonly fallback: string;
+  readonly subject: string;
+}): Promise<readonly RuntimeDoctorDiagnostic[]> {
+  const value = resolveRuntimeExecutable(options.root, options.configured ?? options.fallback);
+  return await executableExists(value) ? [] : [{
+    severity: "error",
+    code: "RUNTIME_EXECUTABLE_MISSING",
+    message: `${options.subject} executable ${value} is unavailable`,
+    subject: value,
+  }];
+}
+
+export function diagnoseRuntimeEnvironmentCredential(
+  variable: string,
+  subject: string,
+): readonly RuntimeDoctorDiagnostic[] {
+  return process.env[variable]?.trim()
+    ? []
+    : [{
+      severity: "error",
+      code: "RUNTIME_CREDENTIAL_MISSING",
+      message: `${subject} requires environment variable ${variable}`,
+      subject: variable,
+    }];
+}
+
+/** Executables inside a Python virtual environment have one platform-defined layout. */
+export function pythonEnvironmentExecutable(environment: string): string {
+  return process.platform === "win32"
+    ? resolve(environment, "Scripts", "python.exe")
+    : resolve(environment, "bin", "python");
+}
+
+/** Console scripts installed by Python use an executable shim on Windows. */
+export function pythonEnvironmentCommand(environment: string, name: string): string {
+  return process.platform === "win32"
+    ? resolve(environment, "Scripts", `${name}.exe`)
+    : resolve(environment, "bin", name);
+}
+
+export {
+  inspectHostPackage,
+  parseRegistryPackageSpec,
+  prepareHostPackages,
+} from "./packages.js";
+export type {
+  HostPackageProgress,
+  HostPackageReport,
+  RegistryPackageSpec,
+} from "./packages.js";