Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

46.0 KB
Raw Blame
import { relative, resolve, sep } from "node:path";

import type { CanonicalValue } from "@hypit/protocol";

import type { OperationalMachineView } from "./machine-view.js";
import { CliUsageError } from "./usage-error.js";

export type CliTerminal = {
  readonly isTTY: boolean;
  readonly color: boolean;
  readonly unicode: boolean;
  readonly columns: number;
};

export type CliIo = {
  readonly write: (text: string) => void;
  /** Human progress that may use stderr while `write` remains a stable machine-output channel. */
  readonly writeProgress?: (text: string) => void;
  /** Concrete command shells expose process status without coupling the engine to Node globals. */
  readonly setExitCode?: (code: number) => void;
  /** Interactive secret input supplied by the concrete CLI shell; never echoed or logged. */
  readonly readSecret?: (prompt: string) => Promise<string>;
  readonly terminal?: CliTerminal;
};

export type CliColorMode = "auto" | "always" | "never";

export type CliOutputOptions = {
  readonly json: boolean;
  readonly jsonl?: boolean;
  readonly color: CliColorMode;
  readonly verbose: boolean;
};

export type CliDiagnostic = {
  readonly severity: "error" | "warning" | "info";
  readonly code: string;
  readonly message: string;
  readonly subject?: string;
};

export type DoctorOutput = {
  readonly format: "hypit.cli-doctor@1";
  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;
};

export type AuthorCheckOutput = {
  readonly format: "hypit.cli-check@1";
  readonly sourceKind: "author";
  readonly ok: true;
  readonly source: string;
  readonly frontend: string;
  readonly units: number;
  readonly assets: number;
  readonly modules: number;
  readonly outputCount: number;
  readonly outputs?: readonly {
    readonly name: string;
    readonly type: string;
  }[];
  readonly omittedOutputs?: number;
  readonly details?: {
    readonly modules: readonly string[];
    readonly values: readonly { readonly name: string; readonly type: string }[];
  };
};

export type RunCheckOutput = {
  readonly format: "hypit.cli-check@1";
  readonly sourceKind: "run";
  readonly ok: true;
  readonly run: string;
  readonly author: string;
  readonly frontend: string;
  readonly targetCount: number;
  readonly targets: readonly string[];
  readonly candidates: number;
  readonly satisfactions: number;
  readonly historicalOutputCount?: number;
  readonly steps?: number;
  readonly unresolvedHistoricalOutputs?: readonly {
    readonly candidate: string;
    readonly build: string;
    readonly output: string;
  }[];
  readonly omittedHistoricalOutputs?: number;
};

export type PlanPreflight = {
  readonly ok: boolean;
  readonly capabilityCount: number;
  readonly capabilities?: readonly string[];
  readonly omittedCapabilities?: number;
  readonly diagnosticCount: number;
  readonly diagnostics: readonly CliDiagnostic[];
  readonly omittedDiagnostics?: number;
};

export type PlanProvider = {
  readonly request: string;
  readonly capability: string;
  readonly status: "resolved" | "unresolved" | "unsupported" | "ambiguous";
  readonly endpoint?: string;
  readonly use?: string;
  readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };
  readonly endpoints?: readonly string[];
  readonly rejections?: readonly { readonly endpoint: string; readonly message: string }[];
  readonly binding?: string;
};

export type PlanOutput = {
  readonly format: "hypit.cli-plan@1";
  readonly ok: boolean;
  readonly run: string;
  readonly targetCount: number;
  readonly targets: readonly string[];
  readonly steps?: number;
  readonly requestCount: number;
  readonly requestIssueCount: number;
  readonly producerFailureCount: number;
  /** Complete deterministic Producer failures; errors are never hidden by the detail limit. */
  readonly producerFailures: readonly {
    readonly step: string;
    readonly message: string;
  }[];
  /** Present when a Runtime Profile was selected. */
  readonly providerRequestCount?: number;
  readonly localRequestCount?: number;
  readonly unresolvedRequestCount?: number;
  readonly unsupportedRequestCount?: number;
  readonly choiceCount: number;
  readonly choices?: readonly { readonly output: string; readonly candidate: string }[];
  readonly omittedChoices?: number;
  readonly unreached?: readonly { readonly output: string; readonly operation: string }[];
  readonly omittedUnreached?: number;
  /** Present only when a Runtime Profile was selected; the Endpoint and price page behind each capability. */
  readonly providers?: readonly PlanProvider[];
  /** Every external request the Build will make, in step order, with its parameters when known. */
  readonly needs?: readonly PlanNeed[];
  readonly preflight?: PlanPreflight;
};

/** Output scope is independent of encoding. Limits apply to expanded detail, not demanded work. */
export function createPlanOutput(plan: PlanOutput, options: { readonly verbose: boolean; readonly limit: number }): PlanOutput {
  const { steps, choices = [], unreached = [], preflight, ...summary } = plan;
  const limit = options.limit;
  return {
    ...summary,
    ...(options.verbose ? {
      steps,
      choices: choices.slice(0, limit),
      ...(choices.length <= limit ? {} : { omittedChoices: choices.length - limit }),
      unreached: unreached.slice(0, limit),
      ...(unreached.length <= limit ? {} : { omittedUnreached: unreached.length - limit }),
    } : {}),
    ...(preflight === undefined ? {} : { preflight: {
      ok: preflight.ok,
      capabilityCount: preflight.capabilityCount,
      diagnosticCount: preflight.diagnosticCount,
      diagnostics: preflight.diagnostics,
      ...(options.verbose ? {
        capabilities: preflight.capabilities?.slice(0, limit) ?? [],
        ...((preflight.capabilities?.length ?? 0) <= limit ? {} : {
          omittedCapabilities: preflight.capabilities!.length - limit,
        }),
      } : {}),
    } }),
  };
}

export type PricingEntry = PlanProvider & {
  readonly pricingDocuments?: readonly PricingDocument[];
  readonly pricingError?: string;
};

export type PricingDocument = {
  readonly source: string;
  readonly data: CanonicalValue;
  readonly summary?: string;
};

export type PricingOutput = {
  readonly format: "hypit.cli-pricing@1";
  readonly run: string;
  readonly requestCount: number;
  readonly noChargeRequestCount: number;
  readonly producerFailureCount: number;
  readonly producerFailures: PlanOutput["producerFailures"];
  readonly groups: readonly (Omit<PricingEntry, "request"> & {
    readonly requests: readonly PlanNeed[];
  })[];
};

export type PlanNeed = {
  readonly request: string;
  readonly step: string;
  readonly port: string;
  readonly capability: string;
  readonly endpoint?: string;
  readonly summary?: {
    readonly fields: Readonly<Record<string, string | number | boolean>>;
    readonly references: Readonly<Record<string, number>>;
  };
  readonly pending: readonly {
    readonly input: string;
    readonly record: string;
    readonly sourceStep?: string;
    readonly kind?: "image" | "video" | "audio" | "other";
  }[];
  readonly issue?: string;
};

/**
 * Stable machine-output envelope shared by built-in and contributed commands.
 *
 * The generic CLI keeps its own outputs precise in `OperationalMachineView`, but
 * must not enumerate every application module's payload in a central union.
 */
export type CliMachineView = {
  readonly format: string;
  readonly [field: string]: unknown;
};

export type CliPresentation =
  | {
      readonly kind: "doctor";
      readonly machine: DoctorOutput;
    }
  | {
      readonly kind: "check-author";
      readonly machine: AuthorCheckOutput;
    }
  | {
      readonly kind: "check-run";
      readonly machine: RunCheckOutput;
    }
  | {
      readonly kind: "plan";
      readonly machine: PlanOutput;
    }
  | {
      readonly kind: "pricing";
      readonly machine: PricingOutput;
      /** Optional human display limit, applied after grouping; JSON always contains every group. */
      readonly limit?: number;
    }
  | {
      readonly kind: "operational";
      readonly machine: CliMachineView;
      readonly title: string;
      readonly status?: "success" | "warning" | "error" | "info";
      readonly facts?: readonly (readonly [string, string])[];
      readonly lines?: readonly string[];
    };

type Palette = {
  readonly accent: (value: string) => string;
  readonly success: (value: string) => string;
  readonly warning: (value: string) => string;
  readonly error: (value: string) => string;
  readonly dim: (value: string) => string;
  readonly strong: (value: string) => string;
};

const ansi = (open: number, close: number) => (enabled: boolean) => (value: string): string =>
  enabled ? `\u001b[${open}m${value}\u001b[${close}m` : value;

function palette(enabled: boolean): Palette {
  return {
    accent: ansi(36, 39)(enabled),
    success: ansi(32, 39)(enabled),
    warning: ansi(33, 39)(enabled),
    error: ansi(31, 39)(enabled),
    dim: ansi(2, 22)(enabled),
    strong: ansi(1, 22)(enabled),
  };
}

function colorEnabled(io: CliIo, mode: CliColorMode): boolean {
  if (mode === "never") return false;
  if (mode === "always") return true;
  return io.terminal?.isTTY === true && io.terminal.color;
}

function glyph(io: CliIo, unicode: string, ascii: string): string {
  return io.terminal?.unicode === false ? ascii : unicode;
}

function shortPath(path: string): string {
  const absolute = resolve(path);
  const local = relative(process.cwd(), absolute);
  return local.length > 0 && local !== ".." && !local.startsWith(`..${sep}`) ? local : absolute;
}

function facts(rows: readonly (readonly [string, string])[], colors: Palette): string[] {
  const width = Math.max(...rows.map(([name]) => name.length), 0);
  return rows.map(([name, value]) => `  ${colors.dim(name.padEnd(width))}  ${value}`);
}

function heading(status: "success" | "warning" | "error" | "info", text: string, io: CliIo, colors: Palette): string {
  const mark = status === "success"
    ? colors.success(glyph(io, "✓", "+"))
    : status === "warning"
      ? colors.warning("!")
      : status === "error"
        ? colors.error(glyph(io, "×", "x"))
        : colors.accent(glyph(io, "•", "i"));
  return `${mark} ${colors.strong(text)}`;
}

function renderDoctor(view: Extract<CliPresentation, { kind: "doctor" }>, io: CliIo, colors: Palette): string {
  const lines = [colors.accent(colors.strong("Hypit Doctor")), ""];
  lines.push(...facts([
    ["Project", shortPath(view.machine.project)],
    ["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 {
    for (const item of view.machine.diagnostics) {
      const status = item.severity === "error" ? "error" : item.severity === "warning" ? "warning" : "info";
      lines.push(heading(status, item.code, io, colors));
      lines.push(`  ${item.message}`);
      if (item.subject !== undefined) lines.push(`  ${colors.dim("Subject")}  ${item.subject}`);
    }
  }
  if ((view.machine.omittedDiagnostics ?? 0) > 0) {
    lines.push(`  ${colors.dim(`${view.machine.omittedDiagnostics} more diagnostics · use --limit <count>`)}`);
  }
  lines.push("");
  const summary = `${view.machine.diagnosticCount} diagnostic${view.machine.diagnosticCount === 1 ? "" : "s"}`;
  lines.push(view.machine.ok ? colors.success(summary) : colors.error(summary));
  return `${lines.join("\n")}\n`;
}

function renderAuthorCheck(
  view: Extract<CliPresentation, { kind: "check-author" }>,
  io: CliIo,
  colors: Palette,
  verbose: boolean,
): string {
  const lines = [heading("success", "Source is valid", io, colors), ""];
  const readable = view.machine.outputs ?? [];
  lines.push(...facts([
    ["Source", shortPath(view.machine.source)],
    ["Outputs", String(view.machine.outputCount)],
    ...(verbose ? [
      ["Frontend", view.machine.frontend] as const,
      ["Modules", String(view.machine.modules)] as const,
      ["Units", String(view.machine.units)] as const,
      ["Assets", String(view.machine.assets)] as const,
      ...(view.machine.details === undefined
        ? [] : [["Values", String(view.machine.details.values.length)] as const]),
    ] : []),
  ], colors));
  if (verbose && readable.length > 0) {
    lines.push("", colors.strong("Outputs"));
    const ordered = [...readable].sort((left, right) => left.name.localeCompare(right.name));
    const width = Math.max(...ordered.map((item) => item.name.length));
    for (const item of ordered) {
      lines.push(`  ${colors.accent(item.name.padEnd(width))}  ${item.type}`);
    }
    if ((view.machine.omittedOutputs ?? 0) > 0) {
      lines.push(`  ${colors.dim(`${view.machine.omittedOutputs} more · use --limit <count>`)}`);
    }
  }
  if (verbose && view.machine.details !== undefined && view.machine.details.values.length > 0) {
    lines.push("", colors.strong("Values"));
    for (const item of view.machine.details.values) {
      lines.push(`  ${colors.accent(item.name)}  ${item.type}`);
    }
  }
  return `${lines.join("\n")}\n`;
}

function renderRunCheck(
  view: Extract<CliPresentation, { kind: "check-run" }>,
  io: CliIo,
  colors: Palette,
  verbose: boolean,
): string {
  const lines = [heading("success", "Run source is valid", io, colors), ""];
  const reuse = view.machine.historicalOutputCount ?? 0;
  const targetSummary = view.machine.targets.length === 0
    ? String(view.machine.targetCount)
    : view.machine.targets.join(", ")
      + (view.machine.targets.length < view.machine.targetCount
        ? ` (+${view.machine.targetCount - view.machine.targets.length})`
        : "");
  lines.push(...facts([
    ["Run", shortPath(view.machine.run)],
    ["Targets", targetSummary],
    ...(reuse === 0 ? [] : [["Reuse", `${reuse} historical Output${reuse === 1 ? "" : "s"}`] as const]),
    ...(verbose ? [
      ["Author", shortPath(view.machine.author)] as const,
      ["Frontend", view.machine.frontend] as const,
      ["Candidates", String(view.machine.candidates)] as const,
      ["Satisfactions", String(view.machine.satisfactions)] as const,
      ...(view.machine.steps === undefined ? [] : [["Steps", String(view.machine.steps)] as const]),
    ] : []),
  ], colors));
  const unresolved = view.machine.unresolvedHistoricalOutputs ?? [];
  if (verbose && unresolved.length > 0) {
    lines.push("", colors.strong("Historical reuse"));
    for (const item of unresolved) lines.push(`  ${item.candidate} ← ${item.build}/${item.output}`);
    if ((view.machine.omittedHistoricalOutputs ?? 0) > 0) {
      lines.push(`  ${colors.dim(`${view.machine.omittedHistoricalOutputs} more · use --limit <count>`)}`);
    }
  }
  return `${lines.join("\n")}\n`;
}

/** `@hypit/seedance@1#seedance-2-mini` → `@hypit/seedance#seedance-2-mini`; the module version is verbose detail. */
function capabilityLabel(name: string): string {
  return name.replace(/@[^@#]+#/u, "#");
}

/** The author-facing part of a step id: the component and operation, without the Source path. */
function stepLabel(step: string): string {
  let decoded = step;
  try { decoded = decodeURIComponent(step); } catch { /* keep the raw id */ }
  const marker = "::component::";
  const at = decoded.lastIndexOf(marker);
  return at === -1 ? decoded : decoded.slice(at + marker.length);
}

const MEASURE = /^(\d+) (words|chars)$/u;

/** Text lengths are ranged across a group rather than splitting otherwise identical requests. */
function groupKey(need: PlanNeed): string {
  const pending = need.pending.map((item) => item.kind ?? "value").sort().join(",");
  if (need.summary === undefined) return `?${pending}|${need.issue ?? ""}`;
  const fields = Object.entries(need.summary.fields)
    .map(([name, value]) => {
      const measured = typeof value === "string" ? MEASURE.exec(value) : null;
      return measured === null ? `${name}=${String(value)}` : `${name}=<${measured[2]}>`;
    });
  const references = Object.entries(need.summary.references).map(([kind, count]) => `${kind}=${count}`);
  return [...fields, "|", ...references, "|", pending, "|", need.issue ?? ""].join(" ");
}

function needSummaryText(needs: readonly PlanNeed[]): string {
  const first = needs[0]!;
  const parts: string[] = [];
  for (const [name, value] of Object.entries(first.summary?.fields ?? {})) {
    const measured = typeof value === "string" ? MEASURE.exec(value) : null;
    if (measured !== null) {
      const unit = measured[2]!;
      const counts = needs.map((need) => Number(MEASURE.exec(String(need.summary?.fields[name] ?? `0 ${unit}`))?.[1] ?? 0));
      const low = Math.min(...counts);
      const high = Math.max(...counts);
      parts.push(`${name} ${low === high ? low : `${low}–${high}`} ${unit}`);
    } else if (typeof value === "boolean") {
      parts.push(value ? name : `no ${name}`);
    } else {
      parts.push(`${name} ${value}`);
    }
  }
  const references = Object.entries(first.summary?.references ?? {}).sort(([left], [right]) => left.localeCompare(right))
    .map(([kind, count]) => `${count} ${kind}`);
  if (references.length > 0) parts.push(`${references.join(" + ")} reference${references.length === 1 && references[0]!.startsWith("1 ") ? "" : "s"}`);
  const pendingCount = first.pending.length;
  if (pendingCount > 0) parts.push(`${pendingCount === 1 ? "input" : `${pendingCount} inputs`} produced during Build`);
  if (first.issue !== undefined) parts.push(`could not inspect: ${first.issue}`);
  return parts.length === 0 ? "request summary unavailable" : parts.join(" · ");
}

/** One line per distinct request shape, counted; the step names when only one request has that shape. */
function groupedNeedLines(needs: readonly PlanNeed[], colors: Palette, verbose: boolean): string[] {
  const groups = new Map<string, PlanNeed[]>();
  for (const need of needs) {
    const key = groupKey(need);
    groups.set(key, [...(groups.get(key) ?? []), need]);
  }
  return [...groups.values()].map((group) => {
    const who = group.length === 1 || verbose ? colors.dim(group.map((need) => stepLabel(need.step)).join(", ")) : "";
    const count = `×${group.length}`.padStart(4);
    return `    ${colors.dim(count)}  ${needSummaryText(group)}${who.length === 0 ? "" : `  ${who}`}`;
  });
}

function providerGroupKey(provider: PlanProvider): string {
  return JSON.stringify({
    capability: provider.capability,
    status: provider.status,
    endpoint: provider.endpoint,
    use: provider.use,
    pricing: provider.pricing,
    endpoints: provider.endpoints,
    rejections: provider.rejections,
    binding: provider.binding,
  });
}

function providerRejectionText(provider: Pick<PlanProvider, "rejections">, verbose: boolean): string {
  const rejections = provider.rejections ?? [];
  if (rejections.length === 0) return "no configured Endpoint accepts this request";
  const shown = verbose ? rejections : rejections.slice(0, 1);
  return shown.map((rejection) => `${rejection.endpoint}: ${rejection.message}`).join("; ")
    + (shown.length === rejections.length ? "" : ` · ${rejections.length - shown.length} more Endpoint rejection${rejections.length - shown.length === 1 ? "" : "s"}`);
}

function renderPlan(
  view: Extract<CliPresentation, { kind: "plan" }>,
  io: CliIo,
  colors: Palette,
  verbose: boolean,
): string {
  const lines = [heading(view.machine.ok ? "success" : "error",
    view.machine.ok ? "Build plan is valid" : "Build plan needs attention", io, colors), ""];
  const targetSummary = view.machine.targets.length === 0
    ? String(view.machine.targetCount)
    : view.machine.targets.join(", ")
      + (view.machine.targets.length < view.machine.targetCount
        ? ` (+${view.machine.targetCount - view.machine.targets.length})`
        : "");
  lines.push(...facts([
    ["Run", shortPath(view.machine.run)],
    ["Targets", targetSummary],
    ["Requests", String(view.machine.requestCount)],
    ...(view.machine.choiceCount === 0 ? [] : [["Run choices", String(view.machine.choiceCount)] as const]),
    ...(view.machine.requestIssueCount === 0 ? [] : [["Request issues", String(view.machine.requestIssueCount)] as const]),
    ...(view.machine.producerFailureCount === 0 ? [] : [["Producer failures", String(view.machine.producerFailureCount)] as const]),
    ...((view.machine.providerRequestCount ?? 0) === 0 ? [] : [["Provider requests", String(view.machine.providerRequestCount)] as const]),
    ...((view.machine.localRequestCount ?? 0) === 0 ? [] : [["Local requests", String(view.machine.localRequestCount)] as const]),
    ...((view.machine.unsupportedRequestCount ?? 0) === 0 ? [] : [["Unsupported", String(view.machine.unsupportedRequestCount)] as const]),
    ...((view.machine.unresolvedRequestCount ?? 0) === 0 ? [] : [["Unresolved", String(view.machine.unresolvedRequestCount)] as const]),
    ...(view.machine.preflight === undefined ? [] : [[
      "Preflight", view.machine.preflight.ok ? "ready" : "needs attention",
    ] as const]),
    ...(!verbose || view.machine.steps === undefined ? [] : [["Steps", String(view.machine.steps)] as const]),
  ], colors));
  if (view.machine.producerFailures.length > 0) {
    lines.push("", colors.strong("Producer failures"));
    for (const failure of view.machine.producerFailures) {
      lines.push(`  ${colors.error(glyph(io, "×", "x"))} ${colors.accent(stepLabel(failure.step))}: ${failure.message}`);
    }
  }
  if (view.machine.providers !== undefined) {
    if (view.machine.providers.length > 0) lines.push("", colors.strong("Providers and price pages"));
    const groups = new Map<string, PlanProvider[]>();
    for (const provider of view.machine.providers) {
      const key = providerGroupKey(provider);
      groups.set(key, [...(groups.get(key) ?? []), provider]);
    }
    for (const group of groups.values()) {
      const item = group[0]!;
      const requestIssue = (view.machine.needs ?? [])
        .find((need) => need.request === item.request)?.issue;
      const where = requestIssue !== undefined
        ? colors.error("request is not completely described before Build")
        : item.status === "resolved"
        ? `${item.endpoint ?? ""} ${colors.dim(`(${item.use ?? "?"})${item.binding === undefined ? "" : ", bound in the Profile"}`)}`
        : item.status === "ambiguous"
          ? colors.warning(`${(item.endpoints ?? []).join(", ")} all offer it; add "bindings": { "${item.capability}": "<instance>" } to the Profile`)
          : item.status === "unsupported"
            ? colors.error(providerRejectionText(item, verbose))
          : item.binding === undefined
            ? colors.error("no selected Endpoint accepts this request")
            : colors.error(`bound to ${item.binding}, which does not offer it`);
      const price = item.pricing === undefined
        ? (item.status === "resolved" ? colors.warning("price source unknown") : undefined)
        : item.pricing.kind === "local"
          ? colors.dim("local, no Provider charge")
          : item.pricing.url;
      lines.push(`  ${colors.accent(verbose ? item.capability : capabilityLabel(item.capability))}`);
      lines.push(`    ${where}${price === undefined ? "" : `  ·  ${price}`}`);
      const requests = new Set(group.map((provider) => provider.request));
      lines.push(...groupedNeedLines((view.machine.needs ?? []).filter((need) => requests.has(need.request)), colors, verbose));
    }
  } else if (view.machine.requestCount > 0) {
    const byCapability = new Map<string, PlanNeed[]>();
    for (const need of view.machine.needs ?? []) {
      byCapability.set(need.capability, [...(byCapability.get(need.capability) ?? []), need]);
    }
    if (byCapability.size > 0) lines.push("", colors.strong("Requests"));
    for (const [capability, needs] of byCapability) {
      lines.push(`  ${colors.accent(verbose ? capability : capabilityLabel(capability))}`);
      lines.push(...groupedNeedLines(needs, colors, verbose));
    }
    lines.push("", colors.dim("Pass --runtime <profile> to see the Endpoint and price page behind each request."));
  }
  const unreached = view.machine.unreached ?? [];
  if (verbose && unreached.length > 0) {
    lines.push("", colors.strong("Declared but not reached"));
    const width = Math.max(...unreached.map((item) => item.output.length));
    for (const item of unreached) {
      lines.push(`  ${colors.accent(item.output.padEnd(width))}  ${colors.dim(item.operation)}`);
    }
    if ((view.machine.omittedUnreached ?? 0) > 0) {
      lines.push(`  ${colors.dim(`${view.machine.omittedUnreached} more · use --limit <count>`)}`);
    }
  }
  if (view.machine.preflight !== undefined
    && (view.machine.preflight.diagnostics.length > 0
      || (verbose && (view.machine.preflight.capabilities?.length ?? 0) > 0))) {
    lines.push("", colors.strong("Runtime preflight"));
    if (verbose) for (const capability of view.machine.preflight.capabilities ?? []) lines.push(`  ${colors.accent(capability)}`);
    if (verbose && (view.machine.preflight.omittedCapabilities ?? 0) > 0) {
      lines.push(`  ${colors.dim(`${view.machine.preflight.omittedCapabilities} more capabilities · use --limit <count>`)}`);
    }
    if (verbose && view.machine.preflight.diagnostics.length === 0) {
      lines.push(`  ${colors.success(glyph(io, "✓", "+"))} required deployment slice is ready`);
    } else {
      for (const item of view.machine.preflight.diagnostics) {
        const mark = item.severity === "error" ? colors.error(glyph(io, "×", "x")) : colors.warning("!");
        lines.push(`  ${mark} ${item.code}: ${item.message}`);
      }
    }
    if (verbose) {
      const capabilityCount = view.machine.preflight.capabilityCount;
      lines.push(`  ${colors.dim(`${capabilityCount} demanded Endpoint ${capabilityCount === 1 ? "capability" : "capabilities"} checked.`)}`);
    }
  }
  if (verbose && (view.machine.choices?.length ?? 0) > 0) {
    lines.push("", colors.strong("Run choices"));
    for (const selection of view.machine.choices ?? []) {
      const status = colors.success(glyph(io, "✓", "+"));
      lines.push(`  ${status} ${colors.accent(selection.output)} ← ${selection.candidate}`);
    }
    if ((view.machine.omittedChoices ?? 0) > 0) {
      lines.push(`  ${colors.dim(`${view.machine.omittedChoices} more choices · use --limit <count>`)}`);
    }
  }
  return `${lines.join("\n")}\n`;
}

function pricingDocumentLines(document: PricingDocument, colors: Palette, verbose: boolean): string[] {
  const rendered = !verbose && document.summary !== undefined
    ? document.summary : JSON.stringify(document.data, undefined, 2);
  return [
    `      ${colors.dim("Source")}  ${document.source}`,
    ...rendered.split("\n").map((line) => `      ${line}`),
  ];
}

/** Factor shared request parameters without losing the combinations of the remaining parameters. */
function pricingNeedLines(needs: readonly PlanNeed[], colors: Palette, verbose: boolean): string[] {
  if (verbose || needs.length < 2) return groupedNeedLines(needs, colors, verbose);
  const first = needs[0]!;
  const sharedFields = Object.fromEntries(Object.entries(first.summary?.fields ?? {}).filter(([key, value]) => {
    const measured = typeof value === "string" ? MEASURE.exec(value) : null;
    return needs.every((need) => {
      const other = need.summary?.fields[key];
      return other === value || (measured !== null && typeof other === "string"
        && MEASURE.exec(other)?.[2] === measured[2]);
    });
  }));
  const sharedReferences = needs.every((need) =>
    JSON.stringify(need.summary?.references ?? {}) === JSON.stringify(first.summary?.references ?? {}));
  const sharedPending = needs.every((need) =>
    JSON.stringify(need.pending.map((input) => input.kind).sort())
      === JSON.stringify(first.pending.map((input) => input.kind).sort()));
  const common = needs.map(({ issue: _issue, ...need }) => ({
    ...need,
    summary: {
      fields: Object.fromEntries(Object.keys(sharedFields).map((key) => [key, need.summary!.fields[key]!])),
      references: sharedReferences ? need.summary?.references ?? {} : {},
    },
    pending: sharedPending ? need.pending : [],
  }));
  const varying = needs.map((need) => ({
    ...need,
    summary: {
      fields: Object.fromEntries(Object.entries(need.summary?.fields ?? {}).filter(([key]) => !Object.hasOwn(sharedFields, key))),
      references: sharedReferences ? {} : need.summary?.references ?? {},
    },
    pending: sharedPending ? [] : need.pending,
  }));
  const hasParameters = (need: PlanNeed) => Object.keys(need.summary?.fields ?? {}).length > 0
    || Object.keys(need.summary?.references ?? {}).length > 0 || need.pending.length > 0 || need.issue !== undefined;
  return [
    ...(common.some(hasParameters) ? [`    ${needSummaryText(common)}`] : []),
    ...(varying.some(hasParameters) ? groupedNeedLines(varying, colors, false) : []),
  ];
}

/** Group Provider facts without interpreting their documents or inferring charges from model names. */
export function createPricingOutput(
  run: string,
  entries: readonly PricingEntry[],
  needs: readonly PlanNeed[],
  includeNoCharge = false,
  producerFailures: PricingOutput["producerFailures"] = [],
): PricingOutput {
  const needsByRequest = new Map(needs.map((need) => [need.request, need]));
  const groups = new Map<string, Omit<PricingEntry, "request"> & { requests: PlanNeed[] }>();
  let noChargeRequestCount = 0;
  for (const { request, ...entry } of entries) {
    if (entry.status === "resolved" && entry.pricing?.kind === "local") {
      noChargeRequestCount++;
      if (!includeNoCharge) continue;
    }
    const key = JSON.stringify(entry);
    let group = groups.get(key);
    if (group === undefined) {
      group = { ...entry, requests: [] };
      groups.set(key, group);
    }
    const need = needsByRequest.get(request);
    if (need !== undefined) group.requests.push(need);
  }
  return {
    format: "hypit.cli-pricing@1", run, requestCount: entries.length,
    noChargeRequestCount, groups: [...groups.values()],
    producerFailureCount: producerFailures.length, producerFailures,
  };
}

function renderPricing(
  view: Extract<CliPresentation, { kind: "pricing" }>,
  io: CliIo,
  colors: Palette,
  verbose: boolean,
): string {
  const machine = view.machine;
  const lines = [heading("info", "Provider pricing information", io, colors), ""];
  lines.push(...facts([
    ["Run", shortPath(machine.run)],
    ["Requests", String(machine.requestCount)],
    ["No Provider charge", `${machine.noChargeRequestCount} requests`],
    ...(machine.producerFailureCount === 0 ? [] : [["Producer failures", String(machine.producerFailureCount)] as const]),
  ], colors));
  if (machine.producerFailures.length > 0) {
    lines.push("", colors.strong("Producer failures"));
    for (const failure of machine.producerFailures) {
      lines.push(`  ${colors.error(glyph(io, "×", "x"))} ${colors.accent(stepLabel(failure.step))}: ${failure.message}`);
    }
  }
  if (machine.noChargeRequestCount > 0 && !verbose) {
    lines.push(`  ${colors.dim("No-charge request details: --verbose")}`);
  }
  if (machine.groups.length > 0) lines.push("", colors.strong("Requests and Provider rates"));
  const shown = view.limit === undefined ? machine.groups : machine.groups.slice(0, view.limit);
  for (const item of shown) {
    const selected = item.status === "resolved"
      ? `${item.endpoint ?? ""} ${colors.dim(`(${item.use ?? "?"})`)}`
      : item.status === "ambiguous"
        ? colors.error(`several Endpoints: ${(item.endpoints ?? []).join(", ")}`)
        : item.status === "unsupported"
          ? colors.error(providerRejectionText(item, verbose))
        : colors.error("no selected Endpoint accepts this request");
    lines.push(`  ${colors.accent(verbose ? item.capability : capabilityLabel(item.capability))}`);
    lines.push(`    ${selected} · ${item.requests.length} request${item.requests.length === 1 ? "" : "s"}`);
    lines.push(...pricingNeedLines(item.requests, colors, verbose));
    if (item.pricing?.kind === "local") {
      lines.push(`      ${colors.dim("local, no Provider charge")}`);
    }
    for (const document of item.pricingDocuments ?? []) {
      lines.push(...pricingDocumentLines(document, colors, verbose));
    }
    if (item.pricingError !== undefined) {
      lines.push(`      ${colors.warning(`Could not read Provider pricing: ${item.pricingError}`)}`);
    }
    if ((item.pricingDocuments?.length ?? 0) === 0 && item.pricing?.kind === "page") {
      lines.push(`      ${colors.dim("Pricing page")}  ${item.pricing.url}`);
    } else if ((item.pricingDocuments?.length ?? 0) === 0 && item.pricing === undefined
      && item.status === "resolved" && item.pricingError === undefined) {
      lines.push(`      ${colors.warning("Pricing unknown: no pricing source declared by this Provider")}`);
    }
    lines.push("");
  }
  if (shown.length < machine.groups.length) {
    lines.push(`  ${colors.dim(`${machine.groups.length - shown.length} more groups · omit --limit or use --json for all groups`)}`);
  }
  return `${lines.join("\n")}\n`;
}

function renderOperational(
  view: Extract<CliPresentation, { kind: "operational" }>,
  io: CliIo,
  colors: Palette,
): string {
  const lines = [heading(view.status ?? "info", view.title, io, colors)];
  if ((view.facts?.length ?? 0) > 0) lines.push("", ...facts(view.facts!, colors));
  if ((view.lines?.length ?? 0) > 0) lines.push("", ...view.lines!);
  return `${lines.join("\n")}\n`;
}

export function writeCliOutput(
  io: CliIo,
  options: CliOutputOptions,
  presentation: CliPresentation,
): void {
  if (options.json) {
    io.write(`${JSON.stringify(presentation.machine, null, options.jsonl === true ? 0 : 2)}\n`);
    return;
  }
  const colors = palette(colorEnabled(io, options.color));
  const output = presentation.kind === "doctor"
    ? renderDoctor(presentation, io, colors)
    : presentation.kind === "check-author"
      ? renderAuthorCheck(presentation, io, colors, options.verbose)
      : presentation.kind === "check-run"
        ? renderRunCheck(presentation, io, colors, options.verbose)
        : presentation.kind === "plan"
          ? renderPlan(presentation, io, colors, options.verbose)
          : presentation.kind === "pricing"
            ? renderPricing(presentation, io, colors, options.verbose)
            : renderOperational(presentation, io, colors);
  io.write(output);
}

function commandHelp(topic: string, colors: Palette): readonly string[] | undefined {
  const common = [
    "",
    colors.strong("Output"),
    "  --json                     stable machine view",
    "  --verbose                  add bounded operational detail",
    "  --color auto|always|never  control ANSI color",
    "  --debug                    include internal trace frames on failure",
    "",
  ];
  const topics: Readonly<Record<string, readonly string[]>> = {
    check: [
      colors.accent(colors.strong("hypit check")),
      colors.dim("Validate one self-described Author Source or Run Source without executing it."),
      "",
      "  hypit check <source> [--project <workspace>] [--asset-root <directory>]",
      "  --verbose lists exported names/types and historical references.",
    ],
    doctor: [
      colors.accent(colors.strong("hypit doctor")),
      colors.dim("Diagnose project Results and, when selected or supplied, one Runtime Profile."),
      "",
      "  hypit doctor [--runtime <profile>] [--project <project>] [--endpoint <instance>]",
      "  A positional Profile is also accepted in place of --runtime.",
      "  Repeat --endpoint <instance> to limit the operation to chosen services; omission covers the Profile.",
      "  Without a Runtime Profile, checks only the project's selected Result Store.",
    ],
    plan: [
      colors.accent(colors.strong("hypit plan")),
      colors.dim("Show targets, demanded requests and their readiness without executing them."),
      "",
      "  hypit plan <run-source> [--runtime <profile>] [--project <workspace>] [--asset-root <directory>]",
      "",
      "With --runtime, plan also preflights only the demanded deployment slice and names the Provider",
      "and price page behind each external request.",
      "--verbose expands Run choices and unreached declarations. --limit bounds that detail,",
      "while all demanded requests and diagnostics remain visible in both text and JSON.",
      "Planning never starts external work.",
    ],
    pricing: [
      colors.accent(colors.strong("hypit pricing")),
      colors.dim("Read current pricing material from the selected Providers for the requests in one Run."),
      "",
      "  hypit pricing <run-source> [--runtime <profile>] [--project <workspace>] [--asset-root <directory>]",
      "",
      "Pricing is an explicit read-only network operation. It starts no Build and submits no generation.",
      "Matching requests share their parameters and Provider rates, with source URLs.",
      "Provider summaries appear when available; --verbose and --json retain the full documents.",
      "Explicit no-charge requests are summarized; --verbose includes their details.",
      "All groups are shown by default. --limit <count> limits human groups; --json always includes all groups.",
      "Hypit calculates no total.",
    ],
    build: [
      colors.accent(colors.strong("hypit build")),
      colors.dim("Submit one durable Build and ensure its selected Runtime Worker is available."),
      "",
      "  hypit build <run-source> [--title <text>] [--runtime <profile>] [--project <workspace>] [--asset-root <directory>] [--follow]",
      "",
      "  --title <text>            give this Result a human-facing title",
      "  --follow                   observe the Build; the Worker still owns execution",
      "  --max-wait-ms <ms>         bound startup or follow waiting",
    ],
    activity: [
      colors.accent(colors.strong("hypit activity")),
      colors.dim("Inspect active Builds and Provider pool capacity."),
      "",
      "  hypit activity [--project <project>] [--runtime <profile>] [--watch]",
      "  hypit activity [--project <project>] [--runtime <profile>] --watch --jsonl",
    ],
    builds: [
      colors.accent(colors.strong("hypit builds")),
      colors.dim("List project-owned Build Results without opening a Runtime."),
      "",
      "  hypit builds [--project <project>] [--limit <count>] [--before <build-id>]",
    ],
    logs: [
      colors.accent(colors.strong("hypit logs")),
      colors.dim("Read Build execution evidence; finished logs need only the project Result Repository."),
      "",
      "  hypit logs <build-id> [--project <project>] [--runtime <profile>] [--lines <count>]",
      "  --lines <count>           show the last N records (default 50)",
    ],
    status: [
      colors.accent(colors.strong("hypit status")),
      colors.dim("Show one Build now, or keep watching it without owning execution."),
      "",
      "  hypit status <build-id> [--project <project>] [--runtime <profile>] [--watch]",
      "  --watch                   observe until a Result outcome or operator attention",
      "  --max-wait-ms <ms>        stop watching after a bounded wait",
    ],
    inspect: [
      colors.accent(colors.strong("hypit inspect")),
      colors.dim("Inspect one project-owned Build Result and its public Outputs."),
      "",
      "  hypit inspect <build-id> [--output <name>] [--limit <count>] [--project <project>]",
      "  Defaults to targets and highlighted Outputs. --verbose expands other available Outputs.",
      "  --output selects one exact name; --limit bounds expanded lists.",
    ],
    get: [
      colors.accent(colors.strong("hypit get")),
      colors.dim("Export one exact named Build Output to an explicit local destination."),
      "",
      "  hypit get <build-id> --output <name> --to <path> [--project <project>]",
      "",
      "Scalar and Resource Outputs become files. A Composite Output becomes a directory",
      "containing value.json and every Resource referenced by that value.",
    ],
    history: [
      colors.accent(colors.strong("hypit history")),
      colors.dim("Find one named Output across project-owned Build Results."),
      "",
      "  hypit history <output-name> [--project <project>] [--source <author-source>] [--limit <count>] [--before <build-id>]",
    ],
    cancel: [
      colors.accent(colors.strong("hypit cancel")),
      colors.dim("Stop one Build and request cancellation of submitted work when supported."),
      "",
      "  hypit cancel <build-id> [--project <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> [--project <project>] [--runtime <profile>]",
      "  hypit result discard <build-id> [--project <project>] [--runtime <profile>]",
      "  hypit result edit <build-id> [--project <project>] [--title <text>] [--note <text>]",
      "                           [--highlight <output> ...]",
      "  --clear-title            remove the Result's human title",
      "  --clear-note             remove its note",
      "  --clear-highlights       remove all highlighted Outputs",
    ],
    auth: [
      colors.accent(colors.strong("hypit auth")),
      colors.dim("Manage credentials required by one declared Endpoint instance."),
      "",
      "  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 --project <project> to use that project's selection.",
      "  status shows credential presence and the Provider's declared browser login, if any.",
      "  login opens that browser flow or securely prompts for the secret; --from imports a secret instead.",
      "  Configure the service's Endpoint first. Storing a key does not install a Provider or select bindings.",
    ],
  };
  const selected = topics[topic];
  return selected === undefined ? undefined : [...selected, ...common];
}

export function writeCliHelp(io: CliIo, topic?: string): void {
  const colors = palette(io.terminal?.isTTY === true && io.terminal.color);
  const row = (command: string, description: string, width = 30): string =>
    `  ${command}${" ".repeat(Math.max(2, width - command.length))}${description}`;
  if (topic !== undefined) {
    const selected = commandHelp(topic, colors);
    if (selected !== undefined) {
      io.write(`${selected.join("\n")}\n`);
      return;
    }
    throw new CliUsageError(`Unknown help topic ${JSON.stringify(topic)}`, "hypit help");
  }
  io.write([
    colors.accent(colors.strong("Hypit")),
    "",
    colors.strong("Authoring"),
    row("check <source>", "verify one self-described Author or Run source"),
    row("plan <run-source>", "show selected work without executing"),
    row("pricing <run-source>", "read selected Providers' current pricing material"),
    row("build <run-source>", "submit a Build; --follow observes it"),
    "",
    colors.strong("Results"),
    row("builds", "list Results newest first"),
    row("history <output>", "find one named Output across Builds"),
    row("logs <build-id> [--lines <count>]", "read saved Build execution phases and diagnostics"),
    row("status <build-id> [--watch]", "show current work and Result facts"),
    row("inspect <build-id>", "inspect one Result"),
    row("get <build-id> --output <name> --to <path>", "export one Build Output"),
    row("result edit <build-id>", "title, annotate or highlight a Result"),
    "",
    colors.strong("Runtime"),
    row("doctor [profile]", "diagnose selected external setup"),
    row("activity [--watch]", "show active Builds and their current phases"),
    row("cancel <build-id>", "withdraw one active Build"),
    row("auth status|login|logout", "manage Endpoint credentials"),
    "",
    colors.strong("Installation"),
    row("version [--check]", "show this installed Hypit Distribution"),
    row("cli status|use|remove", "manage explicit project CLI contributions"),
    "",
    colors.strong("Output"),
    row("--json", "stable machine view"),
    row("--verbose", "add bounded operational detail"),
    row("--color auto|always|never", "control ANSI color"),
    row("--debug", "include internal trace frames on failure"),
    "",
  ].join("\n"));
}

export function renderCliError(error: unknown, options: {
  readonly json: boolean;
  readonly color: boolean;
  readonly unicode: boolean;
  readonly debug: boolean;
}): string {
  const source = error instanceof Error ? error : new Error(String(error));
  const trace = source.stack?.split("\n").slice(1).join("\n").trim();
  const candidateCode = (source as Error & { readonly code?: unknown }).code;
  const code = typeof candidateCode === "string" && candidateCode.trim().length > 0
    ? candidateCode
    : "CLI_ERROR";
  if (options.json) {
    return `${JSON.stringify({
      format: "hypit.cli-error@1",
      ok: false,
      error: {
        code,
        message: source.message,
        ...(source instanceof CliUsageError ? { help: source.help } : {}),
        ...(options.debug && trace !== undefined && trace.length > 0 ? { trace } : {}),
      },
    }, null, 2)}\n`;
  }
  const colors = palette(options.color);
  const mark = options.unicode ? "×" : "x";
  const lines = [
    `${colors.error(mark)} ${colors.strong("Command failed")}`,
    "",
    `  ${colors.error(code)}`,
    ...source.message.split("\n").map((line) => `  ${line}`),
  ];
  if (options.debug && trace !== undefined && trace.length > 0) {
    lines.push("", colors.dim(trace));
  } else if (source instanceof CliUsageError) {
    lines.push("", `Usage    ${source.help}`);
  } else {
    lines.push("", colors.dim("Run with --debug to include the internal stack trace."));
  }
  return `${lines.join("\n")}\n`;
}