monday-cli 0.2.0

package/dist/api/phones.js

@@ -0,0 +1,167 @@
+/**
+ * Pure phone-resolution helpers for the `phone` column-value translator
+ * (`cli-design.md` §5.3 step 3 v0.2 expansion, `v0.2-plan.md` §3 M8).
+ *
+ * Surface:
+ *   - `parsePhoneInput` — accepts the **mandatory** pipe-form
+ *     `<phone>|<country>` cli-design §5.3 enumerates. E.164-loose
+ *     phone validation; ISO 3166-1 alpha-2 country code validated
+ *     against a frozen allowlist (`iso-country-codes.ts`).
+ *
+ * **Why pipe form is mandatory.** Monday's phone-column validation
+ * requires both the number AND the 2-letter country code AND verifies
+ * they match (per Monday's phone-validation changelog). The friendly
+ * translator can't safely default `countryShortName: ""` — Monday
+ * would reject the mutation as `validation_failed`. Agents who need
+ * to write a phone with no country (Monday allows it for some legacy
+ * fixtures) use `--set-raw`.
+ *
+ * **E.164-loose validation.** The phone segment matches `+?\d{6,15}`
+ * — leading `+` optional, 6-15 digits otherwise. E.164's strict rule
+ * is "1-15 digits" but the CLI insists on at least 6 to catch
+ * obvious typos (`--set Mobile=+1|US` would silently land at Monday
+ * and fail server-side). The bound is a sanity check, not a
+ * complete E.164 validator — Monday is the validator of last resort.
+ *
+ * **No internal whitespace, no dashes.** `+1 555 123 4567` and
+ * `+1-555-123-4567` are rejected. cli-design doesn't pin this
+ * explicitly but Monday's API expects bare digits + an optional
+ * leading `+`. Agents who paste a formatted phone strip the
+ * separators in the shell pipeline (`tr -d ' -'`).
+ *
+ * **Why a separate module.** Same template `links.ts` / `dates.ts`
+ * follow — column-values.ts owns translator dispatch; the per-type
+ * grammar machinery lives one module deeper. The ISO allowlist is
+ * larger again (`iso-country-codes.ts`) so the layering keeps
+ * column-values.ts at one screen of dispatch logic.
+ */
+import { UsageError } from '../utils/errors.js';
+import { isIsoCountryCode } from './iso-country-codes.js';
+const PHONE_PATTERN = /^\+?\d{6,15}$/u;
+/**
+ * Parses a `phone` column input per cli-design.md §5.3 step 3 v0.2
+ * expansion.
+ *
+ * Accepted input — pipe form is **mandatory**:
+ *   - `<phone>|<country>` → `{phone, countryShortName}`. Both
+ *     segments trimmed; pipe-split max 1. Country code uppercased
+ *     before allowlist check (so `us` and `US` both work).
+ *
+ * Rejected (all `usage_error`):
+ *   - **Single segment** (`+15551234567` without `|US`) — Monday
+ *     requires both. Agents who need an empty country use
+ *     `--set-raw`. cli-design §5.3 line 819-827.
+ *   - **Phone fails E.164-loose** (`+?\d{6,15}` after trim).
+ *   - **Country fails ISO allowlist** (after uppercase).
+ *   - **Empty leader / trailer** (`|US` or `+1555|`).
+ *   - **Empty input** after trim.
+ *
+ * @param raw - The raw user-supplied value (post-`--set` parsing).
+ * @param columnId - Column ID for error messages.
+ */
+export const parsePhoneInput = (raw, columnId) => {
+    const trimmedRaw = raw.trim();
+    if (trimmedRaw.length === 0) {
+        throw emptyPhoneInputError(columnId, raw);
+    }
+    const pipeIdx = trimmedRaw.indexOf('|');
+    if (pipeIdx === -1) {
+        // Single-segment input — rejected. Monday requires both phone +
+        // country, and the friendly translator won't paper over the
+        // mismatch by silently defaulting `countryShortName: ""`.
+        throw new UsageError(`Phone column "${columnId}" requires the pipe form ` +
+            `<phone>|<country> (got "${raw}"). Monday's phone-column ` +
+            `validation needs both the number and a 2-letter ISO 3166-1 ` +
+            `alpha-2 country code AND verifies they match — the friendly ` +
+            `translator can't safely default the country. Use --set-raw to ` +
+            `write a phone with no country if Monday's legacy behaviour ` +
+            `permits it.`, {
+            details: {
+                column_id: columnId,
+                column_type: 'phone',
+                raw_input: raw,
+                hint: `pass --set ${columnId}='+15551234567|US'. The country code ` +
+                    `is uppercase ISO 3166-1 alpha-2 (e.g. US, GB, JP). To write ` +
+                    `with empty country: --set-raw ${columnId}=` +
+                    `'{"phone":"+15551234567","countryShortName":""}'.`,
+            },
+        });
+    }
+    const phoneSegment = trimmedRaw.slice(0, pipeIdx).trim();
+    const countrySegment = trimmedRaw.slice(pipeIdx + 1).trim();
+    if (phoneSegment.length === 0) {
+        throw new UsageError(`Phone column "${columnId}" got an empty phone segment ("${raw}"). ` +
+            `The friendly translator requires a non-empty number before "|".`, {
+            details: {
+                column_id: columnId,
+                column_type: 'phone',
+                raw_input: raw,
+                hint: `pass --set ${columnId}='+15551234567|US' with the phone ` +
+                    `before the "|" and the ISO 3166-1 alpha-2 country after.`,
+            },
+        });
+    }
+    if (countrySegment.length === 0) {
+        throw new UsageError(`Phone column "${columnId}" got an empty country segment ("${raw}"). ` +
+            `Monday requires a 2-letter ISO 3166-1 alpha-2 country code after ` +
+            `the "|". Use --set-raw to write a phone with no country.`, {
+            details: {
+                column_id: columnId,
+                column_type: 'phone',
+                raw_input: raw,
+                hint: `pass --set ${columnId}='+15551234567|US'. To write with ` +
+                    `empty country: --set-raw ${columnId}=` +
+                    `'{"phone":"+15551234567","countryShortName":""}'.`,
+            },
+        });
+    }
+    if (!PHONE_PATTERN.test(phoneSegment)) {
+        throw new UsageError(`Phone column "${columnId}" got invalid phone "${phoneSegment}". ` +
+            `The friendly translator accepts E.164-loose digits with an ` +
+            `optional leading "+" (6-15 digits, no whitespace, no dashes). ` +
+            `Strip separators before --set, or use --set-raw with Monday's ` +
+            `documented wire shape.`, {
+            details: {
+                column_id: columnId,
+                column_type: 'phone',
+                raw_input: raw,
+                phone_segment: phoneSegment,
+                hint: `strip whitespace and dashes — pass --set ${columnId}=` +
+                    `'+15551234567|US' (not "+1 555 123 4567|US"). The shell ` +
+                    `pipeline can do this with \`tr -d ' -'\`.`,
+            },
+        });
+    }
+    const countryUpper = countrySegment.toUpperCase();
+    if (!isIsoCountryCode(countryUpper)) {
+        throw new UsageError(`Phone column "${columnId}" got invalid country code ` +
+            `"${countrySegment}". Monday requires a 2-letter ISO 3166-1 ` +
+            `alpha-2 code (e.g. US, GB, JP). The CLI checks against a ` +
+            `frozen 249-code allowlist; exceptionally-reserved (UK, EU), ` +
+            `transitional, and user-assigned codes are excluded.`, {
+            details: {
+                column_id: columnId,
+                column_type: 'phone',
+                raw_input: raw,
+                country_segment: countrySegment,
+                hint: `pass an ISO 3166-1 alpha-2 code (US, GB, JP, etc.). The ` +
+                    `code is uppercased before validation, so "us" works the ` +
+                    `same as "US". The full list is at ` +
+                    `https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.`,
+            },
+        });
+    }
+    return { phone: phoneSegment, countryShortName: countryUpper };
+};
+const emptyPhoneInputError = (columnId, raw) => new UsageError(`Phone column "${columnId}" needs <phone>|<country> input. Got ` +
+    `"${raw}". To clear a phone column, use \`monday item clear ` +
+    `<iid> ${columnId} [--board <bid>]\` instead.`, {
+    details: {
+        column_id: columnId,
+        column_type: 'phone',
+        raw_input: raw,
+        hint: `pass --set ${columnId}='+15551234567|US'. The country code ` +
+            `is uppercase ISO 3166-1 alpha-2 (e.g. US, GB, JP).`,
+    },
+});
+//# sourceMappingURL=phones.js.map

package/dist/api/phones.js.map

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

package/dist/api/raw-document.d.ts

@@ -0,0 +1,53 @@
+export interface RawDocumentAnalysis {
+    /**
+     * The `operationName` to send on the wire. `undefined` when the
+     * document has exactly one anonymous operation (Monday picks it).
+     */
+    readonly operationName: string | undefined;
+    /**
+     * The kind of the *selected* operation — the one Monday will
+     * actually execute. For 1-op docs this is the only operation's
+     * kind; for N-op docs `--operation-name` picks one and that
+     * pick's kind lands here. Callers gating on "is the executed
+     * op a mutation?" (e.g. raw's `--dry-run` branch — Codex M6
+     * pass-5 P2) should key off this, NOT off `hasMutation`, since
+     * a mixed doc selecting a query operation should be treated as
+     * read-only at execution time.
+     */
+    readonly selectedOperationKind: 'query' | 'mutation' | 'subscription';
+    /** `true` when at least one operation in the doc is a mutation. */
+    readonly hasMutation: boolean;
+    /** `true` when at least one operation is a subscription. */
+    readonly hasSubscription: boolean;
+    /**
+     * One entry per operation in input order — used for error details
+     * and tests so the caller can confirm the parser saw what it
+     * expected.
+     */
+    readonly operations: readonly {
+        readonly operation: 'query' | 'mutation' | 'subscription';
+        readonly name: string | undefined;
+    }[];
+}
+export interface AnalyzeRawDocumentInputs {
+    readonly query: string;
+    /**
+     * Caller-supplied `--operation-name`. Required when the document
+     * has more than one operation; optional otherwise (used as a
+     * sanity check — must match one of the operation names if set).
+     */
+    readonly explicitOperationName: string | undefined;
+    /**
+     * `true` when `--allow-mutation` is set. Mutations and
+     * subscriptions are rejected with `usage_error` when this is
+     * `false`.
+     */
+    readonly allowMutation: boolean;
+}
+/**
+ * Parses the GraphQL document and applies the two raw-command
+ * contract gates: mutation rejection (unless allowed) and
+ * `operationName` selection.
+ */
+export declare const analyzeRawDocument: (inputs: AnalyzeRawDocumentInputs) => RawDocumentAnalysis;
+//# sourceMappingURL=raw-document.d.ts.map

package/dist/api/raw-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-document.d.ts","sourceRoot":"","sources":["../../src/api/raw-document.ts"],"names":[],"mappings":"AAuCA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;;;;OASG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;IACtE,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS;QAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;QAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;KACnC,EAAE,CAAC;CACL;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,wBAAwB,KAC/B,mBAsLF,CAAC"}

package/dist/api/raw-document.js

@@ -0,0 +1,177 @@
+/**
+ * GraphQL document analysis for `monday raw` (M6 close, P1 fix).
+ *
+ * `monday raw` accepts an arbitrary GraphQL document. Two contract
+ * decisions ride on what the document actually contains, and neither
+ * can be answered by a string sniff:
+ *
+ *   1. **Mutation gate.** The CLI rejects `mutation` / `subscription`
+ *      operations unless `--allow-mutation` is passed. Read paths
+ *      stay safe-by-default; an agent that meant to mutate has to
+ *      say so explicitly (`cli-design.md` §10.5). A naive
+ *      `query.includes('mutation')` regex matches the comment
+ *      `# uses the mutation api` and the field `mutation_test` —
+ *      neither is an actual mutation operation.
+ *   2. **`operationName` selection.** GraphQL servers use
+ *      `operationName` to pick which operation to execute when a
+ *      document has multiple. Hard-coding `'MondayRaw'` (the
+ *      pre-fix M6 behaviour) breaks every document that doesn't
+ *      happen to be named `MondayRaw` — Monday's server returns a
+ *      "Unknown operation" error instead of executing the only
+ *      operation present. The right answer:
+ *        - 0 ops: `usage_error` ("no operations").
+ *        - 1 op, anonymous: omit `operationName` from the wire
+ *          request so Monday picks the only operation.
+ *        - 1 op, named: pass that name.
+ *        - N ops: require explicit `--operation-name <n>` and
+ *          confirm it matches one of the operation names.
+ *
+ * The `graphql` reference parser does both jobs by walking the AST
+ * — comments, fragment names, string literals can't fool it.
+ *
+ * Errors thrown are `UsageError`s carrying the error code
+ * `usage_error` (cli-design §6.5). The fix landed alongside the
+ * `--allow-mutation` and `--operation-name` flags on the `raw`
+ * command in M6 close.
+ */
+import { parse, Kind, OperationTypeNode } from 'graphql';
+import { UsageError } from '../utils/errors.js';
+/**
+ * Parses the GraphQL document and applies the two raw-command
+ * contract gates: mutation rejection (unless allowed) and
+ * `operationName` selection.
+ */
+export const analyzeRawDocument = (inputs) => {
+    let ast;
+    try {
+        ast = parse(inputs.query);
+    }
+    catch (err) {
+        throw new UsageError(`monday raw: GraphQL document failed to parse (${err instanceof Error ? err.message : String(err)}).`, {
+            cause: err,
+            details: { hint: 'check the document for syntax errors' },
+        });
+    }
+    const operations = ast.definitions.filter((d) => d.kind === Kind.OPERATION_DEFINITION);
+    if (operations.length === 0) {
+        throw new UsageError('monday raw: GraphQL document has no executable operations ' +
+            '(found only fragments / type definitions). Pass a document ' +
+            'with at least one query or mutation.', {
+            details: {
+                definition_kinds: ast.definitions.map((d) => d.kind),
+            },
+        });
+    }
+    const opSummaries = operations.map((op) => ({
+        operation: op.operation,
+        name: op.name?.value,
+    }));
+    const hasMutation = opSummaries.some((o) => o.operation === OperationTypeNode.MUTATION);
+    const hasSubscription = opSummaries.some((o) => o.operation === OperationTypeNode.SUBSCRIPTION);
+    // Subscriptions never work over Monday's HTTP endpoint and the
+    // CLI's transport doesn't speak websockets, so reject them
+    // unconditionally — `--allow-mutation` doesn't unlock them.
+    if (hasSubscription) {
+        throw new UsageError('monday raw: GraphQL `subscription` operations are not supported ' +
+            '(the CLI transport is HTTP, not websocket). Rewrite the ' +
+            'document as a query.', {
+            details: {
+                operations: opSummaries,
+            },
+        });
+    }
+    if (hasMutation && !inputs.allowMutation) {
+        const mutationNames = opSummaries
+            .filter((o) => o.operation === OperationTypeNode.MUTATION)
+            .map((o) => o.name ?? '<anonymous>');
+        throw new UsageError('monday raw: GraphQL `mutation` operations are blocked by default. ' +
+            'Pass `--allow-mutation` if you intend to write through the ' +
+            'escape hatch (the friendly verbs — `item set`, `item update`, ' +
+            '`update create` — are preferred for the v0.1-modelled writes).', {
+            details: {
+                mutation_operations: mutationNames,
+                hint: '--allow-mutation acknowledges the write intent',
+            },
+        });
+    }
+    // Operation-name selection. Three cases keyed off operation count.
+    if (operations.length === 1) {
+        const only = opSummaries[0];
+        /* c8 ignore next 5 — defensive: length === 1 means index 0 is
+           defined; the branch exists to satisfy noUncheckedIndexedAccess
+           without a non-null assertion. */
+        if (only === undefined) {
+            throw new UsageError('monday raw: internal — operation index 0 missing.');
+        }
+        if (inputs.explicitOperationName !== undefined &&
+            only.name !== undefined &&
+            inputs.explicitOperationName !== only.name) {
+            throw new UsageError(`monday raw: --operation-name ${JSON.stringify(inputs.explicitOperationName)} doesn't match the document's only operation ` +
+                `${JSON.stringify(only.name)}. Drop --operation-name or ` +
+                `correct the value.`, {
+                details: {
+                    requested: inputs.explicitOperationName,
+                    available: [only.name],
+                },
+            });
+        }
+        if (inputs.explicitOperationName !== undefined &&
+            only.name === undefined) {
+            throw new UsageError(`monday raw: --operation-name ${JSON.stringify(inputs.explicitOperationName)} was passed but the document's single operation is ` +
+                `anonymous (no name). Either drop --operation-name or name ` +
+                `the operation in the document.`, {
+                details: {
+                    requested: inputs.explicitOperationName,
+                    available: [],
+                },
+            });
+        }
+        return {
+            operationName: only.name,
+            selectedOperationKind: only.operation,
+            hasMutation,
+            hasSubscription,
+            operations: opSummaries,
+        };
+    }
+    // Multi-operation: caller MUST disambiguate.
+    const namedOps = opSummaries
+        .map((o) => o.name)
+        .filter((n) => n !== undefined);
+    if (inputs.explicitOperationName === undefined) {
+        throw new UsageError(`monday raw: document has ${String(operations.length)} operations ` +
+            `(${namedOps.length === 0 ? '<all anonymous>' : namedOps.join(', ')}); ` +
+            `pass --operation-name <name> to select one.`, {
+            details: {
+                operations: opSummaries,
+                available: namedOps,
+            },
+        });
+    }
+    if (!namedOps.includes(inputs.explicitOperationName)) {
+        throw new UsageError(`monday raw: --operation-name ${JSON.stringify(inputs.explicitOperationName)} doesn't match any operation in the document.`, {
+            details: {
+                requested: inputs.explicitOperationName,
+                available: namedOps,
+            },
+        });
+    }
+    // Multi-op: pull the selected op's kind out of opSummaries by
+    // matching on name (length === namedOps.length when we land here
+    // because the inclusion check above passed).
+    const selected = opSummaries.find((o) => o.name === inputs.explicitOperationName);
+    /* c8 ignore next 5 — defensive: the inclusion check above
+       guarantees a match exists. The branch satisfies
+       noUncheckedIndexedAccess without a non-null assertion. */
+    if (selected === undefined) {
+        throw new UsageError('monday raw: internal — selected operation missing.');
+    }
+    return {
+        operationName: inputs.explicitOperationName,
+        selectedOperationKind: selected.operation,
+        hasMutation,
+        hasSubscription,
+        operations: opSummaries,
+    };
+};
+//# sourceMappingURL=raw-document.js.map

package/dist/api/raw-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-document.js","sourceRoot":"","sources":["../../src/api/raw-document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAmD,MAAM,SAAS,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAkDhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,MAAgC,EACX,EAAE;IACvB,IAAI,GAAiB,CAAC;IACtB,IAAI,CAAC;QACH,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAClB,iDACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,IAAI,EACJ;YACE,KAAK,EAAE,GAAG;YACV,OAAO,EAAE,EAAE,IAAI,EAAE,sCAAsC,EAAE;SAC1D,CACF,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAA8B,GAAG,CAAC,WAAW,CAAC,MAAM,CAClE,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,oBAAoB,CAC1E,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAClB,4DAA4D;YAC1D,6DAA6D;YAC7D,sCAAsC,EACxC;YACE,OAAO,EAAE;gBACP,gBAAgB,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aACrD;SACF,CACF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1C,SAAS,EAAE,EAAE,CAAC,SAAS;QACvB,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK;KACrB,CAAC,CAAC,CAAC;IAEJ,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,iBAAiB,CAAC,QAAQ,CAClD,CAAC;IACF,MAAM,eAAe,GAAG,WAAW,CAAC,IAAI,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,iBAAiB,CAAC,YAAY,CACtD,CAAC;IAEF,+DAA+D;IAC/D,2DAA2D;IAC3D,4DAA4D;IAC5D,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAClB,kEAAkE;YAChE,0DAA0D;YAC1D,sBAAsB,EACxB;YACE,OAAO,EAAE;gBACP,UAAU,EAAE,WAAW;aACxB;SACF,CACF,CAAC;IACJ,CAAC;IAED,IAAI,WAAW,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QACzC,MAAM,aAAa,GAAG,WAAW;aAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,iBAAiB,CAAC,QAAQ,CAAC;aACzD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,aAAa,CAAC,CAAC;QACvC,MAAM,IAAI,UAAU,CAClB,oEAAoE;YAClE,6DAA6D;YAC7D,gEAAgE;YAChE,gEAAgE,EAClE;YACE,OAAO,EAAE;gBACP,mBAAmB,EAAE,aAAa;gBAClC,IAAI,EAAE,gDAAgD;aACvD;SACF,CACF,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC5B;;2CAEmC;QACnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;QAC5E,CAAC;QACD,IACE,MAAM,CAAC,qBAAqB,KAAK,SAAS;YAC1C,IAAI,CAAC,IAAI,KAAK,SAAS;YACvB,MAAM,CAAC,qBAAqB,KAAK,IAAI,CAAC,IAAI,EAC1C,CAAC;YACD,MAAM,IAAI,UAAU,CAClB,gCAAgC,IAAI,CAAC,SAAS,CAC5C,MAAM,CAAC,qBAAqB,CAC7B,+CAA+C;gBAC9C,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,6BAA6B;gBACzD,oBAAoB,EACtB;gBACE,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,qBAAqB;oBACvC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;iBACvB;aACF,CACF,CAAC;QACJ,CAAC;QACD,IACE,MAAM,CAAC,qBAAqB,KAAK,SAAS;YAC1C,IAAI,CAAC,IAAI,KAAK,SAAS,EACvB,CAAC;YACD,MAAM,IAAI,UAAU,CAClB,gCAAgC,IAAI,CAAC,SAAS,CAC5C,MAAM,CAAC,qBAAqB,CAC7B,qDAAqD;gBACpD,4DAA4D;gBAC5D,gCAAgC,EAClC;gBACE,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,qBAAqB;oBACvC,SAAS,EAAE,EAAE;iBACd;aACF,CACF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,aAAa,EAAE,IAAI,CAAC,IAAI;YACxB,qBAAqB,EAAE,IAAI,CAAC,SAAS;YACrC,WAAW;YACX,eAAe;YACf,UAAU,EAAE,WAAW;SACxB,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,WAAW;SACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAClB,4BAA4B,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,cAAc;YACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YACxE,6CAA6C,EAC/C;YACE,OAAO,EAAE;gBACP,UAAU,EAAE,WAAW;gBACvB,SAAS,EAAE,QAAQ;aACpB;SACF,CACF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAClB,gCAAgC,IAAI,CAAC,SAAS,CAC5C,MAAM,CAAC,qBAAqB,CAC7B,+CAA+C,EAChD;YACE,OAAO,EAAE;gBACP,SAAS,EAAE,MAAM,CAAC,qBAAqB;gBACvC,SAAS,EAAE,QAAQ;aACpB;SACF,CACF,CAAC;IACJ,CAAC;IACD,8DAA8D;IAC9D,iEAAiE;IACjE,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,qBAAqB,CAC/C,CAAC;IACF;;gEAE4D;IAC5D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CAAC,oDAAoD,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,qBAAqB;QAC3C,qBAAqB,EAAE,QAAQ,CAAC,SAAS;QACzC,WAAW;QACX,eAAe;QACf,UAAU,EAAE,WAAW;KACxB,CAAC;AACJ,CAAC,CAAC"}

package/dist/api/raw-write.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `--set-raw <col>=<json>` escape-hatch helpers (`cli-design.md` §5.3
+ * escape-hatch contract, `v0.2-plan.md` §3 M8).
+ *
+ * Two surfaces split across argv-parse vs. post-resolution:
+ *
+ *   - `parseSetRawExpression` — argv-parse-time. Splits `<col>=<json>`
+ *     on the first `=`, then parses the JSON segment via `JSON.parse`
+ *     and validates the result is a JsonObject (string / number /
+ *     array / null at the top level rejected). Malformed JSON or
+ *     non-object JSON surfaces as `usage_error` with the parse error
+ *     in `details` per cli-design §5.3 line 949-960. Cheap-fail —
+ *     no network call fires for an obviously-broken `<json>`.
+ *
+ *   - `translateRawColumnValue` — post-resolution. Takes the resolved
+ *     column + the pre-parsed JsonObject and runs the two reject
+ *     lists per cli-design §5.3 escape-hatch contract:
+ *       * **Read-only-forever** (`mirror` / `formula` / etc.) →
+ *         `unsupported_column_type` with `read_only: true`. Monday
+ *         never accepts writes against these regardless of payload,
+ *         so accepting a raw payload would just shift the failure
+ *         from CLI-time to Monday-time with no new information.
+ *       * **`files`-shaped** (`file`, anything else where Monday
+ *         uses `add_file_to_column` rather than `change_column_value`)
+ *         → `unsupported_column_type` with `deferred_to: "v0.4"`.
+ *         The `--set-raw` payload reaches `change_column_value` /
+ *         `change_multiple_column_values` only; files-shaped types
+ *         can't be written through that wire surface.
+ *     Otherwise builds a `TranslatedColumnValue` with `payload:
+ *     { format: 'rich', value: <parsed> }` so the existing
+ *     `selectMutation` dispatcher handles it uniformly.
+ *
+ * **Why the split.** The argv-parse-time JSON validation lets the
+ * CLI fail fast on malformed input without a network round-trip; the
+ * post-resolution type gate needs the resolved column's `type`,
+ * which is only known after `resolveColumnWithRefresh` (the resolver
+ * needs board metadata, which comes from the network or cache). The
+ * caller threads parsed → resolved → translated; each step has one
+ * concern.
+ *
+ * **No type-shape validation.** Per cli-design §5.3 line 949-960:
+ * "the CLI does not validate the parsed object against any per-type
+ * schema; Monday's server-side rejection surfaces as
+ * `validation_failed` with Monday's message." The whole point of
+ * `--set-raw` is to bypass the friendly translator's grammar; the
+ * user owns wire-shape correctness. The CLI's contract here is
+ * narrower: parse the JSON, gate on the column's category, build
+ * a `TranslatedColumnValue`.
+ *
+ * **Mutual exclusion with `--set` is the caller's concern.** The
+ * cli-design §5.3 contract pins resolution-time enforcement (after
+ * both flags' tokens resolve to column IDs). This module doesn't see
+ * `--set` translations — the command layer collects all translated
+ * values and passes them to `selectMutation`, which raises
+ * `usage_error` on duplicate column IDs. The escape-hatch contract
+ * is upheld by reusing `selectMutation`'s existing duplicate-ID
+ * check rather than introducing a separate pre-flight check here.
+ */
+import type { JsonObject } from '../types/json.js';
+import type { TranslatedColumnValue } from './column-values.js';
+export interface ParsedSetRawExpression {
+    /** The raw column token agent typed (`status`, `id:status_4`, `External link`). */
+    readonly token: string;
+    /**
+     * The pre-parsed JSON object the agent supplied. Validated as a
+     * JsonObject at parse-time per cli-design §5.3 line 949-960 —
+     * malformed JSON / non-object JSON rejected with `usage_error`
+     * before the call reaches `translateRawColumnValue`.
+     */
+    readonly value: JsonObject;
+    /** The original `<json>` string — preserved for error contexts only. */
+    readonly rawJson: string;
+}
+/**
+ * Splits `--set-raw <col>=<json>` on the FIRST `=` per cli-design
+ * §5.3 step 2 (matching `--set`'s split rule). Tokens with `=` in
+ * the title need shell quoting plus the explicit `id:` / `title:`
+ * prefix, same as `--set`.
+ *
+ * Then parses the `<json>` segment via `JSON.parse` and validates
+ * the result is a JsonObject (per cli-design §5.3 line 949-952:
+ * "verifies it is a JSON object — malformed JSON or non-object JSON
+ * (string / number / array / null at the top level) returns
+ * usage_error").
+ *
+ * **Throws** `UsageError(usage_error)`:
+ *   - empty token, missing `=`, or empty value;
+ *   - `JSON.parse` throws SyntaxError;
+ *   - parsed JSON is not an object (string / number / boolean /
+ *     null / array at the top level).
+ */
+export declare const parseSetRawExpression: (raw: string) => ParsedSetRawExpression;
+/**
+ * Builds a `TranslatedColumnValue` for an already-resolved column +
+ * a pre-parsed JsonObject payload. Runs the two reject lists per
+ * cli-design §5.3 escape-hatch contract before constructing the
+ * translated value:
+ *
+ *   - **Read-only-forever** → `unsupported_column_type` with
+ *     `read_only: true`. Monday computes these server-side; no
+ *     payload (raw or friendly) is ever accepted.
+ *   - **`files`-shaped** → `unsupported_column_type` with
+ *     `deferred_to: "v0.4"`. Monday writes via `add_file_to_column`
+ *     (multipart upload), not `change_column_value`; the raw
+ *     payload can't reach the right wire surface.
+ *
+ * Anything else (writable + tentative-slipped + future where the API
+ * accepts `change_column_value`) is accepted — the user took the
+ * escape hatch and owns wire-shape correctness; Monday's server-side
+ * rejection surfaces as `validation_failed` with Monday's message.
+ *
+ * **`columnType` slot.** The translated value carries the resolved
+ * column's actual type string (`column.type`) cast through the
+ * `WritableColumnType` union via `as`. The cast is structural —
+ * `--set-raw` accepts types outside `WRITABLE_COLUMN_TYPES`, so the
+ * runtime value may be any non-rejected type string. Downstream
+ * consumers (`selectMutation`, the dry-run engine) use `columnType`
+ * for the `long_text` re-wrap branch only; that branch doesn't fire
+ * for raw payloads (`payload.format` is always `'rich'`), so the
+ * cast is safe by construction.
+ */
+export declare const translateRawColumnValue: (column: {
+    readonly id: string;
+    readonly type: string;
+}, value: JsonObject, rawJson: string) => TranslatedColumnValue;
+export type { JsonObject } from '../types/json.js';
+//# sourceMappingURL=raw-write.d.ts.map

package/dist/api/raw-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-write.d.ts","sourceRoot":"","sources":["../../src/api/raw-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,sBA8DnD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,UAAU,EACjB,SAAS,MAAM,KACd,qBA+DF,CAAC;AAsBF,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}