monday-cli 0.2.0 → 0.4.0

package/dist/api/board-favorites.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Board-favorites resolver for the v0.3-M23 `monday board favorites`
+ * verb + the `monday item search --favorites` cross-board scoping
+ * lever (`cli-design.md` §13 v0.3 entry).
+ *
+ * **Empirical probe findings (2026-05-11, against `api.monday.com`,
+ * API version `2026-01`) — `scripts/probe/m23-favorites*.ts` +
+ * `scripts/probe/m23-hierarchy-*.ts`:**
+ *
+ *   - **Favorites lives at the TOP-LEVEL `Query.favorites:
+ *     [GraphqlHierarchyObjectItem!]`** — NOT `User.favorites` /
+ *     `Board.is_starred` / `me { favorites }`. The original M23
+ *     pre-decision wording ("current user's starred boards") was
+ *     directionally correct but the surface lives on the Query
+ *     root, not the User type.
+ *   - **Polymorphic element shape.** Each `GraphqlHierarchyObjectItem`
+ *     carries `id` (hierarchy-item ID, distinct from the underlying
+ *     object ID), `accountId`, `object: { id: ID, type:
+ *     GraphqlMondayObject }` (enum: `Board` | `Folder` |
+ *     `Dashboard` | `Workspace`), `folderId`, `position` (Float —
+ *     Monday's UI sort order), `createdAt`, `updatedAt`. The
+ *     hierarchy-item ID is distinct from `object.id`; the latter
+ *     is the underlying Board ID when `object.type === Board`.
+ *   - **2-stage GraphQL operation.** Stage 1 fetches `Query.
+ *     favorites { id object { id type } position }` and filters
+ *     client-side to `object.type === Board`. Stage 2 hydrates the
+ *     surviving board IDs via
+ *     `boards(ids: [<board-typed-ids>]) { id name workspace_id
+ *     state url }` for human-readable + agent-useful slots.
+ *   - **Order by `position` (Float).** The probe's `position` field
+ *     is Monday's UI sidebar order (lower = higher in the list).
+ *     `monday board favorites` sorts by `position` ascending for
+ *     parity with what users see in Monday's UI.
+ *   - **No write surface in v0.3.** The probe did NOT enumerate
+ *     mutations under `Mutation` for favorite/unfavorite — the v0.3
+ *     scope is READ-ONLY (`board favorites` lists; the
+ *     `item search --favorites` flag consumes the list as a scoping
+ *     filter). Writes (`board favorite <bid>` / `board unfavorite
+ *     <bid>`) are a v0.4+ candidate.
+ *
+ * **Sharing with `item search --favorites`.** Both verbs share the
+ * favorites-resolver. `monday board favorites` emits the full
+ * 2-stage hydrate output (id + name + workspace_id + state + url);
+ * `monday item search --favorites` consumes only the board IDs
+ * (Stage 1 filter result) since the cross-board fan-out hydrates
+ * board names inline via the same `boards(ids:)` call.
+ *
+ * **What's stub vs runtime at the pre-flight.** `fetchBoardFavorites`
+ * ships as a `Promise.reject(internal_error)` stub under `c8 ignore
+ * start/stop` — M23 implementation lands the runtime 2-stage body.
+ * The schema definitions, type exports, the GraphQL document
+ * constants, the pure-helper `filterFavoritesToBoardIds`, and the
+ * `sortByPosition` projection ship as REAL implementations so the
+ * pre-flight Codex review can verify the projection shape against
+ * the empirical-probe fixtures inline.
+ *
+ * **Mirrors M22 `monday usage` shape.** M22's `fetchUsage` runs a
+ * 2-stage projection (`platform_api.daily_limit` +
+ * `platform_api.daily_analytics`); `fetchBoardFavorites` runs a
+ * 2-stage filter+hydrate. The pre-flight pattern (schema + pure
+ * helper as real impl, async fetcher as stub) is the same.
+ */
+import { z } from 'zod';
+import type { MondayClient } from './client.js';
+import type { Complexity } from '../utils/output/envelope.js';
+/**
+ * Monday's `GraphqlMondayObject` enum discriminator on
+ * `HierarchyObjectID.type`. Empirically confirmed via
+ * `scripts/probe/m23-monday-object-enum.ts` at 2026-05-11 against
+ * API `2026-01`. Includes non-Board kinds because Monday's UI
+ * favorites bar includes docs / dashboards / folders / workspaces;
+ * the M23 `board favorites` verb FILTERS to `Board` only.
+ *
+ * Schema kept open-ended (`z.string()` not `z.enum`) to forward-
+ * compatibly absorb future Monday enum additions; the filter step
+ * matches the LITERAL `Board` string so an unrecognised kind is
+ * just "not a board, skip" rather than a parse error.
+ */
+export declare const HIERARCHY_OBJECT_TYPE_BOARD: "Board";
+/**
+ * Stage-1 GraphQL document — fetches the polymorphic favorites
+ * list. No args (`Query.favorites: [GraphqlHierarchyObjectItem!]`
+ * empirically has zero args per the introspection probe).
+ *
+ * The selection set is the minimum the M23 verbs need:
+ *   - `id` of the hierarchy item (NOT used downstream — Monday's
+ *     surrogate identifier; logged for traceability).
+ *   - `object { id type }` — the discriminator + underlying object
+ *     ID. The `id` here is the Board ID when `type === Board`.
+ *   - `position` — Monday's UI sort key (Float).
+ *
+ * Not selected: `accountId`, `folderId`, `createdAt`, `updatedAt`
+ * — neither verb uses them; selecting widens the response payload
+ * for marginal benefit. Future v0.4 may add `createdAt` /
+ * `updatedAt` if a "favorited since" filter ships.
+ */
+export declare const FAVORITES_LIST_QUERY = "\n  query BoardFavoritesStage1 {\n    favorites {\n      id\n      object { id type }\n      position\n    }\n  }\n";
+/**
+ * Stage-2 GraphQL document — hydrates the surviving board IDs from
+ * Stage 1. The `boards(ids:)` surface silently omits inaccessible
+ * board IDs (per `scripts/probe/m23-cross-board-search-2.ts` finding
+ * #3); the favorites case is one path where silent-omission is the
+ * EXPECTED behaviour (the user removed access to a board after
+ * favoriting it; we don't want to crash the verb). The hydrator
+ * surfaces this as the count delta on the `board_favorites_stale`
+ * warning per {@link buildStaleFavoritesWarning}.
+ *
+ * **Codex P1-1 fix.** The query selects ONLY the leaf board fields
+ * `monday board favorites` projects — `complexity` is NOT selected
+ * here. Per the project's complexity-injection contract
+ * (`src/api/client.ts:257-307` `MondayClient.raw`), the
+ * `complexity { ... }` selection is injected at the operation root
+ * ONLY when `--verbose` is on, and parsed back out via
+ * `parseComplexity`. Hard-coding `complexity` here would (a) leak
+ * the field into non-verbose responses (cli-design §6.1 pins
+ * `meta.complexity: null` outside `--verbose`), and (b) inflate the
+ * per-call cost for every favorites read. The verbose path injects
+ * via MondayClient automatically.
+ */
+export declare const BOARDS_HYDRATE_QUERY = "\n  query BoardFavoritesStage2($ids: [ID!]!) {\n    boards(ids: $ids) {\n      id\n      name\n      state\n      workspace_id\n      url\n    }\n  }\n";
+/**
+ * One favorites entry post-Stage-1 parse. The `object.type` field is
+ * the polymorphic-favorites discriminator; `object.id` is the
+ * underlying object's ID (Board ID when `type === Board`).
+ */
+export interface RawFavoriteEntry {
+    readonly id: string;
+    readonly object: {
+        readonly id: string;
+        readonly type: string;
+    };
+    readonly position: number;
+}
+export declare const rawFavoriteEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    object: z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strict>;
+    position: z.ZodNumber;
+}, z.core.$strict>;
+export declare const favoritesListResponseSchema: z.ZodObject<{
+    favorites: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        object: z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strict>;
+        position: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$loose>;
+export type FavoritesListResponse = z.infer<typeof favoritesListResponseSchema>;
+/**
+ * One hydrated board after Stage 2. Matches Monday's `boards(ids:)`
+ * selection set on the wire.
+ */
+export interface RawHydratedBoard {
+    readonly id: string;
+    readonly name: string;
+    readonly state: string | null;
+    readonly workspace_id: string | null;
+    readonly url: string | null;
+}
+export declare const rawHydratedBoardSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    workspace_id: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const boardsHydrateResponseSchema: z.ZodObject<{
+    boards: z.ZodNullable<z.ZodArray<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        state: z.ZodNullable<z.ZodString>;
+        workspace_id: z.ZodNullable<z.ZodString>;
+        url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>>;
+}, z.core.$loose>;
+export type BoardsHydrateResponse = z.infer<typeof boardsHydrateResponseSchema>;
+/**
+ * One row in the `monday board favorites` output. The `position`
+ * slot carries Monday's UI sort key for parity — the output is
+ * sorted by `position` ascending so agents see the same order
+ * users see.
+ */
+export interface BoardFavoriteOutput {
+    readonly id: string;
+    readonly name: string;
+    readonly state: string | null;
+    readonly workspace_id: string | null;
+    readonly url: string | null;
+    readonly position: number;
+}
+export declare const boardFavoriteOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    workspace_id: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    position: z.ZodNumber;
+}, z.core.$strict>;
+export declare const boardFavoritesOutputSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    workspace_id: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    position: z.ZodNumber;
+}, z.core.$strict>>;
+export type BoardFavoritesOutput = z.infer<typeof boardFavoritesOutputSchema>;
+/**
+ * Warning the resolver surfaces when Stage 1 returned N favorite
+ * board entries but Stage 2 hydrated fewer (because the user lost
+ * access to a board after favoriting it, or the board was deleted).
+ * Not fatal — the verb still returns the boards Stage 2 hydrated.
+ */
+export interface StaleFavoritesWarning {
+    readonly code: 'board_favorites_stale';
+    readonly message: string;
+    readonly details: {
+        readonly favorited_count: number;
+        readonly hydrated_count: number;
+        readonly missing_board_ids: readonly string[];
+        readonly hint: string;
+    };
+}
+export declare const staleFavoritesWarningSchema: z.ZodObject<{
+    code: z.ZodLiteral<"board_favorites_stale">;
+    message: z.ZodString;
+    details: z.ZodObject<{
+        favorited_count: z.ZodNumber;
+        hydrated_count: z.ZodNumber;
+        missing_board_ids: z.ZodArray<z.ZodString>;
+        hint: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * Filters {@link FavoritesListResponse} to the surviving Board-typed
+ * entries, sorted by `position` ascending for Monday-UI parity.
+ * Pure helper — **real implementation** at pre-flight (not a stub).
+ */
+export declare const filterFavoritesToBoards: (response: FavoritesListResponse) => readonly RawFavoriteEntry[];
+/**
+ * Builds a {@link StaleFavoritesWarning} from the Stage-1 / Stage-2
+ * delta. **Real implementation** at pre-flight (pure helper).
+ */
+export declare const buildStaleFavoritesWarning: (favoritedIds: readonly string[], hydratedIds: readonly string[]) => StaleFavoritesWarning;
+/**
+ * Joins the Stage-1 filtered favorites entries (carrying `position`)
+ * with the Stage-2 hydrated boards (carrying `name` / `state` /
+ * `workspace_id` / `url`) into the final {@link BoardFavoriteOutput}
+ * shape. Pure helper — **real implementation** at pre-flight.
+ *
+ * Result is sorted by `position` ascending (input order from
+ * {@link filterFavoritesToBoards}); rows where Stage 2 didn't
+ * hydrate (silently omitted by `boards(ids:)`) are filtered out and
+ * surfaced via {@link buildStaleFavoritesWarning} at the caller.
+ */
+export declare const joinFavoritesWithBoards: (filteredFavorites: readonly RawFavoriteEntry[], hydratedBoards: readonly RawHydratedBoard[]) => readonly BoardFavoriteOutput[];
+/**
+ * Inputs to {@link fetchBoardFavorites}.
+ *
+ * **Codex P1-1 fix.** Takes the {@link MondayClient} (not
+ * `Transport`) so the resolver inherits the project's `--retry` +
+ * `--verbose`-complexity contract automatically. MondayClient owns
+ * the AbortSignal end-to-end; no per-call `signal` slot needed.
+ */
+export interface FetchBoardFavoritesInputs {
+    readonly client: MondayClient;
+}
+/**
+ * Result of the 2-stage favorites resolver. Carries the hydrated
+ * board rows + the optional warning + the per-call envelope-meta
+ * fields the command-action emits.
+ *
+ * **Codex P1-1 fix.** `complexity` is now `Complexity | null` from
+ * `src/utils/output/envelope.ts` (matches the project-wide envelope
+ * shape on `meta.complexity`); the previous bespoke shape was
+ * redundant with the canonical envelope type. `source` /
+ * `cacheAgeSeconds` are added so the command-action emits a fully
+ * correct §6.1 collection envelope. Favorites is a pure read with
+ * no per-call cache; both stages always hit live, so `source` is
+ * fixed at `'live'` and `cacheAgeSeconds` at `null`.
+ */
+export interface FetchBoardFavoritesResult {
+    readonly boards: readonly BoardFavoriteOutput[];
+    readonly warnings: readonly StaleFavoritesWarning[];
+    readonly source: 'live';
+    readonly cacheAgeSeconds: null;
+    readonly complexity: Complexity | null;
+}
+/**
+ * Issues the 2-stage favorites resolver against `inputs.client`.
+ *
+ * Stage 1: `FAVORITES_LIST_QUERY` → parse via
+ * `favoritesListResponseSchema` → filter via
+ * {@link filterFavoritesToBoards} (kind === Board, sort by
+ * `position` ascending).
+ *
+ * Stage 2: `BOARDS_HYDRATE_QUERY` with the filtered Stage-1 IDs →
+ * parse via `boardsHydrateResponseSchema` → join via
+ * {@link joinFavoritesWithBoards}.
+ *
+ * Stage-1/Stage-2 count delta surfaces a
+ * {@link StaleFavoritesWarning} on `result.warnings`.
+ *
+ * **Edge case: empty favorites.** When Stage 1 returns no Board-
+ * typed entries (or the favorites list is empty/null) the helper
+ * short-circuits — no Stage-2 call, empty `boards` output, no
+ * warnings. The verb-level envelope is success with an empty
+ * `data` array; agents detect via `data.length === 0`.
+ *
+ * **Parse-failure handling.** A schema mismatch on either stage
+ * surfaces `internal_error` with `details.issues` carrying the
+ * per-field zod path — a parse failure means Monday amended the
+ * surface (forward-compat additions pass through the `.loose()`
+ * wrappers; this catches the type-mismatch shapes that the v0.3
+ * surface doesn't tolerate).
+ *
+ * **Complexity / source.** The result's `complexity` is the last
+ * stage's value (Stage 2 when it runs, Stage 1 otherwise) — under
+ * `--verbose` MondayClient.raw injects + parses `complexity { ... }`
+ * at the operation root and returns it on the `MondayResponse`.
+ * `source: 'live'` + `cacheAgeSeconds: null` are constants per the
+ * P1-1 contract — favorites is a pure live read.
+ */
+export declare const fetchBoardFavorites: (inputs: FetchBoardFavoritesInputs) => Promise<FetchBoardFavoritesResult>;
+//# sourceMappingURL=board-favorites.d.ts.map

package/dist/api/board-favorites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-favorites.d.ts","sourceRoot":"","sources":["../../src/api/board-favorites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,EAAG,OAAgB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,wHAQhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,4JAUhC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,sBAAsB;;;;;;;kBAexB,CAAC;AAEZ,eAAO,MAAM,2BAA2B;;;;;;;;;iBAO9B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,eAAO,MAAM,sBAAsB;;;;;;kBAQxB,CAAC;AAEZ,eAAO,MAAM,2BAA2B;;;;;;;;iBAI9B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,yBAAyB;;;;;;;kBAS3B,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;mBAAqC,CAAC;AAC7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,eAAO,MAAM,2BAA2B;;;;;;;;;kBAa7B,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,UAAU,qBAAqB,KAC9B,SAAS,gBAAgB,EAW3B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GACrC,cAAc,SAAS,MAAM,EAAE,EAC/B,aAAa,SAAS,MAAM,EAAE,KAC7B,qBAaF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAClC,mBAAmB,SAAS,gBAAgB,EAAE,EAC9C,gBAAgB,SAAS,gBAAgB,EAAE,KAC1C,SAAS,mBAAmB,EAgB9B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,yBAAyB,KAChC,OAAO,CAAC,yBAAyB,CA2EnC,CAAC"}

package/dist/api/board-favorites.js

@@ -0,0 +1,353 @@
+/**
+ * Board-favorites resolver for the v0.3-M23 `monday board favorites`
+ * verb + the `monday item search --favorites` cross-board scoping
+ * lever (`cli-design.md` §13 v0.3 entry).
+ *
+ * **Empirical probe findings (2026-05-11, against `api.monday.com`,
+ * API version `2026-01`) — `scripts/probe/m23-favorites*.ts` +
+ * `scripts/probe/m23-hierarchy-*.ts`:**
+ *
+ *   - **Favorites lives at the TOP-LEVEL `Query.favorites:
+ *     [GraphqlHierarchyObjectItem!]`** — NOT `User.favorites` /
+ *     `Board.is_starred` / `me { favorites }`. The original M23
+ *     pre-decision wording ("current user's starred boards") was
+ *     directionally correct but the surface lives on the Query
+ *     root, not the User type.
+ *   - **Polymorphic element shape.** Each `GraphqlHierarchyObjectItem`
+ *     carries `id` (hierarchy-item ID, distinct from the underlying
+ *     object ID), `accountId`, `object: { id: ID, type:
+ *     GraphqlMondayObject }` (enum: `Board` | `Folder` |
+ *     `Dashboard` | `Workspace`), `folderId`, `position` (Float —
+ *     Monday's UI sort order), `createdAt`, `updatedAt`. The
+ *     hierarchy-item ID is distinct from `object.id`; the latter
+ *     is the underlying Board ID when `object.type === Board`.
+ *   - **2-stage GraphQL operation.** Stage 1 fetches `Query.
+ *     favorites { id object { id type } position }` and filters
+ *     client-side to `object.type === Board`. Stage 2 hydrates the
+ *     surviving board IDs via
+ *     `boards(ids: [<board-typed-ids>]) { id name workspace_id
+ *     state url }` for human-readable + agent-useful slots.
+ *   - **Order by `position` (Float).** The probe's `position` field
+ *     is Monday's UI sidebar order (lower = higher in the list).
+ *     `monday board favorites` sorts by `position` ascending for
+ *     parity with what users see in Monday's UI.
+ *   - **No write surface in v0.3.** The probe did NOT enumerate
+ *     mutations under `Mutation` for favorite/unfavorite — the v0.3
+ *     scope is READ-ONLY (`board favorites` lists; the
+ *     `item search --favorites` flag consumes the list as a scoping
+ *     filter). Writes (`board favorite <bid>` / `board unfavorite
+ *     <bid>`) are a v0.4+ candidate.
+ *
+ * **Sharing with `item search --favorites`.** Both verbs share the
+ * favorites-resolver. `monday board favorites` emits the full
+ * 2-stage hydrate output (id + name + workspace_id + state + url);
+ * `monday item search --favorites` consumes only the board IDs
+ * (Stage 1 filter result) since the cross-board fan-out hydrates
+ * board names inline via the same `boards(ids:)` call.
+ *
+ * **What's stub vs runtime at the pre-flight.** `fetchBoardFavorites`
+ * ships as a `Promise.reject(internal_error)` stub under `c8 ignore
+ * start/stop` — M23 implementation lands the runtime 2-stage body.
+ * The schema definitions, type exports, the GraphQL document
+ * constants, the pure-helper `filterFavoritesToBoardIds`, and the
+ * `sortByPosition` projection ship as REAL implementations so the
+ * pre-flight Codex review can verify the projection shape against
+ * the empirical-probe fixtures inline.
+ *
+ * **Mirrors M22 `monday usage` shape.** M22's `fetchUsage` runs a
+ * 2-stage projection (`platform_api.daily_limit` +
+ * `platform_api.daily_analytics`); `fetchBoardFavorites` runs a
+ * 2-stage filter+hydrate. The pre-flight pattern (schema + pure
+ * helper as real impl, async fetcher as stub) is the same.
+ */
+import { z } from 'zod';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+/**
+ * Monday's `GraphqlMondayObject` enum discriminator on
+ * `HierarchyObjectID.type`. Empirically confirmed via
+ * `scripts/probe/m23-monday-object-enum.ts` at 2026-05-11 against
+ * API `2026-01`. Includes non-Board kinds because Monday's UI
+ * favorites bar includes docs / dashboards / folders / workspaces;
+ * the M23 `board favorites` verb FILTERS to `Board` only.
+ *
+ * Schema kept open-ended (`z.string()` not `z.enum`) to forward-
+ * compatibly absorb future Monday enum additions; the filter step
+ * matches the LITERAL `Board` string so an unrecognised kind is
+ * just "not a board, skip" rather than a parse error.
+ */
+export const HIERARCHY_OBJECT_TYPE_BOARD = 'Board';
+/**
+ * Stage-1 GraphQL document — fetches the polymorphic favorites
+ * list. No args (`Query.favorites: [GraphqlHierarchyObjectItem!]`
+ * empirically has zero args per the introspection probe).
+ *
+ * The selection set is the minimum the M23 verbs need:
+ *   - `id` of the hierarchy item (NOT used downstream — Monday's
+ *     surrogate identifier; logged for traceability).
+ *   - `object { id type }` — the discriminator + underlying object
+ *     ID. The `id` here is the Board ID when `type === Board`.
+ *   - `position` — Monday's UI sort key (Float).
+ *
+ * Not selected: `accountId`, `folderId`, `createdAt`, `updatedAt`
+ * — neither verb uses them; selecting widens the response payload
+ * for marginal benefit. Future v0.4 may add `createdAt` /
+ * `updatedAt` if a "favorited since" filter ships.
+ */
+export const FAVORITES_LIST_QUERY = `
+  query BoardFavoritesStage1 {
+    favorites {
+      id
+      object { id type }
+      position
+    }
+  }
+`;
+/**
+ * Stage-2 GraphQL document — hydrates the surviving board IDs from
+ * Stage 1. The `boards(ids:)` surface silently omits inaccessible
+ * board IDs (per `scripts/probe/m23-cross-board-search-2.ts` finding
+ * #3); the favorites case is one path where silent-omission is the
+ * EXPECTED behaviour (the user removed access to a board after
+ * favoriting it; we don't want to crash the verb). The hydrator
+ * surfaces this as the count delta on the `board_favorites_stale`
+ * warning per {@link buildStaleFavoritesWarning}.
+ *
+ * **Codex P1-1 fix.** The query selects ONLY the leaf board fields
+ * `monday board favorites` projects — `complexity` is NOT selected
+ * here. Per the project's complexity-injection contract
+ * (`src/api/client.ts:257-307` `MondayClient.raw`), the
+ * `complexity { ... }` selection is injected at the operation root
+ * ONLY when `--verbose` is on, and parsed back out via
+ * `parseComplexity`. Hard-coding `complexity` here would (a) leak
+ * the field into non-verbose responses (cli-design §6.1 pins
+ * `meta.complexity: null` outside `--verbose`), and (b) inflate the
+ * per-call cost for every favorites read. The verbose path injects
+ * via MondayClient automatically.
+ */
+export const BOARDS_HYDRATE_QUERY = `
+  query BoardFavoritesStage2($ids: [ID!]!) {
+    boards(ids: $ids) {
+      id
+      name
+      state
+      workspace_id
+      url
+    }
+  }
+`;
+export const rawFavoriteEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    object: z
+        .object({
+        id: z.string().min(1),
+        // Open-ended `z.string()` so a future Monday enum extension
+        // (e.g., `Form`, `Workdoc`, etc.) doesn't break the parse
+        // — the filter step matches the literal `Board` string
+        // so unrecognised kinds are just "not a board, skip".
+        type: z.string().min(1),
+    })
+        .strict(),
+    position: z.number(),
+})
+    .strict();
+export const favoritesListResponseSchema = z
+    .object({
+    favorites: z.array(rawFavoriteEntrySchema).nullable(),
+})
+    // `.loose()` so future Monday Query-root extension fields don't
+    // fail this parse. Same forward-compat policy as M22's
+    // `usageQueryResponseSchema`.
+    .loose();
+export const rawHydratedBoardSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    state: z.string().nullable(),
+    workspace_id: z.string().nullable(),
+    url: z.string().nullable(),
+})
+    .strict();
+export const boardsHydrateResponseSchema = z
+    .object({
+    boards: z.array(rawHydratedBoardSchema.nullable()).nullable(),
+})
+    .loose();
+export const boardFavoriteOutputSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    state: z.string().nullable(),
+    workspace_id: z.string().nullable(),
+    url: z.string().nullable(),
+    position: z.number(),
+})
+    .strict();
+export const boardFavoritesOutputSchema = z.array(boardFavoriteOutputSchema);
+export const staleFavoritesWarningSchema = z
+    .object({
+    code: z.literal('board_favorites_stale'),
+    message: z.string().min(1),
+    details: z
+        .object({
+        favorited_count: z.number().int().nonnegative(),
+        hydrated_count: z.number().int().nonnegative(),
+        missing_board_ids: z.array(z.string().min(1)),
+        hint: z.string().min(1),
+    })
+        .strict(),
+})
+    .strict();
+/**
+ * Filters {@link FavoritesListResponse} to the surviving Board-typed
+ * entries, sorted by `position` ascending for Monday-UI parity.
+ * Pure helper — **real implementation** at pre-flight (not a stub).
+ */
+export const filterFavoritesToBoards = (response) => {
+    const entries = response.favorites ?? [];
+    const boards = entries.filter((e) => e.object.type === HIERARCHY_OBJECT_TYPE_BOARD);
+    // Sort by position ascending; ties broken by hierarchy-item id
+    // for deterministic output across runs.
+    return [...boards].sort((a, b) => {
+        if (a.position !== b.position)
+            return a.position - b.position;
+        return a.id.localeCompare(b.id);
+    });
+};
+/**
+ * Builds a {@link StaleFavoritesWarning} from the Stage-1 / Stage-2
+ * delta. **Real implementation** at pre-flight (pure helper).
+ */
+export const buildStaleFavoritesWarning = (favoritedIds, hydratedIds) => {
+    const hydratedSet = new Set(hydratedIds);
+    const missing = favoritedIds.filter((id) => !hydratedSet.has(id));
+    return {
+        code: 'board_favorites_stale',
+        message: `${String(missing.length)} of ${String(favoritedIds.length)} favorited boards were not accessible or no longer exist`,
+        details: {
+            favorited_count: favoritedIds.length,
+            hydrated_count: hydratedIds.length,
+            missing_board_ids: missing,
+            hint: 'a favorited board was deleted, archived to a private workspace, or had access revoked since being favorited',
+        },
+    };
+};
+/**
+ * Joins the Stage-1 filtered favorites entries (carrying `position`)
+ * with the Stage-2 hydrated boards (carrying `name` / `state` /
+ * `workspace_id` / `url`) into the final {@link BoardFavoriteOutput}
+ * shape. Pure helper — **real implementation** at pre-flight.
+ *
+ * Result is sorted by `position` ascending (input order from
+ * {@link filterFavoritesToBoards}); rows where Stage 2 didn't
+ * hydrate (silently omitted by `boards(ids:)`) are filtered out and
+ * surfaced via {@link buildStaleFavoritesWarning} at the caller.
+ */
+export const joinFavoritesWithBoards = (filteredFavorites, hydratedBoards) => {
+    const byId = new Map(hydratedBoards.map((b) => [b.id, b]));
+    const out = [];
+    for (const fav of filteredFavorites) {
+        const board = byId.get(fav.object.id);
+        if (board === undefined)
+            continue; // stale; warning surfaced at the action
+        out.push({
+            id: board.id,
+            name: board.name,
+            state: board.state,
+            workspace_id: board.workspace_id,
+            url: board.url,
+            position: fav.position,
+        });
+    }
+    return out;
+};
+/**
+ * Issues the 2-stage favorites resolver against `inputs.client`.
+ *
+ * Stage 1: `FAVORITES_LIST_QUERY` → parse via
+ * `favoritesListResponseSchema` → filter via
+ * {@link filterFavoritesToBoards} (kind === Board, sort by
+ * `position` ascending).
+ *
+ * Stage 2: `BOARDS_HYDRATE_QUERY` with the filtered Stage-1 IDs →
+ * parse via `boardsHydrateResponseSchema` → join via
+ * {@link joinFavoritesWithBoards}.
+ *
+ * Stage-1/Stage-2 count delta surfaces a
+ * {@link StaleFavoritesWarning} on `result.warnings`.
+ *
+ * **Edge case: empty favorites.** When Stage 1 returns no Board-
+ * typed entries (or the favorites list is empty/null) the helper
+ * short-circuits — no Stage-2 call, empty `boards` output, no
+ * warnings. The verb-level envelope is success with an empty
+ * `data` array; agents detect via `data.length === 0`.
+ *
+ * **Parse-failure handling.** A schema mismatch on either stage
+ * surfaces `internal_error` with `details.issues` carrying the
+ * per-field zod path — a parse failure means Monday amended the
+ * surface (forward-compat additions pass through the `.loose()`
+ * wrappers; this catches the type-mismatch shapes that the v0.3
+ * surface doesn't tolerate).
+ *
+ * **Complexity / source.** The result's `complexity` is the last
+ * stage's value (Stage 2 when it runs, Stage 1 otherwise) — under
+ * `--verbose` MondayClient.raw injects + parses `complexity { ... }`
+ * at the operation root and returns it on the `MondayResponse`.
+ * `source: 'live'` + `cacheAgeSeconds: null` are constants per the
+ * P1-1 contract — favorites is a pure live read.
+ */
+export const fetchBoardFavorites = async (inputs) => {
+    // Stage 1 — fetch the polymorphic favorites list.
+    const stage1 = await inputs.client.raw(FAVORITES_LIST_QUERY, undefined, { operationName: 'BoardFavoritesStage1' });
+    // R-NEW-19 lift — `unwrapOrThrow` produces the canonical
+    // `internal_error` + `details.issues` shape (path + message +
+    // zod code per failing field); the manual block here was the
+    // same shape minus the `code` slot.
+    const stage1Data = unwrapOrThrow(favoritesListResponseSchema.safeParse(stage1.data), {
+        context: 'Monday `Query.favorites` response',
+        hint: 'Monday may have amended the `Query.favorites` surface — re-probe via `scripts/probe/m23-favorites-deep.ts` and amend cli-design §13 v0.3 entry if so',
+    });
+    // Filter to Board-typed entries + sort by `position` ascending
+    // for Monday-UI parity. Drops Folder / Dashboard / Workspace and
+    // any future enum extension (open-ended `z.string()` on
+    // `object.type` is forward-compat).
+    const filtered = filterFavoritesToBoards(stage1Data);
+    // Empty short-circuit — no Stage 2 if there are no Board-typed
+    // favorites. Stage 1's complexity carries forward.
+    if (filtered.length === 0) {
+        return {
+            boards: [],
+            warnings: [],
+            source: 'live',
+            cacheAgeSeconds: null,
+            complexity: stage1.complexity,
+        };
+    }
+    // Stage 2 — hydrate the surviving board IDs.
+    const filteredIds = filtered.map((e) => e.object.id);
+    const stage2 = await inputs.client.raw(BOARDS_HYDRATE_QUERY, { ids: filteredIds }, { operationName: 'BoardFavoritesStage2' });
+    const stage2Data = unwrapOrThrow(boardsHydrateResponseSchema.safeParse(stage2.data), {
+        context: 'Monday `boards(ids:)` response',
+        hint: 'Monday may have amended the `boards(ids:)` selection — re-probe via `scripts/probe/m23-favorites-deep.ts` and amend cli-design §13 v0.3 entry if so',
+    });
+    // Monday's `boards(ids:)` typically silently omits inaccessible
+    // entries (per the cross-board probe finding); the schema's
+    // `.nullable()` on each entry is defensive for accounts where
+    // Monday returns null placeholders instead of omitting. Drop
+    // nulls — the favorites case treats both shapes as "stale".
+    const hydrated = (stage2Data.boards ?? []).filter((b) => b !== null);
+    const joined = joinFavoritesWithBoards(filtered, hydrated);
+    const hydratedIds = hydrated.map((b) => b.id);
+    const warnings = [];
+    if (hydratedIds.length < filteredIds.length) {
+        warnings.push(buildStaleFavoritesWarning(filteredIds, hydratedIds));
+    }
+    return {
+        boards: joined,
+        warnings,
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: stage2.complexity,
+    };
+};
+//# sourceMappingURL=board-favorites.js.map