monday-cli 0.2.0

package/dist/api/raw-write.js

@@ -0,0 +1,233 @@
+/**
+ * `--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 { ApiError, UsageError } from '../utils/errors.js';
+import { isFilesShapedType, isReadOnlyForeverType, } from './column-types.js';
+/**
+ * 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 const parseSetRawExpression = (raw) => {
+    const idx = raw.indexOf('=');
+    if (idx <= 0) {
+        throw new UsageError(`--set-raw: expected <col>=<json> (got ${JSON.stringify(raw)}); ` +
+            `use shell quoting and the id:/title: prefix when the column ` +
+            `token contains "="`, { details: { input: raw } });
+    }
+    const token = raw.slice(0, idx);
+    const rawJson = raw.slice(idx + 1);
+    if (rawJson.length === 0) {
+        throw new UsageError(`--set-raw: empty <json> after "=" (got ${JSON.stringify(raw)}); ` +
+            `pass a JSON object literal (e.g. --set-raw status='{"label":"Done"}')`, { details: { input: raw, token } });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch (err) {
+        throw new UsageError(`--set-raw: JSON parse failed for column "${token}". ` +
+            `${err instanceof Error ? err.message : String(err)}. ` +
+            `Pass a well-formed JSON object literal (e.g. --set-raw ` +
+            `status='{"label":"Done"}'). Use single-quote-around-double-` +
+            `quote shell quoting on POSIX shells.`, {
+            cause: err,
+            details: {
+                token,
+                raw_json: rawJson,
+                parse_error: err instanceof Error ? err.message : String(err),
+                hint: 'JSON property names + string values use double quotes; ' +
+                    'wrap the whole literal in single quotes in the shell.',
+            },
+        });
+    }
+    if (!isJsonObject(parsed)) {
+        throw new UsageError(`--set-raw: expected a JSON object for column "${token}", got ` +
+            `${describeJsonShape(parsed)}. Per cli-design §5.3 the escape ` +
+            `hatch accepts only JSON objects — Monday's column wire shapes ` +
+            `are all keyed records (e.g. {"label":"Done"}, {"date":"2026-` +
+            `05-01"}, {"personsAndTeams":[...]}).`, {
+            details: {
+                token,
+                raw_json: rawJson,
+                parsed_shape: describeJsonShape(parsed),
+                hint: 'wrap the literal in {…} — Monday\'s column wire shapes ' +
+                    'are objects, never bare strings / numbers / arrays.',
+            },
+        });
+    }
+    return { token, value: parsed, rawJson };
+};
+/**
+ * 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 const translateRawColumnValue = (column, value, rawJson) => {
+    if (isReadOnlyForeverType(column.type)) {
+        throw new ApiError('unsupported_column_type', `Column "${column.id}" has type "${column.type}", which Monday ` +
+            `computes server-side and does not make writable via the API. ` +
+            `--set-raw cannot bypass this — Monday rejects writes against ` +
+            `read-only-forever columns regardless of payload. Set the ` +
+            `underlying source column instead (e.g. for a mirror column, ` +
+            `write to the column the mirror reflects on the linked board).`, {
+            details: {
+                column_id: column.id,
+                type: column.type,
+                read_only: true,
+                hint: 'this column type is computed by Monday and is permanently ' +
+                    'read-only via the API. --set-raw rejects these too — ' +
+                    'identify the underlying source column (the column the ' +
+                    'mirror / formula / auto_number / etc. reflects) and write ' +
+                    'to that instead. See cli-design.md §5.3 escape-hatch ' +
+                    'contract.',
+            },
+        });
+    }
+    if (isFilesShapedType(column.type)) {
+        throw new ApiError('unsupported_column_type', `Column "${column.id}" has type "${column.type}", which Monday ` +
+            `writes via add_file_to_column (multipart upload) rather than ` +
+            `change_column_value. --set-raw goes through change_column_value ` +
+            `/ change_multiple_column_values, so a raw payload can't reach ` +
+            `the right wire surface for this type. Asset upload is pinned ` +
+            `to v0.4 per cli-design §13.`, {
+            details: {
+                column_id: column.id,
+                type: column.type,
+                deferred_to: 'v0.4',
+                hint: 'file upload uses Monday\'s add_file_to_column mutation ' +
+                    '(multipart). The CLI does not expose that wire path in ' +
+                    'v0.2; v0.4 will add a dedicated --file flag. --set-raw ' +
+                    'rejects this type at column-resolution time.',
+            },
+        });
+    }
+    return {
+        columnId: column.id,
+        // Cast: --set-raw accepts types outside WRITABLE_COLUMN_TYPES; the
+        // type slot tracks the resolved Monday type string for diagnostic
+        // continuity with friendly translations. Downstream `long_text`
+        // re-wrap (the only consumer that branches on columnType) doesn't
+        // fire for raw payloads (payload.format is always 'rich'), so the
+        // cast is safe by construction.
+        columnType: column.type,
+        rawInput: rawJson,
+        payload: { format: 'rich', value },
+        resolvedFrom: null,
+        peopleResolution: null,
+    };
+};
+const isJsonObject = (value) => {
+    if (value === null)
+        return false;
+    if (typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    return true;
+};
+const describeJsonShape = (value) => {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    const t = typeof value;
+    // typeof null is 'object' but the null branch above handles it; the
+    // remaining 'object' case is the non-array, non-null JsonObject
+    // path which doesn't reach this function. The other primitive types
+    // (string / number / boolean) are reported verbatim.
+    return t;
+};
+//# sourceMappingURL=raw-write.js.map

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

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

package/dist/api/resolution-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `dateResolution` + `peopleResolution` builder, shared by every
+ * mutation surface that calls into `translateColumnValueAsync` /
+ * `planChanges` / `planCreate`.
+ *
+ * Both contexts close over `ctx.clock` + `ctx.env.MONDAY_TIMEZONE`
+ * (date side) and `client` + `ctx.env` + `globalFlags.noCache`
+ * (people side via `resolveMeFactory` + `userByEmail`). The
+ * builder is a pure function — no caching, no memoisation; each
+ * call returns a fresh pair. v0.3 is the natural home for `me`-token
+ * memoisation across translate calls in one command run; lifting
+ * this builder gives that change a single seam to extend.
+ *
+ * Lifted from four identical 12-line copies (`set.ts:327`,
+ * `update.ts:450` single, `update.ts:1275` bulk, `create.ts:893`)
+ * — see v0.2-plan §12 R24.
+ */
+import type { MondayClient } from './client.js';
+import type { RunContext } from '../cli/run.js';
+import type { GlobalFlags } from '../types/global-flags.js';
+import type { DateResolutionContext, PeopleResolutionContext } from './column-values.js';
+export interface BuildResolutionContextsInputs {
+    readonly client: MondayClient;
+    readonly ctx: RunContext;
+    readonly globalFlags: GlobalFlags;
+}
+export interface ResolutionContexts {
+    readonly dateResolution: DateResolutionContext;
+    readonly peopleResolution: PeopleResolutionContext;
+}
+export declare const buildResolutionContexts: (inputs: BuildResolutionContextsInputs) => ResolutionContexts;
+//# sourceMappingURL=resolution-context.d.ts.map

package/dist/api/resolution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-context.d.ts","sourceRoot":"","sources":["../../src/api/resolution-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EACV,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,uBAAuB,CAAC;CACpD;AAED,eAAO,MAAM,uBAAuB,GAClC,QAAQ,6BAA6B,KACpC,kBAqBF,CAAC"}

package/dist/api/resolution-context.js

@@ -0,0 +1,42 @@
+/**
+ * `dateResolution` + `peopleResolution` builder, shared by every
+ * mutation surface that calls into `translateColumnValueAsync` /
+ * `planChanges` / `planCreate`.
+ *
+ * Both contexts close over `ctx.clock` + `ctx.env.MONDAY_TIMEZONE`
+ * (date side) and `client` + `ctx.env` + `globalFlags.noCache`
+ * (people side via `resolveMeFactory` + `userByEmail`). The
+ * builder is a pure function — no caching, no memoisation; each
+ * call returns a fresh pair. v0.3 is the natural home for `me`-token
+ * memoisation across translate calls in one command run; lifting
+ * this builder gives that change a single seam to extend.
+ *
+ * Lifted from four identical 12-line copies (`set.ts:327`,
+ * `update.ts:450` single, `update.ts:1275` bulk, `create.ts:893`)
+ * — see v0.2-plan §12 R24.
+ */
+import { resolveMeFactory } from './item-helpers.js';
+import { userByEmail } from './resolvers.js';
+export const buildResolutionContexts = (inputs) => {
+    const { client, ctx, globalFlags } = inputs;
+    const dateResolution = {
+        now: ctx.clock,
+        ...(ctx.env.MONDAY_TIMEZONE === undefined
+            ? {}
+            : { timezone: ctx.env.MONDAY_TIMEZONE }),
+    };
+    const peopleResolution = {
+        resolveMe: resolveMeFactory(client),
+        resolveEmail: async (email) => {
+            const result = await userByEmail({
+                client,
+                email,
+                env: ctx.env,
+                noCache: globalFlags.noCache,
+            });
+            return result.user.id;
+        },
+    };
+    return { dateResolution, peopleResolution };
+};
+//# sourceMappingURL=resolution-context.js.map

package/dist/api/resolution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-context.js","sourceRoot":"","sources":["../../src/api/resolution-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAa7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,MAAqC,EACjB,EAAE;IACtB,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAC5C,MAAM,cAAc,GAA0B;QAC5C,GAAG,EAAE,GAAG,CAAC,KAAK;QACd,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;KAC3C,CAAC;IACF,MAAM,gBAAgB,GAA4B;QAChD,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC;QACnC,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC5B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;gBAC/B,MAAM;gBACN,KAAK;gBACL,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,OAAO,EAAE,WAAW,CAAC,OAAO;aAC7B,CAAC,CAAC;YACH,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;IACF,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAC9C,CAAC,CAAC"}

package/dist/api/resolution-pass.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Three-pass column resolution + value translation for `--set` and
+ * `--set-raw` entries.
+ *
+ * Lifted from five sites — see v0.2-plan §12 R20:
+ *   - `api/dry-run.ts planChanges` (single-item dry-run)
+ *   - `api/dry-run.ts planCreate` (create dry-run)
+ *   - `commands/item/update.ts` action (single-item live)
+ *   - `commands/item/update.ts runBulk` (bulk live)
+ *   - `commands/item/create.ts` action (create live)
+ *
+ * Each implemented the same ~80-90 LOC three-pass discipline:
+ *
+ *   - **Pass (a)** — resolve every `--set` token, then every
+ *     `--set-raw` token, against the supplied board. Same-token
+ *     duplicates surface as `usage_error` (cli-design §5.3 line
+ *     961-972). Archived columns surface as `column_archived` (per
+ *     §5.3 step 6 — "Mutations against archived columns return
+ *     `column_archived` regardless"). Each leg's `source` /
+ *     `cacheAgeSeconds` / `warnings` aggregates into the running
+ *     totals.
+ *
+ *   - **Pass (b)** — cross-token duplicate-resolved-ID check. Two
+ *     distinct tokens (e.g. `status` and `id:status_4`, or `--set
+ *     status=Done` and `--set-raw id:status_4='{...}'`) resolving to
+ *     the same column ID surface as `usage_error`. The check fires
+ *     pre-translation to keep the engine from producing a half-built
+ *     diff and to avoid translator errors pre-empting the mutual-
+ *     exclusion error (Codex M8 finding #2).
+ *
+ *   - **Pass (c)** — translate. Friendly entries through
+ *     `translateColumnValueAsync`; raw entries through
+ *     `translateRawColumnValue`. Each catch folds the cumulative
+ *     `warnings` array (every leg's warnings) so prior tokens'
+ *     collision / `stale_cache_refreshed` signals survive into
+ *     the failure envelope's `details.resolver_warnings` (Codex M8
+ *     finding #1, M5b R19 contract).
+ *
+ * **Why this lift earns its place pre-M10.** M10 archive / delete /
+ * duplicate don't take `--set` so they're not consumers — but R20's
+ * payoff is in the M5b/M9 sites that already exist: a fix to the
+ * three-pass shape (bug, perf, contract change) lands in one place
+ * rather than five. Also a consistency win — pre-lift the message
+ * wording diverged across sites ("Monday rejects mutations against
+ * archived columns" vs "Monday rejects writes against archived
+ * columns") and the ApiError-vs-MondayCliError catch in pass (c)
+ * was inconsistent (planChanges/planCreate caught only `ApiError`,
+ * missing translator UsageErrors; update.ts/create.ts caught
+ * `MondayCliError`). The lift normalises both.
+ *
+ * **Behaviour-preservation contract.** Every existing test passes
+ * byte-for-byte. The two consistency normalisations above
+ * (archived-message wording + UsageError catch in dry-run paths)
+ * are observable but no test exercises them, and the unified
+ * behaviour is the M5b R19 contract's intent.
+ */
+import { ApiError } from '../utils/errors.js';
+import type { MondayClient } from './client.js';
+import { type ResolverWarning } from './columns.js';
+import { type DateResolutionContext, type PeopleResolutionContext, type TranslatedColumnValue } from './column-values.js';
+import { type ParsedSetRawExpression } from './raw-write.js';
+export interface SetEntry {
+    readonly token: string;
+    readonly value: string;
+}
+export interface ResolvedSet {
+    readonly kind: 'set';
+    readonly token: string;
+    readonly value: string;
+    readonly columnId: string;
+    readonly columnType: string;
+}
+export interface ResolvedRaw {
+    readonly kind: 'raw';
+    readonly token: string;
+    readonly entry: ParsedSetRawExpression;
+    readonly columnId: string;
+    readonly columnType: string;
+}
+export type ResolvedEntry = ResolvedSet | ResolvedRaw;
+export interface ResolveAndTranslateInputs {
+    readonly client: MondayClient;
+    /**
+     * The board column tokens resolve against. For `item set` /
+     * `item update` (single + bulk), this is the item's home board.
+     * For `item create` top-level, the explicit `--board <bid>`. For
+     * `item create --parent`, the auto-derived subitems board.
+     */
+    readonly boardId: string;
+    readonly setEntries: readonly SetEntry[];
+    readonly rawEntries: readonly ParsedSetRawExpression[];
+    readonly dateResolution?: DateResolutionContext;
+    readonly peopleResolution?: PeopleResolutionContext;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly noCache?: boolean;
+    /**
+     * Initial `source` seed. Defaults to `undefined` so the first leg
+     * of resolution becomes the seed value. Bulk callers pass the
+     * board-metadata leg's source (`'cache'` or `'live'`) so the
+     * downstream aggregator reflects every leg that fired (Codex M8
+     * finding #3 in update.ts bulk).
+     */
+    readonly initialSource?: 'live' | 'cache' | 'mixed';
+    /**
+     * Initial `cacheAgeSeconds` seed. Defaults to `null`. Bulk callers
+     * pass the board-metadata cacheAge so a cache-served metadata leg
+     * shows up in the worst-case staleness aggregate.
+     */
+    readonly initialCacheAgeSeconds?: number | null;
+}
+export interface ResolveAndTranslateResult {
+    readonly resolved: readonly ResolvedEntry[];
+    /**
+     * Translated values in argv order — `setEntries` first (in their
+     * argv order), then `rawEntries` (in their argv order). Callers
+     * downstream of the helper iterate this for their wire payload
+     * builders (`selectMutation` / `bundleColumnValues`).
+     */
+    readonly translated: readonly TranslatedColumnValue[];
+    /**
+     * Token → resolved column ID echo per cli-design §5.3 step 2 and
+     * §6.4 mutation-envelope shape.
+     */
+    readonly resolvedIds: Readonly<Record<string, string>>;
+    /**
+     * Cumulative resolver warnings across every resolution leg.
+     * Callers fold these into the success envelope's `warnings` slot
+     * and into the failure envelope's `details.resolver_warnings` via
+     * `foldResolverWarningsIntoError` (already done internally by the
+     * helper for every typed throw it raises — callers re-fold only
+     * for downstream throws their own catch arms produce).
+     */
+    readonly warnings: readonly ResolverWarning[];
+    /**
+     * Aggregate envelope source. `undefined` only when the helper was
+     * called with zero entries AND no `initialSource`; in practice
+     * callers gate the empty case before calling the helper.
+     */
+    readonly source: 'live' | 'cache' | 'mixed' | undefined;
+    readonly cacheAgeSeconds: number | null;
+}
+/**
+ * Builds a `column_archived` ApiError with the unified §6.5 wording
+ * + the canonical `details` slot (column_id / column_title /
+ * column_type / board_id). Single source of truth for the
+ * pre-mutation archived-column check; the three single-token
+ * surfaces (`item set`, `item clear`, `planClear`) call this so the
+ * message matches the helper-backed multi-token surfaces (`item
+ * update` single + bulk, `item create`, `planChanges`,
+ * `planCreate`). Mirrors the M5b R19 message convention; the
+ * `column_archived` error from the post-mutation F4 remap in
+ * `resolver-error-fold.ts` keeps its remap-specific message because
+ * the remap context is observably distinct (forced refresh +
+ * `details.remapped_from`).
+ */
+export declare const buildColumnArchivedError: (inputs: {
+    readonly columnId: string;
+    readonly columnTitle: string;
+    readonly columnType: string;
+    readonly boardId: string;
+}) => ApiError;
+export declare const resolveAndTranslate: (inputs: ResolveAndTranslateInputs) => Promise<ResolveAndTranslateResult>;
+//# sourceMappingURL=resolution-pass.d.ts.map

package/dist/api/resolution-pass.d.ts.map

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