@opvs-ai/cli 0.14.0 → 0.15.1

package/dist/commands/boards.js

@@ -3,6 +3,149 @@
  */
 import { getEffectiveConfig, createClient } from "@opvs-ai/core";
 import { buildUrl, printResponse, printJson } from "../lib/format.js";
+import { confirm } from "../lib/confirm.js";
+import { isUuid } from "../lib/board-refs.js";
+import { healthParams, renderHealthReport, withHealthOptions } from "../lib/health.js";
+import { buildRoutingBody, withRoutingOptions } from "../lib/routing.js";
+import { FACTORY_PROJECT_GATE, warnIfFactoryUnresolved } from "../lib/factory-gate.js";
+import { boolFlag, oneOf } from "../lib/options.js";
+import { readFileSync } from "node:fs";
+/** `BoardCreate.mode` pattern (agentboard `schemas/board.py`). */
+const BOARD_MODES = ["pipeline", "evergreen"];
+/** `BoardUpdate.status` pattern. */
+const BOARD_STATUSES = ["active", "completed"];
+// `graph_service` is the only reader of `mode` (7-day throughput for evergreen).
+const MODE_HELP = "pipeline | evergreen. A label for how the board runs: a pipeline has an end, an evergreen board runs continuously " +
+    "and the board graph shows its 7-day throughput. Nothing else reads it.";
+// Nothing but the response builders reads `boards.status` — no claim, move or list filter.
+const STATUS_HELP = "active | completed. A LABEL (O-B1): completing a board moves no card, and its cards stay claimable.";
+// The gateway list (`board.py` list_boards) filters `is_archived = false`; the
+// claim engine does not check it.
+const ARCHIVED_HELP = "true | false. An archived board drops out of `opvs boards list` but stays reachable by id, and its cards stay " +
+    "CLAIMABLE — archiving does not stop a factory.";
+// `field_visibility.py`: a key absent from field_config is PUBLIC.
+const FIELD_CONFIG_HELP = "Custom field definitions as a JSON array of {key,label,type,visible,position,group,options,visibility}. " +
+    "REPLACES the whole list. A field you leave out loses its visibility tier — an owner_only or internal field " +
+    "becomes readable by everyone who can see the board. Read the current list with `opvs boards get` first.";
+const BOARD_TYPE_FACTORY_NOTE = ` ${FACTORY_PROJECT_GATE}`;
+/**
+ * `--field-config <json>` / `--field-config-file <path>` → the array the PATCH
+ * sends. Exactly one; an object or a scalar exits here rather than 422ing with a
+ * pydantic path the operator did not type.
+ */
+function readFieldConfig(opts) {
+    if (opts.fieldConfig === undefined && opts.fieldConfigFile === undefined)
+        return undefined;
+    if (opts.fieldConfig !== undefined && opts.fieldConfigFile !== undefined) {
+        console.error("Error: pass --field-config or --field-config-file, not both");
+        process.exit(1);
+    }
+    const raw = opts.fieldConfig ?? readFileSync(opts.fieldConfigFile, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        console.error("Error: field config must be valid JSON (an array of field definitions)");
+        process.exit(1);
+    }
+    if (!Array.isArray(parsed)) {
+        console.error("Error: field config must be a JSON ARRAY of field definitions — it replaces the whole list");
+        process.exit(1);
+    }
+    return parsed;
+}
+function fmtProject(p) {
+    return `${p.name} (${p.id})${p.is_archived ? " [archived]" : ""}`;
+}
+function fmtValue(v) {
+    if (v === null || v === undefined)
+        return "—";
+    if (Array.isArray(v))
+        return `[${v.join(",")}]`;
+    return String(v);
+}
+/**
+ * Print an apply-preset plan: one line per column with the card count it puts
+ * in scope, then conflicts and the columns the preset leaves alone. The card
+ * count is the number an operator reads to decide whether to apply, so it is
+ * on every row rather than only in the summary.
+ */
+export function renderPresetPlan(plan) {
+    const lines = [];
+    lines.push(`Preset ${plan.preset ?? "?"} on a ${plan.board_type ?? "?"} board — ${plan.applied ? "APPLIED" : "DRY RUN, nothing written"}`);
+    lines.push("");
+    for (const c of plan.columns ?? []) {
+        const cards = `${c.cards_affected ?? 0} card(s)`;
+        lines.push(`  ${c.action.toUpperCase().padEnd(9)}  ${c.slug.padEnd(16)}  ${cards.padStart(10)}  ${c.name}`);
+        for (const [field, pair] of Object.entries(c.changes ?? {})) {
+            const [before, after] = pair ?? [];
+            lines.push(`  ${"".padEnd(9)}    ${field}: ${fmtValue(before)} → ${fmtValue(after)}`);
+        }
+        for (const n of c.notes ?? [])
+            lines.push(`  ${"".padEnd(9)}    note: ${n}`);
+    }
+    const extra = plan.extra_columns ?? [];
+    if (extra.length) {
+        lines.push("");
+        lines.push(`Left in place (not in the preset, cards untouched): ${extra.join(", ")}`);
+    }
+    const conflicts = plan.conflicts ?? [];
+    if (conflicts.length) {
+        lines.push("");
+        lines.push("Conflicts:");
+        for (const k of conflicts) {
+            lines.push(`  ${k.blocking === false ? "NON-BLOCKING" : "BLOCKING"}  ${k.slug}  ${k.code} — ${k.detail}`);
+        }
+    }
+    const s = plan.summary ?? {};
+    lines.push("");
+    lines.push(`Summary: ${s.created ?? 0} created · ${s.updated ?? 0} updated · ${s.unchanged ?? 0} unchanged · ` +
+        `${s.cards_affected ?? 0} card(s) affected. No card is moved or deleted.`);
+    return lines.join("\n");
+}
+/** Stable, key-order-independent rendering of a column's `changes` map. */
+function canonicalChanges(changes) {
+    const c = changes ?? {};
+    return JSON.stringify(Object.keys(c).sort().map((k) => [k, c[k]]));
+}
+/**
+ * The columns whose planned change differs between the dry run the operator saw
+ * and the plan the server actually applied (ASP-118 F14).
+ *
+ * The apply is a SECOND request with no plan token or version check
+ * (`board_preset_service.py`), so another session can change the columns in
+ * between — and then a different set of rebinds and card counts is written
+ * than the one on screen. Same shape as `move-to-project`'s `removed_from`
+ * comparison: the server's answer is the truth, and a difference is reported.
+ *
+ * @returns one line per differing column slug; empty when they match.
+ */
+export function presetPlanDrift(preview, applied) {
+    const index = (plan) => new Map((plan.columns ?? []).map((c) => [c.slug, c]));
+    const before = index(preview);
+    const after = index(applied);
+    const out = [];
+    for (const slug of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const b = before.get(slug);
+        const a = after.get(slug);
+        if (!b || !a) {
+            out.push(`${slug}: ${b ? "in the preview, not in what was applied" : "applied, but not in the preview"}`);
+            continue;
+        }
+        const diffs = [];
+        if (b.action !== a.action)
+            diffs.push(`action ${b.action} → ${a.action}`);
+        if ((b.cards_affected ?? 0) !== (a.cards_affected ?? 0)) {
+            diffs.push(`cards ${b.cards_affected ?? 0} → ${a.cards_affected ?? 0}`);
+        }
+        if (canonicalChanges(b.changes) !== canonicalChanges(a.changes))
+            diffs.push("field changes differ");
+        if (diffs.length)
+            out.push(`${slug}: ${diffs.join(", ")}`);
+    }
+    return out;
+}
 export function registerBoardCommands(program) {
     const boards = program.command("boards").description("AgentBoard management");
     boards
@@ -51,9 +194,21 @@ export function registerBoardCommands(program) {
         .requiredOption("-n, --name <name>", "Board name")
         .option("-d, --description <desc>", "Board description")
         .option("--visibility <vis>", "Visibility: public or private", "public")
-        .option("--board-type <type>", "Board type: tasks, emails, contacts, companies, deals, content_calendar, factory")
+        .option("--board-type <type>", `Board type: tasks, emails, contacts, companies, deals, content_calendar, factory.${BOARD_TYPE_FACTORY_NOTE} ` +
+        "A new board is in no project.")
+        // ASP-113: "the fully claim-wired pipeline" was true of the COLUMNS and
+        // false of the board — ORP-6 refuses every claim until the project link.
+        .option("--column-preset <preset>", "Seed the columns from a named preset instead of the board type's default — see `opvs boards templates`. " +
+        "The preset must belong to --board-type (a mismatch is a 422 naming the valid ones). " +
+        "e.g. --board-type factory --column-preset factory-full wires every column for claiming — and the board still " +
+        "claims NOTHING until it is linked to exactly one active project (`opvs projects add-board <project> <board>`).")
+        .option("--mode <mode>", `${MODE_HELP} Default: pipeline.`)
+        // `BoardService.create` reads `column_preset` only inside the seed branch.
+        .option("--no-seed-columns", "Create the board with NO columns (--column-preset is then ignored). A card needs a column, so nothing can be " +
+        "created on it until you add some with `opvs columns create`.")
         .action(async (opts) => {
         const wsSlug = program.opts().workspace;
+        const mode = oneOf("--mode", opts.mode, BOARD_MODES);
         try {
             const client = createClient(wsSlug);
             const body = { name: opts.name };
@@ -63,9 +218,19 @@ export function registerBoardCommands(program) {
                 body.visibility = opts.visibility;
             if (opts.boardType)
                 body.board_type = opts.boardType;
+            if (opts.columnPreset)
+                body.column_preset = opts.columnPreset;
+            if (mode)
+                body.mode = mode;
+            // commander's `--no-x` makes `seedColumns` default true; only the
+            // explicit opt-out is sent, so the body without it is unchanged.
+            if (opts.seedColumns === false)
+                body.seed_default_columns = false;
             const res = await client.post("/api/v1/board/boards", body);
-            const data = await res.json();
+            const data = (await res.json());
             printJson(data);
+            if (data.board_type === "factory" && data.id)
+                await warnIfFactoryUnresolved(client, data.id);
         }
         catch (err) {
             const e = err;
@@ -79,7 +244,12 @@ export function registerBoardCommands(program) {
         .option("-n, --name <name>", "New name")
         .option("-d, --description <desc>", "New description")
         .option("--visibility <vis>", "Visibility: public or private")
-        .option("--board-type <type>", "Switch board type (tasks↔factory only; other values are rejected)")
+        .option("--board-type <type>", `Switch board type (tasks↔factory only; other values are rejected).${BOARD_TYPE_FACTORY_NOTE}`)
+        .option("--mode <mode>", MODE_HELP)
+        .option("--status <status>", STATUS_HELP)
+        .option("--archived <bool>", ARCHIVED_HELP)
+        .option("--field-config <json>", FIELD_CONFIG_HELP)
+        .option("--field-config-file <path>", "The same as --field-config, read from a file.")
         .option("--final-stage-column <slug>", "Column slug a card moves to when its final stage completes (board.settings.on_final_stage_move_to_column). Pass '' to clear.")
         .action(async (id, opts) => {
         const wsSlug = program.opts().workspace;
@@ -94,6 +264,18 @@ export function registerBoardCommands(program) {
                 body.visibility = opts.visibility;
             if (opts.boardType)
                 body.board_type = opts.boardType;
+            const mode = oneOf("--mode", opts.mode, BOARD_MODES);
+            if (mode)
+                body.mode = mode;
+            const status = oneOf("--status", opts.status, BOARD_STATUSES);
+            if (status)
+                body.status = status;
+            const archived = boolFlag("--archived", opts.archived);
+            if (archived !== undefined)
+                body.is_archived = archived;
+            const fieldConfig = readFieldConfig(opts);
+            if (fieldConfig)
+                body.field_config = fieldConfig;
             // The board PATCH replaces `settings` wholesale, so read-modify-write:
             // fetch current settings, merge just our key, send the full dict back.
             if (opts.finalStageColumn !== undefined) {
@@ -111,12 +293,15 @@ export function registerBoardCommands(program) {
                 body.settings = settings;
             }
             if (Object.keys(body).length === 0) {
-                console.error("Nothing to update. Provide --name, --description, --visibility, --board-type, or --final-stage-column");
+                console.error("Nothing to update. Provide --name, --description, --visibility, --board-type, --mode, --status, " +
+                    "--archived, --field-config, --field-config-file, or --final-stage-column");
                 process.exit(1);
             }
             const res = await client.patch(`/api/v1/board/boards/${id}`, body);
             const data = await res.json();
             printJson(data);
+            if (opts.boardType === "factory")
+                await warnIfFactoryUnresolved(client, id);
         }
         catch (err) {
             const e = err;
@@ -140,6 +325,311 @@ export function registerBoardCommands(program) {
             process.exit(1);
         }
     });
+    // ── Templates (ASP-25, plan §B) ───────────────────────────────────
+    // Every preset `boards create --column-preset` accepts, WITH its claim
+    // wiring. Before ASP-4 the template read dropped the wiring, so a wired
+    // preset and an unwired one rendered identically — that is why the roles
+    // and move-to slugs are on every column line here, not behind a flag.
+    boards
+        .command("templates")
+        .description("List the column presets a board can be created with, including each column's claim wiring")
+        .option("--board-type <type>", "Only presets for this board type, e.g. factory")
+        .option("--json", "Print the raw JSON instead of the text listing")
+        .action(async (opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.get("/api/v1/board/boards/templates");
+            const data = (await res.json());
+            let templates = data.templates ?? [];
+            if (opts.boardType)
+                templates = templates.filter((t) => t.board_type === opts.boardType);
+            if (opts.json) {
+                printJson({ templates });
+                return;
+            }
+            if (templates.length === 0) {
+                console.log(opts.boardType ? `No presets for board type '${opts.boardType}'.` : "No presets.");
+                return;
+            }
+            for (const t of templates) {
+                const cols = t.columns ?? [];
+                const wired = cols.some((c) => (c.claimable_by_roles?.length ?? 0) > 0);
+                console.log(`${t.preset}  [${t.board_type}]  ${cols.length} column(s)  ${wired ? "claim-wired" : "NO claim wiring"}` +
+                    (t.display_name && t.display_name !== t.preset ? `  — ${t.display_name}` : ""));
+                if (t.summary)
+                    console.log(`    ${t.summary}`);
+                for (const c of cols) {
+                    const bits = [];
+                    if (c.mapped_status)
+                        bits.push(`status=${c.mapped_status}`);
+                    if (c.is_default)
+                        bits.push("default");
+                    if (c.is_done_column)
+                        bits.push("done");
+                    if (c.claimable_by_roles?.length)
+                        bits.push(`roles=${c.claimable_by_roles.join(",")}`);
+                    if (c.on_claim_move_to)
+                        bits.push(`on_claim→${c.on_claim_move_to}`);
+                    if (c.on_done_move_to)
+                        bits.push(`on_done→${c.on_done_move_to}`);
+                    console.log(`    - ${c.slug}${bits.length ? `  (${bits.join(" · ")})` : ""}`);
+                }
+            }
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to list board templates"}`);
+            process.exit(1);
+        }
+    });
+    // ── Routing defaults (ASP-25, plan §C / migration 062) ────────────
+    withRoutingOptions(boards
+        .command("set-routing <board>")
+        .description("Set the board's routing defaults (model / provider / harness / claimable-by). Only the flags you pass change."), "board").action(async (board, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const body = buildRoutingBody(opts);
+            if (Object.keys(body).length === 0) {
+                console.error("Nothing to set. Provide --model, --provider, --harness, or --claimable-by");
+                process.exit(1);
+            }
+            const client = createClient(wsSlug);
+            const res = await client.patch(`/api/v1/board/boards/${board}`, body);
+            const data = (await res.json());
+            // Report the SERVER's values, not our request: a blank is normalised to
+            // null on the way in, and an echo of our own body would hide that.
+            printJson({
+                id: data.id,
+                ref: data.ref,
+                default_model: data.default_model ?? null,
+                default_provider: data.default_provider ?? null,
+                default_harness: data.default_harness ?? null,
+                default_claimable_by: data.default_claimable_by ?? null,
+            });
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to set board routing"}`);
+            process.exit(1);
+        }
+    });
+    // ── Board ↔ project membership (ASP-25, plan §F) ──────────────────
+    // Membership is many-to-many by design, and a board claimed by TWO active
+    // projects resolves no bundle at all (`resolution: ambiguous`) — both
+    // projects' rules silently stop applying to its cards. `add` can create that
+    // state; `move` can silently take a board out of projects the operator is
+    // not looking at. Both say what they did.
+    boards
+        .command("projects <board>")
+        .description("List the projects that actively claim this board, and whether that resolves (none | resolved | ambiguous)")
+        .action(async (board) => {
+        const wsSlug = program.opts().workspace;
+        const cfg = getEffectiveConfig(wsSlug);
+        try {
+            const client = createClient(wsSlug);
+            const url = buildUrl(`/api/v1/board/boards/${board}/projects`, undefined, cfg.format);
+            const res = await client.get(url);
+            await printResponse(res);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to list board projects"}`);
+            process.exit(1);
+        }
+    });
+    boards
+        .command("add-to-project <board> <projectId>")
+        .description("Add this board to a project (additive — it stays in any other project). " +
+        "If it is already in another active project the board becomes AMBIGUOUS and inherits NO project's rules. " +
+        FACTORY_PROJECT_GATE)
+        .action(async (board, projectId) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            requireProjectUuid(projectId);
+            const client = createClient(wsSlug);
+            const res = await client.post(`/api/v1/board/boards/${board}/projects`, {
+                project_id: projectId,
+                mode: "add",
+            });
+            const data = (await res.json());
+            printJson(data);
+            if (data.resolution === "ambiguous") {
+                console.error(`Warning: this board is now claimed by ${data.projects?.length ?? "several"} active projects ` +
+                    "(resolution: ambiguous), so its cards inherit NO project bundle or routing default. " +
+                    "Use `opvs boards move-to-project` if it should belong to one.");
+            }
+            await warnIfFactoryUnresolved(client, board);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to add board to project"}`);
+            process.exit(1);
+        }
+    });
+    boards
+        .command("move-to-project <board> <projectId>")
+        .description("Move this board into a project: adds it there AND REMOVES it from every other project that claims it, " +
+        "in one transaction. Prints the projects it will leave first; requires --yes (or a y at a terminal prompt).")
+        .option("--yes", "Confirm the removal from the projects listed. Without it nothing is sent.")
+        .action(async (board, projectId, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            requireProjectUuid(projectId);
+            const client = createClient(wsSlug);
+            // Preview from the same read `opvs boards projects` uses. The POST has
+            // no dry-run, so this is the only way to name the casualties BEFORE
+            // they happen.
+            const before = await client.get(`/api/v1/board/boards/${board}/projects`);
+            const current = (await before.json()).projects ?? [];
+            const target = projectId.toLowerCase();
+            const leaving = current.filter((p) => p.id.toLowerCase() !== target);
+            const alreadyIn = current.some((p) => p.id.toLowerCase() === target);
+            if (leaving.length === 0) {
+                console.error(alreadyIn
+                    ? `Board ${board} is already only in project ${projectId}. The move removes it from no other project.`
+                    : `Board ${board} is in no other project. The move removes it from nothing.`);
+            }
+            else {
+                console.error(`Moving board ${board} to project ${projectId} will REMOVE it from ${leaving.length} project(s):`);
+                for (const p of leaving)
+                    console.error(`  - ${fmtProject(p)}`);
+                console.error("Its cards stop inheriting those projects' commands, skills, rules and routing defaults.");
+            }
+            const ok = await confirm(`Move board ${board} to project ${projectId}?`, !!opts.yes, leaving.length
+                ? `This removes the board from ${leaving.length} other project(s)`
+                : "This changes the board's project membership");
+            if (!ok) {
+                process.exit(1);
+            }
+            const res = await client.post(`/api/v1/board/boards/${board}/projects`, {
+                project_id: projectId,
+                mode: "move",
+            });
+            const data = (await res.json());
+            printJson(data);
+            // The server's `removed_from` is the truth; the preview was a read that
+            // another session could have overtaken. Say so when they differ.
+            const removed = new Set((data.removed_from ?? []).map((p) => p.id.toLowerCase()));
+            const previewed = new Set(leaving.map((p) => p.id.toLowerCase()));
+            const differs = removed.size !== previewed.size || [...removed].some((id) => !previewed.has(id));
+            if (differs) {
+                console.error("Warning: the projects actually removed differ from the preview above (membership changed in between). " +
+                    "`removed_from` in the output is what happened.");
+            }
+            // Moving into an ARCHIVED project leaves the board in no active one.
+            await warnIfFactoryUnresolved(client, board);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to move board to project"}`);
+            process.exit(1);
+        }
+    });
+    // ── Health (ASP-25, plan §J4) ─────────────────────────────────────
+    withHealthOptions(boards
+        .command("health <board>")
+        .description("Structural health of a board and its cards. OPVS reports structure; YOU supply the thresholds. " +
+        "A check whose threshold you did not pass prints NOT CHECKED and makes the verdict INCOMPLETE — never a pass.")).action(async (board, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            // JSON always — the text rendering below needs the structure, and a
+            // yaml/md workspace format would hand us text we cannot re-render.
+            const url = buildUrl(`/api/v1/board/boards/${board}/health`, healthParams(opts));
+            const res = await client.get(url);
+            const report = (await res.json());
+            if (opts.json)
+                printJson(report);
+            else
+                console.log(renderHealthReport(report));
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to get board health"}`);
+            process.exit(1);
+        }
+    });
+    // ── Apply a preset to an existing board (ASP-25, plan §J1) ────────
+    boards
+        .command("apply-preset <board> <preset>")
+        .description("Reshape an EXISTING board's columns to a preset. DRY RUN BY DEFAULT: prints what each column would become " +
+        "and how many cards each change puts in scope, and writes nothing. Add --yes to apply. " +
+        "Cards are never moved or deleted; columns the preset lacks are left in place.")
+        .option("--yes", "Apply the plan printed by the dry run. Without it this command only previews.")
+        .option("--manager <slug=type:id>", "Assign a column's owner, e.g. review=user:<ab_user uuid> or deploy=agent:<agent uuid> (repeatable). " +
+        "A preset cannot carry an owner, so without this the column is reported unowned — never given one OPVS invented.", (val, prev) => prev.concat([val]), [])
+        .option("--json", "Print exactly ONE JSON document on stdout: the dry-run plan, or with --yes the APPLIED plan (the preview is not printed).")
+        .action(async (board, preset, opts) => {
+        const wsSlug = program.opts().workspace;
+        let client;
+        try {
+            client = createClient(wsSlug);
+        }
+        catch (err) {
+            reportPresetError(err, "Failed to preview preset");
+            return;
+        }
+        const url = `/api/v1/board/boards/${board}/apply-preset`;
+        const managers = parseManagers(opts.manager ?? []);
+        // Only send `managers` when given, so the body without the flag is
+        // byte-identical to what the route documents as its default.
+        const request = (mode) => Object.keys(managers).length ? { preset, mode, managers } : { preset, mode };
+        let plan;
+        try {
+            // Always dry-run first, even with --yes: the operator sees the per-column
+            // card counts for THIS run before anything is written.
+            const res = await client.post(url, request("dry_run"));
+            plan = (await res.json());
+        }
+        catch (err) {
+            reportPresetError(err, "Failed to preview preset");
+            return;
+        }
+        if (!opts.yes) {
+            if (opts.json)
+                printJson(plan);
+            else
+                console.log(renderPresetPlan(plan));
+            console.error("Dry run only — nothing was written. Re-run with --yes to apply this plan.");
+            return;
+        }
+        // ASP-118 F10: with --json, stdout carries ONE document — the applied
+        // plan below. Printing the preview too made `| jq` see two objects and a
+        // strict JSON.parse of stdout throw.
+        if (!opts.json)
+            console.log(renderPresetPlan(plan));
+        let applied;
+        try {
+            const res = await client.post(url, request("apply"));
+            applied = (await res.json());
+        }
+        catch (err) {
+            reportPresetError(err, "Failed to apply preset");
+            return;
+        }
+        // Text mode used to print only the preview, so a drifted apply was
+        // indistinguishable from the plan on screen. What was written is printed
+        // too — its header reads APPLIED, the preview's DRY RUN.
+        if (opts.json)
+            printJson(applied);
+        else
+            console.log(renderPresetPlan(applied));
+        if (!applied.applied) {
+            console.error("Error: the server did not apply the preset (applied: false).");
+            process.exit(1);
+        }
+        console.error(`Applied preset ${preset} to board ${board}.`);
+        const drift = presetPlanDrift(plan, applied);
+        if (drift.length) {
+            console.error("Warning: what was APPLIED differs from the dry run taken just before it (the board changed in between). " +
+                "The applied plan is what happened:");
+            for (const line of drift)
+                console.error(`  - ${line}`);
+        }
+        // factory-full on a board in no project is the ORP-6 trap (ASP-113).
+        await warnIfFactoryUnresolved(client, board);
+    });
     // ── Export (A.15) ──────────────────────────────────────────────
     // Read-only board → Markdown snapshot. Output is deterministic — same
     // board state → same bytes — so it's safe to commit and diff.
@@ -178,4 +668,56 @@ export function registerBoardCommands(program) {
         }
     });
 }
+/**
+ * A project id must be a UUID: the body field is `project_id: UUID` and no hop
+ * resolves anything else, so a name would be a bare 422. Say what to run instead.
+ */
+function requireProjectUuid(projectId) {
+    if (!isUuid(projectId)) {
+        console.error(`Error: project must be a UUID (got '${projectId}'). Find it with \`opvs projects list\`.`);
+        process.exit(1);
+    }
+}
+/**
+ * A blocking preset conflict is a 409 in BOTH modes, carrying the conflict list
+ * in `detail`. Print the list — "409 Conflict" alone tells the operator nothing
+ * about which column to fix.
+ */
+function reportPresetError(err, fallback) {
+    const e = err;
+    const detail = e.body?.detail;
+    if (e.status === 409 && detail && typeof detail === "object" && Array.isArray(detail.conflicts)) {
+        console.error(`Error: ${detail.message ?? "preset cannot be applied"}`);
+        for (const k of detail.conflicts) {
+            console.error(`  ${k.blocking === false ? "NON-BLOCKING" : "BLOCKING"}  ${k.slug}  ${k.code} — ${k.detail}`);
+        }
+    }
+    else {
+        console.error(`Error: ${e.detail || fallback}`);
+    }
+    process.exit(1);
+}
+/**
+ * Parse repeatable `--manager slug=type:id` into the `managers` map
+ * `ApplyPresetRequest` takes. The shape is checked here because the server's
+ * coherence rule (a `user` needs `managed_by_user_id`, an `agent` needs
+ * `managed_by_agent_id`) is exactly what a hand-typed flag gets wrong, and a
+ * whole-request 422 names the field path rather than the flag.
+ */
+export function parseManagers(raw) {
+    const out = {};
+    for (const item of raw) {
+        const m = /^([a-z0-9_-]+)=(user|agent):(.+)$/.exec(item.trim());
+        if (!m || !isUuid(m[3])) {
+            console.error(`Error: --manager expects <slug>=<user|agent>:<uuid>, e.g. review=user:<uuid> (got '${item}')`);
+            process.exit(1);
+        }
+        const [, slug, type, id] = m;
+        out[slug] =
+            type === "user"
+                ? { managed_by_type: "user", managed_by_user_id: id }
+                : { managed_by_type: "agent", managed_by_agent_id: id };
+    }
+    return out;
+}
 //# sourceMappingURL=boards.js.map