@hypit/hypit 0.0.1 → 0.1.1

package/packages/cli/src/commands/execution.ts

@@ -0,0 +1,321 @@
+import type { BuildResultManifest, BuildResultRepository } from "@hypit/build-result";
+import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
+
+import type { CliCommand, ExecutionCommand } from "../command.js";
+import { activityObservationKey, buildProgressLines, observeBuildView } from "../observation.js";
+import type { CliIo } from "../output.js";
+import type { CliRuntimeController } from "../runtime-port.js";
+import { formatOperationProgress } from "../runtime-view.js";
+import { buildStatusView } from "../view.js";
+import type { OperationalWriter } from "./types.js";
+
+type OpenProjectResults = () => Promise<{
+  readonly repository: BuildResultRepository;
+  close(): void | Promise<void>;
+}>;
+
+export function isExecutionCommand(args: CliCommand): args is ExecutionCommand {
+  return args.command === "status" || args.command === "cancel" || args.command === "activity"
+    || (args.command === "result" && (args.action === "finish" || args.action === "discard"));
+}
+
+/** Inspect or control accepted Build work. Observation never owns execution. */
+export async function runExecutionCommand(input: {
+  readonly args: ExecutionCommand;
+  readonly runtimeProfile: string | undefined;
+  readonly io: CliIo;
+  readonly runtimeHost: (profile: string) => Promise<NodeRuntimeHost>;
+  readonly runtimeController: (profile: string) => Promise<CliRuntimeController>;
+  readonly openProjectResults: OpenProjectResults;
+  readonly write: OperationalWriter;
+}): Promise<void> {
+  const { args, runtimeProfile, io, runtimeHost, runtimeController, openProjectResults, write } = input;
+  if (args.command === "status" && runtimeProfile === undefined) {
+    const openedResults = await openProjectResults();
+    let result;
+    try {
+      result = await openedResults.repository.read(args.build);
+    } finally {
+      await openedResults.close();
+    }
+    if (args.watch && result?.outcome === undefined) {
+      throw new Error(`Build ${args.build} has no finished Result; select its Runtime to observe active execution`);
+    }
+    const finished = result?.outcome !== undefined;
+    const build = result === undefined ? null : buildStatusView({ id: result.id, result });
+    const outcome = result?.outcome;
+    write({ format: "hypit.cli-status@1", build }, result === undefined
+      ? "Build Result not found"
+      : outcome === "complete" ? "Build complete"
+        : outcome === "failed" ? "Build failed"
+          : outcome === "cancelled" ? "Build cancelled" : "Build Result is open",
+    result === undefined || !finished ? "warning"
+      : outcome === "failed" ? "error"
+        : outcome === "cancelled" ? "warning" : "success", [
+      ["Build", args.build],
+      ...(build?.title === undefined ? [] : [["Title", build.title] as const]),
+      ...(outcome === undefined ? [] : [["Outcome", outcome] as const]),
+      ...(!finished && result !== undefined ? [["Result", "open"] as const] : []),
+      ...(build?.result.outputCount === undefined ? [] : [["Outputs", String(build.result.outputCount)] as const]),
+    ], !finished && result !== undefined
+      ? ["Select the Runtime to inspect active work."]
+      : []);
+    if (result === undefined || !finished) io.setExitCode?.(1);
+    return;
+  }
+
+  if (runtimeProfile === undefined) {
+    throw new Error(`${args.command} requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>`);
+  }
+  const selectedHost = await runtimeHost(runtimeProfile);
+
+  if (args.command === "result" && args.action === "discard") {
+    const resultControl = await selectedHost.openResultControl();
+    const discarded = await resultControl.discardSubmission(args.build)
+      .finally(async () => await resultControl.close());
+    write({ format: "hypit.cli-result-discard@1", build: args.build, discarded }, discarded
+      ? "Incomplete Build discarded"
+      : "Incomplete Build not found", discarded ? "success" : "warning", [
+        ["Build", args.build],
+        ["State", discarded ? "discarded" : "missing"],
+      ], discarded ? ["The incomplete submission was removed."] : []);
+    if (!discarded) io.setExitCode?.(1);
+    return;
+  }
+
+  const runtime = await selectedHost.openControl({ readOnly: args.command !== "cancel" });
+  try {
+    if (args.command === "activity") {
+      const controller = await runtimeController(runtimeProfile);
+      let previous: string | undefined;
+      const writeActivity = async (): Promise<void> => {
+        const [activity, worker] = await Promise.all([
+          runtime.activity(),
+          controller.worker.status(),
+        ]);
+        const builds = activity.builds.slice(0, args.limit).map((item) => {
+          const status = buildStatusView({ id: item.id, runtime: item });
+          return {
+            id: item.id,
+            work: status.work,
+            ...(item.outcome === undefined ? {} : { outcome: item.outcome }),
+            ...(status.attention === undefined ? {} : { attention: status.attention }),
+          };
+        });
+        const currentView = activityObservationKey(worker.state, activity.builds);
+        if (args.watch && currentView === previous) return;
+        previous = currentView;
+        const value = {
+          format: "hypit.cli-activity@1" as const,
+          at: Date.now(),
+          worker: worker.state,
+          builds,
+          ...(activity.builds.length <= args.limit ? {} : { omittedBuilds: activity.builds.length - args.limit }),
+          capacity: activity.capacity,
+        };
+        const buildLines = activity.builds.slice(0, args.limit).map((item) => {
+          const requestProgress = item.requests === undefined || item.requests.total === 0
+            ? ""
+            : ` · ${item.requests.completed}/${item.requests.total} steps`;
+          return `${item.id}: ${buildStatusView({ id: item.id, runtime: item }).work.state}`
+            + requestProgress
+            + `${item.stop?.cause === "execution-failed" ? " · stopping after failure" : item.cancellationRequested ? " · cancelling" : ""}`
+            + `${item.issue === undefined ? "" : ` · ${item.issue.message}`}`;
+        });
+        const activeOperations = activity.builds.flatMap((item) => item.operations)
+          .filter((item) => item.status === "pending");
+        const operationLines = args.presentation.verbose
+          ? activity.builds.flatMap((build) => build.operations.filter((item) => item.status === "pending")
+              .map((item) => `${build.id} · ${item.endpoint}: ${item.progress === undefined
+                ? item.status
+                : formatOperationProgress(item.progress)}`)).slice(0, args.limit)
+          : [];
+        write(value, "Runtime activity", activity.builds.length === 0 ? "success" : "info", [
+          ["Active Builds", String(activity.builds.length)],
+          ["Active Operations", String(activeOperations.length)],
+          ["Worker", worker.state],
+        ], [
+          ...buildLines,
+          ...(operationLines.length === 0 ? [] : ["Operations:", ...operationLines]),
+        ]);
+      };
+      if (!args.watch) await writeActivity();
+      else while (true) {
+        await writeActivity();
+        await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));
+      }
+      return;
+    }
+
+    if (args.command === "status") {
+      let view = await runtime.inspect(args.build);
+      let result: BuildResultManifest | undefined;
+      let resultReadError: string | undefined;
+      let openedResults: Awaited<ReturnType<OpenProjectResults>> | undefined;
+      try {
+        openedResults = await openProjectResults();
+        if (args.watch && view !== undefined && view.issue === undefined) {
+          const controller = await runtimeController(runtimeProfile);
+          view = await observeBuildView(runtime, args.build, view, {
+            ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
+            controller,
+            ...(args.presentation.json ? {} : {
+              onProgress: (progress) => {
+                for (const line of buildProgressLines(progress, {
+                  verbose: args.presentation.verbose,
+                  limit: args.limit,
+                })) io.write(`${line}\n`);
+              },
+            }),
+          });
+        }
+        result = await openedResults.repository.read(args.build);
+      } catch (error) {
+        resultReadError = error instanceof Error ? error.message : String(error);
+      } finally {
+        await openedResults?.close();
+      }
+      const found = view !== undefined || result !== undefined;
+      const activity = view?.activity;
+      const resultOutcome = result?.outcome;
+      const outcome = resultOutcome ?? view?.outcome;
+      const savingResult = activity === "saving-result" && resultOutcome === undefined;
+      const issue = view?.issue;
+      const build = !found ? null : buildStatusView({
+        id: view?.id ?? result!.id,
+        ...(view === undefined ? {} : { runtime: view }),
+        ...(result === undefined ? {} : { result }),
+        ...(resultReadError === undefined ? {} : { resultReadError }),
+        verbose: args.presentation.verbose,
+        operationLimit: args.limit,
+      });
+      const attention = build?.attention;
+      const humanTitle = !found
+        ? "Build not found"
+        : attention !== undefined
+          ? "Build needs attention"
+          : savingResult
+            ? "Saving Build Result"
+            : resultOutcome === "complete"
+              ? "Build complete"
+              : resultOutcome === "failed"
+                ? "Build failed"
+                : resultOutcome === "cancelled"
+                  ? "Build cancelled"
+                  : args.watch && activity === undefined ? "Build finished" : "Build active";
+      write({ format: "hypit.cli-status@1", build }, !found
+        ? "Build not found" : humanTitle,
+      !found
+        ? "warning"
+        : attention !== undefined
+          ? "error"
+          : outcome === "failed"
+            ? "error"
+            : outcome === "cancelled"
+              ? "warning"
+              : resultOutcome === "complete"
+                ? "success"
+                : args.watch && activity !== undefined ? "warning" : "info", [
+          ["Build", args.build],
+          ...(build?.title === undefined ? [] : [["Title", build.title] as const]),
+          ...(attention !== undefined ? [
+            ["Execution", build?.work.outcome ?? build?.work.state ?? "unknown"] as const,
+            ["Result", build?.result.state ?? "missing"] as const,
+          ] : savingResult ? [
+            ["Execution", view?.outcome ?? "complete"] as const,
+            ["Result", "saving"] as const,
+          ] : resultOutcome !== undefined ? [
+            ["Outcome", resultOutcome] as const,
+            ...(build?.result.outputCount === undefined
+              ? [] : [["Outputs", String(build.result.outputCount)] as const]),
+          ] : [["State", build?.work.state ?? "unknown"] as const]),
+        ], (build?.operations ?? []).map((operation) => operation.failure !== undefined
+          ? `${operation.endpoint}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}: ${operation.failure.code} — ${operation.failure.message}`
+          : operation.progress === undefined
+            ? `${operation.endpoint}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}: ${operation.state}`
+            : `${operation.endpoint}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}: ${formatOperationProgress(operation.progress)}`)
+          .concat(attention === undefined ? [] : [
+            `Attention  ${attention.message}`,
+            ...(attention.action === undefined ? [] : [`Action     ${attention.action}`]),
+          ]));
+      if (!found || issue !== undefined || resultReadError !== undefined || outcome === "failed") io.setExitCode?.(1);
+      return;
+    }
+
+    if (args.command === "result") {
+      const before = await runtime.inspect(args.build);
+      if (before !== undefined && before.activity !== "saving-result") {
+        throw new Error(`Build ${args.build} is still ${before.activity}; there is no Result write to finish`);
+      }
+      if (before !== undefined && before.issue === undefined) {
+        const worker = await (await selectedHost.controller()).worker.status();
+        if (worker.state === "running") {
+          throw new Error(`Build ${args.build} Result is currently being written by the Runtime Worker`);
+        }
+      }
+      const resultControl = await selectedHost.openResultControl();
+      const finished = await resultControl.finishResult(args.build)
+        .finally(async () => await resultControl.close());
+      if (finished === undefined) {
+        const openedResults = await openProjectResults();
+        const existing = await openedResults.repository.read(args.build)
+          .finally(async () => await openedResults.close());
+        if (existing?.outcome === undefined) {
+          write({ format: "hypit.cli-result-finish@1", build: args.build, found: false },
+            "Result cannot be finished", "warning", [["Build", args.build]],
+            ["No decided Result write exists for this Build."]);
+          io.setExitCode?.(1);
+          return;
+        }
+        write({ format: "hypit.cli-result-finish@1", build: args.build, outcome: existing.outcome },
+          "Result already finished", "info", [["Build", args.build], ["Outcome", existing.outcome]]);
+        return;
+      }
+      write({
+        format: "hypit.cli-result-finish@1",
+        build: args.build,
+        outcome: finished.outcome,
+        ...(finished.issue === undefined ? {} : { attention: {
+          message: finished.issue.message,
+          action: `hypit result finish ${args.build}`,
+        } }),
+      }, finished.issue === undefined ? "Result finished" : "Result still needs attention",
+      finished.issue === undefined ? "success" : "error", [
+        ["Build", args.build],
+        ["Outcome", finished.outcome],
+      ], finished.issue === undefined ? [] : [`Attention  ${finished.issue.message}`]);
+      if (finished.issue !== undefined) io.setExitCode?.(1);
+      return;
+    }
+
+    const active = await runtime.cancel(args.build, args.reason);
+    const openedResults = active === undefined ? await openProjectResults() : undefined;
+    const finished = openedResults === undefined
+      ? undefined
+      : await openedResults.repository.read(args.build).finally(async () => await openedResults.close());
+    const build = active === undefined && finished === undefined ? null : buildStatusView({
+      id: args.build,
+      ...(active === undefined ? {} : { runtime: active }),
+      ...(finished === undefined ? {} : { result: finished }),
+    });
+    const machine = {
+      format: "hypit.cli-cancel@1" as const,
+      requested: active?.cancellationRequested === true,
+      build,
+    };
+    const alreadyStopping = active?.stop?.cause === "execution-failed";
+    const title = active === undefined && finished === undefined
+      ? "Build not found"
+      : active === undefined ? "Build already finished"
+        : alreadyStopping ? "Build already stopping after failure" : "Build cancellation requested";
+    write(machine, title,
+      active === undefined && finished === undefined ? "warning" : active === undefined || alreadyStopping ? "info" : "success", [
+        ["Build", args.build], ...(build === null ? [] : [["Work", build.work.state] as const]),
+      ], active === undefined && finished?.outcome !== undefined
+        ? [`No running work was changed; this Build is already ${finished.outcome}.`]
+        : alreadyStopping ? [active.stop!.reason ?? "Waiting for submitted work to finish."] : []);
+    if (active === undefined && finished === undefined) io.setExitCode?.(1);
+  } finally {
+    await runtime.close();
+  }
+}

package/packages/cli/src/commands/results.ts

@@ -0,0 +1,187 @@
+import { resolve } from "node:path";
+
+import type { BuildResultRepository } from "@hypit/build-result";
+
+import type { CliCommand, ProjectResultCommand } from "../command.js";
+import { exportBuildResultOutput } from "../result-export.js";
+import { browseBuildOutputHistory } from "../result-query.js";
+import {
+  buildCreatedAtIso,
+  buildResultView,
+  cliTypeName,
+  outputView,
+  projectPath,
+} from "../view.js";
+import type { OperationalWriter } from "./types.js";
+
+export function isProjectResultCommand(args: CliCommand): args is ProjectResultCommand {
+  return args.command === "builds" || args.command === "history" || args.command === "inspect"
+    || args.command === "get" || (args.command === "result" && args.action === "edit");
+}
+
+/** Execute commands that need only project-owned Result history, never a Runtime. */
+export async function runProjectResultCommand(input: {
+  readonly args: ProjectResultCommand;
+  readonly projectRoot: string;
+  readonly repository: BuildResultRepository;
+  readonly write: OperationalWriter;
+}): Promise<void> {
+  const { args, projectRoot, repository, write } = input;
+  if (args.command === "builds") {
+    const page = await repository.browse({
+      limit: args.limit,
+      ...(args.before === undefined ? {} : { before: args.before }),
+    });
+    const builds = page.results.map((manifest) => ({
+      id: manifest.id,
+      createdAt: buildCreatedAtIso(manifest.id),
+      ...(manifest.title === undefined ? {} : { title: manifest.title }),
+      outcome: manifest.outcome,
+      ...(manifest.run === undefined ? {} : { run: projectPath(manifest.run.path, projectRoot) }),
+      targetCount: manifest.targets.length,
+      ...(args.presentation.verbose ? {
+        targets: manifest.targets.slice(0, args.limit),
+        ...(manifest.targets.length <= args.limit ? {} : { omittedTargets: manifest.targets.length - args.limit }),
+      } : {}),
+      outputCount: Object.keys(manifest.outputs).length,
+    }));
+    write({
+      format: "hypit.cli-builds@1",
+      builds,
+      ...(page.next === undefined ? {} : { next: page.next }),
+    }, "Build results", "info", [["Builds", String(builds.length)]],
+    builds.map((item) => {
+      const label = item.title === undefined ? item.id : `${item.title} · ${item.id}`;
+      const run = item.run === undefined ? "" : ` · ${item.run}`;
+      return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}${run} · ${item.targetCount} target${item.targetCount === 1 ? "" : "s"}`;
+    }).concat(page.next === undefined ? [] : [`Older    hypit builds --before ${page.next}`]));
+    return;
+  }
+
+  if (args.command === "history") {
+    const source = args.source === undefined ? undefined : resolve(args.source);
+    const page = await browseBuildOutputHistory(repository, {
+      projectRoot,
+      output: args.outputName,
+      ...(source === undefined ? {} : { source }),
+      ...(args.before === undefined ? {} : { before: args.before }),
+      limit: args.limit,
+    });
+    const entries = await Promise.all(page.results.map(async (manifest) => ({
+      build: manifest.id,
+      ...(manifest.title === undefined ? {} : { title: manifest.title }),
+      createdAt: buildCreatedAtIso(manifest.id),
+      outcome: manifest.outcome,
+      output: await outputView(repository, manifest, args.outputName),
+    })));
+    write({
+      format: "hypit.cli-history@1",
+      output: args.outputName,
+      ...(source === undefined ? {} : { source: projectPath(source, projectRoot) }),
+      entries,
+      ...(page.next === undefined ? {} : { next: page.next }),
+    }, entries.length === 0 ? "No matching Output" : "Output history",
+    entries.length === 0 ? "warning" : "info", [
+      ["Output", args.outputName],
+      ...(source === undefined ? [] : [["Source", projectPath(source, projectRoot)] as const]),
+      ["Builds", String(entries.length)],
+    ], entries.map((item) => {
+      const label = item.title === undefined ? item.build : `${item.title} · ${item.build}`;
+      return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}`
+        + (args.presentation.verbose ? ` · ${item.output.kind} · ${item.output.type}` : "");
+    }).concat(page.next === undefined ? [] : [`Older    hypit history ${args.outputName} --before ${page.next}`]));
+    return;
+  }
+
+  if (args.command === "inspect") {
+    const manifest = await repository.read(args.build);
+    if (manifest === undefined) throw new Error(`Build Result ${args.build} does not exist`);
+    const build = await buildResultView(repository, manifest, {
+      projectRoot,
+      ...(args.outputName === undefined ? {} : { output: args.outputName }),
+      limit: args.limit,
+    });
+    const focusedOutputs = args.outputName === undefined
+      ? build.outputs.filter((item) => item.target || item.highlighted)
+      : build.outputs;
+    const visibleOutputs = args.presentation.verbose ? build.outputs : focusedOutputs;
+    const outputCount = build.outputs.length + (build.omittedOutputs ?? 0);
+    const hiddenOutputCount = args.outputName === undefined ? outputCount - focusedOutputs.length : 0;
+    write({ format: "hypit.cli-inspect@1", build }, "Build Result",
+      manifest.outcome === "failed" ? "error"
+        : manifest.outcome === "cancelled" ? "warning"
+          : manifest.outcome === "complete" ? "success" : "info", [
+        ["Build", build.id],
+        ["Created", new Date(build.createdAt).toLocaleString()],
+        ...(build.title === undefined ? [] : [["Title", build.title] as const]),
+        ["Outcome", build.outcome],
+        ...(args.outputName === undefined ? [
+          ["Targets", String(build.targetCount)] as const,
+          ["Outputs", String(outputCount)] as const,
+        ] : []),
+      ], [
+        ...(build.failure === undefined ? [] : [`Reason    ${build.failure}`]),
+        ...(build.operations ?? []).map((operation) =>
+          `${operation.endpoint}: ${operation.status}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}`
+          + (operation.failure === undefined ? "" : ` · ${operation.failure.code}: ${operation.failure.message}`)),
+        ...(build.omittedOperations === undefined ? [] : [`${build.omittedOperations} more execution receipts · use --limit <count>`]),
+        ...(build.note === undefined ? [] : [`Note      ${build.note}`]),
+        ...visibleOutputs.map((item) => `${item.highlighted ? "★" : item.target ? "Target" : "Output"}    ${item.name}`
+          + (!args.presentation.verbose ? "" : ` · ${item.type} · ${item.kind}`
+            + `${item.mediaType === undefined ? "" : ` · ${item.mediaType}`}`
+            + `${item.size === undefined ? "" : ` · ${item.size} bytes`}`)),
+        ...(!args.presentation.verbose && hiddenOutputCount > 0 ? [
+          `${hiddenOutputCount} other Output${hiddenOutputCount === 1 ? "" : "s"} · use --verbose or --output <name>`,
+        ] : []),
+        ...(args.presentation.verbose && build.omittedOutputs !== undefined ? [
+          `${build.omittedOutputs} more Outputs · use --limit <count> or --output <name>`,
+        ] : []),
+      ]);
+    return;
+  }
+
+  if (args.command === "result") {
+    const manifest = await repository.updatePresentation(args.build, {
+      ...(args.clearTitle ? { title: null } : args.title === undefined ? {} : { title: args.title }),
+      ...(args.clearNote ? { note: null } : args.note === undefined ? {} : { note: args.note }),
+      ...(args.clearHighlights
+        ? { highlightedOutputs: [] }
+        : args.highlightedOutputs.length === 0 ? {} : { highlightedOutputs: args.highlightedOutputs }),
+    });
+    const presentation = {
+      format: "hypit.cli-result-edit@1" as const,
+      build: manifest.id,
+      title: manifest.title ?? null,
+      note: manifest.note ?? null,
+      highlightedOutputCount: manifest.highlightedOutputs?.length ?? 0,
+      highlightedOutputs: manifest.highlightedOutputs?.slice(0, args.limit) ?? [],
+      ...((manifest.highlightedOutputs?.length ?? 0) <= args.limit
+        ? {}
+        : { omittedHighlightedOutputs: manifest.highlightedOutputs!.length - args.limit }),
+    };
+    write(presentation, "Build Result updated", "success", [
+      ["Build", manifest.id],
+      ["Title", manifest.title ?? "—"],
+      ["Highlighted", String(manifest.highlightedOutputs?.length ?? 0)],
+    ], manifest.note === undefined ? [] : [`Note    ${manifest.note}`]);
+    return;
+  }
+
+  const exported = await exportBuildResultOutput(repository, args.build, args.outputName, args.destination);
+  const machine = {
+    format: "hypit.cli-get@1" as const,
+    build: exported.build,
+    output: exported.output,
+    type: cliTypeName(exported.type),
+    kind: exported.kind,
+    path: exported.path,
+  };
+  const path = projectPath(exported.path, projectRoot);
+  write(machine, `Exported ${exported.output} → ${path}`, "success",
+    args.presentation.verbose ? [
+      ["Build", exported.build],
+      ["Type", machine.type],
+      ["Kind", exported.kind],
+      ["Path", exported.path],
+    ] : []);
+}

package/packages/cli/src/commands/types.ts

@@ -0,0 +1,9 @@
+import type { CliMachineView } from "../output.js";
+
+export type OperationalWriter = (
+  machine: CliMachineView,
+  title: string,
+  status?: "success" | "warning" | "error" | "info",
+  facts?: readonly (readonly [string, string])[],
+  lines?: readonly string[],
+) => void;

package/packages/cli/src/distribution.ts

@@ -0,0 +1,74 @@
+import type { NodeCompiler } from "@hypit/compiler-node";
+import type { LoadedPackage, NodePackageContribution } from "@hypit/package-loader-node";
+import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
+import type { BuildResultRepository } from "@hypit/build-result";
+import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
+import type { BuildResultRepositoryDiagnostic } from "@hypit/build-result-kit";
+import type { CanonicalValue } from "@hypit/protocol";
+
+export type CliCompilerOptions = {
+  /** Canonical containment boundary for Author and Run Sources plus source assets. */
+  readonly workspaceRoot?: string;
+  /** Additional Host-authorized asset roots. These never widen Source imports. */
+  readonly assetRoots?: readonly string[];
+  /** Project-owned package resolution boundary for package Source imports. */
+  readonly packageRoot?: string;
+  /** Read-only application Distribution that owns the reserved @hypit namespace. */
+  readonly distributionPackageRoot?: string;
+  readonly packageContributions: readonly NodePackageContribution[];
+};
+
+/**
+ * Explicit application assembly for the generic command engine.
+ *
+ * A Distribution selects author vocabulary/compiler semantics and trusted Runtime-config adapters.
+ * It is Host configuration, never Core state or source-import authority.
+ */
+export type CliDistribution = {
+  /** Packages shipped with this CLI distribution. */
+  readonly packageRoot?: string;
+  /** Explicit Host bootstrap packages; never inferred from Source contents. */
+  readonly bootstrapPackages: readonly LoadedPackage[];
+  /** Product-owned starter Profile. The generic CLI only writes this explicit value. */
+  readonly initialRuntimeProfile?: CanonicalValue;
+  createCompiler(options: CliCompilerOptions): NodeCompiler;
+  /**
+   * Read the self-described Run Source and its Author Source closure, then return
+   * only the installed package roots those sources explicitly select.
+   *
+   * This is Distribution syntax work. The generic CLI never scans a directory,
+   * guesses an entry filename or teaches Core about package names.
+   */
+  discoverSourcePackages?(path: string, options?: {
+    readonly workspaceRoot?: string;
+    readonly packageRoot?: string;
+    readonly distributionPackageRoot?: string;
+    /** Exact packages already trusted for the current fixed-point discovery pass. */
+    readonly packages?: readonly LoadedPackage[];
+  }): Promise<{
+    readonly selected: readonly string[];
+    readonly logical?: readonly import("@hypit/package-loader-node").LogicalPackageAddress[];
+  }>;
+  /** Open the Runtime Profile with this application's Runtime implementation. */
+  openRuntimeHost(path: string, options: {
+    readonly packageRoot: string;
+    readonly distributionPackageRoot?: string;
+  }): Promise<NodeRuntimeHost>;
+  /** Open project-owned Result history even when no Runtime Profile is selected. */
+  openProjectResults(projectRoot: string, options: {
+    readonly packageRoot: string;
+    readonly distributionPackageRoot?: string;
+  }): Promise<{
+    readonly location: BuildResultRepositoryLocation;
+    readonly repository: BuildResultRepository;
+    close(): void | Promise<void>;
+  }>;
+  /** Actively diagnose this project's selected Result Store without reading its history. */
+  diagnoseProjectResults(projectRoot: string, options: {
+    readonly packageRoot: string;
+    readonly distributionPackageRoot?: string;
+  }): Promise<{
+    readonly location?: BuildResultRepositoryLocation;
+    readonly diagnostics: readonly BuildResultRepositoryDiagnostic[];
+  }>;
+};

package/packages/cli/src/index.ts

@@ -0,0 +1,30 @@
+export { runCli } from "./main.js";
+export { discoverSourcePackages } from "./source-discovery.js";
+export { loadDiscoveredSourcePackages } from "./source-packages.js";
+export { collectRunFrontends, loadRunFile, resolveBuildResultValue } from "./run-file.js";
+export type { LoadedRunFile } from "./run-file.js";
+export { hypitHostStateRoot, hypitProjectStateRoot } from "./paths.js";
+export { resolvePackageRoot, resolveProjectRoot } from "./project-context.js";
+export { findRuntimeProfile } from "./runtime-selection.js";
+export { renderCliError, writeCliHelp, writeCliOutput } from "./output.js";
+export type {
+  CliColorMode,
+  CliIo,
+  CliMachineView,
+  CliOutputOptions,
+  CliPresentation,
+  CliTerminal,
+} from "./output.js";
+export type {
+  CliBuildResultView,
+  CliBuildStatusView,
+  CliBuildSummary,
+  CliOutputView,
+  PublicOutputKind,
+} from "./view.js";
+export type { OperationalMachineView } from "./machine-view.js";
+export type {
+  CliCompilerOptions,
+  CliDistribution,
+} from "./distribution.js";
+export type * from "./runtime-port.js";

package/packages/cli/src/machine-view.ts

@@ -0,0 +1,28 @@
+import type { CliBuildResultView, CliBuildStatusView, CliOutputView } from "./view.js";
+
+type ProgramStateView = { readonly id: string; readonly state: string; readonly action?: string };
+type AttentionView = { readonly message: string; readonly action?: string };
+
+export type OperationalMachineView =
+  | { readonly format: "hypit.cli-runtime-init@1"; readonly profile: string; readonly project: string; readonly selected: true }
+  | { readonly format: "hypit.cli-runtime-selection@1"; readonly selected: boolean; readonly removed?: boolean; readonly profile?: string; readonly project?: string }
+  | { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: string; readonly profile?: string; readonly runtimeData?: string; readonly hostState: string; readonly machinePackages: string; readonly distribution?: string }
+  | { readonly format: "hypit.cli-package@1"; readonly action: "install" | "status"; readonly package: string; readonly ready: boolean }
+  | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ready: boolean; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
+  | { readonly format: "hypit.cli-runtime-up@1"; readonly ready: boolean; readonly worker: string; readonly preparedPackages: number; readonly programs: { readonly total: number; readonly ready: number } }
+  | { readonly format: "hypit.cli-runtime-logs@1"; readonly lines: readonly string[]; readonly totalLines: number; readonly omittedLines: number; readonly path?: string }
+  | { readonly format: "hypit.cli-runtime-down@1"; readonly worker: string }
+  | { readonly format: "hypit.cli-runtime-status@1"; readonly ready: boolean; readonly attention: boolean; readonly worker: { readonly state: string; readonly configuration?: string }; readonly builds: Readonly<Record<string, number>>; readonly programs: { readonly total: number; readonly ready: number; readonly unavailable: readonly ProgramStateView[] }; readonly capacity: { readonly active: number } }
+  | { readonly format: "hypit.cli-auth-status@1"; readonly endpoint: string; readonly credentials: readonly { readonly endpoint: string; readonly slot: string; readonly label: string; readonly kind: string; readonly configured: boolean; readonly writable: boolean }[]; readonly omittedCredentials?: number }
+  | { readonly format: "hypit.cli-auth-change@1"; readonly endpoint: string; readonly slot: string; readonly configured: boolean; readonly changed?: boolean }
+  | { readonly format: "hypit.cli-builds@1"; readonly builds: readonly { readonly id: string; readonly createdAt: string; readonly title?: string; readonly outcome: string; readonly run?: string; readonly targetCount: number; readonly targets?: readonly string[]; readonly omittedTargets?: number; readonly outputCount: number }[]; readonly next?: string }
+  | { readonly format: "hypit.cli-history@1"; readonly output: string; readonly source?: string; readonly entries: readonly { readonly build: string; readonly title?: string; readonly createdAt: string; readonly outcome: string; readonly output: CliOutputView }[]; readonly next?: string }
+  | { readonly format: "hypit.cli-inspect@1"; readonly build: CliBuildResultView }
+  | { readonly format: "hypit.cli-result-edit@1"; readonly build: string; readonly title: string | null; readonly note: string | null; readonly highlightedOutputCount: number; readonly highlightedOutputs: readonly string[]; readonly omittedHighlightedOutputs?: number }
+  | { readonly format: "hypit.cli-get@1"; readonly build: string; readonly output: string; readonly type: string; readonly kind: "scalar" | "resource" | "composite"; readonly path: string }
+  | { readonly format: "hypit.cli-status@1"; readonly build: CliBuildStatusView | null }
+  | { readonly format: "hypit.cli-activity@1"; readonly at: number; readonly worker: string; readonly builds: readonly { readonly id: string; readonly work: CliBuildStatusView["work"]; readonly outcome?: string; readonly attention?: AttentionView }[]; readonly omittedBuilds?: number; readonly capacity: readonly import("@hypit/runtime").CapacityReservation[] }
+  | { readonly format: "hypit.cli-result-discard@1"; readonly build: string; readonly discarded: boolean }
+  | { readonly format: "hypit.cli-result-finish@1"; readonly build: string; readonly found?: false; readonly outcome?: string; readonly attention?: AttentionView }
+  | { readonly format: "hypit.cli-cancel@1"; readonly requested: boolean; readonly build: CliBuildStatusView | null }
+  | { readonly format: "hypit.cli-build@1"; readonly build: CliBuildStatusView };