@hypit/hypit 0.1.2 → 0.1.4

package/packages/cli/src/arguments.ts

@@ -157,7 +157,7 @@ export function parseCommand(argv: readonly string[]): CliCommand {
     }
     case "status": {
       const [build, rest] = requiredPositional(tail, "status requires one Build id");
-      const options = commandOptions(command, rest, "--runtime", "--watch", "--max-wait-ms", "--limit");
+      const options = commandOptions(command, rest, "--runtime", "--workspace", "--watch", "--max-wait-ms", "--limit");
       if (!options.watch && options.maxWaitMs !== undefined) {
         throw new Error("--max-wait-ms applies to status --watch");
       }
@@ -172,7 +172,7 @@ export function parseCommand(argv: readonly string[]): CliCommand {
       };
     }
     case "activity": {
-      const options = commandOptions(command, tail, "--runtime", "--watch", "--jsonl", "--limit");
+      const options = commandOptions(command, tail, "--runtime", "--workspace", "--watch", "--jsonl", "--limit");
       if (options.presentation.jsonl === true && !options.watch) {
         throw new Error("--jsonl applies only to activity --watch");
       }
@@ -189,7 +189,7 @@ export function parseCommand(argv: readonly string[]): CliCommand {
     }
     case "cancel": {
       const [build, rest] = requiredPositional(tail, "cancel requires one Build id");
-      const options = commandOptions(command, rest, "--runtime", "--reason");
+      const options = commandOptions(command, rest, "--runtime", "--workspace", "--reason");
       return {
         command,
         build,
@@ -205,17 +205,20 @@ export function parseCommand(argv: readonly string[]): CliCommand {
     case "auth": return parseAuthCommand(tail);
     case "doctor": {
       const [profile, rest] = optionalPositional(tail);
-      const options = commandOptions(command, rest, "--workspace", "--limit");
+      const options = commandOptions(command, rest, "--workspace", "--runtime", "--limit");
+      if (profile !== undefined && options.runtimeProfile !== undefined) {
+        throw new Error("doctor accepts the Runtime Profile either positionally or with --runtime, not both");
+      }
       return {
         command,
         presentation: options.presentation,
         limit: options.limit,
         ...optionalProject(options),
-        ...runtimeOption(profile),
+        ...runtimeOption(profile ?? options.runtimeProfile),
       };
     }
     case "paths": {
-      const options = commandOptions(command, tail, "--runtime");
+      const options = commandOptions(command, tail, "--runtime", "--workspace");
       return { command, presentation: options.presentation, ...optionalRuntime(options) };
     }
     case "_worker": {
@@ -244,7 +247,7 @@ function parseResultCommand(tail: readonly string[]): ProjectResultCommand | Exe
   }
   const [build, rest] = requiredPositional(values, `result ${action} requires one Build id`);
   if (action === "finish" || action === "discard") {
-    const options = commandOptions(`result ${action}`, rest, "--runtime");
+    const options = commandOptions(`result ${action}`, rest, "--runtime", "--workspace");
     return { command: "result", action, build, presentation: options.presentation, ...optionalRuntime(options) };
   }
   const options = commandOptions("result edit", rest,
@@ -306,7 +309,7 @@ function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand |
     : action === "status"
       ? ["--runtime", "--limit"] as const
       : ["--runtime", "--lines"] as const;
-  const options = commandOptions(`runtime ${action}`, rest, ...allowed);
+  const options = commandOptions(`runtime ${action}`, rest, "--workspace", ...allowed);
   rejectDuplicateProfile("runtime", profile, options.runtimeProfile);
   const runtime = runtimeOption(profile ?? options.runtimeProfile);
   const common = {
@@ -314,6 +317,7 @@ function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand |
     action,
     presentation: options.presentation,
     ...runtime,
+    ...optionalProject(options),
   };
   if (action === "up" || action === "down") {
     return { ...common, action, ...(options.maxWaitMs === undefined ? {} : { maxWaitMs: options.maxWaitMs }) };
@@ -329,7 +333,7 @@ function parseProgramsCommand(tail: readonly string[]): ProgramsCommand {
   }
   const [profile, rest] = optionalPositional(values);
   const options = commandOptions(`programs ${action}`, rest,
-    "--runtime", "--limit", "--max-wait-ms");
+    "--runtime", "--workspace", "--limit", "--max-wait-ms");
   if (action !== "up" && options.maxWaitMs !== undefined) {
     throw new Error("--max-wait-ms applies to programs up");
   }
@@ -341,6 +345,7 @@ function parseProgramsCommand(tail: readonly string[]): ProgramsCommand {
     presentation: options.presentation,
     limit: options.limit,
     ...runtime,
+    ...optionalProject(options),
   };
   return action === "up"
     ? { ...common, action, ...(options.maxWaitMs === undefined ? {} : { maxWaitMs: options.maxWaitMs }) }
@@ -362,7 +367,7 @@ function parseAuthCommand(tail: readonly string[]): AuthCommand {
   }
   const [endpoint, rest] = requiredPositional(values, `auth ${action} requires one Endpoint instance`);
   const options = commandOptions(`auth ${action}`, rest,
-    "--runtime", "--slot", ...(action === "login" ? ["--from"] as const : []),
+    "--runtime", "--workspace", "--slot", ...(action === "login" ? ["--from"] as const : []),
     ...(action === "status" ? ["--limit"] as const : []));
   const common = {
     command: "auth" as const,
@@ -576,7 +581,7 @@ function optionalProject(options: RawOptions): ProjectOption {
 }
 
 function optionalRuntime(options: RawOptions): RuntimeOption {
-  return runtimeOption(options.runtimeProfile);
+  return { ...runtimeOption(options.runtimeProfile), ...optionalProject(options) };
 }
 
 function runtimeOption(profile: string | undefined): RuntimeOption {

package/packages/cli/src/build-planning.ts

@@ -24,7 +24,12 @@ export function createCatalogDescriptor(options: {
     if (item.ref.kind === "operation-result") {
       throw new Error(`public output ${item.name} was not lowered to a stable Record or Logical Output`);
     }
-    return item.ref.kind === "logical-output" ? [{ name: item.name, ref: item.ref }] : [];
+    if (item.ref.kind !== "logical-output") return [];
+    const outputId = item.ref.id;
+    const element = options.compilation.provenance.elements.find((element) => element.outputs.some((output) => output.id === outputId));
+    const authored = element?.outputs.find((output) => output.id === outputId);
+    const displayName = element?.components.find((component) => component.id === authored?.component)?.local;
+    return [{ name: item.name, ref: item.ref, ...(displayName === undefined ? {} : { displayName }) }];
   });
   const names = new Set<string>();
   const outputs = new Set<string>();

package/packages/cli/src/command.ts

@@ -4,7 +4,7 @@ type CommandBase = {
   readonly presentation: CliOutputOptions;
 };
 
-export type RuntimeOption = {
+export type RuntimeOption = ProjectOption & {
   readonly runtimeProfile: string | undefined;
 };
 

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

@@ -10,9 +10,27 @@ import { acquireOAuthCredential } from "../oauth.js";
 import { writeCliOutput } from "../output.js";
 import type { CliIo } from "../output.js";
 import { hypitHostStateRoot, hypitProjectStateRoot } from "../paths.js";
-import type { CliRuntimeController } from "../runtime-port.js";
+import type { CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
 import type { OperationalWriter } from "./types.js";
 
+function programRecord(item: CliManagedProgramReport) {
+  return {
+    ...item,
+    state: item.state.state,
+    ...(item.state.state === "ready" ? {} : { stateDetail: item.state.detail }),
+  };
+}
+
+function programDescription(item: CliManagedProgramReport): string {
+  const details = [...new Set([
+    ...(item.state.state === "ready" ? [] : [item.state.detail]),
+    ...(item.detail === undefined ? [] : [item.detail]),
+  ])];
+  return `${item.id}: ${item.state.state}${details.length === 0 ? "" : ` — ${details.join("; ")}`}`
+    + (item.pid === undefined ? "" : ` · PID ${item.pid}`)
+    + (item.logPath === undefined ? "" : ` · log ${item.logPath}`);
+}
+
 export function isEnvironmentCommand(args: CliCommand): args is EnvironmentCommand {
   return args.command === "paths" || args.command === "packages" || args.command === "doctor"
     || args.command === "programs" || args.command === "auth"
@@ -23,6 +41,7 @@ export function isEnvironmentCommand(args: CliCommand): args is EnvironmentComma
 export async function runEnvironmentCommand(input: {
   readonly args: EnvironmentCommand;
   readonly runtimeProfile: string | undefined;
+  readonly runtimeSelectionFile: string | undefined;
   readonly io: CliIo;
   readonly distribution: CliDistribution;
   readonly projectRoot: string;
@@ -32,11 +51,16 @@ export async function runEnvironmentCommand(input: {
   readonly write: OperationalWriter;
 }): Promise<void> {
   const {
-    args, runtimeProfile, io, distribution, projectRoot, packageRootForProject, runtimeHost, runtimeController, write,
+    args, runtimeProfile, runtimeSelectionFile, io, distribution, projectRoot, packageRootForProject, runtimeHost, runtimeController, write,
   } = input;
+  const profileSource: "none" | "argument" | "project" = runtimeProfile === undefined
+    ? "none" : runtimeSelectionFile === undefined ? "argument" : "project";
+  const selectionDescription = profileSource === "argument"
+    ? "command argument (this invocation only)"
+    : runtimeSelectionFile ?? "none";
   const reportProgramProgress = args.presentation.json
     ? undefined
-    : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready" }): void => {
+    : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready"; readonly logPath?: string }): void => {
       if (!args.presentation.verbose && event.phase !== "installing" && event.phase !== "starting") return;
       const verb = {
         checking: "Checking",
@@ -45,7 +69,7 @@ export async function runEnvironmentCommand(input: {
         waiting: "Waiting for",
         ready: "Ready",
       }[event.phase];
-      io.write(`  · ${verb} ${event.id}\n`);
+      io.write(`  · ${verb} ${event.id}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
     };
   const reportPackageProgress = args.presentation.json
     ? undefined
@@ -63,6 +87,8 @@ export async function runEnvironmentCommand(input: {
     const machine = {
       format: "hypit.cli-paths@1" as const,
       project: projectRoot,
+      profileSource,
+      selectionFile: resolve(projectRoot, ".hypit/runtime"),
       projectState: hypitProjectStateRoot(projectRoot),
       ...(runtimeProfile === undefined ? {} : { profile: runtimeProfile }),
       ...(runtimePaths === undefined ? {} : { runtimeData: runtimePaths.runtimeDataRoot }),
@@ -74,11 +100,14 @@ export async function runEnvironmentCommand(input: {
       ["Project", machine.project],
       ["Project state", machine.projectState],
       ["Runtime Profile", machine.profile ?? "not selected"],
+      ["Runtime selection", selectionDescription],
       ["Runtime data", machine.runtimeData ?? "not selected"],
       ["Host state", machine.hostState],
       ["Machine packages", machine.machinePackages],
       ["Distribution", machine.distribution ?? "embedded"],
-    ]);
+    ], runtimeProfile === undefined
+      ? ["Select an existing Profile with hypit runtime use <profile> --workspace <project>, or create one with hypit runtime init."]
+      : []);
     return;
   }
 
@@ -122,6 +151,8 @@ export async function runEnvironmentCommand(input: {
       format: "hypit.cli-doctor@1" as const,
       ok: !diagnostics.some((item) => item.severity === "error"),
       project: projectRoot,
+      profileSource,
+      ...(runtimeSelectionFile === undefined ? {} : { selectionFile: runtimeSelectionFile }),
       ...(profile === undefined ? {} : { profile }),
       diagnosticCount: diagnostics.length,
       diagnostics: diagnostics.slice(0, args.limit),
@@ -151,7 +182,7 @@ export async function runEnvironmentCommand(input: {
     const ready = result.programs.every((item) => item.state.state === "ready");
     const desiredState = args.action === "down" ? !result.programs.some((item) => item.state.state === "ready") : ready;
     const lifecycleOk = args.action === "status" || desiredState;
-    const shownPrograms = result.programs.filter((item) => item.state.state !== "ready").slice(0, args.limit);
+    const shownPrograms = result.programs.filter((item) => args.presentation.verbose || item.state.state !== "ready").slice(0, args.limit);
     const title = args.action === "up"
       ? desiredState ? "External programs ready" : "External programs need attention"
       : args.action === "down"
@@ -161,11 +192,7 @@ export async function runEnvironmentCommand(input: {
       format: "hypit.cli-programs@1",
       action: args.action,
       ready,
-      programs: result.programs.slice(0, args.limit).map((item) => ({
-        id: item.id,
-        state: item.state.state,
-        ...(args.presentation.verbose && item.action !== undefined ? { action: item.action } : {}),
-      })),
+      programs: result.programs.slice(0, args.limit).map(programRecord),
       ...(result.programs.length <= args.limit ? {} : { omittedPrograms: result.programs.length - args.limit }),
     }, title,
     args.action === "status" ? ready ? "success" : "info" : lifecycleOk ? "success" : "warning", [
@@ -173,7 +200,7 @@ export async function runEnvironmentCommand(input: {
         ["Programs", String(result.programs.length)] as const,
         ["Ready", String(result.programs.filter((item) => item.state.state === "ready").length)] as const,
       ]),
-    ], shownPrograms.map((item) => `${item.id}: ${item.state.state}`));
+    ], shownPrograms.map(programDescription));
     if (!lifecycleOk) io.setExitCode?.(1);
     return;
   }
@@ -207,6 +234,7 @@ export async function runEnvironmentCommand(input: {
         programs: {
           total: external.programs.length,
           ready: external.programs.filter((item) => item.state.state === "ready").length,
+          items: external.programs.map(programRecord),
         },
       }, ok ? "Local Runtime ready" : "Local Runtime needs attention", ok ? "success" : "warning", [
         ...(!args.presentation.verbose && ok ? [] : [
@@ -214,7 +242,8 @@ export async function runEnvironmentCommand(input: {
           ["Worker", processState.state] as const,
           ["Managed programs", `${external.programs.filter((item) => item.state.state === "ready").length}/${external.programs.length} ready`] as const,
         ]),
-      ]);
+      ], external.programs.filter((item) => args.presentation.verbose || item.state.state !== "ready")
+        .map(programDescription));
       if (!ok) io.setExitCode?.(1);
       return;
     }

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

@@ -1,15 +1,24 @@
 import type { CliBuildResultView, CliBuildStatusView, CliOutputView } from "./view.js";
 
-type ProgramStateView = { readonly id: string; readonly state: string; readonly action?: string };
+type ProgramStateView = {
+  readonly id: string;
+  readonly state: string;
+  readonly action?: string;
+  readonly endpoint?: string;
+  readonly stateDetail?: string;
+  readonly detail?: string;
+  readonly pid?: number;
+  readonly logPath?: 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-paths@1"; readonly project: string; readonly projectState: string; readonly profileSource: "argument" | "project" | "none"; readonly selectionFile: 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-up@1"; readonly ready: boolean; readonly worker: string; readonly preparedPackages: number; readonly programs: { readonly total: number; readonly ready: number; readonly items: readonly ProgramStateView[] } }
   | { 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 } }

package/packages/cli/src/main.ts

@@ -177,12 +177,14 @@ export async function runCli(
   }
 
   let runtimeProfile = acceptsRuntimeContext(args) ? args.runtimeProfile : undefined;
+  let runtimeSelectionFile: string | undefined;
   const runtimeWasExplicit = runtimeProfile !== undefined;
   let runtimeNeedsHint = runtimeWasExplicit;
   if (acceptsRuntimeContext(args) && runtimeProfile === undefined) {
     const selected = await findRuntimeProfile(await commandProjectRoot());
     if (selected !== undefined) {
       runtimeProfile = selected.profile;
+      runtimeSelectionFile = selected.selectionFile;
       runtimeNeedsHint = false;
     }
   }
@@ -196,6 +198,7 @@ export async function runCli(
     await runEnvironmentCommand({
       args,
       runtimeProfile,
+      runtimeSelectionFile,
       io,
       distribution,
       projectRoot: await commandProjectRoot(),
@@ -387,6 +390,7 @@ export async function runCli(
         result: {
           repository: buildResults.location,
           ...(args.title === undefined ? {} : { title: args.title }),
+          resourceReferences: loadedRun.resultResourceReferences,
           forwards: result.resultForwards.filter((forward) =>
             catalog.publishedOutputs.some((published) => published.ref.id === forward.output)),
         },

package/packages/cli/src/output.ts

@@ -43,6 +43,8 @@ export type DoctorOutput = {
   readonly ok: boolean;
   readonly project: string;
   readonly profile?: string;
+  readonly profileSource?: "argument" | "project" | "none";
+  readonly selectionFile?: string;
   readonly diagnosticCount: number;
   readonly diagnostics: readonly CliDiagnostic[];
   readonly omittedDiagnostics?: number;
@@ -272,9 +274,16 @@ function renderDoctor(view: Extract<CliPresentation, { kind: "doctor" }>, io: Cl
   const lines = [colors.accent(colors.strong("Hypit Doctor")), ""];
   lines.push(...facts([
     ["Project", shortPath(view.machine.project)],
-    ...(view.machine.profile === undefined ? [] : [["Profile", shortPath(view.machine.profile)] as const]),
+    ["Runtime Profile", view.machine.profile === undefined ? "not selected" : shortPath(view.machine.profile)],
+    ...(view.machine.profileSource === "argument"
+      ? [["Runtime selection", "command argument (this invocation only)"] as const]
+      : view.machine.selectionFile === undefined ? [] : [["Runtime selection", shortPath(view.machine.selectionFile)] as const]),
+    ["Scope", view.machine.profile === undefined ? "project Results only" : "selected Runtime and project Results"],
   ], colors));
   lines.push("");
+  if (view.machine.profile === undefined) {
+    lines.push("Select an existing Profile with hypit runtime use <profile>, or pass --runtime <profile> to check it.", "");
+  }
   if (view.machine.diagnostics.length === 0) {
     lines.push(heading("success", "No problems found", io, colors));
   } else {
@@ -770,7 +779,8 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit doctor")),
       colors.dim("Diagnose project Results and, when selected or supplied, one Runtime Profile."),
       "",
-      "  hypit doctor [<runtime-profile>] [--workspace <project>]",
+      "  hypit doctor [--runtime <profile>] [--workspace <project>]",
+      "  A positional Profile is also accepted in place of --runtime.",
       "  Without a Runtime Profile, checks only the project's selected Result Store.",
     ],
     plan: [
@@ -819,6 +829,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit runtime down [<profile>]    stop the Worker; external programs keep running",
       "",
       "The project is resolved first. Selection is read only from that project's .hypit/runtime.",
+      "All runtime actions accept --workspace <project>; operational actions also accept --runtime <profile>.",
       "No Profile filename discovery or parent-project inheritance is performed.",
       "Remote Endpoints such as HypiHub are not started by this command; use doctor to test them.",
     ],
@@ -836,22 +847,26 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit programs")),
       colors.dim("Prepare and operate external programs declared by Endpoints in one Runtime Profile."),
       "",
-      "  hypit programs up [<profile>] [--max-wait-ms <ms>]",
-      "  hypit programs status [<profile>]",
-      "  hypit programs down [<profile>]",
+      "  hypit programs up [--runtime <profile>] [--workspace <project>] [--max-wait-ms <ms>]",
+      "  hypit programs status [--runtime <profile>] [--workspace <project>]",
+      "  hypit programs down [--runtime <profile>] [--workspace <project>]",
+      "  A positional Profile is also accepted in place of --runtime.",
     ],
     activity: [
       colors.accent(colors.strong("hypit activity")),
       colors.dim("Inspect active Builds and Provider pool capacity."),
       "",
-      "  hypit activity [--runtime <profile>] [--watch]",
-      "  hypit activity [--runtime <profile>] --watch --jsonl",
+      "  hypit activity [--workspace <project>] [--runtime <profile>] [--watch]",
+      "  hypit activity [--workspace <project>] [--runtime <profile>] --watch --jsonl",
     ],
     paths: [
       colors.accent(colors.strong("hypit paths")),
       colors.dim("Show project, Runtime and host state locations without creating them."),
       "",
-      "  hypit paths [--runtime <profile>]",
+      "  hypit paths [--workspace <project>] [--runtime <profile>]",
+      "  Shows whether Runtime selection comes from a command argument or the project's .hypit/runtime.",
+      "  Without --workspace, the nearest package.json above cwd defines the project (otherwise cwd).",
+      "  Relative command-line paths start at cwd, including when --workspace is supplied.",
     ],
     builds: [
       colors.accent(colors.strong("hypit builds")),
@@ -863,7 +878,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit status")),
       colors.dim("Show one Build now, or keep watching it without owning execution."),
       "",
-      "  hypit status <build-id> [--runtime <profile>] [--watch]",
+      "  hypit status <build-id> [--workspace <project>] [--runtime <profile>] [--watch]",
       "  --watch                   observe until a Result outcome or operator attention",
       "  --max-wait-ms <ms>        stop watching after a bounded wait",
     ],
@@ -892,14 +907,14 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit cancel")),
       colors.dim("Stop one Build and request cancellation of submitted work when supported."),
       "",
-      "  hypit cancel <build-id> [--runtime <profile>] [--reason <text>]",
+      "  hypit cancel <build-id> [--workspace <project>] [--runtime <profile>] [--reason <text>]",
     ],
     result: [
       colors.accent(colors.strong("hypit result")),
       colors.dim("Edit one Result, finish an interrupted Result write, or discard an incomplete submission."),
       "",
-      "  hypit result finish <build-id> [--runtime <profile>]",
-      "  hypit result discard <build-id> [--runtime <profile>]",
+      "  hypit result finish <build-id> [--workspace <project>] [--runtime <profile>]",
+      "  hypit result discard <build-id> [--workspace <project>] [--runtime <profile>]",
       "  hypit result edit <build-id> [--workspace <project>] [--title <text>] [--note <text>]",
       "                           [--highlight <output> ...]",
       "  --clear-title            remove the Result's human title",
@@ -913,6 +928,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       "  hypit auth status <endpoint-instance> [--runtime <profile>] [--slot <name>]",
       "  hypit auth login <endpoint-instance> [--runtime <profile>] [--slot <name>] [--from <secret-file>]",
       "  hypit auth logout <endpoint-instance> [--runtime <profile>] [--slot <name>]",
+      "  All auth actions accept --workspace <project> to use that project's selection.",
     ],
   };
   const selected = topics[topic];

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

@@ -1,3 +1,4 @@
+import { fileReferenceIdentity } from "@hypit/build-result";
 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";
@@ -53,7 +54,7 @@ async function openResultFile(
   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`);
+  if (input === undefined) throw new Error(`File ${fileReferenceIdentity(build, file)} is unavailable`);
   return input;
 }
 
@@ -83,20 +84,28 @@ async function exportComposite(
   const temporary = join(dirname(target), `.${basename(target)}.part-${randomUUID()}`);
   try {
     await mkdir(temporary);
-    const copied = new Set<string>();
+    const copied = new Map<string, BuildResultFileRef>();
+    const paths = new Set<string>();
+    const bindings = [];
     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),
-      );
+      const file = await repository.describeFile(resolvedOutput.build, binding.file);
+      const identity = fileReferenceIdentity(resolvedOutput.build, file);
+      let local = copied.get(identity);
+      if (local === undefined) {
+        let path = file.kind === "build-file" ? file.path : `files/file-${copied.size + 1}`;
+        const name = basename(path);
+        let index = copied.size + 1;
+        while (paths.has(path) || path === "value.json") path = `files/import-${index++}/${name}`;
+        paths.add(path);
+        local = { kind: "build-file", path, size: file.size, mediaType: file.mediaType };
+        copied.set(identity, local);
+        await writeStream(containedPath(temporary, path), await openResultFile(repository, resolvedOutput.build, file));
+      }
+      bindings.push({ at: binding.at, file: local });
     }
     await writeFile(
       join(temporary, "value.json"),
-      `${JSON.stringify(resolvedOutput.value.document, null, 2)}\n`,
+      `${JSON.stringify({ ...resolvedOutput.value.document, resources: bindings }, null, 2)}\n`,
       { flag: "wx" },
     );
     await rename(temporary, target);
@@ -122,7 +131,7 @@ export async function exportBuildResultOutput(
   const target = resolve(destination);
   if (resolvedOutput.value.kind === "value") {
     await exportComposite(repository, { ...resolvedOutput, value: resolvedOutput.value }, target);
-  } else if (resolvedOutput.value.kind === "build-file") {
+  } else if ((resolvedOutput.value.kind === "build-file" || resolvedOutput.value.kind === "external-file")) {
     const resource = resolvedOutput.value;
     await exportFile(target, async (temporary) => {
       await writeStream(
@@ -142,7 +151,7 @@ export async function exportBuildResultOutput(
     type: publishedOutput.type,
     kind: resolvedOutput.value.kind === "inline"
       ? "scalar"
-      : resolvedOutput.value.kind === "build-file" ? "resource" : "composite",
+      : (resolvedOutput.value.kind === "build-file" || resolvedOutput.value.kind === "external-file") ? "resource" : "composite",
     path: target,
   };
 }

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

@@ -1,3 +1,4 @@
+import { fileReferenceIdentity, ownedFileReference } from "@hypit/build-result";
 import { randomUUID } from "node:crypto";
 import type {
   BuildResultRepository,
@@ -24,15 +25,17 @@ import type { RunFrontend } from "@hypit/run";
 export type LoadedRunFile = NodeCompiledRun & {
   readonly path: string;
   readonly compiler: NodeRunCompiler;
+  readonly resultResourceReferences: Readonly<Record<string, BuildResultFileRef>>;
 };
 
 type BuildResultResolutionSession = {
   readonly files: Map<string, ArtifactAttachment>;
+  readonly references: Map<string, BuildResultFileRef>;
   readonly outputs: Map<string, Promise<RepositoryBuildResultOutput | undefined>>;
 };
 
 function createBuildResultResolutionSession(): BuildResultResolutionSession {
-  return { files: new Map(), outputs: new Map() };
+  return { files: new Map(), outputs: new Map(), references: new Map() };
 }
 
 export async function checkRunFile(options: {
@@ -88,9 +91,10 @@ export async function resolveBuildResultValue(
   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 address = fileReferenceIdentity(owner, file);
     const existing = session.files.get(address);
     if (existing !== undefined) return existing;
+    file = await repository.describeFile(owner, file);
     const artifact: BlobRef = {
       kind: "blob",
       resource: `res_${randomUUID()}`,
@@ -101,11 +105,12 @@ export async function resolveBuildResultValue(
       artifact,
       async open() {
         const stream = await repository.openFile(owner, file);
-        if (stream === undefined) throw new Error(`Build ${owner} file ${file.path} is unavailable`);
+        if (stream === undefined) throw new Error(`File ${address} is unavailable`);
         return stream;
       },
     };
     session.files.set(address, attachment);
+    session.references.set(artifact.resource, ownedFileReference(owner, file));
     return attachment;
   };
   const attachments = new Map<string, ArtifactAttachment>();
@@ -120,7 +125,7 @@ export async function resolveBuildResultValue(
   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") {
+  if (resolved.value.kind === "build-file" || resolved.value.kind === "external-file") {
     const attachment = await resultAttachment(resolved.build, resolved.value);
     attachments.set(attachment.artifact.resource, attachment);
     value = attachment.artifact;
@@ -147,8 +152,7 @@ function createRunCompiler(options: {
   readonly frontends: readonly RunFrontend[];
   readonly packageContributions: readonly NodePackageContribution[];
   readonly results?: BuildResultRepository;
-}): NodeRunCompiler {
-  const resultSession = createBuildResultResolutionSession();
+}, resultSession = createBuildResultResolutionSession()): NodeRunCompiler {
   const fragments = new RunFragmentRegistry();
   for (const item of options.packageContributions) {
     installRunFragmentHostFacets(item.hostFacets ?? [], fragments);
@@ -180,7 +184,14 @@ export async function loadRunFile(options: {
   readonly packageContributions: readonly NodePackageContribution[];
   readonly results?: BuildResultRepository;
 }): Promise<LoadedRunFile> {
-  const compiler = createRunCompiler(options);
+  const resultSession = createBuildResultResolutionSession();
+  const compiler = createRunCompiler(options, resultSession);
   const compiled = await compiler.compileSource(options.workspace.entry, options.workspace);
-  return { path: options.workspace.entry.id, compiler, ...compiled };
+  const references = new Map<string, BuildResultFileRef>(compiled.attachments.flatMap((attachment) =>
+    attachment.location === undefined ? [] : [[attachment.artifact.resource, {
+      kind: "external-file" as const, uri: attachment.location,
+      size: attachment.artifact.size, mediaType: attachment.artifact.mediaType,
+    }]]));
+  for (const [resource, file] of resultSession.references) references.set(resource, file);
+  return { path: options.workspace.entry.id, compiler, ...compiled, resultResourceReferences: Object.fromEntries(references) };
 }

package/packages/comment-sticker-studio/src/index.ts

@@ -117,12 +117,13 @@ export const commentStickerStudioTrackCompanions: readonly StudioTrackCompanion[
     inspector: [
       ...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
         binding: `frame.${name}`, label: title(name), domain: "where" as const,
-        page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text" as const,
+        page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
       })),
       ...commentInspector,
       ...["comment", "author", "header", "meta"].map((binding) => ({
         binding, label: title(binding), domain: "how" as const,
         page: { id: "copy", label: "Copy" }, section: { id: "copy", label: "Copy" }, control: "text" as const,
+        ...(binding === "comment" ? { multiline: true } : {}),
       })),
     ],
     requiredValues: ["program"], project: projectComments,

package/packages/compiler-node/src/compiler.ts

@@ -51,6 +51,7 @@ export function mergeAttachments(groups: readonly (readonly ArtifactAttachment[]
     merged.set(key, {
       artifact: { ...item.artifact },
       open: item.open,
+      ...(item.location === undefined ? {} : { location: item.location }),
     });
   }
   return [...merged.values()]