@opvs-ai/cli 0.15.0 → 0.16.0

package/dist/lib/factory-gate.js

@@ -0,0 +1,65 @@
+/**
+ * The factory project gate, said out loud where a command can trip it (ASP-113).
+ *
+ * Since ORP-6 (#1612) `ClaimService` refuses EVERY claim on a `factory` board
+ * that is not in exactly one ACTIVE project — `{task_id: null, reason:
+ * "board_project_unresolved", project_unresolved_reason: "none" | "ambiguous"}`.
+ * It is unconditional, has no flag, and runs before the candidate scan, so a
+ * factory that is wired perfectly still builds nothing.
+ *
+ * "Active" is `_active_project_claim_predicate` (agentboard
+ * `board_group_service.py`): not deleted and NOT ARCHIVED. `status`
+ * (on_hold / completed) does not count — so archiving a project can drop a board
+ * to `none`, and unarchiving can make one `ambiguous`.
+ *
+ * Several CLI commands can put a board into that state, and until this module
+ * none of them said so. The check lives here, in `lib/`, and not inline in each
+ * command: it READS `/boards/{id}/projects`, and a command file that also POSTs
+ * to a sibling path would read to the surface-parity gate as calling that
+ * route (its parser pairs every verb with every URL in a command).
+ */
+/** One sentence, shared by every help string that needs it. */
+export const FACTORY_PROJECT_GATE = "A FACTORY board must be in exactly ONE active (unarchived) project, or every claim on it is refused " +
+    "(reason board_project_unresolved) and the factory builds nothing.";
+/**
+ * After a write that can change a board's project membership or type, read the
+ * server's verdict and warn on stderr when a factory board no longer resolves.
+ *
+ * Best-effort by design: the write already succeeded, so a failed READ must not
+ * turn the command red — it says it could not check instead of staying silent,
+ * because silence here is the exact defect this exists to remove.
+ *
+ * @returns the resolution it read (`none` | `resolved` | `ambiguous`) for a
+ *          factory board, `null` for any other board type or when it could not tell.
+ */
+export async function warnIfFactoryUnresolved(client, boardId) {
+    let boardType;
+    let resolution;
+    let count;
+    try {
+        const board = (await (await client.get(`/api/v1/board/boards/${boardId}`)).json());
+        boardType = board?.board_type;
+        if (boardType !== "factory")
+            return null;
+        const projects = (await (await client.get(`/api/v1/board/boards/${boardId}/projects`)).json());
+        resolution = projects?.resolution;
+        count = projects?.count;
+    }
+    catch {
+        console.error(`Note: could not check whether board ${boardId} can still claim. ${FACTORY_PROJECT_GATE} ` +
+            `Check with \`opvs boards projects ${boardId}\`.`);
+        return null;
+    }
+    if (resolution === "none") {
+        console.error(`Warning: factory board ${boardId} is in NO active project, so EVERY claim on it is refused ` +
+            "(board_project_unresolved: none). Link it to one: `opvs projects add-board <project> " +
+            `${boardId}\` or \`opvs boards move-to-project ${boardId} <project> --yes\`.`);
+    }
+    else if (resolution === "ambiguous") {
+        console.error(`Warning: factory board ${boardId} is in ${count ?? "2+"} active projects, so EVERY claim on it is refused ` +
+            "(board_project_unresolved: ambiguous). Keep exactly one: " +
+            `\`opvs boards move-to-project ${boardId} <project> --yes\`.`);
+    }
+    return resolution ?? null;
+}
+//# sourceMappingURL=factory-gate.js.map

package/dist/lib/factory-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-gate.js","sourceRoot":"","sources":["../../src/lib/factory-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAC/B,sGAAsG;IACtG,mEAAmE,CAAC;AAMtE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,MAAc,EAAE,OAAe;IAC3E,IAAI,SAA6B,CAAC;IAClC,IAAI,UAA8B,CAAC;IACnC,IAAI,KAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAA4B,CAAC;QAC9G,SAAS,GAAG,KAAK,EAAE,UAAU,CAAC;QAC9B,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACzC,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,wBAAwB,OAAO,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAG5F,CAAC;QACF,UAAU,GAAG,QAAQ,EAAE,UAAU,CAAC;QAClC,KAAK,GAAG,QAAQ,EAAE,KAAK,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CACX,uCAAuC,OAAO,qBAAqB,oBAAoB,GAAG;YACxF,qCAAqC,OAAO,KAAK,CACpD,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,CAAC,KAAK,CACX,0BAA0B,OAAO,4DAA4D;YAC3F,uFAAuF;YACvF,GAAG,OAAO,uCAAuC,OAAO,qBAAqB,CAChF,CAAC;IACJ,CAAC;SAAM,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;QACtC,OAAO,CAAC,KAAK,CACX,0BAA0B,OAAO,UAAU,KAAK,IAAI,IAAI,oDAAoD;YAC1G,2DAA2D;YAC3D,iCAAiC,OAAO,qBAAqB,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,IAAI,IAAI,CAAC;AAC5B,CAAC"}

package/dist/lib/options.d.ts

@@ -29,3 +29,20 @@ export declare function oneOf<T extends string>(flag: string, raw: string | unde
  * the filter silently disappears — see `resolveBoardRefs`.
  */
 export declare function csv(raw: string | undefined): string[] | undefined;
+/**
+ * The CLEAR verb for a nullable scalar flag — a shell cannot write JSON null,
+ * and an omitted flag has to keep meaning "leave it alone". One definition:
+ * `columns`, `routing` and `tasks` used to each spell it (ASP-119 F15).
+ */
+export declare const CLEAR = "none";
+/**
+ * Strict integer flag. `parseInt("12abc")` is 12 and `parseInt("ten")` is NaN,
+ * which `JSON.stringify` sends as `null` — on a PATCH that CLEARS the field with
+ * a 200 (ASP-119: `columns update --wip-limit ten` wiped the WIP limit). So a
+ * value that is not all digits, or is below `min`, exits before anything is sent.
+ *
+ * @returns the number, or `undefined` when the flag was not given.
+ */
+export declare function intFlag(flag: string, raw: string | undefined, min: number): number | undefined;
+/** Strict `true` / `false` flag. `undefined` when not given; exits on anything else. */
+export declare function boolFlag(flag: string, raw: string | undefined): boolean | undefined;

package/dist/lib/options.js

@@ -45,4 +45,41 @@ export function csv(raw) {
         .filter((s) => s.length > 0);
     return out.length ? out : undefined;
 }
+/**
+ * The CLEAR verb for a nullable scalar flag — a shell cannot write JSON null,
+ * and an omitted flag has to keep meaning "leave it alone". One definition:
+ * `columns`, `routing` and `tasks` used to each spell it (ASP-119 F15).
+ */
+export const CLEAR = "none";
+/**
+ * Strict integer flag. `parseInt("12abc")` is 12 and `parseInt("ten")` is NaN,
+ * which `JSON.stringify` sends as `null` — on a PATCH that CLEARS the field with
+ * a 200 (ASP-119: `columns update --wip-limit ten` wiped the WIP limit). So a
+ * value that is not all digits, or is below `min`, exits before anything is sent.
+ *
+ * @returns the number, or `undefined` when the flag was not given.
+ */
+export function intFlag(flag, raw, min) {
+    if (raw === undefined)
+        return undefined;
+    const s = String(raw).trim();
+    if (!/^[0-9]+$/.test(s) || Number(s) < min || !Number.isSafeInteger(Number(s))) {
+        const shape = min === 0 ? "a non-negative integer" : min === 1 ? "a positive integer" : `an integer >= ${min}`;
+        console.error(`Error: ${flag} must be ${shape} (got '${raw}')`);
+        process.exit(1);
+    }
+    return Number(s);
+}
+/** Strict `true` / `false` flag. `undefined` when not given; exits on anything else. */
+export function boolFlag(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    const v = String(raw).trim().toLowerCase();
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    console.error(`Error: ${flag} must be true or false (got '${raw}')`);
+    process.exit(1);
+}
 //# sourceMappingURL=options.js.map

package/dist/lib/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/lib/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CACnB,IAAY,EACZ,GAAuB,EACvB,OAAqB;IAErB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,CAAE,OAA6B,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,oBAAoB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,GAAuB;IACzC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,GAAG,GAAG,GAAG;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/lib/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CACnB,IAAY,EACZ,GAAuB,EACvB,OAAqB;IAErB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,CAAE,OAA6B,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,oBAAoB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,GAAuB;IACzC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,GAAG,GAAG,GAAG;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC;AAE5B;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,GAAuB,EAAE,GAAW;IACxE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,MAAM,KAAK,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,iBAAiB,GAAG,EAAE,CAAC;QAC/G,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,YAAY,KAAK,UAAU,GAAG,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,GAAuB;IAC5D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,UAAU,IAAI,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/lib/routing.js

@@ -15,8 +15,7 @@
  * a copy is where the fourth one gets forgotten (the server says the same about
  * its own validator).
  */
-/** The CLEAR verb. The server reads a blank string as "no opinion" (062). */
-const CLEAR = "none";
+import { CLEAR } from "./options.js";
 /**
  * Build the PATCH body. Only flags given become keys — both routes are
  * `exclude_unset`, so an omitted flag leaves that default alone, and `none`

package/dist/lib/routing.js.map

@@ -1 +1 @@
-{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/lib/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,6EAA6E;AAC7E,MAAM,KAAK,GAAG,MAAM,CAAC;AASrB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,GAAuB,EAAE,EAAE;QACnD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAC9B,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,CAAC,CAAC;IACF,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAM,EACN,KAA0B;IAE1B,MAAM,KAAK,GACT,KAAK,KAAK,OAAO;QACf,CAAC,CAAC,wFAAwF;QAC1F,CAAC,CAAC,wFAAwF;YACxF,qFAAqF,CAAC;IAC5F,OAAO,GAAG;SACP,MAAM,CACL,iBAAiB,EACjB,8CAA8C,KAAK,yBAAyB,CAC7E;SACA,MAAM,CACL,mBAAmB,EACnB,+GAA+G;QAC7G,WAAW,KAAK,yBAAyB,CAC5C;SACA,MAAM,CACL,sBAAsB,EACtB,4EAA4E,KAAK,yBAAyB,CAC3G;SACA,MAAM,CACL,wBAAwB,EACxB,uDAAuD,KAAK,oDAAoD;QAC9G,8GAA8G;QAC9G,mCAAmC,CACtC,CAAC;AACN,CAAC"}
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/lib/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAWrC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,GAAuB,EAAE,EAAE;QACnD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO;QAC9B,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,CAAC,CAAC;IACF,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAM,EACN,KAA0B;IAE1B,MAAM,KAAK,GACT,KAAK,KAAK,OAAO;QACf,CAAC,CAAC,wFAAwF;QAC1F,CAAC,CAAC,wFAAwF;YACxF,qFAAqF,CAAC;IAC5F,OAAO,GAAG;SACP,MAAM,CACL,iBAAiB,EACjB,8CAA8C,KAAK,yBAAyB,CAC7E;SACA,MAAM,CACL,mBAAmB,EACnB,+GAA+G;QAC7G,WAAW,KAAK,yBAAyB,CAC5C;SACA,MAAM,CACL,sBAAsB,EACtB,4EAA4E,KAAK,yBAAyB,CAC3G;SACA,MAAM,CACL,wBAAwB,EACxB,uDAAuD,KAAK,oDAAoD;QAC9G,8GAA8G;QAC9G,mCAAmC,CACtC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opvs-ai/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "OPVS CLI \u2014 Terminal access to AgentBoard + AgentDocs for AI coding agents",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@opvs-ai/core": "^0.4.7",
+    "@opvs-ai/core": "^0.4.8",
     "commander": "^12.1.0"
   },
   "devDependencies": {