@orchestraworks/cli 0.5.1 → 0.5.3

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.5.1      # this exact release
+npm install @orchestraworks/cli@0.5.3      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/dist/cli/api/compute-provider-check.d.ts

@@ -0,0 +1,29 @@
+import type { FetchAPI } from "@orchestraworks/client";
+import { type CliIo } from "../core/output.js";
+import type { Profile } from "../core/profile.js";
+export interface ComputeProviderCheckOptions {
+    output?: string;
+    profile?: string;
+    baseUrl?: string;
+    org?: string;
+}
+/** Every seam a test replaces; production leaves them all undefined. */
+export interface ComputeProviderCheckDeps {
+    env?: NodeJS.ProcessEnv;
+    io?: CliIo;
+    fetchApi?: FetchAPI;
+    loadProfile?: (name?: string) => Profile | undefined;
+    /** Milliseconds. */
+    now?: () => number;
+    onExitCode?: (code: number) => void;
+}
+export declare class ComputeProviderCheckUsageError extends Error {
+    constructor(message: string);
+}
+/** Named, so the shared mapper prints its message as the error line. */
+export declare class ComputeProviderCheckFailed extends Error {
+    constructor(message: string);
+}
+export declare function computeProviderCheckCommand(id: string, options?: ComputeProviderCheckOptions, deps?: ComputeProviderCheckDeps): Promise<void>;
+/** The two largest units of a duration in milliseconds; a negative one, from clock skew, reads as zero. */
+export declare function formatAge(ms: number): string;

package/dist/cli/api/compute-provider-check.js

@@ -0,0 +1,207 @@
+// One read of a compute provider, shown so a person installing a Launcher can see why it does not work. It
+// adds no wire shape of its own: it dispatches through the same generated row `orchestra compute-providers
+// get` uses, prints that read, and judges it. The exit code is the judgment, so a script can wait on it:
+// 0 when the Launcher polls, its protocol was accepted and every target serves; 1 otherwise, with one line
+// naming each failure on stderr while stdout keeps the read.
+import { findCommand } from "../../generated/cli-commands.js";
+import { CLI_DISPATCH } from "../../generated/cli-dispatch.js";
+import { authFlagsFrom, platformTargetFrom, resolveAuthWithWarnings } from "../core/auth.js";
+import { runCommand, settleExitCode } from "../core/errors.js";
+import { defaultIo, parseOutputMode, printRedactionNotes, printResponse, printWarnings, writeLines, } from "../core/output.js";
+import { createPlatformApis } from "../core/platform-client.js";
+import { redact } from "../core/redaction.js";
+const NOUN = "compute-providers";
+export class ComputeProviderCheckUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ComputeProviderCheckUsageError";
+    }
+}
+/** Named, so the shared mapper prints its message as the error line. */
+export class ComputeProviderCheckFailed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ComputeProviderCheckFailed";
+    }
+}
+export async function computeProviderCheckCommand(id, options = {}, deps = {}) {
+    const io = deps.io ?? defaultIo;
+    const ctx = { notFound: { resource: "compute provider", key: id } };
+    const code = await runCommand(() => check(id, options, deps, ctx), ctx, io);
+    settleExitCode(code, deps.onExitCode);
+}
+/** Throws on every failure, a Launcher that does not work included; the caller owns reporting and the exit code. */
+async function check(id, options, deps, ctx) {
+    const env = deps.env ?? process.env;
+    const io = deps.io ?? defaultIo;
+    const now = deps.now ?? (() => Date.now());
+    const mode = parseOutputMode(options.output, (message) => new ComputeProviderCheckUsageError(message));
+    ctx.mode = mode;
+    const row = getRow();
+    const dispatch = CLI_DISPATCH[row.operationId];
+    if (dispatch === undefined) {
+        throw new Error(`this orchestra build has no dispatch entry for operation '${row.operationId}'.`);
+    }
+    const { auth, warnings } = await resolveAuthWithWarnings(env, authFlagsFrom(options), deps.loadProfile !== undefined ? { loadProfile: deps.loadProfile } : {});
+    printWarnings(warnings, io);
+    ctx.provider = auth.provider;
+    ctx.baseUrl = auth.baseUrl;
+    const platformTarget = platformTargetFrom(auth);
+    const apis = createPlatformApis(platformTarget, deps.fetchApi, { warn: (lines) => printWarnings(lines, io) });
+    const organizationId = platformTarget.organizationId;
+    const response = await dispatch(apis, {
+        pathParams: { [row.positionals[0]?.param ?? "id"]: id },
+        query: {},
+        ...(organizationId !== undefined ? { organizationId } : {}),
+    });
+    const text = await response.raw.text();
+    const body = text.trim() === "" ? undefined : JSON.parse(text);
+    // The judgment reads the raw body and the printed lines read the redacted one, as every read command does.
+    const redaction = redact(body, row.responseSchema, { reveal: false });
+    if (mode === "json") {
+        printResponse(redaction.rendered, { mode, io, redaction });
+    }
+    else {
+        writeLines(io, "out", renderReport(viewOf(redaction.rendered), now()));
+        printRedactionNotes(redaction, io);
+    }
+    const failures = judge(viewOf(body), now());
+    if (failures.length > 0) {
+        throw new ComputeProviderCheckFailed(`${describe(viewOf(body))} does not work: ${failures.join("; ")}.`);
+    }
+}
+function getRow() {
+    const row = findCommand(NOUN, "get");
+    if (row === undefined) {
+        throw new Error(`this orchestra build has no \`${NOUN} get\` command to read.`);
+    }
+    return row;
+}
+/** Each reason the Launcher does not work, in the order a person fixes them. Empty means it works. */
+function judge(provider, nowMs) {
+    if (provider.kind === "managed") {
+        return [];
+    }
+    const failures = [];
+    if (provider.protocolRefusal !== undefined) {
+        failures.push(`the platform refused the Launcher's protocol: ${provider.protocolRefusal}`);
+    }
+    if (provider.state === "never_connected" || provider.lastPollAt === undefined) {
+        failures.push("the Launcher has never polled");
+    }
+    else if (provider.state !== "connected") {
+        const age = ageOf(provider.lastPollAt, nowMs);
+        failures.push(`the Launcher is ${provider.state ?? "in an unknown state"}: its last poll was ${age} ago`);
+    }
+    if (provider.state === "connected" && provider.targets.length === 0) {
+        failures.push("the Launcher reported no targets");
+    }
+    for (const target of provider.targets) {
+        if (target.refusedReason !== undefined) {
+            failures.push(`target ${target.kind} ${target.place}: ${target.refusedReason}`);
+        }
+    }
+    return failures;
+}
+function renderReport(provider, nowMs) {
+    const lines = [field("compute provider", describe(provider))];
+    if (provider.kind === "managed") {
+        lines.push(field("kind", "managed: this deployment runs it, so there is no Launcher to check"));
+        return lines.join("\n");
+    }
+    lines.push(field("state", provider.state ?? "unknown"));
+    lines.push(field("last poll", provider.lastPollAt === undefined ? "never" : `${provider.lastPollAt} (${ageOf(provider.lastPollAt, nowMs)} ago)`));
+    const version = provider.protocolVersion;
+    lines.push(field("protocol", version === undefined ? "none reported" : `version ${String(version)}`));
+    if (provider.protocolRefusal !== undefined) {
+        lines.push(field("protocol refusal", provider.protocolRefusal));
+    }
+    const health = provider.health;
+    lines.push(field("health", health === undefined
+        ? "none reported"
+        : `orders held ${String(health.ordersHeld)}, cloud errors ${String(health.cloudErrors)}, ` +
+            `reports pending ${String(health.reportsPending)}`));
+    if (provider.targets.length === 0) {
+        lines.push(field("targets", "none reported"));
+    }
+    else {
+        lines.push("targets");
+        const kindWidth = Math.max(...provider.targets.map((target) => target.kind.length));
+        const placeWidth = Math.max(...provider.targets.map((target) => target.place.length));
+        for (const target of provider.targets) {
+            const result = target.refusedReason === undefined ? "passed" : `failed: ${target.refusedReason}`;
+            lines.push(`  ${target.kind.padEnd(kindWidth)}  ${target.place.padEnd(placeWidth)}  ${result}`);
+        }
+    }
+    const failures = judge(provider, nowMs);
+    lines.push(field("result", failures.length === 0 ? "working" : "not working"));
+    return lines.join("\n");
+}
+const LABEL_WIDTH = 18;
+function field(label, value) {
+    return `${label.padEnd(LABEL_WIDTH)}${value}`;
+}
+function describe(provider) {
+    return provider.name === "" ? provider.id : `${provider.name} (${provider.id})`;
+}
+function ageOf(isoInstant, nowMs) {
+    const at = Date.parse(isoInstant);
+    return Number.isNaN(at) ? "an unknown time" : formatAge(nowMs - at);
+}
+/** The two largest units of a duration in milliseconds; a negative one, from clock skew, reads as zero. */
+export function formatAge(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    const days = Math.floor(seconds / 86_400);
+    const hours = Math.floor((seconds % 86_400) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const rest = seconds % 60;
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m ${rest}s`;
+    return `${rest}s`;
+}
+/** A field of the wrong type reads as absent, so an odd body is judged not working rather than crashing the read. */
+function viewOf(body) {
+    const record = asRecord(body);
+    const listed = record["targets"];
+    const targets = Array.isArray(listed) ? listed.map((entry) => targetOf(asRecord(entry))) : [];
+    const health = asRecord(record["health"]);
+    return {
+        id: stringOf(record["id"]) ?? "",
+        kind: stringOf(record["kind"]),
+        name: stringOf(record["name"]) ?? "",
+        state: stringOf(record["state"]),
+        lastPollAt: stringOf(record["lastPollAt"]),
+        protocolVersion: record["protocolVersion"] ?? undefined,
+        protocolRefusal: stringOf(record["protocolRefusal"]),
+        health: record["health"] === undefined || record["health"] === null
+            ? undefined
+            : {
+                ordersHeld: health["ordersHeld"],
+                cloudErrors: health["cloudErrors"],
+                reportsPending: health["reportsPending"],
+            },
+        targets,
+    };
+}
+/** The place as the Launcher wrote it, or the fields it is made of when it wrote none. */
+function targetOf(record) {
+    const written = stringOf(record["place"]);
+    const parts = ["subscription", "resourceGroup", "cluster", "namespace"]
+        .map((key) => stringOf(record[key]))
+        .filter((part) => part !== undefined);
+    return {
+        kind: stringOf(record["kind"]) ?? "unknown",
+        place: written ?? (parts.length > 0 ? parts.join("/") : "(no place)"),
+        refusedReason: stringOf(record["refusedReason"]),
+    };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function stringOf(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/dist/cli/api/tail.d.ts

@@ -0,0 +1,66 @@
+import type { FetchAPI } from "@orchestraworks/client";
+import { type CliIo } from "../core/output.js";
+import type { Profile } from "../core/profile.js";
+/** Seconds. The first pause after a failed read, doubled per failure up to {@link RETRY_MAX_SECONDS}. */
+export declare const RETRY_FIRST_SECONDS = 0.5;
+export declare const RETRY_MAX_SECONDS = 8;
+/** Seconds. The pause while no turn is open, doubled per empty pass up to {@link IDLE_MAX_SECONDS}. */
+export declare const IDLE_FIRST_SECONDS = 1;
+/** The platform's own waiting-read budget, so an idle follow reacts no slower than a running one. */
+export declare const IDLE_MAX_SECONDS = 5;
+/**
+ * `turn`: the row can change while its turn is open, or may be part of a turn no read has seen end.
+ * `background`: the row's turn has ended, but background work it names still updates it in place.
+ */
+export type ItemState = "final" | "turn" | "background";
+export declare class TailUsageError extends Error {
+    constructor(message: string);
+}
+export interface TailCommandOptions {
+    /** Start after this item; omitted prints the items that already exist first. */
+    after?: string;
+    untilSettled?: boolean;
+    output?: string;
+    reveal?: boolean;
+    profile?: string;
+    baseUrl?: string;
+    org?: string;
+}
+/** Every seam a test replaces; production leaves them all undefined. */
+export interface TailDeps {
+    env?: NodeJS.ProcessEnv;
+    io?: CliIo;
+    fetchApi?: FetchAPI;
+    loadProfile?: (name?: string) => Profile | undefined;
+    sleep?: (seconds: number, signal: AbortSignal) => Promise<void>;
+    /** Stops the command cleanly. Omitted, Ctrl-C does. */
+    signal?: AbortSignal;
+    onExitCode?: (code: number) => void;
+}
+type Json = Record<string, unknown>;
+/** The bounds of one waiting read, compared between passes to tell a stale answer from a new event. */
+interface WaitBounds {
+    waitForItem: string;
+    waitForAttempt: number;
+    waitForSeq: number;
+}
+export declare function tailCommand(id: string, options?: TailCommandOptions, deps?: TailDeps): Promise<void>;
+/**
+ * The state of each row, from the row's own fields and the read it came in. One read is one snapshot, so a
+ * prompt in it that shows its turn ended means that turn's rows in the same read are as they will stay.
+ * A row of a turn whose prompt is not in the read, that no earlier read saw end, and that the session read
+ * did not name, counts as changing; its turn is returned in `unseenTurns` for the caller to look up.
+ */
+export declare function classifyItems(window: readonly Json[], endedTurns: Set<string>, openTurnId: string | undefined): {
+    states: ItemState[];
+    unseenTurns: Set<string>;
+};
+/**
+ * The read answers once the prompt's recorded position reaches `waitForSeq - 1`, so one past the recorded
+ * event waits for the next one. A prompt that has not started a run yet carries no attempt: its first run is
+ * attempt 1, and the read waits for that run's first event.
+ */
+export declare function waitBoundsFor(promptId: string, prompt: Json): WaitBounds;
+/** Messages and thoughts in full; every other item on one line, from its own fields. */
+export declare function itemLine(item: Json): string;
+export {};