@hypit/hypit 0.1.4 → 0.1.6

package/packages/caption-fine-studio/package.json

@@ -15,6 +15,8 @@
     "@hypit/composition": "workspace:*",
     "@hypit/narrative": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
-    "@hypit/fonts-open": "workspace:*"
+    "@hypit/fonts-open": "workspace:*",
+    "@hypit/caption": "workspace:*",
+    "@hypit/timeline": "workspace:*"
   }
 }

package/packages/caption-fine-studio/src/activation.ts

@@ -1,7 +1,7 @@
-import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
-import { captionFineStudioTrackCompanions } from "./index.js";
+import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
+import { captionFineStudioTrackCompanions, captionFineStudioParameterCompanions } from "./index.js";
 
 export default {
   format: "hypit.node-package@1" as const,
-  hostFacets: [createStudioTrackCompanionHostFacet(captionFineStudioTrackCompanions)],
+  hostFacets: [createStudioCompanionHostFacet({ tracks: captionFineStudioTrackCompanions, parameters: captionFineStudioParameterCompanions })],
 };

package/packages/caption-fine-studio/src/index.ts

@@ -1,5 +1,7 @@
+import { temporalTypes } from "@hypit/temporal";
+import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
 import { openFontStudioFields } from "@hypit/fonts-open/studio";
-import { captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
+import { fineCaptionEditableDefaults, captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
 import type { FineCaptionSchedule } from "@hypit/caption-fine";
 import { compositionTypes } from "@hypit/composition";
 import { narrativeTypes } from "@hypit/narrative";
@@ -10,11 +12,11 @@ import type {
   StudioEntityDraft,
   StudioInspectorFieldDeclaration,
 } from "@hypit/studio-adapter";
-import { requiredReferencedValue, requiredSurfaceValue, textLayer } from "@hypit/studio-adapter";
+import { authoredChildFor, temporalLineageFor, temporalSemanticSource, requiredReferencedValue, requiredSurfaceValue } from "@hypit/studio-adapter";
 
 const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
 
-const fontInspector = openFontStudioFields("program");
+const fontInspector = openFontStudioFields("style");
 
 const recipeVocabulary = styleSurface?.vocabulary.attributes
   .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
@@ -95,7 +97,7 @@ export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaratio
   if (placement === undefined) throw new Error(`Caption Studio has no explicit Inspector declaration for ${property.name}.`);
   const options = valuesFor(property);
   return {
-    binding: `program.${property.name}`,
+    binding: `style.${property.name}`,
     label: title(property.name),
     ...placement,
     summary: property.summary,
@@ -118,39 +120,40 @@ function cueText(document: CaptionDocument | undefined, unitIds: readonly string
     .trim();
 }
 
-function projectCaption(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+export function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const content = requiredSurfaceValue(context, "content") as TimedCaptionProjection;
   const schedule = requiredSurfaceValue(context, "schedule") as FineCaptionSchedule;
   const document = requiredReferencedValue(context, "document", narrativeTypes.captionDocument) as CaptionDocument;
-  if (document.id !== schedule.documentId) throw new Error("Caption Studio Schedule belongs to another CaptionDocument.");
-  const rendered = new Map(context.generic().flatMap((entity) =>
-    entity.presentId === undefined ? [] : [[entity.presentId, entity] as const]));
-  return schedule.cues.map((cue): StudioEntityDraft => {
-    const base = rendered.get(cue.id);
-    const label = cueText(document, cue.units.map((unit) => unit.unitId));
-    const authoredId = context.placement?.id ?? cue.id;
+  if (document.id !== content.documentId) throw new Error("Caption content belongs to another CaptionDocument.");
+  return content.cues.map((cue, index): StudioEntityDraft => ({
+    id: `${context.track.outputRef}:cue:${cue.id}`, authoredId: cue.id,
+    display: { title: `#${index + 1}`, layers: [{ kind: "text", role: "content", text: cueText(document, cue.units.map(unit => unit.unitId)) }] },
+    startFrame: cue.startFrame, endFrameExclusive: cue.endFrameExclusive, stackOrder: 0,
+    renderIds: schedule.cues.filter(item => item.cueId === cue.id).map(item => item.id),
+    presentation: { entity: "caption-cue", chrome: "standard" },
+    inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "cue", label: "Cue" }, value: `${cue.startFrame}–${cue.endFrameExclusive}`, unit: "f" }],
+  }));
+}
+
+export function projectCaption(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const program = requiredSurfaceValue(context, "program") as CaptionProgram;
+  const uses: StudioEntityDraft[] = program.uses.map((use, index) => {
+    const authoredId = use.window.subjectId;
+    const child = authoredChildFor(context, authoredId, [temporalTypes.windowSpec]);
+    if (child === undefined) throw new Error(`Caption Use ${authoredId} has no author provenance.`);
+    const temporal = temporalLineageFor(context, authoredId, "window");
+    const semantic = temporalSemanticSource(temporal);
     return {
-      ...(base ?? {
-        id: `${context.track.outputRef}:entity:${cue.id}`,
-        authoredId: cue.id,
-        display: { title: "Caption", layers: [] },
-        startFrame: cue.visibleStartFrame,
-        endFrameExclusive: cue.visibleEndFrameExclusive,
-        stackOrder: 0,
-        presentId: cue.id,
-        renderIds: [cue.id],
-      }),
-      authoredId,
-      ...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
-      display: {
-        title: "Caption",
-        layers: label.length === 0 ? [] : [textLayer(label)],
-      },
-      startFrame: cue.visibleStartFrame,
-      endFrameExclusive: cue.visibleEndFrameExclusive,
-      presentation: { entity: "caption-cue", chrome: "standard" },
-      parameterReferences: { program: cue.styleId },
+      id: `${context.track.outputRef}:use:${authoredId}`, authoredId,
+      display: { title: use.styleId, layers: [] },
+      ...use.window.span, stackOrder: index, elementRange: child.range,
+      ...(temporal === undefined ? {} : { temporal }),
+      ...(semantic === undefined ? {} : { markerId: semantic.id }),
+      presentation: { entity: "caption-use", chrome: "standard" }, band: "uses",
+      inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f" }],
     };
   });
+  return [...projectCaptionContents(context), ...uses];
 }
 
 export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] = [
@@ -158,15 +161,24 @@ export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] =
     id: "track", role: "track",
     output: { type: compositionTypes.visualTrack, surface: "track", modules: [captionFineModuleRef] },
     family: "caption", tone: "magenta", icon: "captions",
-    bindings: [
-      {
-        name: "program",
-        referenced: [fontInspector.binding],
-        recipe: { through: ["recipe"], bindings: recipeVocabulary.map(({ name }) => ({ name })) },
-      },
-    ],
-    inspector: [...fontInspector.fields, ...captionFineInspectorFields],
-    requiredValues: ["schedule"], project: projectCaption,
-    lane: { heightPx: 48 },
+    lane: { heightPx: 36 },
+    bands: [{
+      id: "uses", placement: "after", heightPx: 15, display: "label",
+      bindings: [{ name: "style", companion: true }],
+      inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text" }],
+    }],
+    requiredValues: ["content", "schedule", "program"], project: projectCaption,
+
   },
 ];
+
+export const captionFineStudioParameterCompanions: readonly import("@hypit/studio-adapter").StudioParameterCompanion[] = [{
+  id: "style", match: { module: captionFineModuleRef, surface: "style" },
+  bindings: [fontInspector.binding, { name: "recipe", recipe: { bindings: recipeVocabulary.map(({ name }) => ({ name,
+    ...(Object.hasOwn(fineCaptionEditableDefaults, name) ? { fallback: fineCaptionEditableDefaults[name as keyof typeof fineCaptionEditableDefaults] } : {}),
+  })) } }],
+  inspector: [
+    ...fontInspector.fields.map(field => ({ ...field, binding: field.binding.replace(/^style\./u, "") })),
+    ...captionFineInspectorFields.map(field => ({ ...field, binding: field.binding.replace(/^style\./u, "recipe.") })),
+  ],
+}];

package/packages/cli/README.md

@@ -11,9 +11,37 @@ Source imports decide which language and component packages give the source mean
 Profile separately selects Credential Stores and Endpoints allowed to execute work. The CLI does not
 invent targets, candidates or Provider choices.
 
-Human output is compact by default. `--json` emits a command-specific view rather than raw compiler,
-Runtime or Repository objects. `--verbose` adds operational detail; it never turns the command into
-an internal state dump.
+Human and JSON output answer the same command-specific question. `--json` changes encoding;
+`--verbose` expands scope. Compiler, Runtime and Repository objects are not default reports.
+
+| Command | Default scope | Explicit detail |
+| --- | --- | --- |
+| `check` | Validation, targets and counts | `--verbose`: exported names/types and historical references |
+| `plan` | Targets, demanded requests, Endpoint selection and diagnostics | `--verbose`: Run choices, graph step count and unreached declarations |
+| `pricing` | Requests that may incur a Provider charge and their rate material | `--verbose`: declared no-charge requests and original documents |
+| `status`, `activity` | Current work, Provider-reported phases and failures | `--verbose`: individual operations; activity also includes capacity reservations |
+| `inspect` | Targets and explicitly highlighted Outputs, outcome and failure evidence | `--output <name>` selects one Output; `--verbose` browses all available Outputs and receipts |
+| `doctor`, `programs` | Complete diagnostics; program discovery or the unmet result of an explicit lifecycle action | `--verbose`: successful lifecycle details; `--limit` bounds the healthy program list |
+
+Run choices count explicit Candidate selections, which can supply existing work or execute an
+alternative producer. They are not a count of reused files. Result output counts describe all
+available named Outputs, including forwarded ones; they are not a count of newly generated assets.
+`history <output>` lists Builds containing that name, including reuse, rather than deduplicating
+generation events or guessing whether mutable external files still contain the same bytes.
+`inspect` chooses names before resolving references, so an unrelated Output cannot delay or break
+inspection of a target. It reports the number of other Outputs without reading their descriptions.
+
+`plan` retains every target, demanded request and preflight diagnostic in both encodings. `--limit`
+bounds expanded detail, not the work inventory before grouping. `inspect` likewise keeps its default
+target/highlight selection intact; `--limit` bounds the broader `--verbose` list, with an omitted count.
+No-charge classification continues to belong to the selected Endpoint's pricing declaration.
+
+Build follow and status include Provider-reported local Command activity as well as asynchronous
+Operations. Follow coalesces counters into readable updates and continues to distinguish execution
+from Result saving. Status groups identical active Operations and retains failures by default;
+completed receipts are detail. Activity reports the phases that trigger its updates and ignores
+changes confined to Builds outside the displayed page. Providers own the phase vocabulary; the CLI
+does not interpret model or renderer names.
 
 ## Project and Runtime context
 
@@ -24,7 +52,8 @@ directory, including when `--workspace` is supplied.
 
 Runtime-aware commands use an explicit `--runtime` for that invocation, or read exactly the resolved
 project's `.hypit/runtime` pointer. `runtime use` writes the pointer; a Profile filename by itself does
-not select it. Project selection is also available on `paths`, `doctor`, execution status/control,
+not select it. The pointer is a file, separate from the Profile's `dataRoot`; a directory at that
+path is reported explicitly and preserved. Project selection is also available on `paths`, `doctor`, execution status/control,
 Runtime operations, `programs` and `auth`. Machine-wide `packages` operations have no project selector.
 
 `paths` shows the effective locations and whether the Profile came from a command argument, a project
@@ -46,6 +75,9 @@ settings without searching arbitrary records for a request-shaped object. When a
 made by an earlier Build step, that direct graph edge stays symbolic until the file exists; the rest
 of the request is still shown. A complete request is resolved through the same Endpoint Registry as
 the Build, including the Endpoint's `supports` check.
+Each component's planned-Need presentation owns its useful request fields. An empty presentation
+means the summary is unavailable, not that the request has no parameters. Structured render inputs
+are summarized by their owning packages; the CLI does not traverse upstream graphs to invent them.
 
 `pricing <run>` uses that selected Runtime to read Provider-owned rate material. The default report
 summarizes requests whose resolved Endpoint explicitly declares `pricing.kind: "local"` as having no
@@ -74,3 +106,24 @@ machine-view union. `main.ts` resolves project and selected Runtime context sepa
 syntax, then routes these command groups. Result commands do not consult or construct a Runtime,
 and the generic CLI cannot silently choose a Result Repository or a Provider-specific login
 flow.
+
+## Execution logs
+
+`hypit logs <build-id> [--workspace <project>] [--runtime <profile>] [--lines <count>]` reads Build
+execution phases and Provider diagnostics. It reads a finished Result directly, without opening the
+Runtime; an active Build is read through Runtime control. The selected Repository handles file access.
+`--lines` limits the tail and the report states the omitted count; JSON carries records plus that count.
+`inspect` exposes an available log separately from authored Outputs. `hypit runtime logs` reads the
+Worker process log instead, for Runtime startup or process-level failures.
+
+Project context resolution is owned by [`@hypit/project-context-node`](../project-context-node/README.md).
+CLI, Studio and creation tools call that same package; the CLI is not another environment owner.
+
+`doctor`, `programs up|status|down`, and `runtime up` accept repeated `--endpoint <instance>` values.
+The same Endpoint scope reaches package preparation and Program operations. Omission means the whole
+Profile. Build preflight instead uses the Endpoints resolved for that Build's concrete requests.
+An unrelated offered capability does not add another credential or Program requirement.
+
+Upstream package installation reports an `install.log` path at preparation time. Exact package
+releases coexist below the machine home, each with npm's own package.json and lockfile. `paths` shows
+the home; `packages status <name@version>` checks the requested release rather than a mutable latest copy.

package/packages/cli/package.json

@@ -16,6 +16,7 @@
     "@hypit/driver-node": "workspace:*",
     "@hypit/elaborator": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/run": "workspace:*",
     "@hypit/runtime": "workspace:*",

package/packages/cli/src/arguments.ts

@@ -18,6 +18,7 @@ type RawOptions = {
   readonly presentation: CliOutputOptions;
   readonly workspaceRoot?: string;
   readonly assetRoots: readonly string[];
+  readonly endpoints: readonly string[];
   readonly packageRoot?: string;
   readonly runtimeProfile?: string;
   readonly follow: boolean;
@@ -36,6 +37,7 @@ type RawOptions = {
   readonly watch: boolean;
   readonly readyFile?: string;
   readonly workerOwner?: string;
+  readonly executionRoot?: string;
   readonly reason?: string;
   readonly slot?: string;
   readonly credentialFile?: string;
@@ -155,6 +157,12 @@ export function parseCommand(argv: readonly string[]): CliCommand {
         ...optionalProject(options),
       };
     }
+    case "logs": {
+      const [build, rest] = requiredPositional(tail, "logs requires one Build id");
+      const options = commandOptions(command, rest, "--runtime", "--workspace", "--lines");
+      return { command, build, lines: options.lines, presentation: options.presentation,
+        ...optionalProject(options), ...optionalRuntime(options) };
+    }
     case "status": {
       const [build, rest] = requiredPositional(tail, "status requires one Build id");
       const options = commandOptions(command, rest, "--runtime", "--workspace", "--watch", "--max-wait-ms", "--limit");
@@ -205,12 +213,13 @@ 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", "--runtime", "--limit");
+      const options = commandOptions(command, rest, "--workspace", "--runtime", "--limit", "--endpoint");
       if (profile !== undefined && options.runtimeProfile !== undefined) {
         throw new Error("doctor accepts the Runtime Profile either positionally or with --runtime, not both");
       }
       return {
         command,
+        ...(options.endpoints.length === 0 ? {} : { endpoints: options.endpoints }),
         presentation: options.presentation,
         limit: options.limit,
         ...optionalProject(options),
@@ -223,7 +232,7 @@ export function parseCommand(argv: readonly string[]): CliCommand {
     }
     case "_worker": {
       const [profile, rest] = requiredPositional(tail, "internal Worker launch is incomplete");
-      const options = commandOptions(command, rest, "--ready-file", "--worker-owner", "--package-root");
+      const options = commandOptions(command, rest, "--ready-file", "--worker-owner", "--package-root", "--execution-root");
       if (options.readyFile === undefined || options.workerOwner === undefined) {
         throw new Error("internal Worker launch is incomplete");
       }
@@ -232,6 +241,7 @@ export function parseCommand(argv: readonly string[]): CliCommand {
         profile,
         readyFile: options.readyFile,
         workerOwner: options.workerOwner,
+        ...(options.executionRoot === undefined ? {} : { executionRoot: options.executionRoot }),
         presentation: options.presentation,
         ...optionalPackageRoot(options),
       };
@@ -305,7 +315,7 @@ function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand |
   }
   const [profile, rest] = optionalPositional(values);
   const allowed = action === "up" || action === "down"
-    ? ["--runtime", "--max-wait-ms"] as const
+    ? action === "up" ? ["--runtime", "--max-wait-ms", "--endpoint"] as const : ["--runtime", "--max-wait-ms"] as const
     : action === "status"
       ? ["--runtime", "--limit"] as const
       : ["--runtime", "--lines"] as const;
@@ -320,7 +330,7 @@ function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand |
     ...optionalProject(options),
   };
   if (action === "up" || action === "down") {
-    return { ...common, action, ...(options.maxWaitMs === undefined ? {} : { maxWaitMs: options.maxWaitMs }) };
+    return { ...common, action, ...(action === "up" && options.endpoints.length > 0 ? { endpoints: options.endpoints } : {}), ...(options.maxWaitMs === undefined ? {} : { maxWaitMs: options.maxWaitMs }) };
   }
   if (action === "status") return { ...common, action, limit: options.limit };
   return { ...common, action, lines: options.lines };
@@ -333,7 +343,7 @@ function parseProgramsCommand(tail: readonly string[]): ProgramsCommand {
   }
   const [profile, rest] = optionalPositional(values);
   const options = commandOptions(`programs ${action}`, rest,
-    "--runtime", "--workspace", "--limit", "--max-wait-ms");
+    "--runtime", "--workspace", "--limit", "--max-wait-ms", "--endpoint");
   if (action !== "up" && options.maxWaitMs !== undefined) {
     throw new Error("--max-wait-ms applies to programs up");
   }
@@ -341,6 +351,7 @@ function parseProgramsCommand(tail: readonly string[]): ProgramsCommand {
   const runtime = runtimeOption(profile ?? options.runtimeProfile);
   const common = {
     command: "programs" as const,
+    ...(options.endpoints.length === 0 ? {} : { endpoints: options.endpoints }),
     action,
     presentation: options.presentation,
     limit: options.limit,
@@ -403,6 +414,7 @@ function parseOptions(values: readonly string[]): RawOptions {
   let runtimeProfile: string | undefined;
   let follow = false;
   let maxWaitMs: number | undefined;
+  const endpoints: string[] = [];
   let outputName: string | undefined;
   let title: string | undefined;
   let note: string | undefined;
@@ -421,6 +433,7 @@ function parseOptions(values: readonly string[]): RawOptions {
   let watch = false;
   let readyFile: string | undefined;
   let workerOwner: string | undefined;
+  let executionRoot: string | undefined;
   let reason: string | undefined;
   let slot: string | undefined;
   let credentialFile: string | undefined;
@@ -429,7 +442,7 @@ function parseOptions(values: readonly string[]): RawOptions {
   for (let index = 0; index < values.length; index += 1) {
     const item = values[index]!;
     if (!item.startsWith("--")) throw new Error(`unexpected positional argument ${item}`);
-    const repeatable = [
+    const repeatable = item === "--endpoint" || [
       "--json", "--jsonl", "--watch", "--verbose", "--debug",
       "--no-color", "--follow", "--asset-root", "--highlight",
     ].includes(item);
@@ -450,6 +463,7 @@ function parseOptions(values: readonly string[]): RawOptions {
       index += 1;
       continue;
     }
+    if (item === "--endpoint") { endpoints.push(optionValue(values, index, "--endpoint requires an Endpoint name")); index += 1; continue; }
     if (item === "--workspace") {
       workspaceRoot = resolve(optionValue(values, index, "--workspace requires a directory")); index += 1; continue;
     }
@@ -506,6 +520,9 @@ function parseOptions(values: readonly string[]): RawOptions {
     if (item === "--worker-owner") {
       workerOwner = optionValue(values, index, "--worker-owner requires an identity"); index += 1; continue;
     }
+    if (item === "--execution-root") {
+      executionRoot = resolve(optionValue(values, index, "--execution-root requires a path")); index += 1; continue;
+    }
     if (item === "--reason") {
       reason = optionValue(values, index, "--reason requires text"); index += 1; continue;
     }
@@ -527,6 +544,7 @@ function parseOptions(values: readonly string[]): RawOptions {
     presentation: { json: json || jsonl, ...(jsonl ? { jsonl: true } : {}), color, verbose },
     assetRoots,
     follow,
+    endpoints,
     highlightedOutputs,
     clearTitle,
     clearNote,
@@ -546,6 +564,7 @@ function parseOptions(values: readonly string[]): RawOptions {
     ...(destination === undefined ? {} : { destination }),
     ...(readyFile === undefined ? {} : { readyFile }),
     ...(workerOwner === undefined ? {} : { workerOwner }),
+    ...(executionRoot === undefined ? {} : { executionRoot }),
     ...(reason === undefined ? {} : { reason }),
     ...(slot === undefined ? {} : { slot }),
     ...(credentialFile === undefined ? {} : { credentialFile }),

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

@@ -421,9 +421,10 @@ export function assertPlannedRequests(
   }
 }
 
-export async function preflightPlan(host: NodeRuntimeHost, state: BuildState) {
+export async function preflightPlan(host: NodeRuntimeHost, state: BuildState, providers: readonly PlanProviderView[]) {
   const capabilities = demandedCapabilities(state);
-  const result = await host.preflight({ capabilities });
+  const endpoints = [...new Set(providers.flatMap((item) => item.status === "resolved" && item.endpoint !== undefined ? [item.endpoint] : []))];
+  const result = await host.preflight({ endpoints });
   return {
     ok: !result.diagnostics.some((item) => item.severity === "error"),
     capabilities: capabilities.map(capabilityName),

package/packages/cli/src/command.ts

@@ -72,6 +72,7 @@ export type ProjectResultCommand =
     });
 
 export type ExecutionCommand =
+  | (CommandBase & RuntimeOption & { readonly command: "logs"; readonly build: string; readonly lines: number })
   | (CommandBase & RuntimeOption & {
       readonly command: "status";
       readonly build: string;
@@ -115,6 +116,7 @@ export type RuntimeOperationCommand =
   | (CommandBase & RuntimeOption & {
       readonly command: "runtime";
       readonly action: "up";
+      readonly endpoints?: readonly string[];
       readonly maxWaitMs?: number;
     })
   | (CommandBase & RuntimeOption & {
@@ -136,12 +138,14 @@ export type RuntimeOperationCommand =
 export type ProgramsCommand =
   | (CommandBase & RuntimeOption & {
       readonly command: "programs";
+      readonly endpoints?: readonly string[];
       readonly action: "up";
       readonly maxWaitMs?: number;
       readonly limit: number;
     })
   | (CommandBase & RuntimeOption & {
       readonly command: "programs";
+      readonly endpoints?: readonly string[];
       readonly action: "down" | "status";
       readonly limit: number;
     });
@@ -182,6 +186,7 @@ export type EnvironmentCommand =
     })
   | (CommandBase & ProjectOption & RuntimeOption & {
       readonly command: "doctor";
+      readonly endpoints?: readonly string[];
       readonly limit: number;
     });
 
@@ -190,6 +195,7 @@ export type WorkerCommand = CommandBase & {
   readonly profile: string;
   readonly readyFile: string;
   readonly workerOwner: string;
+  readonly executionRoot?: string;
   readonly packageRoot?: string;
 };
 

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

@@ -73,8 +73,8 @@ export async function runEnvironmentCommand(input: {
     };
   const reportPackageProgress = args.presentation.json
     ? undefined
-    : (event: { readonly specifier: string; readonly phase: "checking" | "installing" | "ready" }): void => {
-      if (event.phase === "installing") io.write(`  · Installing ${event.specifier}\n`);
+    : (event: { readonly specifier: string; readonly phase: "checking" | "installing" | "ready"; readonly logPath?: string }): void => {
+      if (event.phase === "installing") io.write(`  · Installing ${event.specifier}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
     };
   const reportCredentialProgress = args.presentation.json
     ? io.writeProgress
@@ -126,10 +126,13 @@ export async function runEnvironmentCommand(input: {
       action: args.action,
       package: args.package,
       ready,
+      ...(reports[0] === undefined ? {} : { installation: reports[0].root }),
+      ...(reports[0]?.logPath === undefined ? {} : { logPath: reports[0].logPath }),
     }, args.action === "install" ? "Machine package is ready" : "Machine package status",
     ready ? "success" : "warning", [
       ["Package", args.package],
       ["Ready", String(ready)],
+      ...(args.presentation.verbose && reports[0] !== undefined ? [["Installation", reports[0].root] as const] : []),
     ]);
     if (!ready) io.setExitCode?.(1);
     return;
@@ -138,7 +141,7 @@ export async function runEnvironmentCommand(input: {
   if (args.command === "doctor") {
     const profile = runtimeProfile === undefined ? undefined : resolve(runtimeProfile);
     const [runtimeResult, projectResult] = await Promise.all([
-      profile === undefined ? undefined : (await runtimeHost(profile)).doctor(),
+      profile === undefined ? undefined : (await runtimeHost(profile)).doctor(args.endpoints === undefined ? {} : { endpoints: args.endpoints }),
       distribution.diagnoseProjectResults(projectRoot, {
         packageRoot: await packageRootForProject(),
         ...(distribution.packageRoot === undefined
@@ -155,8 +158,7 @@ export async function runEnvironmentCommand(input: {
       ...(runtimeSelectionFile === undefined ? {} : { selectionFile: runtimeSelectionFile }),
       ...(profile === undefined ? {} : { profile }),
       diagnosticCount: diagnostics.length,
-      diagnostics: diagnostics.slice(0, args.limit),
-      ...(diagnostics.length <= args.limit ? {} : { omittedDiagnostics: diagnostics.length - args.limit }),
+      diagnostics,
     };
     writeCliOutput(io, args.presentation, { kind: "doctor", machine });
     if (!machine.ok) io.setExitCode?.(1);
@@ -168,21 +170,27 @@ export async function runEnvironmentCommand(input: {
     const profile = resolve(runtimeProfile);
     const host = await runtimeHost(profile);
     if (args.action === "up") {
-      await host.prepare(reportPackageProgress === undefined ? {} : { onProgress: reportPackageProgress });
+      await host.prepare({ ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }), ...(reportPackageProgress === undefined ? {} : { onProgress: reportPackageProgress }) });
     }
     const controller = await runtimeController(profile);
     const result = args.action === "up"
       ? await controller.programs.up({
+        ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }),
         ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
         ...(reportProgramProgress === undefined ? {} : { onProgress: reportProgramProgress }),
       })
       : args.action === "down"
-        ? await controller.programs.down()
-        : await controller.programs.report();
+        ? await controller.programs.down(args.endpoints === undefined ? {} : { endpoints: args.endpoints })
+        : await controller.programs.report(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
     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) => args.presentation.verbose || item.state.state !== "ready").slice(0, args.limit);
+    const needsAttention = (item: typeof result.programs[number]) => args.action === "down"
+      ? item.state.state === "ready" : item.state.state !== "ready";
+    const relevant = result.programs.filter((item) => args.presentation.verbose || args.action === "status" || needsAttention(item));
+    const urgent = relevant.filter(needsAttention);
+    const shownPrograms = [...urgent, ...relevant.filter((item) => !needsAttention(item)).slice(0, Math.max(0, args.limit - urgent.length))];
+    const omittedPrograms = relevant.length - shownPrograms.length;
     const title = args.action === "up"
       ? desiredState ? "External programs ready" : "External programs need attention"
       : args.action === "down"
@@ -192,15 +200,17 @@ export async function runEnvironmentCommand(input: {
       format: "hypit.cli-programs@1",
       action: args.action,
       ready,
-      programs: result.programs.slice(0, args.limit).map(programRecord),
-      ...(result.programs.length <= args.limit ? {} : { omittedPrograms: result.programs.length - args.limit }),
+      programCount: result.programs.length,
+      readyCount: result.programs.filter((item) => item.state.state === "ready").length,
+      programs: shownPrograms.map(programRecord),
+      ...(omittedPrograms === 0 ? {} : { omittedPrograms }),
     }, title,
     args.action === "status" ? ready ? "success" : "info" : lifecycleOk ? "success" : "warning", [
       ...(!args.presentation.verbose && lifecycleOk && args.action !== "status" ? [] : [
         ["Programs", String(result.programs.length)] as const,
         ["Ready", String(result.programs.filter((item) => item.state.state === "ready").length)] as const,
       ]),
-    ], shownPrograms.map(programDescription));
+    ], shownPrograms.map(programDescription).concat(omittedPrograms === 0 ? [] : [`${omittedPrograms} more programs · use --limit <count>`]));
     if (!lifecycleOk) io.setExitCode?.(1);
     return;
   }
@@ -213,11 +223,12 @@ export async function runEnvironmentCommand(input: {
       const packageRoot = await packageRootForProject();
       const host = await runtimeHost(profile, packageRoot);
       const prepared = await host.prepare(
-        reportPackageProgress === undefined ? {} : { onProgress: reportPackageProgress },
+        { ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }), ...(reportPackageProgress === undefined ? {} : { onProgress: reportPackageProgress }) },
       );
-      const validated = await host.createRuntime();
+      const validated = await host.createRuntime(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
       await validated.close();
       const external = await controller.programs.up({
+        ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }),
         ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
         ...(reportProgramProgress === undefined ? {} : { onProgress: reportProgramProgress }),
       });
@@ -234,7 +245,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),
+          items: external.programs.filter((item) => args.presentation.verbose || item.state.state !== "ready").map(programRecord),
         },
       }, ok ? "Local Runtime ready" : "Local Runtime needs attention", ok ? "success" : "warning", [
         ...(!args.presentation.verbose && ok ? [] : [
@@ -300,13 +311,12 @@ export async function runEnvironmentCommand(input: {
         attention,
         worker: {
           state: worker.state,
-          ...(worker.configuration === undefined ? {} : { configuration: worker.configuration }),
         },
         builds: counts,
         programs: {
           total: external.programs.length,
           ready: external.programs.length - unavailable.length,
-          unavailable: unavailable.slice(0, args.limit).map((item) => ({ id: item.id, state: item.state.state })),
+          unavailable: unavailable.map(programRecord),
         },
         capacity: {
           active: activity.capacity.length,
@@ -326,7 +336,7 @@ export async function runEnvironmentCommand(input: {
           ["Capacity in use", String(activity.capacity.length)] as const,
         ] : []),
       ], [
-        ...unavailable.slice(0, args.limit).map((item) => `${item.id}: ${item.state.state}`),
+        ...unavailable.map(programDescription),
       ]);
     } finally {
       if (runtime !== undefined) await runtime.close();