monday-cli 0.2.0

package/dist/api/complexity.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Complexity selection + extraction (`v0.1-plan.md` §3 M2,
+ * `cli-design.md` §6.1).
+ *
+ * Two halves:
+ *
+ *  - **Injection.** When `--verbose` is on, every Monday GraphQL
+ *    request gets a `complexity { used remaining reset_in_seconds }`
+ *    selection appended at the operation root. This costs ~1
+ *    complexity point per call but lets the CLI surface the budget
+ *    in `meta.complexity` without a separate query. Without
+ *    `--verbose`, `meta.complexity` is `null` per §6.1.
+ *
+ *  - **Extraction.** Reads the `complexity` field off the response
+ *    body and projects the SDK's three integer fields (`query`,
+ *    `after`, `reset_in_x_seconds`) onto the CLI's stable shape
+ *    (`used`, `remaining`, `reset_in_seconds`). The CLI re-spells
+ *    Monday's field names so a future API renaming doesn't ripple
+ *    through every command's output schema.
+ *
+ * The injector lives at the *string* level rather than via an AST
+ * because:
+ *  - `graphql-request` ships no AST helper at the SDK we depend on;
+ *    pulling in `graphql/parser` for one selection is a heavy cost.
+ *  - The transformation is mechanical and bounded: locate the first
+ *    top-level `query`/`mutation`/`{` and inject the field at the
+ *    end of its outermost selection set. Edge cases (operation
+ *    name, variable declarations, fragments) leave the injection
+ *    site unchanged.
+ *
+ * The implementation is conservative: if the query string is not
+ * recognised as a single top-level operation, the injector returns
+ * the input unchanged and the caller proceeds without complexity
+ * tracking. That trades absolute coverage for resilience — `monday
+ * raw` accepts arbitrary GraphQL, and we'd rather lose verbose
+ * complexity on a custom multi-operation document than break the
+ * query.
+ */
+import type { Complexity } from '../utils/output/envelope.js';
+export interface ComplexityInjectionOptions {
+    /**
+     * The selection to append. Defaults to the documented v0.1 set;
+     * tests can override to assert on the wire shape, but commands
+     * should leave it on the default so the field stays consistent
+     * across the surface.
+     */
+    readonly selection?: string;
+}
+export interface ComplexityInjectionResult {
+    /** The (possibly modified) GraphQL document. */
+    readonly query: string;
+    /**
+     * True if a `complexity { ... }` selection was added by this
+     * call. False when the document already contained one (no-op) or
+     * when the injector couldn't find a single recognisable operation
+     * body. Callers use this to know whether to strip the field from
+     * the response (it was theirs to add) or leave it (it was the
+     * caller's own selection — e.g. `account complexity` directly
+     * queries the field as its only payload).
+     */
+    readonly injected: boolean;
+}
+/**
+ * Returns `query` (possibly modified) plus a flag indicating
+ * whether the injector actually appended the selection. If the
+ * document doesn't have a single top-level operation we can
+ * identify, returns the input unchanged with `injected: false`.
+ */
+export declare const injectComplexity: (query: string, options?: ComplexityInjectionOptions) => ComplexityInjectionResult;
+/**
+ * Reads the `complexity` field from a Monday GraphQL response body,
+ * shaping it into the CLI's `meta.complexity` contract.
+ *
+ *  - `used`     ← Monday's `query` field (cost of the query).
+ *  - `remaining`← Monday's `after` (budget left after this call).
+ *  - `reset_in_seconds` ← Monday's `reset_in_x_seconds`.
+ *
+ * Returns `null` (not undefined) when the response carries no
+ * `complexity` block, matching `cli-design.md` §6.1's rule that
+ * `meta.complexity` is always present and either an object or `null`.
+ *
+ * The function is permissive about which shape gets handed in:
+ *  - `body` may be the entire response body (`{ data: { complexity }
+ *     }`), the `data` object, or just the `complexity` object itself.
+ *  - Numeric fields that aren't finite numbers fall back through the
+ *    chain so a partial response (Monday's reverse-proxy returning
+ *    half the fields) still produces something usable.
+ */
+export declare const parseComplexity: (body: unknown) => Complexity | null;
+//# sourceMappingURL=complexity.d.ts.map

package/dist/api/complexity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complexity.d.ts","sourceRoot":"","sources":["../../src/api/complexity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA2ED,MAAM,WAAW,yBAAyB;IACxC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,MAAM,EACb,UAAS,0BAA+B,KACvC,yBAiBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,OAAO,KAAG,UAAU,GAAG,IAmD5D,CAAC"}

package/dist/api/complexity.js

@@ -0,0 +1,194 @@
+/**
+ * Complexity selection + extraction (`v0.1-plan.md` §3 M2,
+ * `cli-design.md` §6.1).
+ *
+ * Two halves:
+ *
+ *  - **Injection.** When `--verbose` is on, every Monday GraphQL
+ *    request gets a `complexity { used remaining reset_in_seconds }`
+ *    selection appended at the operation root. This costs ~1
+ *    complexity point per call but lets the CLI surface the budget
+ *    in `meta.complexity` without a separate query. Without
+ *    `--verbose`, `meta.complexity` is `null` per §6.1.
+ *
+ *  - **Extraction.** Reads the `complexity` field off the response
+ *    body and projects the SDK's three integer fields (`query`,
+ *    `after`, `reset_in_x_seconds`) onto the CLI's stable shape
+ *    (`used`, `remaining`, `reset_in_seconds`). The CLI re-spells
+ *    Monday's field names so a future API renaming doesn't ripple
+ *    through every command's output schema.
+ *
+ * The injector lives at the *string* level rather than via an AST
+ * because:
+ *  - `graphql-request` ships no AST helper at the SDK we depend on;
+ *    pulling in `graphql/parser` for one selection is a heavy cost.
+ *  - The transformation is mechanical and bounded: locate the first
+ *    top-level `query`/`mutation`/`{` and inject the field at the
+ *    end of its outermost selection set. Edge cases (operation
+ *    name, variable declarations, fragments) leave the injection
+ *    site unchanged.
+ *
+ * The implementation is conservative: if the query string is not
+ * recognised as a single top-level operation, the injector returns
+ * the input unchanged and the caller proceeds without complexity
+ * tracking. That trades absolute coverage for resilience — `monday
+ * raw` accepts arbitrary GraphQL, and we'd rather lose verbose
+ * complexity on a custom multi-operation document than break the
+ * query.
+ */
+const DEFAULT_COMPLEXITY_SELECTION = 'complexity { before after query reset_in_x_seconds }';
+/**
+ * Returns true when `query` already declares a top-level
+ * `complexity` selection — we don't want to inject a duplicate.
+ *
+ * Match is intentionally narrow: a literal `complexity {` outside a
+ * variable declaration. Arguments named `complexity:` (rare, but
+ * possible in mutation inputs) won't match because the regex
+ * insists on the `{` delimiter immediately after.
+ */
+const hasComplexitySelection = (query) => /\bcomplexity\s*\{/u.test(query);
+/**
+ * Locates the closing `}` of the *outermost* selection set inside the
+ * GraphQL document — i.e. the operation body. Returns the index of
+ * that `}` on success, or undefined if the document doesn't have a
+ * recognisable single-operation shape.
+ *
+ * The scan walks brace depth: the first `{` is the operation body's
+ * opener; we count up/down until we land back at depth 0. String
+ * literals (block strings or quoted strings inside arguments) are
+ * skipped to avoid mis-counting braces buried in `description: "{"`.
+ */
+const findOperationBodyClose = (query) => {
+    let firstBrace = -1;
+    let depth = 0;
+    let inBlockString = false;
+    let inString = false;
+    for (let i = 0; i < query.length; i++) {
+        const ch = query[i];
+        if (inBlockString) {
+            if (ch === '"' && query.slice(i, i + 3) === '"""') {
+                inBlockString = false;
+                i += 2;
+            }
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\' && i + 1 < query.length) {
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"' && query.slice(i, i + 3) === '"""') {
+            inBlockString = true;
+            i += 2;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            if (firstBrace === -1)
+                firstBrace = i;
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0 && firstBrace !== -1) {
+                return i;
+            }
+            if (depth < 0) {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+};
+/**
+ * Returns `query` (possibly modified) plus a flag indicating
+ * whether the injector actually appended the selection. If the
+ * document doesn't have a single top-level operation we can
+ * identify, returns the input unchanged with `injected: false`.
+ */
+export const injectComplexity = (query, options = {}) => {
+    if (hasComplexitySelection(query)) {
+        return { query, injected: false };
+    }
+    const selection = options.selection ?? DEFAULT_COMPLEXITY_SELECTION;
+    const close = findOperationBodyClose(query);
+    if (close === undefined) {
+        return { query, injected: false };
+    }
+    // Insert before the closing `}` with surrounding whitespace so the
+    // result still parses cleanly. Don't try to indent — Monday's
+    // server doesn't care, and aligning to existing whitespace would
+    // double the cost of this function for no observable difference.
+    return {
+        query: `${query.slice(0, close)} ${selection} ${query.slice(close)}`,
+        injected: true,
+    };
+};
+/**
+ * Reads the `complexity` field from a Monday GraphQL response body,
+ * shaping it into the CLI's `meta.complexity` contract.
+ *
+ *  - `used`     ← Monday's `query` field (cost of the query).
+ *  - `remaining`← Monday's `after` (budget left after this call).
+ *  - `reset_in_seconds` ← Monday's `reset_in_x_seconds`.
+ *
+ * Returns `null` (not undefined) when the response carries no
+ * `complexity` block, matching `cli-design.md` §6.1's rule that
+ * `meta.complexity` is always present and either an object or `null`.
+ *
+ * The function is permissive about which shape gets handed in:
+ *  - `body` may be the entire response body (`{ data: { complexity }
+ *     }`), the `data` object, or just the `complexity` object itself.
+ *  - Numeric fields that aren't finite numbers fall back through the
+ *    chain so a partial response (Monday's reverse-proxy returning
+ *    half the fields) still produces something usable.
+ */
+export const parseComplexity = (body) => {
+    if (body === null || typeof body !== 'object') {
+        return null;
+    }
+    const obj = body;
+    // Try to peel back the wrappings: `{data: {complexity: ...}}` →
+    // `{complexity: ...}` → the leaf object.
+    let leaf;
+    if ('complexity' in obj &&
+        typeof obj.complexity === 'object' &&
+        obj.complexity !== null) {
+        leaf = obj.complexity;
+    }
+    else if ('data' in obj &&
+        typeof obj.data === 'object' &&
+        obj.data !== null) {
+        const data = obj.data;
+        if ('complexity' in data &&
+            typeof data.complexity === 'object' &&
+            data.complexity !== null) {
+            leaf = data.complexity;
+        }
+    }
+    else if ('query' in obj || 'after' in obj || 'reset_in_x_seconds' in obj) {
+        leaf = obj;
+    }
+    if (leaf === undefined) {
+        return null;
+    }
+    const finiteNumber = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    const used = finiteNumber(leaf.query) ?? finiteNumber(leaf.used) ?? 0;
+    const remaining = finiteNumber(leaf.after) ?? finiteNumber(leaf.remaining) ?? 0;
+    const resetInSeconds = finiteNumber(leaf.reset_in_x_seconds) ??
+        finiteNumber(leaf.reset_in_seconds) ??
+        0;
+    return {
+        used,
+        remaining,
+        reset_in_seconds: resetInSeconds,
+    };
+};
+//# sourceMappingURL=complexity.js.map

package/dist/api/complexity.js.map

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

package/dist/api/dates.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure date-resolution helpers for the `date` column-value
+ * translator (`cli-design.md` §5.3 step 3 + the
+ * "Relative dates and timezone" subsection).
+ *
+ * Two surfaces:
+ *
+ *   - `parseDateInput` — accepts every input shape `cli-design.md`
+ *     §5.3 step 3 enumerates: ISO date (`YYYY-MM-DD`), ISO date+time
+ *     (`YYYY-MM-DDTHH:MM[:SS]`), and the relative-token set
+ *     (`today`, `tomorrow`, `+Nd`, `-Nw`, `+Nh`). Returns the
+ *     Monday wire payload (`{date}` or `{date, time}`) plus the
+ *     `resolvedFrom` echo `cli-design.md` §6.4 puts on the
+ *     dry-run envelope.
+ *   - `formatNowInTimezone` — used internally to format an
+ *     instant in an IANA timezone for the `resolvedFrom.now`
+ *     echo. Exported because the dry-run engine (M5a follow-up)
+ *     will need the same shape for non-date columns' `now`
+ *     timestamp.
+ *
+ * **Why a separate module.** column-values.ts owns translator
+ * *dispatch* — the switch over WritableColumnType, the
+ * mutation-selection helper, and the ApiError builder. The date
+ * translator's machinery is ~150 LOC of regex + Intl
+ * gymnastics with no dispatch concerns. Splitting keeps
+ * column-values.ts at one screen of dispatch logic and the date
+ * machinery isolated for unit testing.
+ *
+ * **No external dep.** Uses only `Intl.DateTimeFormat` for tz
+ * formatting + `Date` arithmetic. The CLI rules forbid pulling
+ * in luxon / date-fns / dayjs for stdlib-doable work; Node 22
+ * ships full ICU and `longOffset` tz formatting, which covers
+ * everything `cli-design.md` §5.3 needs.
+ */
+/**
+ * Wire payload shape for a `date` column. Matches Monday's
+ * `change_column_value(value: JSON!)` JSON scalar:
+ *   - date-only input → `{date: "YYYY-MM-DD"}`
+ *   - date+time input → `{date: "YYYY-MM-DD", time: "HH:MM:SS"}`
+ *
+ * `time` is always `HH:MM:SS` (24-hour, padded). Inputs that
+ * omit seconds default to `:00` so the wire shape stays
+ * consistent — Monday's API accepts `:30` as `:30:00` already
+ * but pinning the format here means the round-trip diff in
+ * dry-run output stays stable.
+ */
+export type DatePayload = {
+    readonly date: string;
+} | {
+    readonly date: string;
+    readonly time: string;
+};
+/**
+ * The `resolved_from` echo `cli-design.md` §5.3 lines 783-786 +
+ * §6.4 prescribe for the dry-run envelope. Returned by
+ * `parseDateInput` for relative-token inputs (where the agent
+ * benefits from seeing the absolute date the CLI computed) and
+ * `null` for explicit ISO inputs (which need no resolution).
+ *
+ * Shape is a struct, not a string blob, because the dry-run
+ * engine (M5a follow-up) reads `timezone` to decide whether
+ * to emit a `MONDAY_TIMEZONE not set` warning when the system
+ * tz was used as a fallback.
+ */
+export interface DateResolution {
+    /** The literal input the agent passed (e.g. `+1w`). */
+    readonly input: string;
+    /** IANA timezone string used for resolution (e.g. `Europe/London`). */
+    readonly timezone: string;
+    /**
+     * The instant "now" was sampled at, formatted as a local-time
+     * ISO string with offset (e.g. `2026-04-25T14:00:00+01:00`).
+     * cli-design §5.3 sample at line 786 pins this format.
+     */
+    readonly now: string;
+}
+export interface DateResolutionContext {
+    /**
+     * Source of "now" for relative-date resolution. Defaults to
+     * `() => new Date()`. Tests inject a deterministic clock to
+     * pin DST-boundary behaviour without wall-clock waits — same
+     * pattern as `pagination.ts`'s cursor clock (M4 §14
+     * post-mortem prophylactic).
+     */
+    readonly now?: () => Date;
+    /**
+     * IANA timezone string for relative-date resolution. Defaults
+     * to the system timezone via
+     * `Intl.DateTimeFormat().resolvedOptions().timeZone` per
+     * cli-design §5.3 line 766. M5b's command layer plumbs
+     * `MONDAY_TIMEZONE` env override through this slot.
+     */
+    readonly timezone?: string;
+}
+export interface ParsedDateInput {
+    readonly payload: DatePayload;
+    /**
+     * `null` for explicit ISO inputs — the input *is* the
+     * resolved value; nothing to echo. A struct for relative
+     * tokens — the dry-run envelope shows the agent what the
+     * CLI computed against which tz at which clock instant.
+     */
+    readonly resolvedFrom: DateResolution | null;
+}
+/**
+ * Parses a `date` column input per cli-design §5.3 step 3.
+ *
+ * Accepted inputs:
+ *   - **ISO date** `YYYY-MM-DD` → `{date}` payload, no
+ *     resolution echo.
+ *   - **ISO date+time** `YYYY-MM-DDTHH:MM` or
+ *     `YYYY-MM-DDTHH:MM:SS` → `{date, time}` payload, no
+ *     resolution echo. Seconds default to `:00`.
+ *   - **Relative tokens**:
+ *     - `today` → today's date in `ctx.timezone`.
+ *     - `tomorrow` → today + 1 day in `ctx.timezone`.
+ *     - `+Nd` / `-Nd` (days), `+Nw` / `-Nw` (weeks) →
+ *       date-only output, calendar arithmetic in `ctx.timezone`.
+ *     - `+Nh` / `-Nh` (hours) → date+time output, instant
+ *       arithmetic (UTC offset preserved across DST per
+ *       industry standard — `+24h` from a GMT instant lands
+ *       at the same UTC instant +24h, which may shift the
+ *       wall-clock time by an hour on a DST boundary day).
+ *
+ * Throws `usage_error` with a structured `details` shape for
+ * unrecognised input. The error message lists the supported
+ * forms so an agent's debug log shows the right shape to
+ * paste-and-edit.
+ *
+ * @param raw - The raw user-supplied value (post-`--set`
+ *   parsing).
+ * @param columnId - Column ID for error messages.
+ * @param ctx - Resolution context. Defaults to system clock +
+ *   system tz when omitted; M5b's command layer plumbs the
+ *   `MONDAY_TIMEZONE` env override.
+ */
+export declare const parseDateInput: (raw: string, columnId: string, ctx?: DateResolutionContext) => ParsedDateInput;
+/**
+ * Formats an instant as a local-time ISO string with UTC
+ * offset, e.g. `2026-04-25T14:00:00+01:00`. cli-design §5.3
+ * line 786 sample pins this exact shape.
+ *
+ * Uses Intl's `longOffset` token (Node 22+ ICU full data) for
+ * the offset suffix; falls back to `+00:00` if the runtime's
+ * Intl reports an unparseable form. Exported for the dry-run
+ * engine which uses the same formatter for non-date columns'
+ * `now` echo.
+ */
+export declare const formatNowInTimezone: (instant: Date, timezone: string) => string;
+//# sourceMappingURL=dates.d.ts.map

package/dist/api/dates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../../src/api/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,GACzB,KAAK,MAAM,EACX,UAAU,MAAM,EAChB,MAAK,qBAA0B,KAC9B,eAyBF,CAAC;AAyWF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,IAAI,EAAE,UAAU,MAAM,KAAG,MAOrE,CAAC"}