monday-cli 0.2.0 → 0.3.0

package/dist/api/response-root.d.ts

@@ -1,65 +1,111 @@
 /**
- * Response-root field assertion (R41 lift, v0.2-plan §22).
+ * Response-root field assertion (R41 + R42 lifts, v0.2-plan §22).
  *
  * Distinguishes "key absent" (response-shape drift →
  * `internal_error`, whole-call) from "value null" (resource missing
- * / can't be applied → `not_found`, per-record). Codex M14 round-2
- * F1 + round-3 F1 pinned the contract; R41 lifts the inline helpers
- * that workspace add-users / workspace remove-users / board add-
- * users each ship verbatim.
+ * / per-record idiomatic null → `not_found`, per-record). Codex M14
+ * round-2 F1 + round-3 F1 pinned the contract; R41 lifted the inline
+ * check that workspace add-users / workspace remove-users / board
+ * add-users each shipped verbatim; R42 (post-v0.2 cleanup window)
+ * extends the same helper across the ~32 single-target mutation
+ * verbs that previously conflated the two cases (or left the
+ * missing-key path silent — projector-only null-handling treated
+ * "key absent" the same as "value null").
  *
- * **Why distinct from `assertUpdateMutationPresent`**
- * (`api/update-mutation-result.ts`). M13's helper handles null /
- * undefined uniformly with `not_found` — pre-dating the M14
- * missing-root-key vs null-value distinction. R42 (retroactive
- * sweep across pre-M14 mutation verbs) handles unifying them; R41
- * stays scoped to the M14 + M15 partial-success-fan-out family.
+ * **Two modes** controlled by `nullHandling` (required — keep the
+ * caller explicit so a future site doesn't silently inherit the
+ * wrong behaviour):
  *
- * **Used by:** `commands/workspace/add-users.ts` /
- * `commands/workspace/remove-users.ts` / `commands/board/add-users.ts`.
+ * - `'caller_handles'` (single-target verbs, R42): only check key
+ *   presence. The caller's downstream projector handles null-value
+ *   per-noun semantics — most M5b/M9-M12 verbs throw `not_found`
+ *   from the projector for `null` (Monday's idiomatic missing-
+ *   payload signal); item set throws `internal_error` for `null`
+ *   per its M5b decision (an item that exists must always return a
+ *   payload from `change_*`). Either way, R42's missing-key check
+ *   surfaces FIRST and produces a uniform `internal_error` for
+ *   schema drift, regardless of the noun's null-value choice.
  *
- * **Not used by:** single-target mutation verbs (board create /
- * update / archive / delete / duplicate, workspace create / update /
- * delete) — those carry their own per-verb missing-root-key checks
- * because the contract is "every successful call returns the
- * resource" rather than "value null is a per-record path"; the
- * single-target verbs never throw `not_found` from the inline check
- * (the per-verb projector does that on the unwrapped value).
+ * - `'throw_not_found'` (partial-success-fan-out verbs, R41): also
+ *   check `data[key]` for null/undefined and throw `not_found` so
+ *   `dispatchSequential` slots it into the per-record failure
+ *   array (whereas `internal_error` propagates and aborts the
+ *   whole call). The `notFoundTarget` field shapes the not_found
+ *   message phrasing and details.
+ *
+ * **Used by:**
+ * - `'throw_not_found'` mode: `users-fan-out-mutation.ts`
+ *   (wraps board add-users / workspace add-users / workspace
+ *   remove-users via `dispatchSequential`).
+ * - `'caller_handles'` mode (R42 sweep): every single-target
+ *   mutation verb across M5b → M17 (item set / clear / update,
+ *   item create / archive / delete / duplicate / move / upsert,
+ *   update create / reply / edit / delete / toggle, board create
+ *   / update / archive / delete / duplicate / add-users, column-
+ *   create / update / delete, group-create / update / archive /
+ *   duplicate / delete). M15-M17 sites inline the check
+ *   verbatim pre-R42; the lift consolidates that boilerplate
+ *   onto this helper. Pre-M14 (M5b/M9-M12) sites had no inline
+ *   missing-key check; R42 adds it as net-new behaviour, picking
+ *   up the M14 contract distinction proactively.
+ *
+ * **Not used by:** `update clear-all` per-target dispatch — that
+ *   site uses `assertUpdateMutationPresent` (api/update-mutation-
+ *   result.ts) which has a different contract (treats null +
+ *   undefined uniformly as `not_found`, pre-dating M14's
+ *   distinction). Migrating it is a separate question for v0.3
+ *   (the two helpers may usefully merge).
  */
 export interface AssertResponseFieldPresentInputs {
-    /** The parsed response data object (after the wire-shape parse). */
-    readonly data: Readonly<Record<string, unknown>>;
-    /** The mutation root key name (e.g. `'add_users_to_board'`). */
+    /**
+     * The response data object. Accepted as `unknown` so callers can
+     * pass `response.data` (typed via per-verb wire interfaces like
+     * `ChangeSimpleResponse`) without casting at every site; the
+     * helper runtime-narrows to a `Record<string, unknown>` once.
+     */
+    readonly data: unknown;
+    /** The mutation root key name (e.g. `'archive_item'`). */
     readonly key: string;
-    /** The operation label for `internal_error` messages
-     * (e.g. `'BoardAddUsers'`). Distinct from `key` because the
-     * GraphQL operation name is human-readable PascalCase whereas
-     * `key` is the snake_case mutation field. */
+    /**
+     * The operation label for `internal_error` messages — typically
+     * the GraphQL operation name (PascalCase). Distinct from `key`
+     * (snake_case mutation field).
+     */
     readonly operationLabel: string;
-    /** The scope-id detail key (`'workspace_id'` or `'board_id'`). */
-    readonly scopeKey: string;
-    /** The scope-id value (the workspace or board ID). */
-    readonly scopeId: string;
-    /** The target-id detail key (always `'user_id'` in M14/M15
-     * partial-success-fan-out verbs; future verbs may use other
-     * targets — keep this parameterised for forward-compat). */
-    readonly targetKey: string;
-    /** The target-id value (the user ID for the current dispatch
-     * iteration). */
-    readonly targetId: string;
+    /**
+     * Detail map echoed in the `internal_error` thrown when `key` is
+     * absent. Caller supplies the full set — for two-target partial-
+     * success-fan-out verbs that's `{[scopeKey]: scopeId, [targetKey]: targetId}`;
+     * for single-target verbs it's just `{[idKey]: idValue}` (or a
+     * pair like `{board_id, item_id}` for two-tuple wire signatures).
+     * The schema-drift `hint` is appended automatically.
+     */
+    readonly details: Readonly<Record<string, unknown>>;
+    /**
+     * Behaviour when `data[key]` is null/undefined. See module doc
+     * for the per-mode contract.
+     */
+    readonly nullHandling: 'caller_handles' | 'throw_not_found';
+    /** Required iff `nullHandling === 'throw_not_found'`. */
+    readonly notFoundTarget?: {
+        readonly key: string;
+        readonly id: string;
+    };
 }
 /**
  * Throws `ApiError('internal_error')` when `key` is absent from
- * `data`; throws `ApiError('not_found')` when present but null.
- * Returns void on success. The caller's downstream code can rely
- * on `data[key]` being a non-null value after this call.
+ * `data` (schema drift). When `nullHandling === 'throw_not_found'`,
+ * also throws `ApiError('not_found')` if `data[key]` is null /
+ * undefined (per-record idiomatic missing). Returns void on success.
  *
  * Distinct error codes per the M14 round-2 F1 / round-3 F1
- * contract — `dispatchSequential` re-throws `internal_error`
- * (whole-call schema drift) but lets `not_found` land in the
- * per-record slot. Without this distinction, a per-record
- * not_found could be produced from a schema-drift response,
- * masking the contract violation.
+ * contract — `dispatchSequential` re-throws `internal_error` (whole-
+ * call schema drift) but lets `not_found` land in the per-record
+ * slot. Without this distinction, a per-record not_found could be
+ * produced from a schema-drift response, masking the contract
+ * violation; agents writing recovery loops keyed off `error.code`
+ * would treat schema drift as "this resource doesn't exist" and
+ * skip the failure rather than reporting it.
  */
 export declare const assertResponseFieldPresent: (inputs: AssertResponseFieldPresentInputs) => void;
 //# sourceMappingURL=response-root.d.ts.map

package/dist/api/response-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-root.d.ts","sourceRoot":"","sources":["../../src/api/response-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,MAAM,WAAW,gCAAgC;IAC/C,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;iDAG6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;gEAE4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;qBACiB;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,GACrC,QAAQ,gCAAgC,KACvC,IA2BF,CAAC"}
+{"version":3,"file":"response-root.d.ts","sourceRoot":"","sources":["../../src/api/response-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AASH,MAAM,WAAW,gCAAgC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IAC5D,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,QAAQ,gCAAgC,KACvC,IAsDF,CAAC"}

package/dist/api/response-root.js

@@ -1,61 +1,113 @@
 /**
- * Response-root field assertion (R41 lift, v0.2-plan §22).
+ * Response-root field assertion (R41 + R42 lifts, v0.2-plan §22).
  *
  * Distinguishes "key absent" (response-shape drift →
  * `internal_error`, whole-call) from "value null" (resource missing
- * / can't be applied → `not_found`, per-record). Codex M14 round-2
- * F1 + round-3 F1 pinned the contract; R41 lifts the inline helpers
- * that workspace add-users / workspace remove-users / board add-
- * users each ship verbatim.
+ * / per-record idiomatic null → `not_found`, per-record). Codex M14
+ * round-2 F1 + round-3 F1 pinned the contract; R41 lifted the inline
+ * check that workspace add-users / workspace remove-users / board
+ * add-users each shipped verbatim; R42 (post-v0.2 cleanup window)
+ * extends the same helper across the ~32 single-target mutation
+ * verbs that previously conflated the two cases (or left the
+ * missing-key path silent — projector-only null-handling treated
+ * "key absent" the same as "value null").
  *
- * **Why distinct from `assertUpdateMutationPresent`**
- * (`api/update-mutation-result.ts`). M13's helper handles null /
- * undefined uniformly with `not_found` — pre-dating the M14
- * missing-root-key vs null-value distinction. R42 (retroactive
- * sweep across pre-M14 mutation verbs) handles unifying them; R41
- * stays scoped to the M14 + M15 partial-success-fan-out family.
+ * **Two modes** controlled by `nullHandling` (required — keep the
+ * caller explicit so a future site doesn't silently inherit the
+ * wrong behaviour):
  *
- * **Used by:** `commands/workspace/add-users.ts` /
- * `commands/workspace/remove-users.ts` / `commands/board/add-users.ts`.
+ * - `'caller_handles'` (single-target verbs, R42): only check key
+ *   presence. The caller's downstream projector handles null-value
+ *   per-noun semantics — most M5b/M9-M12 verbs throw `not_found`
+ *   from the projector for `null` (Monday's idiomatic missing-
+ *   payload signal); item set throws `internal_error` for `null`
+ *   per its M5b decision (an item that exists must always return a
+ *   payload from `change_*`). Either way, R42's missing-key check
+ *   surfaces FIRST and produces a uniform `internal_error` for
+ *   schema drift, regardless of the noun's null-value choice.
  *
- * **Not used by:** single-target mutation verbs (board create /
- * update / archive / delete / duplicate, workspace create / update /
- * delete) — those carry their own per-verb missing-root-key checks
- * because the contract is "every successful call returns the
- * resource" rather than "value null is a per-record path"; the
- * single-target verbs never throw `not_found` from the inline check
- * (the per-verb projector does that on the unwrapped value).
+ * - `'throw_not_found'` (partial-success-fan-out verbs, R41): also
+ *   check `data[key]` for null/undefined and throw `not_found` so
+ *   `dispatchSequential` slots it into the per-record failure
+ *   array (whereas `internal_error` propagates and aborts the
+ *   whole call). The `notFoundTarget` field shapes the not_found
+ *   message phrasing and details.
+ *
+ * **Used by:**
+ * - `'throw_not_found'` mode: `users-fan-out-mutation.ts`
+ *   (wraps board add-users / workspace add-users / workspace
+ *   remove-users via `dispatchSequential`).
+ * - `'caller_handles'` mode (R42 sweep): every single-target
+ *   mutation verb across M5b → M17 (item set / clear / update,
+ *   item create / archive / delete / duplicate / move / upsert,
+ *   update create / reply / edit / delete / toggle, board create
+ *   / update / archive / delete / duplicate / add-users, column-
+ *   create / update / delete, group-create / update / archive /
+ *   duplicate / delete). M15-M17 sites inline the check
+ *   verbatim pre-R42; the lift consolidates that boilerplate
+ *   onto this helper. Pre-M14 (M5b/M9-M12) sites had no inline
+ *   missing-key check; R42 adds it as net-new behaviour, picking
+ *   up the M14 contract distinction proactively.
+ *
+ * **Not used by:** `update clear-all` per-target dispatch — that
+ *   site uses `assertUpdateMutationPresent` (api/update-mutation-
+ *   result.ts) which has a different contract (treats null +
+ *   undefined uniformly as `not_found`, pre-dating M14's
+ *   distinction). Migrating it is a separate question for v0.3
+ *   (the two helpers may usefully merge).
  */
 import { ApiError } from '../utils/errors.js';
+const SCHEMA_DRIFT_HINT = "this is a schema-drift error in Monday's GraphQL response; " +
+    'verify the mutation declaration and update the response ' +
+    "schema if Monday's contract has changed.";
 /**
  * Throws `ApiError('internal_error')` when `key` is absent from
- * `data`; throws `ApiError('not_found')` when present but null.
- * Returns void on success. The caller's downstream code can rely
- * on `data[key]` being a non-null value after this call.
+ * `data` (schema drift). When `nullHandling === 'throw_not_found'`,
+ * also throws `ApiError('not_found')` if `data[key]` is null /
+ * undefined (per-record idiomatic missing). Returns void on success.
  *
  * Distinct error codes per the M14 round-2 F1 / round-3 F1
- * contract — `dispatchSequential` re-throws `internal_error`
- * (whole-call schema drift) but lets `not_found` land in the
- * per-record slot. Without this distinction, a per-record
- * not_found could be produced from a schema-drift response,
- * masking the contract violation.
+ * contract — `dispatchSequential` re-throws `internal_error` (whole-
+ * call schema drift) but lets `not_found` land in the per-record
+ * slot. Without this distinction, a per-record not_found could be
+ * produced from a schema-drift response, masking the contract
+ * violation; agents writing recovery loops keyed off `error.code`
+ * would treat schema drift as "this resource doesn't exist" and
+ * skip the failure rather than reporting it.
  */
 export const assertResponseFieldPresent = (inputs) => {
-    const { data, key, operationLabel, scopeKey, scopeId, targetKey, targetId } = inputs;
-    if (!(key in data)) {
-        throw new ApiError('internal_error', `Monday's ${operationLabel} response is missing the ${key} root field`, {
-            details: {
-                [scopeKey]: scopeId,
-                [targetKey]: targetId,
-                hint: 'this is a schema-drift error in Monday\'s GraphQL response; ' +
-                    'verify the mutation declaration and update the response ' +
-                    'schema if Monday\'s contract has changed.',
-            },
-        });
+    const { data, key, operationLabel, details, nullHandling, notFoundTarget } = inputs;
+    // Defensive narrow — the wire-schema parse upstream typically
+    // guarantees object-shape, but pre-M14 sites pass `response.data`
+    // directly without a wire-schema parse, so a malformed (non-
+    // object) response surfaces here rather than crashing on a later
+    // property access. Matched against `internal_error` since it's
+    // the same class of contract violation as a missing root key.
+    if (typeof data !== 'object' || data === null) {
+        throw new ApiError('internal_error', `Monday's ${operationLabel} response data is not object-shaped`, { details: { ...details, hint: SCHEMA_DRIFT_HINT } });
+    }
+    const record = data;
+    if (!(key in record)) {
+        throw new ApiError('internal_error', `Monday's ${operationLabel} response is missing the ${key} root field`, { details: { ...details, hint: SCHEMA_DRIFT_HINT } });
     }
-    const raw = data[key];
+    if (nullHandling === 'caller_handles')
+        return;
+    const raw = record[key];
     if (raw === null || raw === undefined) {
-        throw new ApiError('not_found', `Monday returned no payload from ${key} for ${targetKey.replace(/_id$/u, '')} ${targetId}`, { details: { [targetKey]: targetId } });
+        // 'throw_not_found' mode requires notFoundTarget to shape the
+        // per-record message + details. The type system marks it
+        // optional (since 'caller_handles' mode doesn't need it), but
+        // logically required here — surface a defensive internal_error
+        // if a future caller omits it in 'throw_not_found' mode.
+        /* c8 ignore next 7 — defensive: every 'throw_not_found' caller
+           supplies notFoundTarget; a future regression that omits it
+           fails loudly here rather than producing a half-shaped
+           not_found. */
+        if (notFoundTarget === undefined) {
+            throw new ApiError('internal_error', `assertResponseFieldPresent: 'throw_not_found' mode requires notFoundTarget`, { details: { ...details, hint: SCHEMA_DRIFT_HINT } });
+        }
+        const noun = notFoundTarget.key.replace(/_id$/u, '');
+        throw new ApiError('not_found', `Monday returned no payload from ${key} for ${noun} ${notFoundTarget.id}`, { details: { [notFoundTarget.key]: notFoundTarget.id } });
     }
 };
 //# sourceMappingURL=response-root.js.map

package/dist/api/response-root.js.map

@@ -1 +1 @@
-{"version":3,"file":"response-root.js","sourceRoot":"","sources":["../../src/api/response-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAyB9C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,MAAwC,EAClC,EAAE;IACR,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,GACzE,MAAM,CAAC;IACT,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,YAAY,cAAc,4BAA4B,GAAG,aAAa,EACtE;YACE,OAAO,EAAE;gBACP,CAAC,QAAQ,CAAC,EAAE,OAAO;gBACnB,CAAC,SAAS,CAAC,EAAE,QAAQ;gBACrB,IAAI,EACF,8DAA8D;oBAC9D,0DAA0D;oBAC1D,2CAA2C;aAC9C;SACF,CACF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,QAAQ,CAChB,WAAW,EACX,mCAAmC,GAAG,QAAQ,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,EAC1F,EAAE,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE,CACvC,CAAC;IACJ,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"response-root.js","sourceRoot":"","sources":["../../src/api/response-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,iBAAiB,GACrB,6DAA6D;IAC7D,0DAA0D;IAC1D,0CAA0C,CAAC;AAoC7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,MAAwC,EAClC,EAAE;IACR,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,GACxE,MAAM,CAAC;IAET,8DAA8D;IAC9D,kEAAkE;IAClE,6DAA6D;IAC7D,iEAAiE;IACjE,+DAA+D;IAC/D,8DAA8D;IAC9D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,YAAY,cAAc,qCAAqC,EAC/D,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,CACrD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAA+B,CAAC;IAC/C,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,YAAY,cAAc,4BAA4B,GAAG,aAAa,EACtE,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,CACrD,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,KAAK,gBAAgB;QAAE,OAAO;IAE9C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,8DAA8D;QAC9D,yDAAyD;QACzD,8DAA8D;QAC9D,+DAA+D;QAC/D,yDAAyD;QACzD;;;wBAGgB;QAChB,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YACjC,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,4EAA4E,EAC5E,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,CACrD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,IAAI,QAAQ,CAChB,WAAW,EACX,mCAAmC,GAAG,QAAQ,IAAI,IAAI,cAAc,CAAC,EAAE,EAAE,EACzE,EAAE,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,CACzD,CAAC;IACJ,CAAC;AACH,CAAC,CAAC"}

package/dist/api/tag-directory.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Per-account tag-directory lookup helper for the v0.3-M19 `tags`
+ * friendly translator. Mirrors the `userByEmail` user-directory
+ * pattern in `src/api/resolvers.ts:191–402` (the existing precedent —
+ * there is no standalone `user-directory.ts` module; the user-
+ * directory cache / lookup / refresh-on-miss machinery lives inside
+ * `resolvers.ts`).
+ *
+ * **Two surfaces.**
+ *
+ *   - `loadAccountTags({client, env?, noCache?})` — full-directory
+ *     reader. Cache-then-live: prefers a fresh on-disk
+ *     `account_tags/index.json` cache entry; falls through to a live
+ *     `account { tags { id name } }` query on miss / expiry / `noCache`,
+ *     and writes the response back to the cache. Also exposes
+ *     `complexity: Complexity | null` for the live-fetch leg, mirroring
+ *     `BoardMetadataLoadResult` so `monday account tags --verbose` can
+ *     report budget like other cache-backed reads.
+ *
+ *   - `resolveTags({client, input, env?, noCache?})` — name-list →
+ *     tag-id resolver. Splits the input on commas, trims, deduplicates,
+ *     NFC + case-fold matches against the cache; on any miss, refreshes
+ *     the directory once (live `account.tags` re-fetch) and re-checks.
+ *     Residual misses surface as `tag_not_found` per cli-design §6.5
+ *     with `details.tags: misses[]` in array form (Decision 1, closed
+ *     at `4c652d5`). Returns `{ ids, misses, source, cacheAgeSeconds }`
+ *     so the caller can populate `meta.source` + `meta.cache_age_seconds`
+ *     per cli-design §6.1.
+ *
+ * **Cache shape.** Per-account scope (`{ kind: 'accountTags' }` cache
+ * key, no per-board fan-out — Monday's data model scopes tags to the
+ * account, not the workspace). On-disk path
+ * `account_tags/index.json`; mode `0600` per the cache layer's existing
+ * security contract.
+ *
+ * **Refresh on miss.** A `--set tags=foo` call against a cache that
+ * doesn't list `foo` re-fetches the account directory, upserts, and
+ * re-checks before surfacing `tag_not_found`. Mirrors the
+ * `userByEmail` cache-then-live-refresh-then-error sequence verbatim.
+ */
+import type { MondayClient } from './client.js';
+import type { Complexity } from '../utils/output/envelope.js';
+/**
+ * Per-account tag entry. Shape mirrors `UserDirectoryEntry` from
+ * `resolvers.ts` (numeric-string id + display name); Monday's
+ * `tags` field on the account node returns `{ id, name }` per the
+ * GraphQL schema.
+ *
+ * The `id` field is constrained to a decimal non-negative integer
+ * string (NOT just any non-empty string) for the same reason the
+ * user directory does it: callers convert it to a JS number for
+ * the wire payload (`{ tag_ids: [N1, N2] }`), and a loose
+ * `z.string().min(1)` would let `"0x2a"` / `"1e3"` / `"42 "` into
+ * the cache where they'd silently corrupt every later
+ * `Number(id)` conversion.
+ */
+export interface AccountTag {
+    readonly id: string;
+    readonly name: string;
+}
+export interface ResolveTagsInputs {
+    /**
+     * The Monday GraphQL client. Required because the cache-then-
+     * live sequence falls through to a live account-tag directory
+     * reload (via `loadAccountTags`) when the input list contains
+     * a name not in the cache, and re-checks the input names
+     * against the freshly-loaded set before surfacing
+     * `tag_not_found` for any residual misses. Mirrors
+     * `UserByEmailInputs.client` in `resolvers.ts:238`.
+     */
+    readonly client: MondayClient;
+    readonly input: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly noCache?: boolean;
+}
+export interface ResolveTagsResult {
+    readonly ids: readonly number[];
+    readonly misses: readonly string[];
+    readonly source: 'cache' | 'live' | 'mixed';
+    /**
+     * Age of the cache entry the resolver read from when `source` is
+     * `'cache'` (full cache hit, no live refresh) or `'mixed'` (cache
+     * had some matches, live refresh covered the rest — the cache
+     * leg's age is preserved as the worst-case staleness the agent
+     * observed). `null` for `'live'` (no cache leg fired — empty
+     * cache or `noCache: true`). Surfaced into `meta.cache_age_seconds`
+     * via the translator-source aggregation pathway, matching the
+     * broader §6.1 mixed-source/cache-age contract.
+     */
+    readonly cacheAgeSeconds: number | null;
+}
+export interface LoadAccountTagsInputs {
+    /**
+     * The Monday GraphQL client. Required because `loadAccountTags`
+     * may bypass the cache (e.g. `monday account tags --refresh` if
+     * that flag ships at M19 implementation) and always hits the live
+     * directory on a cache miss. Mirrors `UserByEmailInputs.client`.
+     */
+    readonly client: MondayClient;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly noCache?: boolean;
+}
+export interface LoadAccountTagsResult {
+    readonly tags: readonly AccountTag[];
+    readonly source: 'cache' | 'live';
+    readonly cacheAgeSeconds: number | null;
+    /**
+     * `meta.complexity` payload from the live request when one ran;
+     * `null` for cache hits and for non-`--verbose` live calls (Monday
+     * doesn't include `complexity` unless the operation selects it).
+     * Surfacing this here is what lets cache-backed commands report
+     * accurate complexity in `--verbose` mode (mirrors
+     * `BoardMetadataLoadResult.complexity` from `board-metadata.ts`).
+     */
+    readonly complexity: Complexity | null;
+}
+/**
+ * Loads the full per-account tag directory. Used by `monday account
+ * tags` (the read verb that resolves the §6.5 `tag_not_found.details
+ * .hint` forward-reference) and by `resolveTags`'s refresh-on-miss
+ * path. Cache-then-live: prefers a fresh on-disk entry; falls
+ * through to a live `account.tags` query on miss / expiry /
+ * `noCache`. Cache writes are best-effort (disk full / permission
+ * flips don't block the lookup).
+ */
+export declare const loadAccountTags: (inputs: LoadAccountTagsInputs) => Promise<LoadAccountTagsResult>;
+/**
+ * Resolves a comma-split tag-name list against the per-account
+ * directory. Returns numeric tag IDs for the matched names and
+ * carries the misses through so the caller can construct a
+ * `tag_not_found` error envelope with `details.tags: misses[]` per
+ * cli-design §6.5 (`4c652d5`).
+ *
+ * **Three-step lookup** mirroring `userByEmail`:
+ *
+ *   1. Read the on-disk cache (skipped on `noCache`). Match input
+ *      tokens against cached entries with NFC + case-fold +
+ *      whitespace-collapse.
+ *   2. If any input token misses against the cached set, refresh
+ *      the directory once via a live `account.tags` query (also
+ *      skipped on `noCache` — the live leg always runs but the
+ *      result isn't cached).
+ *   3. Match input tokens against the freshly-loaded set. Any
+ *      residual miss is surfaced as `tag_not_found` (caller's
+ *      responsibility — this function returns the misses array
+ *      and the caller decides whether to throw).
+ *
+ * **Empty input handled by the caller** — this function does not
+ * reject an empty input list; `column-values.ts`'s `tags` translator
+ * is the boundary that surfaces `usage_error` for `--set tags=""`
+ * (mirroring the dropdown / people empty-input contract).
+ */
+export declare const resolveTags: (inputs: ResolveTagsInputs) => Promise<ResolveTagsResult>;
+//# sourceMappingURL=tag-directory.d.ts.map

package/dist/api/tag-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-directory.d.ts","sourceRoot":"","sources":["../../src/api/tag-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAeD,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAC5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AA0DD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CAoF/B,CAAC;AAgFF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,iBAAiB,KACxB,OAAO,CAAC,iBAAiB,CAyE3B,CAAC"}