@hypit/hypit 0.0.1 → 0.1.1

package/packages/cli/src/paths.ts

@@ -0,0 +1,7 @@
+import { resolve } from "node:path";
+
+export { hypitHostStateRoot } from "@hypit/runtime-host-node";
+
+export function hypitProjectStateRoot(projectRoot: string): string {
+  return resolve(projectRoot, ".hypit");
+}

package/packages/cli/src/project-context.ts

@@ -0,0 +1,38 @@
+import { stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+async function nearestProjectPackageRoot(start: string): Promise<string | undefined> {
+  let directory = resolve(start);
+  while (true) {
+    const candidate = resolve(directory, "package.json");
+    try {
+      if ((await stat(candidate)).isFile()) return directory;
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/**
+ * Resolve the project before any Runtime selection is considered.
+ *
+ * An explicit Workspace is already the boundary. Otherwise the nearest
+ * package.json declares the boundary; when none exists, cwd itself is the
+ * explicit shell context. Source paths and Runtime state never choose it.
+ */
+export async function resolveProjectRoot(options: {
+  readonly workspaceRoot?: string;
+  readonly cwd?: string;
+} = {}): Promise<string> {
+  const start = resolve(options.workspaceRoot ?? options.cwd ?? process.cwd());
+  if (options.workspaceRoot !== undefined) return start;
+  return await nearestProjectPackageRoot(start) ?? start;
+}
+
+/** Project package discovery cannot escape an already resolved project. */
+export async function resolvePackageRoot(projectRoot: string): Promise<string> {
+  return resolve(projectRoot);
+}

package/packages/cli/src/reachability.ts

@@ -0,0 +1,91 @@
+import type { BuildState, CompiledGraph } from "@hypit/protocol";
+
+export type UnreachedGeneration = {
+  /** The Producer that would have run, as the Source named it. */
+  readonly name: string;
+  readonly producer: string;
+};
+
+/**
+ * Generations a Source declares that this Run will not perform.
+ *
+ * Whether anything *consumes* a declaration cannot answer this. An Author Source has no targets, so
+ * "nothing needs this" has no meaning there, and a package's own expansion consumes its own
+ * intermediate steps — a generated picture is read by the step that picks the primary image, which
+ * makes the generation look used even when the picture it produces is read by nobody.
+ *
+ * A Run Source does have targets, and planning already prunes to what they reach. So the question
+ * that can be answered is the one that matters: this Run declares the generation and will not run
+ * it. Either nothing needs it, a target is missing, or an explicit Candidate supplies the Output.
+ */
+export function unreachedGenerations(
+  graph: CompiledGraph,
+  state: BuildState,
+  outputNames: Readonly<Record<string, string>> = {},
+): readonly UnreachedGeneration[] {
+  const built = new Set<string>();
+  for (const step of state.plan.steps) {
+    for (const record of Object.values(step.outputs)) built.add(record);
+    // A Need's result lands through the binding rather than the step's outputs, so a plan that
+    // performs a generation shows it here and nowhere else.
+    for (const binding of Object.values(step.needs)) built.add(binding.result);
+  }
+  // A satisfied output is deliberately not produced again; that is reuse working, not a leftover.
+  for (const binding of state.plan.outputBindings) built.add(binding.record);
+
+  // The author's name for a generation sits on the Logical Output, which selects a Candidate, which
+  // roots at the Operation. Reporting the Operation's internal name instead would be accurate and
+  // useless: nobody searches a Source for "request-nano-banana-2".
+  const candidateById = new Map(graph.candidates.map((item) => [item.id, item]));
+  const namedOperation = new Map<string, string>();
+  for (const output of graph.outputs) {
+    const name = outputNames[output.id];
+    if (name === undefined) continue;
+    const root = candidateById.get(output.primary)?.root;
+    if (root?.kind === "operation") namedOperation.set(root.result.operation, name);
+  }
+
+  // A package expands one authored element into several Operations, and the author's name usually
+  // sits on the last of them — `gpt:Image` generates, then picks the primary image, and the name is
+  // on the pick. Reporting "generation" would be true and unusable, so follow the chain forward to
+  // the first Operation anyone named.
+  const consumers = new Map<string, string[]>();
+  for (const operation of graph.operations) {
+    for (const input of Object.values(operation.inputs)) {
+      const from = input.kind === "operation-result" ? input.operation : input.id;
+      consumers.set(from, [...consumers.get(from) ?? [], operation.id]);
+      if (operation.result.kind === "output" || operation.result.kind === "need") {
+        consumers.set(operation.result.record, [...consumers.get(operation.result.record) ?? [], operation.id]);
+      }
+    }
+  }
+  const authoredName = (start: string, startRecord: string): string | undefined => {
+    const seen = new Set<string>([start]);
+    let frontier = [...consumers.get(start) ?? [], ...consumers.get(startRecord) ?? []];
+    while (frontier.length > 0) {
+      const next: string[] = [];
+      for (const id of frontier) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        const name = namedOperation.get(id);
+        if (name !== undefined) return name;
+        next.push(...consumers.get(id) ?? []);
+      }
+      frontier = next;
+    }
+    return undefined;
+  };
+
+  const found: UnreachedGeneration[] = [];
+  for (const operation of graph.operations) {
+    if (operation.result.kind !== "need") continue;
+    if (built.has(operation.result.record)) continue;
+    found.push({
+      name: namedOperation.get(operation.id)
+        ?? authoredName(operation.id, operation.result.record)
+        ?? operation.result.name,
+      producer: `${operation.producer.module.name}@${operation.producer.module.version}/${operation.producer.name}`,
+    });
+  }
+  return found;
+}

package/packages/cli/src/result-export.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+import type {
+  BuildResultFileRef,
+  BuildResultRepository,
+  RepositoryBuildResultOutput,
+} from "@hypit/build-result";
+
+export type BuildResultExport = {
+  readonly build: string;
+  readonly output: string;
+  readonly type: RepositoryBuildResultOutput["type"];
+  readonly kind: "scalar" | "resource" | "composite";
+  readonly path: string;
+};
+
+type CompositeResultOutput = Omit<RepositoryBuildResultOutput, "value"> & {
+  readonly value: Extract<RepositoryBuildResultOutput["value"], { readonly kind: "value" }>;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  return await lstat(path).then(() => true, (error: unknown) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  });
+}
+
+function containedPath(root: string, path: string): string {
+  const target = resolve(root, path);
+  const relation = relative(root, target);
+  assert(relation.length > 0 && relation !== ".." && !relation.startsWith(`..${sep}`),
+    `Result file ${path} leaves export directory ${root}`);
+  return target;
+}
+
+async function writeStream(
+  path: string,
+  input: AsyncIterable<Uint8Array>,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, input, { flag: "wx" });
+}
+
+async function openResultFile(
+  repository: BuildResultRepository,
+  build: string,
+  file: BuildResultFileRef,
+): Promise<AsyncIterable<Uint8Array>> {
+  const input = await repository.openFile(build, file);
+  if (input === undefined) throw new Error(`Build ${build} file ${file.path} is unavailable`);
+  return input;
+}
+
+async function exportFile(
+  target: string,
+  write: (temporary: string) => Promise<void>,
+): Promise<void> {
+  assert(!await pathExists(target), `Export destination ${target} already exists`);
+  await mkdir(dirname(target), { recursive: true });
+  const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
+  try {
+    await write(temporary);
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+async function exportComposite(
+  repository: BuildResultRepository,
+  resolvedOutput: CompositeResultOutput,
+  target: string,
+): Promise<void> {
+  assert(!await pathExists(target), `Export destination ${target} already exists`);
+  await mkdir(dirname(target), { recursive: true });
+  const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
+  try {
+    await mkdir(temporary);
+    const copied = new Set<string>();
+    for (const binding of resolvedOutput.value.document.resources) {
+      const file = binding.file;
+      if (copied.has(file.path)) continue;
+      copied.add(file.path);
+      assert(file.path !== "value.json", "Composite Result file value.json conflicts with its exported value document");
+      await writeStream(
+        containedPath(temporary, file.path),
+        await openResultFile(repository, resolvedOutput.build, file),
+      );
+    }
+    await writeFile(
+      join(temporary, "value.json"),
+      `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`,
+      { flag: "wx" },
+    );
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/** Export one resolved public Output into an explicit user-owned local destination. */
+export async function exportBuildResultOutput(
+  repository: BuildResultRepository,
+  build: string,
+  output: string,
+  destination: string,
+): Promise<BuildResultExport> {
+  const manifest = await repository.read(build);
+  if (manifest === undefined) throw new Error(`Build Result ${build} does not exist`);
+  const publishedOutput = manifest.outputs[output];
+  if (publishedOutput === undefined) throw new Error(`Build ${build} has no Output ${output}`);
+  const resolvedOutput = await repository.resolve(build, output);
+  if (resolvedOutput === undefined) throw new Error(`Build ${build} Output ${output} cannot be resolved`);
+  const target = resolve(destination);
+  if (resolvedOutput.value.kind === "value") {
+    await exportComposite(repository, { ...resolvedOutput, value: resolvedOutput.value }, target);
+  } else if (resolvedOutput.value.kind === "build-file") {
+    const resource = resolvedOutput.value;
+    await exportFile(target, async (temporary) => {
+      await writeStream(
+        temporary,
+        await openResultFile(repository, resolvedOutput.build, resource),
+      );
+    });
+  } else {
+    const scalar = resolvedOutput.value.value;
+    await exportFile(target, async (temporary) => {
+      await writeFile(temporary, `${JSON.stringify(scalar, null, 2)}\n`, { flag: "wx" });
+    });
+  }
+  return {
+    build,
+    output,
+    type: publishedOutput.type,
+    kind: resolvedOutput.value.kind === "inline"
+      ? "scalar"
+      : resolvedOutput.value.kind === "build-file" ? "resource" : "composite",
+    path: target,
+  };
+}

package/packages/cli/src/result-query.ts

@@ -0,0 +1,46 @@
+import { resolve } from "node:path";
+
+import type { BuildResultRepository, FinishedBuildResultManifest } from "@hypit/build-result";
+
+export type BuildOutputHistoryPage = {
+  readonly results: readonly FinishedBuildResultManifest[];
+  /** Read older Builds strictly before this id. */
+  readonly next?: string;
+};
+
+/**
+ * Collect a page of matching Outputs rather than filtering one arbitrary page of Builds. This is a
+ * request-local scan over the Repository's own chronological cursor; it creates no index or history.
+ */
+export async function browseBuildOutputHistory(
+  repository: BuildResultRepository,
+  request: {
+    readonly projectRoot: string;
+    readonly output: string;
+    readonly source?: string;
+    readonly before?: string;
+    readonly limit: number;
+  },
+): Promise<BuildOutputHistoryPage> {
+  const source = request.source === undefined ? undefined : resolve(request.source);
+  const pageSize = Math.max(32, request.limit);
+  let before = request.before;
+  const matches: FinishedBuildResultManifest[] = [];
+  while (matches.length < request.limit) {
+    const page = await repository.browse({ limit: pageSize, ...(before === undefined ? {} : { before }) });
+    if (page.results.length === 0) return { results: matches };
+    for (let index = 0; index < page.results.length; index += 1) {
+      const manifest = page.results[index]!;
+      const sameSource = source === undefined
+        || resolve(request.projectRoot, manifest.source.path) === source;
+      if (sameSource && manifest.outputs[request.output] !== undefined) matches.push(manifest);
+      if (matches.length === request.limit) {
+        const hasOlder = index < page.results.length - 1 || page.next !== undefined;
+        return { results: matches, ...(hasOlder ? { next: manifest.id } : {}) };
+      }
+    }
+    if (page.next === undefined) return { results: matches };
+    before = page.next;
+  }
+  return { results: matches };
+}

package/packages/cli/src/run-file.ts

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import type {
+  BuildResultRepository,
+  BuildResultFileRef,
+  BuildResultValuePath,
+  RepositoryBuildResultOutput,
+} from "@hypit/build-result";
+import { NodeRunCompiler } from "@hypit/compiler-node";
+import type {
+  NodeCompiledRun,
+  NodeCompiler,
+} from "@hypit/compiler-node";
+import type { NodePackageContribution } from "@hypit/package-loader-node";
+import type { ArtifactAttachment, WorkspaceSession } from "@hypit/workspace";
+import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
+import {
+  installRunFragmentHostFacets,
+  runFrontendsFromHostFacets,
+  RunFragmentRegistry,
+  RunFrontendRegistry,
+} from "@hypit/run";
+import type { RunFrontend } from "@hypit/run";
+
+export type LoadedRunFile = NodeCompiledRun & {
+  readonly path: string;
+  readonly compiler: NodeRunCompiler;
+};
+
+type BuildResultResolutionSession = {
+  readonly files: Map<string, ArtifactAttachment>;
+  readonly outputs: Map<string, Promise<RepositoryBuildResultOutput | undefined>>;
+};
+
+function createBuildResultResolutionSession(): BuildResultResolutionSession {
+  return { files: new Map(), outputs: new Map() };
+}
+
+export async function checkRunFile(options: {
+  readonly workspace: WorkspaceSession;
+  readonly authorCompiler: NodeCompiler;
+  readonly frontends: readonly RunFrontend[];
+  readonly packageContributions: readonly NodePackageContribution[];
+}) {
+  const compiler = createRunCompiler(options);
+  return await compiler.checkSource(options.workspace.entry, options.workspace);
+}
+
+function replaceValueAtPath(
+  value: CanonicalValue,
+  path: BuildResultValuePath,
+  replacement: BlobRef,
+): CanonicalValue {
+  if (path.length === 0) return replacement;
+  const segment = path[0]!;
+  const rest = path.slice(1);
+  if (typeof segment === "number") {
+    if (!Array.isArray(value) || segment < 0 || segment >= value.length) {
+      throw new Error(`Result Resource path ${JSON.stringify(path)} does not address an array item`);
+    }
+    return value.map((item, index) => index === segment
+      ? replaceValueAtPath(item, rest, replacement)
+      : item);
+  }
+  if (value === null || Array.isArray(value) || typeof value !== "object" || !Object.hasOwn(value, segment)) {
+    throw new Error(`Result Resource path ${JSON.stringify(path)} does not address an object property`);
+  }
+  return {
+    ...value,
+    [segment]: replaceValueAtPath(
+      (value as Readonly<Record<string, CanonicalValue>>)[segment]!,
+      rest,
+      replacement,
+    ),
+  };
+}
+
+/** Resolve one historical public Output into an ordinary Run value plus lazy file attachments. */
+export async function resolveBuildResultValue(
+  repository: BuildResultRepository,
+  build: string,
+  output: string,
+  session: BuildResultResolutionSession = createBuildResultResolutionSession(),
+): Promise<{
+  readonly type: RepositoryBuildResultOutput["type"];
+  readonly value: StoredValue;
+  readonly attachments?: readonly ArtifactAttachment[];
+  } | undefined> {
+  const manifest = await repository.read(build);
+  if (manifest?.outcome === undefined) return undefined;
+  const resultAttachment = async (owner: string, file: BuildResultFileRef): Promise<ArtifactAttachment> => {
+    const address = `${owner}\u0000${file.path}`;
+    const existing = session.files.get(address);
+    if (existing !== undefined) return existing;
+    const artifact: BlobRef = {
+      kind: "blob",
+      resource: `res_${randomUUID()}`,
+      size: file.size,
+      mediaType: file.mediaType,
+    };
+    const attachment = {
+      artifact,
+      async open() {
+        const stream = await repository.openFile(owner, file);
+        if (stream === undefined) throw new Error(`Build ${owner} file ${file.path} is unavailable`);
+        return stream;
+      },
+    };
+    session.files.set(address, attachment);
+    return attachment;
+  };
+  const attachments = new Map<string, ArtifactAttachment>();
+  const address = `${build}\u0000${output}`;
+  let pending = session.outputs.get(address);
+  if (pending === undefined) {
+    pending = repository.resolve(build, output);
+    session.outputs.set(address, pending);
+  }
+  const resolved = await pending;
+  if (resolved === undefined) return undefined;
+  const owner = resolved.build === build ? manifest : await repository.read(resolved.build);
+  if (owner?.outcome === undefined) return undefined;
+  let value: StoredValue;
+  if (resolved.value.kind === "build-file") {
+    const attachment = await resultAttachment(resolved.build, resolved.value);
+    attachments.set(attachment.artifact.resource, attachment);
+    value = attachment.artifact;
+  } else if (resolved.value.kind === "inline") {
+    value = { kind: "inline", value: resolved.value.value };
+  } else {
+    let composite = resolved.value.document.value;
+    for (const binding of resolved.value.document.resources) {
+      const attachment = await resultAttachment(resolved.build, binding.file);
+      attachments.set(attachment.artifact.resource, attachment);
+      composite = replaceValueAtPath(composite, binding.at, attachment.artifact);
+    }
+    value = { kind: "inline", value: composite };
+  }
+  return {
+    type: resolved.type,
+    value,
+    ...(attachments.size === 0 ? {} : { attachments: [...attachments.values()] }),
+  };
+}
+
+function createRunCompiler(options: {
+  readonly authorCompiler: NodeCompiler;
+  readonly frontends: readonly RunFrontend[];
+  readonly packageContributions: readonly NodePackageContribution[];
+  readonly results?: BuildResultRepository;
+}): NodeRunCompiler {
+  const resultSession = createBuildResultResolutionSession();
+  const fragments = new RunFragmentRegistry();
+  for (const item of options.packageContributions) {
+    installRunFragmentHostFacets(item.hostFacets ?? [], fragments);
+  }
+  const frontends = new RunFrontendRegistry();
+  for (const frontend of options.frontends) frontends.register(frontend);
+  return new NodeRunCompiler({
+    authorCompiler: options.authorCompiler,
+    frontends,
+    fragments,
+    ...(options.results === undefined ? {} : {
+      async resolveHistoricalOutput(id: string, output: string) {
+        return await resolveBuildResultValue(options.results!, id, output, resultSession);
+      },
+    }),
+  });
+}
+
+export function collectRunFrontends(
+  packages: readonly NodePackageContribution[],
+): readonly RunFrontend[] {
+  return packages.flatMap((item) => runFrontendsFromHostFacets(item.hostFacets ?? []));
+}
+
+export async function loadRunFile(options: {
+  readonly workspace: WorkspaceSession;
+  readonly authorCompiler: NodeCompiler;
+  readonly frontends: readonly RunFrontend[];
+  readonly packageContributions: readonly NodePackageContribution[];
+  readonly results?: BuildResultRepository;
+}): Promise<LoadedRunFile> {
+  const compiler = createRunCompiler(options);
+  const compiled = await compiler.compileSource(options.workspace.entry, options.workspace);
+  return { path: options.workspace.entry.id, compiler, ...compiled };
+}

package/packages/cli/src/runtime-port.ts

@@ -0,0 +1,13 @@
+export type {
+  ManagedProgramProgress as CliManagedProgramProgress,
+  ManagedProgramReport as CliManagedProgramReport,
+  RuntimeController as CliRuntimeController,
+  RuntimeHostControl as CliRuntimeControl,
+  RuntimeHostBuildSubmission as CliBuildSubmission,
+  RuntimeHostCredentialControl as CliCredentialControl,
+  RuntimeHostCredentialStatus as CliCredentialStatus,
+  RuntimeHostDoctorResult as CliRuntimeDoctorResult,
+  RuntimeHostExecution as CliRuntime,
+  BuildView as CliBuildView,
+  RuntimeWorkerState as CliRuntimeWorkerState,
+} from "@hypit/runtime-host-node";

package/packages/cli/src/runtime-selection.ts

@@ -0,0 +1,94 @@
+import { mkdir, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+
+const stateDirectoryName = ".hypit";
+const selectionFileName = "runtime";
+
+export type RuntimeProfileSelection = {
+  readonly profile: string;
+  readonly projectRoot: string;
+  readonly selectionFile: string;
+};
+
+function errorCode(error: unknown): string | undefined {
+  return error !== null && typeof error === "object" && "code" in error
+    ? String((error as { readonly code?: unknown }).code)
+    : undefined;
+}
+
+async function readSelectionFile(projectRoot: string): Promise<{
+  readonly projectRoot: string;
+  readonly selectionFile: string;
+  readonly value: string;
+} | undefined> {
+  const root = resolve(projectRoot);
+  const selectionFile = resolve(root, stateDirectoryName, selectionFileName);
+  try {
+    return {
+      projectRoot: root,
+      selectionFile,
+      value: (await readFile(selectionFile, "utf8")).trim(),
+    };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Remember one Runtime Profile for a project. This is local CLI context, not
+ * Author Source, Run Source, package selection or Core state.
+ */
+export async function selectRuntimeProfile(projectRoot: string, profile: string): Promise<RuntimeProfileSelection> {
+  const root = await realpath(resolve(projectRoot));
+  const selectedProfile = await realpath(resolve(profile));
+  const stateDirectory = resolve(root, stateDirectoryName);
+  const selectionFile = resolve(stateDirectory, selectionFileName);
+  await mkdir(stateDirectory, { recursive: true });
+  try {
+    await writeFile(resolve(stateDirectory, ".gitignore"), "*\n", { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (errorCode(error) !== "EEXIST") throw error;
+  }
+  const stored = relative(root, selectedProfile) || ".";
+  await writeFile(selectionFile, `${stored}\n`, "utf8");
+  return { profile: selectedProfile, projectRoot: root, selectionFile };
+}
+
+/** Read only the explicitly resolved project's Runtime selection. */
+export async function findRuntimeProfile(projectRoot: string): Promise<RuntimeProfileSelection | undefined> {
+  const selected = await readSelectionFile(projectRoot);
+  if (selected === undefined) return undefined;
+  if (selected.value.length === 0) {
+    throw new Error(`Runtime selection is empty: ${selected.selectionFile}; run hypit runtime use <profile>`);
+  }
+  const root = selected.projectRoot;
+  const candidate = resolve(root, selected.value);
+  try {
+    return {
+      profile: await realpath(candidate),
+      projectRoot: root,
+      selectionFile: selected.selectionFile,
+    };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new Error(
+        `Selected Runtime Profile no longer exists: ${candidate}; run hypit runtime use <profile>`,
+      );
+    }
+    throw error;
+  }
+}
+
+/** Remove only the local pointer. Runtime state, Programs and Builds are untouched. */
+export async function clearRuntimeProfile(projectRoot: string): Promise<RuntimeProfileSelection | undefined> {
+  const selected = await readSelectionFile(projectRoot);
+  if (selected === undefined) return undefined;
+  const profile = resolve(selected.projectRoot, selected.value);
+  await unlink(selected.selectionFile);
+  return {
+    profile,
+    projectRoot: selected.projectRoot,
+    selectionFile: selected.selectionFile,
+  };
+}

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

@@ -0,0 +1,15 @@
+import type { OperationProgress } from "@hypit/runtime";
+
+export function formatOperationProgress(progress: OperationProgress): string {
+  if (progress.completed === undefined) return progress.phase;
+  const amount = progress.total === undefined
+    ? String(progress.completed)
+    : `${progress.completed}/${progress.total}`;
+  return `${progress.phase} · ${amount}${progress.unit === undefined ? "" : ` ${progress.unit}`}`;
+}
+
+export function inlineValuePreview(value: unknown, limit = 240): string {
+  const encoded = JSON.stringify(value);
+  if (encoded.length <= limit) return encoded;
+  return `${encoded.slice(0, Math.max(0, limit - 3))}...`;
+}