@opvs-ai/cli 0.27.10 → 0.27.11

package/dist/commands/machines.js

@@ -0,0 +1,227 @@
+import { createClient } from "@opvs-ai/core";
+import { printJson } from "../lib/format.js";
+/**
+ * The allow-list — the ONLY fields this command may print.
+ *
+ * The first block is what the reply carries today. The second block is the
+ * "if present" block from the card: the project and capacity fields the reply
+ * does NOT carry today, listed so that the day the API grows them they print
+ * themselves, and so that a reader can see the command is ready for them
+ * rather than silently dropping them.
+ */
+export const MACHINE_FIELDS = [
+    "name",
+    "short_id",
+    "status",
+    "sidecar_version",
+    "last_health_check",
+    // Worker loop — the row HAS `worker_loop_running` / `worker_loop_changed_at`
+    // (migration 139), but `EnvironmentResponse` does not declare them, so
+    // pydantic drops them and the reply does not carry them YET. They are in the
+    // allow-list so the day the model declares them they appear by themselves.
+    "worker_loop_running",
+    "worker_loop_changed_at",
+    // Project — not on the environment row today. The reply answers a project
+    // question only when it carries one.
+    "project_id",
+    "board_id",
+    // Capacity — the platform stores no per-machine desk capacity, so these are
+    // absent today; `desk_count` appears when the reply carries an occupancy.
+    "desk_count",
+    "max_desks",
+    "capacity",
+];
+/** The PLACEHOLDER for a field the reply does not carry. */
+const MISSING = "-";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Render one reply value for a cell: `-` when the reply does not carry it. */
+function cell(value) {
+    if (value === undefined || value === null || value === "")
+        return MISSING;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+/**
+ * Project ONE reply row onto the allow-list. Nothing else survives: a field
+ * the reply adds later (a token, a key, an install one-liner) is not printed,
+ * because it was never in the list.
+ */
+export function summarizeMachine(row) {
+    const source = isRecord(row) ? row : {};
+    const out = {};
+    for (const field of MACHINE_FIELDS) {
+        out[field] = cell(source[field]);
+    }
+    return out;
+}
+/** The rows of a fleet reply, tolerating a reply that is not the shape we expect. */
+export function machineRows(reply) {
+    if (!isRecord(reply))
+        return [];
+    const list = reply.environments;
+    return Array.isArray(list) ? list : [];
+}
+/**
+ * The `--project` filter, applied CLIENT-SIDE on what the reply carries.
+ *
+ * The environments route takes no project parameter, so the filter can only
+ * match a field the row actually has. A row with no project field matches
+ * NOTHING when `--project` is given — a filter that silently kept
+ * project-less rows would answer "these are the tenant's project machines"
+ * with rows that belong to no project at all.
+ */
+export function matchesProject(row, projectId) {
+    if (!isRecord(row))
+        return false;
+    for (const field of PROJECT_FIELDS) {
+        const value = row[field];
+        if (value === undefined || value === null)
+            continue;
+        if (String(value) === projectId)
+            return true;
+    }
+    return false;
+}
+/** The reply fields that can carry a project reference. */
+const PROJECT_FIELDS = ["project_id", "board_id"];
+/**
+ * Does this row carry a project reference AT ALL?
+ *
+ * A row whose project fields are all null says nothing about projects, which
+ * is a different fact from a row whose project is a DIFFERENT project.
+ */
+function carriesProject(row) {
+    if (!isRecord(row))
+        return false;
+    for (const field of PROJECT_FIELDS) {
+        const value = row[field];
+        if (value === undefined || value === null)
+            continue;
+        if (String(value) === "")
+            continue;
+        return true;
+    }
+    return false;
+}
+/**
+ * Does ANY row of the reply carry a project reference?
+ *
+ * THIS IS THE DIFFERENCE BETWEEN "no machine is in that project" and "this
+ * reply does not say". The environments reply carries no project field on any
+ * row today, so a `--project` filter over it drops every row — and printing
+ * "(no machines)" would tell a planner checking a client's onboarding that
+ * the client has no machines, which is a FALSE ANSWER (CP-359 fix round 1).
+ *
+ * So when the reply says nothing about projects, the command says so and
+ * stops, rather than answering a question the reply cannot answer.
+ */
+export function replyCarriesProject(rows) {
+    return rows.some(carriesProject);
+}
+/** The sentence the command prints when the reply cannot answer `--project`. */
+export const PROJECT_NOT_IN_REPLY = "This reply does not say which project a machine belongs to, so --project cannot filter it. " +
+    "Run opvs machines list without --project.";
+/** The text table: one row per machine, one column per allow-listed field. */
+export function renderMachinesTable(rows) {
+    if (rows.length === 0) {
+        console.log("(no machines)");
+        return;
+    }
+    const columns = MACHINE_FIELDS.map((f) => f);
+    const widths = columns.map((col, index) => Math.max(col.length, ...rows.map((row) => row[col].length)));
+    const header = columns.map((col, i) => col.padEnd(widths[i])).join("  ").trimEnd();
+    const sep = widths.map((w) => "-".repeat(w)).join("  ");
+    console.log(header);
+    console.log(sep);
+    for (const row of rows) {
+        const record = row;
+        console.log(columns.map((col, i) => record[col].padEnd(widths[i])).join("  ").trimEnd());
+    }
+}
+/** The API's own refusal — the sentence the server sent, not a paraphrase. */
+function apiMessage(err, fallback) {
+    const candidate = err;
+    if (typeof candidate?.detail === "string" && candidate.detail)
+        return candidate.detail;
+    if (candidate?.detail && typeof candidate.detail === "object") {
+        const nested = candidate.detail.message;
+        if (typeof nested === "string" && nested)
+            return nested;
+    }
+    if (typeof candidate?.message === "string" && candidate.message)
+        return candidate.message;
+    return fallback;
+}
+export function registerMachinesCommands(program) {
+    const machines = program
+        .command("machines")
+        .description("Read the machines (environments) of this workspace");
+    machines
+        .command("list")
+        .description("List this workspace's machines")
+        .option("--project <id>", "Keep only the machines the reply ties to this project (the reply must carry a project field)")
+        .option("--json", "Print the allow-listed fields as JSON instead of the table")
+        .action(async (opts) => {
+        const wsSlug = program.opts().workspace;
+        let raw;
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.get("/api/v1/environments");
+            const reply = (await res.json());
+            raw = machineRows(reply);
+        }
+        catch (err) {
+            console.error(`Error: ${apiMessage(err, "Failed to list machines")}`);
+            process.exit(1);
+            return;
+        }
+        // OUTSIDE the try: the guard's exit must not be caught by the API-error
+        // handler above and re-reported as "Error: exit 1".
+        if (opts.project) {
+            // A reply that says nothing about projects cannot answer the
+            // question. Printing "(no machines)" for a workspace that HAS
+            // machines would be a false answer, so the command says what is
+            // wrong and stops — in text and in `--json` alike.
+            if (raw.length > 0 && !replyCarriesProject(raw)) {
+                console.error(PROJECT_NOT_IN_REPLY);
+                process.exit(1);
+                return;
+            }
+            raw = raw.filter((row) => matchesProject(row, opts.project));
+        }
+        const rows = raw.map(summarizeMachine);
+        if (opts.json) {
+            printJson({ machines: rows, total: rows.length });
+            return;
+        }
+        renderMachinesTable(rows);
+    });
+    machines
+        .command("get <ref>")
+        .description("Show one machine by id, short code or prefix")
+        .option("--json", "Print the allow-listed fields as JSON instead of the text")
+        .action(async (ref, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.get(`/api/v1/environments/${encodeURIComponent(ref)}`);
+            const row = (await res.json());
+            const summary = summarizeMachine(row);
+            if (opts.json) {
+                printJson(summary);
+                return;
+            }
+            renderMachinesTable([summary]);
+        }
+        catch (err) {
+            console.error(`Error: ${apiMessage(err, `Failed to get machine '${ref}'`)}`);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=machines.js.map

package/dist/commands/machines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines.js","sourceRoot":"","sources":["../../src/commands/machines.ts"],"names":[],"mappings":"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"}

package/dist/commands/tasks.js

@@ -8,7 +8,7 @@ import { clampLimit } from "../lib/pagination.js";
 import { CLEAR, csv, intFlag, oneOf } from "../lib/options.js";
 import { confirm, YES_HELP } from "../lib/confirm.js";
 import { isUuid, resolveBoardRefs } from "../lib/board-refs.js";
-import { CalendarSpecError, parseEnds, parseRemind, parseZonedTime, } from "../lib/calendar-spec.js";
+import { CalendarSpecError, parseEndsWithTz, parseRemind, parseZonedTime, } from "../lib/calendar-spec.js";
 import { TASK_STATUSES } from "./columns.js";
 /** A board KEY's grammar (agentboard `ck_boards_key_format`). A UUID prefix
  *  is 8+ characters, so it can never pass this — which is how `tasks search`
@@ -32,6 +32,36 @@ function warnIfNotReady(data) {
         : "unknown";
     console.error(`Warning: task is not ready for builders; missing: ${missing}`);
 }
+/** `$12.50` — money as the budget routes report it, in dollars. */
+function usd(value) {
+    return typeof value === "number" && Number.isFinite(value) ? `$${value.toFixed(2)}` : "$?";
+}
+/** A card's completion-budget envelope as one line (REAS-304):
+ *  `budget: $15.00/$15.00 (drawn/total; slice $5.00, cap $50.00)`.
+ *  `null` for a body that is not an envelope, so the caller prints nothing. */
+function budgetLine(data) {
+    const b = (data ?? {});
+    if (typeof b.drawn_usd !== "number" || typeof b.total_usd !== "number")
+        return null;
+    const sizing = typeof b.slice_usd === "number" && typeof b.cap_usd === "number"
+        ? `; slice ${usd(b.slice_usd)}, cap ${usd(b.cap_usd)}`
+        : "";
+    return `budget: ${usd(b.drawn_usd)}/${usd(b.total_usd)} (drawn/total${sizing})`;
+}
+/** The card's completion-budget envelope for `tasks get`, or `null` when it has
+ *  none. Best effort on purpose: a card never minted against has none (404), and
+ *  an older server has no such route — neither makes `tasks get` fail. */
+async function readBudget(client, id) {
+    try {
+        const res = await client.get(`/api/v1/board/tasks/${id}/budget`);
+        const data = await res.json();
+        return budgetLine(data) ? data : null;
+    }
+    catch {
+        // no envelope, no route or no scope: there is no budget to show
+        return null;
+    }
+}
 /** Collect a repeatable `--field key=value` option into an array. */
 function collectField(val, prev) {
     return prev.concat([val]);
@@ -105,7 +135,7 @@ function buildTaskSchedule(opts) {
             ends: "never",
         };
         if (opts.ends !== undefined) {
-            const end = parseEnds(opts.ends);
+            const end = parseEndsWithTz(opts.ends);
             if (end.repeat_ends === "on_date") {
                 repeat.ends = "on";
                 repeat.until = end.repeat_until;
@@ -435,9 +465,25 @@ export function registerTaskCommands(program) {
             const detail = oneOf("--detail", opts.detail, ["summary", "standard", "full"]);
             if (detail)
                 params.detail = detail;
-            const url = buildUrl(`/api/v1/board/tasks/${id}`, params, opts.json ? "json" : cfg.format);
+            // `--json` or a saved `format: json` — the same JSON output either way.
+            const asJson = Boolean(opts.json) || cfg.format === "json";
+            const url = buildUrl(`/api/v1/board/tasks/${id}`, params, asJson ? "json" : cfg.format);
             const res = await client.get(url);
+            if (asJson && (res.headers.get("content-type") || "").includes("application/json")) {
+                // ONE JSON document: the budget is a key in it, never a line after it,
+                // which would break every parser reading the output.
+                const task = await res.json();
+                const budget = await readBudget(client, id);
+                const isCard = typeof task === "object" && task !== null && !Array.isArray(task);
+                printJson(budget && isCard ? { ...task, budget } : task);
+                return;
+            }
             await printResponse(res);
+            if (!asJson) {
+                const line = budgetLine(await readBudget(client, id));
+                if (line)
+                    console.log(line);
+            }
         }
         catch (err) {
             const e = err;
@@ -598,6 +644,7 @@ export function registerTaskCommands(program) {
         .description("Update a task (status, priority, result)")
         .option("--status <status>", "Status: pending, assigned, in_progress, blocked, review, done, cancelled, failed (pending can only go to assigned/in_progress/cancelled)")
         .option("--any-status", "Skip status compare-and-set and write regardless of the card's current status")
+        .option("--force-release", "Release a builder claim when this update also moves the card. Use only when you know the box has stopped.")
         .option("--priority <priority>", "Priority: low, medium, high, critical")
         .option("--title <title>", "New title")
         .option("-d, --description <desc>", "New description (markdown)")
@@ -660,6 +707,15 @@ export function registerTaskCommands(program) {
         try {
             const schedule = buildTaskSchedule(opts);
             const body = {};
+            // `force_release` releases a builder claim, and the server only acts on
+            // it while this same PATCH also moves the card. Without --status there
+            // is nothing to move, so the flag would be a no-op the server ignores —
+            // refuse it here rather than let a planner believe the card was freed.
+            if (opts.forceRelease && !opts.status) {
+                console.error("Error: --force-release needs --status — it only releases a claim when the update also moves the card.");
+                process.exit(1);
+                return;
+            }
             if (opts.status)
                 body.status = opts.status;
             if (opts.priority)
@@ -807,6 +863,13 @@ export function registerTaskCommands(program) {
             // Keep the optimistic-concurrency precondition out of the printed
             // changed-field list: it controls this write but is not persisted.
             const changedFields = Object.keys(body);
+            // `force_release` is request control, not a persisted field (the server
+            // pops it out of the update data before it reaches the task row), so it
+            // is set here, after the changed-field snapshot, and never sent as
+            // false — an absent key means "not requested".
+            if (opts.forceRelease) {
+                body.force_release = true;
+            }
             if (opts.status && !opts.anyStatus) {
                 const currentRes = await client.get(`/api/v1/board/tasks/${id}`);
                 // createClient returns a Response or throws. The truthiness check
@@ -1020,6 +1083,48 @@ export function registerTaskCommands(program) {
             process.exit(1);
         }
     });
+    tasks
+        .command("budget-extend <id>")
+        .description("Give a card ONE more completion-budget slice (one build's draw), e.g. after it died " +
+        "card_budget_exhausted, and lift its card_budget_exhausted park; then move the card to " +
+        "Ready. Written on the card as a comment and in its activity log; refused while the card " +
+        "still has a slice left, past the card's cap, and for a desk's own token. <id> accepts a " +
+        "ref (OPS-142), a UUID prefix, or a full UUID")
+        .requiredOption("--reason <text>", "Why the card gets another slice: 10 to 1000 characters, written on the card verbatim")
+        .option("--json", "Print the raw grant response")
+        .action(async (id, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.post(`/api/v1/board/tasks/${id}/budget-extend`, {
+                reason: opts.reason,
+            });
+            const data = await res.json();
+            if (opts.json) {
+                printJson(data);
+                return;
+            }
+            console.log(`${data.ref || data.task_id || id}  budget slice +${usd(data.slice_usd)} granted: ` +
+                `total now ${usd(data.total_usd)} of cap ${usd(data.cap_usd)} (drawn ${usd(data.drawn_usd)})`);
+            if (data.park_cleared === true) {
+                console.log("  park lifted: waiting_reason card_budget_exhausted cleared");
+            }
+            if (Array.isArray(data.warnings)) {
+                for (const w of data.warnings)
+                    console.log(`  ⚠ ${String(w)}`);
+            }
+            // Last, because it is the planner's to do: the park sent the card to
+            // Backlog, and the grant does not move it back to Ready.
+            if (typeof data.next_step === "string" && data.next_step) {
+                console.log(`  next: ${data.next_step}`);
+            }
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to extend the card's budget"}`);
+            process.exit(1);
+        }
+    });
     tasks
         .command("subtasks <id>")
         .description("List subtasks of a task")