monday-cli 0.3.0 → 0.4.0

package/dist/commands/item/upload.js

@@ -0,0 +1,370 @@
+/**
+ * `monday item upload <iid> --column <col> <file>` — attach a file to
+ * a `file`-typed column on an item via Monday's `add_file_to_column`
+ * mutation (cli-design.md §4.3 + §6.4 asset-upload sub-section +
+ * §13 v0.4 entry; v0.4-plan.md §3 M31).
+ *
+ * **Wire shape.** Single multipart/form-data round-trip via
+ * {@link addFileToColumn} against `mutation AddFileToColumn` with
+ * `operationName: 'AddFileToColumn'` (R-NEW-37 W2 audit-point).
+ * Uses the new `MultipartTransport` seam (`src/api/multipart-
+ * transport.ts`) — first v0.4 verb that does NOT cross the wire via
+ * the JSON-only `client.request` transport. See R-NEW-41 lift at
+ * `docs/architecture.md` "Wire-vs-CLI semantics documentation
+ * conventions" for the asymmetry context.
+ *
+ * **Argv shape.** Two positional args + one required flag:
+ *
+ *   - `<iid>` — numeric item ID; brand-validated via
+ *     {@link ItemIdSchema}.
+ *   - `<file>` — local file path; resolved relative to cwd. Must be
+ *     a readable regular file (not a directory). M31 does NOT
+ *     support stdin (`<file>='-'`) — stdin support is a
+ *     v0.4.x / v0.5 contract-extension once a clean `--filename
+ *     <name>` companion flag is pinned (no upload Asset.name when
+ *     reading from stdin).
+ *   - `--column <col>` — required; column ID on the target board
+ *     (resolved at runtime against board metadata to confirm
+ *     `type === 'file'`). Brand-validated via {@link ColumnIdSchema}
+ *     at the parse boundary; the column-type check fires at IMPL.
+ *
+ * **Column-type validation.** At IMPL, the action body resolves the
+ * column via the standard `resolveColumnWithRefresh` machinery and
+ * confirms `type === 'file'`. Non-`file` columns surface
+ * `unsupported_column_type` (matching the existing files_shaped
+ * rejection in `src/api/column-values.ts`'s UNSUPPORTED_TABLE) with
+ * a hint pointing at the right write path: `change_column_value` for
+ * `change_column_value`-shaped types (use `monday item set` /
+ * `monday item update --set-raw`); the rejection for `doc`-shaped
+ * columns is deferred to a future v0.4+ doc-upload milestone.
+ *
+ * **Local file failures + size handling — `details.reason`
+ * discrimination.** Three failure modes route through
+ * `usage_error` with a discriminated `details.reason` slot:
+ *
+ *   - `'file_not_readable'` — local path doesn't exist
+ *     (`ENOENT`), isn't readable (`EACCES`), or resolves to a
+ *     directory rather than a regular file. Fires at IMPL via
+ *     `fs.stat()` before any wire call.
+ *   - `'file_empty'` — file exists but is zero bytes. Monday
+ *     rejects empty uploads server-side; the CLI surfaces the
+ *     rejection with a clearer hint via `fs.stat()` pre-check
+ *     at IMPL.
+ *   - `'file_too_large'` — Monday's server-side size-cap
+ *     rejection rewrap (`FILE_SIZE_LIMIT_EXCEEDED` or HTTP
+ *     413). The CLI does NOT pre-check file size against a
+ *     hardcoded ceiling — Monday's per-file cap is plan-tier-
+ *     dependent (typically 500 MB at standard tiers, larger
+ *     at enterprise) and NOT exposed via the GraphQL schema
+ *     (empirical probe `scripts/probe/m31-asset-upload.ts`
+ *     2026-05-13 — `Plan` + `Account` carry no file-quota
+ *     fields). Rewrap carries `details.file_size_bytes` from
+ *     the **local `fs.stat()` measurement at upload time**
+ *     (NOT a Monday error-payload field — Monday's wire
+ *     rejection may not surface a size; the CLI already has
+ *     the local size from the read leg and threads it into
+ *     the details slot for a stable agent-keyed envelope)
+ *     + `details.hint` pointing at the plan-tier dependency.
+ *
+ * **`--dry-run` shape** per cli-design §3.1 #6 + §6.4 asset-upload
+ * variant. Strictly local-derived — no wire mutation fires. Planned
+ * change carries `{operation: 'add_file_to_column', item_id,
+ * column_id, file_path, filename, file_size_bytes}` (size from
+ * `fs.stat()`; no file bytes are actually transmitted on a dry-
+ * run). `meta.source: 'none'`.
+ *
+ * **Idempotency: NO** — re-running uploads the file a second time
+ * minting a new `Asset` ID. Agents needing register-once semantics
+ * read `Item.assets` first and skip the upload if a matching name
+ * exists (read-side surface deferred to v0.4.x — see v0.4-plan §3
+ * M31 Decision D6 closure).
+ *
+ * **Cache invalidation.** Successful upload changes the file
+ * column's `FileValue` ColumnValue → cached board metadata for that
+ * board stale; the action body fires `invalidateBoard(boardId, env)`
+ * after success per the §8 single-leg invalidation pattern (BEFORE
+ * `emitMutation` so a cache-unlink failure surfaces through the
+ * runner's catch-all rather than double-emitting after a success
+ * envelope already hit stdout).
+ *
+ * **Side effects.** None at IMPL — `add_file_to_column` does not
+ * post an update or trigger automations beyond Monday's own
+ * file-change activity log (which `item history` surfaces).
+ *
+ * **Status: runtime body shipped at v0.4-M31 IMPL.** Argv parsing
+ * + file-read + dry-run + multipart-dispatch + envelope emit + cache
+ * invalidation all land below.
+ */
+import { z } from 'zod';
+import { stat as fsStat, access as fsAccess, readFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { resolve as resolvePath, basename } from 'node:path';
+import { ensureSubcommand } from '../types.js';
+import { parseArgv } from '../parse-argv.js';
+import { ItemIdSchema, ColumnIdSchema } from '../../types/ids.js';
+import { itemUploadOutputSchema, addFileToColumn, } from '../../api/assets.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { resolveColumnWithRefresh } from '../../api/columns.js';
+import { lookupItemBoard } from '../../api/item-board-lookup.js';
+import { invalidateBoard } from '../../api/cache.js';
+import { foldResolverWarningsIntoError } from '../../api/resolver-error-fold.js';
+import { ApiError, UsageError, asError, errorCode } from '../../utils/errors.js';
+import { sniffContentType } from '../../utils/mime.js';
+import { emitMutation, emitDryRun } from '../emit.js';
+const inputSchema = z
+    .object({
+    itemId: ItemIdSchema,
+    column: ColumnIdSchema,
+    file: z
+        .string()
+        .min(1, {
+        message: '<file> must be a non-empty local file path; stdin (`-`) is not supported in v0.4-M31 (a future contract extension may add stdin support once a `--filename <name>` companion flag is pinned).',
+    })
+        .refine((p) => p !== '-', {
+        message: '<file> cannot be `-` — stdin upload is not supported in v0.4-M31. Pass a local file path resolved relative to cwd. A future contract extension may add stdin support once a `--filename <name>` companion flag is pinned.',
+    }),
+})
+    .strict();
+export const itemUploadCommand = {
+    name: 'item.upload',
+    summary: 'Attach a file to a file-typed column on an item via add_file_to_column',
+    examples: [
+        'monday item upload 12345 --column files ./screenshot.png',
+        'monday item upload 12345 --column attachments_3 ./report.pdf --dry-run',
+    ],
+    idempotent: false,
+    inputSchema,
+    outputSchema: itemUploadOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands (cli-design §4.3 ITEM)');
+        noun
+            .command('upload <itemId> <file>')
+            .description(itemUploadCommand.summary)
+            .requiredOption('--column <c>', 'Column ID on the target board. Must resolve to a `file`-typed column at runtime; non-`file` columns surface `unsupported_column_type` per cli-design §5.3.')
+            .addHelpText('after', [
+            '',
+            'Examples:',
+            ...itemUploadCommand.examples.map((e) => `  ${e}`),
+            '',
+            'Notes:',
+            '  - Uploads cross the wire as multipart/form-data (different transport from JSON-only verbs).',
+            '  - File path is resolved relative to the cwd; stdin (`-`) is not supported in this release.',
+            '  - Re-running with the same args creates a second Asset; `add_file_to_column` is not idempotent.',
+            '',
+        ].join('\n'))
+            .action(async (itemIdArg, fileArg, opts) => {
+            const parsed = parseArgv(itemUploadCommand.inputSchema, {
+                itemId: itemIdArg,
+                file: fileArg,
+                column: opts.column,
+            });
+            // Resolve the absolute file path relative to cwd. Pre-check
+            // existence + type + read-permission + emptiness via
+            // `fs.stat()` + `fs.access(..., R_OK)` BEFORE resolveClient
+            // so a missing/unreadable-file error surfaces as usage_error
+            // (exit 1) rather than getting tangled up with config_error
+            // (exit 3) on a token miss OR firing AFTER `lookupItemBoard`
+            // / `resolveColumnWithRefresh` Monday wire calls (round-1
+            // P2-2 fix — `fs.stat()` alone confirms type/size but not
+            // R_OK; an unreadable file would otherwise pass the
+            // pre-check and `fs.readFile()` would throw a raw fs error
+            // mid-upload after wire calls).
+            const filePath = resolvePath(process.cwd(), parsed.file);
+            const filename = basename(filePath);
+            let fileSizeBytes;
+            try {
+                const stats = await fsStat(filePath);
+                if (!stats.isFile()) {
+                    throw new UsageError(`<file> ${JSON.stringify(parsed.file)} is not a regular file ` +
+                        `(resolved to ${JSON.stringify(filePath)}).`, {
+                        details: {
+                            reason: 'file_not_readable',
+                            file_path: filePath,
+                            hint: 'pass a path to a regular readable file; directories ' +
+                                'and special files (sockets, devices) are rejected.',
+                        },
+                    });
+                }
+                await fsAccess(filePath, fsConstants.R_OK);
+                fileSizeBytes = stats.size;
+            }
+            catch (err) {
+                if (err instanceof UsageError) {
+                    throw err;
+                }
+                const code = errorCode(err);
+                throw new UsageError(`<file> ${JSON.stringify(parsed.file)} cannot be read ` +
+                    `(resolved to ${JSON.stringify(filePath)}): ` +
+                    `${asError(err).message}.`, {
+                    cause: err,
+                    details: {
+                        reason: 'file_not_readable',
+                        file_path: filePath,
+                        ...(code === undefined ? {} : { errno_code: code }),
+                        hint: 'check that the path exists, is readable by the current ' +
+                            'user, and isn\'t a directory.',
+                    },
+                });
+            }
+            if (fileSizeBytes === 0) {
+                throw new UsageError(`<file> ${JSON.stringify(parsed.file)} is empty (0 bytes); ` +
+                    `Monday rejects empty uploads server-side.`, {
+                    details: {
+                        reason: 'file_empty',
+                        file_path: filePath,
+                        filename,
+                        file_size_bytes: 0,
+                        hint: 'Monday returns FILE_SIZE_LIMIT_EXCEEDED on empty ' +
+                            'uploads. Provide a non-empty file or remove the upload ' +
+                            'call.',
+                    },
+                });
+            }
+            const { client, globalFlags, apiVersion, multipart, toEmit } = resolveClient(ctx, program.opts());
+            if (globalFlags.dryRun) {
+                // D5 closure: dry-run is fs.stat()-backed (NOT a 0-byte
+                // stub). Planned-change carries `{operation, item_id,
+                // column_id, file_path, filename, file_size_bytes}` from
+                // the local stat; no wire mutation fires; no file bytes
+                // loaded into memory. `meta.source: 'none'`.
+                //
+                // `file_path` is the **argv-derived** path the agent
+                // passed (relative or absolute), preserving the
+                // invocation surface — matches cli-design §6.4 +
+                // output-shapes which sample `./screenshot.png` (round-2
+                // P3-2 fix). Agents that need an absolute path can
+                // resolve from cwd + `file_path` themselves; the
+                // resolved absolute path lives in `details.file_path`
+                // on `usage_error.details.reason: 'file_not_readable'` /
+                // `'file_empty'` rejections (where the absolute is
+                // useful for diagnosing path resolution mismatches).
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: [
+                        {
+                            operation: 'add_file_to_column',
+                            item_id: parsed.itemId,
+                            column_id: parsed.column,
+                            file_path: parsed.file,
+                            filename,
+                            file_size_bytes: fileSizeBytes,
+                        },
+                    ],
+                    source: 'none',
+                    cacheAgeSeconds: null,
+                    apiVersion,
+                });
+                return;
+            }
+            // Live path. Resolve the parent board so we can (a) pin the
+            // column-type check to the right board metadata and (b) fire
+            // cache invalidation on the right board after a successful
+            // upload (D6 single-leg per §8). `lookupItemBoard` throws
+            // `not_found` on a missing item or null-board, so a bad
+            // <iid> surfaces a typed envelope before file BYTES are
+            // loaded — the local `fs.stat()` + `fs.access()` pre-check
+            // above already ran (round-3 P3-2 prose precision; ordering
+            // stays "argv parse → local file pre-check → wire lookup →
+            // column resolution → file bytes → multipart dispatch →
+            // cache invalidation → emit").
+            const { boardId } = await lookupItemBoard({
+                client,
+                itemId: parsed.itemId,
+            });
+            const resolution = await resolveColumnWithRefresh({
+                client,
+                boardId,
+                token: parsed.column,
+                includeArchived: true,
+                env: ctx.env,
+                noCache: globalFlags.noCache,
+            });
+            const resolverWarnings = resolution.warnings;
+            const resolvedColumn = resolution.match.column;
+            if (resolvedColumn.archived === true) {
+                throw foldResolverWarningsIntoError(new ApiError('column_archived', `Column ${JSON.stringify(resolvedColumn.title)} ` +
+                    `(id ${resolvedColumn.id}) on board ${boardId} is ` +
+                    `archived; un-archive the column before uploading to it.`, {
+                    details: {
+                        column_id: resolvedColumn.id,
+                        column_title: resolvedColumn.title,
+                        column_type: resolvedColumn.type,
+                        board_id: boardId,
+                    },
+                }), resolverWarnings);
+            }
+            if (resolvedColumn.type !== 'file') {
+                throw foldResolverWarningsIntoError(new ApiError('unsupported_column_type', `Column ${JSON.stringify(resolvedColumn.title)} ` +
+                    `(id ${resolvedColumn.id}) has type ` +
+                    `${JSON.stringify(resolvedColumn.type)}, which Monday ` +
+                    `writes via change_column_value not add_file_to_column. ` +
+                    `monday item upload only accepts file-typed columns.`, {
+                    details: {
+                        column_id: resolvedColumn.id,
+                        column_title: resolvedColumn.title,
+                        type: resolvedColumn.type,
+                        board_id: boardId,
+                        hint: 'use `monday item set` / `monday item update --set` ' +
+                            'against this column; `monday item upload` only ' +
+                            'accepts file-typed columns (cli-design §5.3 ' +
+                            'writer-expansion roadmap "files" row).',
+                    },
+                }), resolverWarnings);
+            }
+            // Read the file bytes into a Blob with a sniffed content-
+            // type. Done AFTER column-type validation so a non-`file`
+            // column rejection doesn't pay for the full read.
+            const bytes = await readFile(filePath);
+            const file = new Blob([bytes], { type: sniffContentType(filename) });
+            const result = await addFileToColumn({
+                client,
+                multipart,
+                itemId: parsed.itemId,
+                columnId: resolvedColumn.id,
+                file,
+                filename,
+                signal: ctx.signal,
+                retries: globalFlags.retry,
+            });
+            // §8 single-leg cache invalidation (D6). Fired BEFORE
+            // emitMutation so a cache-unlink failure surfaces through
+            // the runner's catch-all rather than double-emitting after
+            // the success envelope already hit stdout.
+            await invalidateBoard(boardId, ctx.env);
+            const data = {
+                operation: 'add_file_to_column',
+                item_id: parsed.itemId,
+                column_id: resolvedColumn.id,
+                filename,
+                file_size_bytes: fileSizeBytes,
+                asset: result.asset,
+            };
+            // `toEmit` carries `source: 'live'` + the resolved
+            // `apiVersion`. Splat first; override `complexity` with the
+            // multipart wire's projection (Monday's asset-upload
+            // mutations don't return a complexity block today, but
+            // honoring the slot mirrors the JSON-fetcher pattern).
+            emitMutation({
+                ctx,
+                data,
+                schema: itemUploadCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings: resolverWarnings.map((w) => ({
+                    code: w.code,
+                    message: w.message,
+                    details: w.details,
+                })),
+                ...toEmit({
+                    data: result.asset,
+                    complexity: result.complexity,
+                    stats: { attempts: 1, totalBackoffMs: 0 },
+                }),
+                source: 'live',
+                cacheAgeSeconds: null,
+                complexity: result.complexity,
+            });
+        });
+    },
+};
+//# sourceMappingURL=upload.js.map

package/dist/commands/item/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../src/commands/item/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,IAAI,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAsB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,sBAAsB,EAEtB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,GAAG,CAAC;KAClB,MAAM,CAAC;IACN,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,cAAc;IACtB,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE;QACN,OAAO,EACL,+LAA+L;KAClM,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,EAAE;QACxB,OAAO,EACL,2NAA2N;KAC9N,CAAC;CACL,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,iBAAiB,GAG1B;IACF,IAAI,EAAE,aAAa;IACnB,OAAO,EACL,wEAAwE;IAC1E,QAAQ,EAAE;QACR,0DAA0D;QAC1D,wEAAwE;KACzE;IACD,UAAU,EAAE,KAAK;IACjB,WAAW;IACX,YAAY,EAAE,sBAAsB;IACpC,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,IAAI,GAAG,gBAAgB,CAC3B,OAAO,EACP,MAAM,EACN,sCAAsC,CACvC,CAAC;QACF,IAAI;aACD,OAAO,CAAC,wBAAwB,CAAC;aACjC,WAAW,CAAC,iBAAiB,CAAC,OAAO,CAAC;aACtC,cAAc,CACb,cAAc,EACd,4JAA4J,CAC7J;aACA,WAAW,CACV,OAAO,EACP;YACE,EAAE;YACF,WAAW;YACX,GAAG,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,EAAE;YACF,QAAQ;YACR,+FAA+F;YAC/F,8FAA8F;YAC9F,mGAAmG;YACnG,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;aACA,MAAM,CACL,KAAK,EACH,SAAkB,EAClB,OAAgB,EAChB,IAAwB,EACxB,EAAE;YACF,MAAM,MAAM,GAAG,SAAS,CAAC,iBAAiB,CAAC,WAAW,EAAE;gBACtD,MAAM,EAAE,SAAS;gBACjB,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,IAAI,CAAC,MAAM;aACpB,CAAC,CAAC;YAEH,4DAA4D;YAC5D,qDAAqD;YACrD,4DAA4D;YAC5D,6DAA6D;YAC7D,4DAA4D;YAC5D,6DAA6D;YAC7D,0DAA0D;YAC1D,0DAA0D;YAC1D,oDAAoD;YACpD,2DAA2D;YAC3D,gCAAgC;YAChC,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACzD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,aAAqB,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACrC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;oBACpB,MAAM,IAAI,UAAU,CAClB,UAAU,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB;wBAC5D,gBAAgB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAC9C;wBACE,OAAO,EAAE;4BACP,MAAM,EAAE,mBAAmB;4BAC3B,SAAS,EAAE,QAAQ;4BACnB,IAAI,EACF,sDAAsD;gCACtD,oDAAoD;yBACvD;qBACF,CACF,CAAC;gBACJ,CAAC;gBACD,MAAM,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;gBAC3C,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC;YAC7B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;oBAC9B,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC5B,MAAM,IAAI,UAAU,CAClB,UAAU,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB;oBACrD,gBAAgB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK;oBAC7C,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,EAC5B;oBACE,KAAK,EAAE,GAAG;oBACV,OAAO,EAAE;wBACP,MAAM,EAAE,mBAAmB;wBAC3B,SAAS,EAAE,QAAQ;wBACnB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;wBACnD,IAAI,EACF,yDAAyD;4BACzD,+BAA+B;qBAClC;iBACF,CACF,CAAC;YACJ,CAAC;YACD,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,UAAU,CAClB,UAAU,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB;oBAC1D,2CAA2C,EAC7C;oBACE,OAAO,EAAE;wBACP,MAAM,EAAE,YAAY;wBACpB,SAAS,EAAE,QAAQ;wBACnB,QAAQ;wBACR,eAAe,EAAE,CAAC;wBAClB,IAAI,EACF,mDAAmD;4BACnD,yDAAyD;4BACzD,OAAO;qBACV;iBACF,CACF,CAAC;YACJ,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,GAC1D,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YAErC,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;gBACvB,wDAAwD;gBACxD,sDAAsD;gBACtD,yDAAyD;gBACzD,wDAAwD;gBACxD,6CAA6C;gBAC7C,EAAE;gBACF,qDAAqD;gBACrD,gDAAgD;gBAChD,iDAAiD;gBACjD,yDAAyD;gBACzD,mDAAmD;gBACnD,iDAAiD;gBACjD,sDAAsD;gBACtD,yDAAyD;gBACzD,mDAAmD;gBACnD,qDAAqD;gBACrD,UAAU,CAAC;oBACT,GAAG;oBACH,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE;oBAC3B,cAAc,EAAE;wBACd;4BACE,SAAS,EAAE,oBAAoB;4BAC/B,OAAO,EAAE,MAAM,CAAC,MAAM;4BACtB,SAAS,EAAE,MAAM,CAAC,MAAM;4BACxB,SAAS,EAAE,MAAM,CAAC,IAAI;4BACtB,QAAQ;4BACR,eAAe,EAAE,aAAa;yBAC/B;qBACF;oBACD,MAAM,EAAE,MAAM;oBACd,eAAe,EAAE,IAAI;oBACrB,UAAU;iBACX,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,4DAA4D;YAC5D,6DAA6D;YAC7D,2DAA2D;YAC3D,0DAA0D;YAC1D,wDAAwD;YACxD,wDAAwD;YACxD,2DAA2D;YAC3D,4DAA4D;YAC5D,2DAA2D;YAC3D,wDAAwD;YACxD,+BAA+B;YAC/B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,eAAe,CAAC;gBACxC,MAAM;gBACN,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC;gBAChD,MAAM;gBACN,OAAO;gBACP,KAAK,EAAE,MAAM,CAAC,MAAM;gBACpB,eAAe,EAAE,IAAI;gBACrB,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,OAAO,EAAE,WAAW,CAAC,OAAO;aAC7B,CAAC,CAAC;YACH,MAAM,gBAAgB,GAAG,UAAU,CAAC,QAAQ,CAAC;YAC7C,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;YAE/C,IAAI,cAAc,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACrC,MAAM,6BAA6B,CACjC,IAAI,QAAQ,CACV,iBAAiB,EACjB,UAAU,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG;oBAC/C,OAAO,cAAc,CAAC,EAAE,cAAc,OAAO,MAAM;oBACnD,yDAAyD,EAC3D;oBACE,OAAO,EAAE;wBACP,SAAS,EAAE,cAAc,CAAC,EAAE;wBAC5B,YAAY,EAAE,cAAc,CAAC,KAAK;wBAClC,WAAW,EAAE,cAAc,CAAC,IAAI;wBAChC,QAAQ,EAAE,OAAO;qBAClB;iBACF,CACF,EACD,gBAAgB,CACjB,CAAC;YACJ,CAAC;YAED,IAAI,cAAc,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACnC,MAAM,6BAA6B,CACjC,IAAI,QAAQ,CACV,yBAAyB,EACzB,UAAU,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG;oBAC/C,OAAO,cAAc,CAAC,EAAE,aAAa;oBACrC,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB;oBACvD,yDAAyD;oBACzD,qDAAqD,EACvD;oBACE,OAAO,EAAE;wBACP,SAAS,EAAE,cAAc,CAAC,EAAE;wBAC5B,YAAY,EAAE,cAAc,CAAC,KAAK;wBAClC,IAAI,EAAE,cAAc,CAAC,IAAI;wBACzB,QAAQ,EAAE,OAAO;wBACjB,IAAI,EACF,qDAAqD;4BACrD,iDAAiD;4BACjD,8CAA8C;4BAC9C,wCAAwC;qBAC3C;iBACF,CACF,EACD,gBAAgB,CACjB,CAAC;YACJ,CAAC;YAED,0DAA0D;YAC1D,0DAA0D;YAC1D,kDAAkD;YAClD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACvC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAErE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;gBACnC,MAAM;gBACN,SAAS;gBACT,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,cAAc,CAAC,EAAE;gBAC3B,IAAI;gBACJ,QAAQ;gBACR,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,OAAO,EAAE,WAAW,CAAC,KAAK;aAC3B,CAAC,CAAC;YAEH,sDAAsD;YACtD,0DAA0D;YAC1D,2DAA2D;YAC3D,2CAA2C;YAC3C,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YAExC,MAAM,IAAI,GAAqB;gBAC7B,SAAS,EAAE,oBAAoB;gBAC/B,OAAO,EAAE,MAAM,CAAC,MAAM;gBACtB,SAAS,EAAE,cAAc,CAAC,EAAE;gBAC5B,QAAQ;gBACR,eAAe,EAAE,aAAa;gBAC9B,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC;YAEF,mDAAmD;YACnD,4DAA4D;YAC5D,qDAAqD;YACrD,uDAAuD;YACvD,uDAAuD;YACvD,YAAY,CAAC;gBACX,GAAG;gBACH,IAAI;gBACJ,MAAM,EAAE,iBAAiB,CAAC,YAAY;gBACtC,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE;gBAC3B,QAAQ,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACrC,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,OAAO,EAAE,CAAC,CAAC,OAAO;iBACnB,CAAC,CAAC;gBACH,GAAG,MAAM,CAAC;oBACR,IAAI,EAAE,MAAM,CAAC,KAAK;oBAClB,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE;iBAC1C,CAAC;gBACF,MAAM,EAAE,MAAM;gBACd,eAAe,EAAE,IAAI;gBACrB,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAC,CAAC;QACL,CAAC,CACF,CAAC;IACN,CAAC;CACF,CAAC"}

package/dist/commands/item/watch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `monday item watch <iid>` — polling-based event stream over the
+ * v0.3-M24 `item-history-projection.ts` projector. Runtime body
+ * shipped at v0.4-M29 IMPL (`7b83a3a` + round-1 fix-ups). Pinned
+ * per cli-design §13 v0.4 entry + §14.4 closure (`31713fb`) +
+ * v0.4-plan §3 M29.
+ *
+ * **What this verb answers:** "wait for changes on this item + emit
+ * them as they arrive". Single CLI invocation polls Monday's
+ * `boards(ids:){ activity_logs(item_ids:, from:, limit:) }` surface
+ * each tick, projects new rows through the M24 projector, emits one
+ * NDJSON record per new event plus a session-summary trailer on exit.
+ *
+ * **GraphQL operation:** `ItemWatchPoll` (one per poll tick;
+ * R-NEW-37 W2 audit-point — operationName pinned in
+ * `WATCH_POLL_QUERY` literal at `src/api/item-watch.ts`).
+ *
+ * **Action shape (M29 IMPL).** Item-board lookup via
+ * `lookupItemBoard` → `watchItem` polling loop with NDJSON
+ * `onEvent` streaming hook + per-event projection via M24's
+ * `projectActivityLogRow` → trailer-meta emit on graceful exit.
+ * SIGINT graceful drain via `ctx.signal` (the same AbortSignal seam
+ * M22 status uses). The polling loop owns:
+ *
+ *   - Cadence (default 30s; range 1s–1h; `--interval <ms>`).
+ *   - Watermark advance (last-seen-event-id; `--since <event-id>`
+ *     bootstraps).
+ *   - Circuit breaker (reactive on Monday wire errors; trip after 5
+ *     consecutive failures; per-failure warnings accumulate on
+ *     `WatchItemResult.warnings` and fold into the trailer's
+ *     `_meta.warnings` slot at session end per cli-design §6.3 —
+ *     NOT interleaved with event lines).
+ *   - Limit enforcement (`--max-events <n>` / `--max-duration
+ *     <seconds>`).
+ *   - `--once` short-circuit (drain backlog and exit; do NOT poll).
+ *
+ * **Output:** NDJSON only at v0.4-M29 — `--json` / `--table` /
+ * `--output` global flags ignored (this is a streaming verb).
+ * Trailer-meta carries seven M29-specific slots:
+ * `events_emitted` + `polls_made` + `failed_polls` +
+ * `watch_duration_seconds` + `last_seen_event_id` +
+ * `circuit_broken_at` + `exit_reason`. Plus the standard §6.3
+ * `_meta.warnings[]` slot collects any `WatchSessionWarning`
+ * records the polling loop accumulated (poll_failed,
+ * circuit_breaker_armed, unknown_event_kind) — warnings are NOT
+ * interleaved with event lines.
+ *
+ * Idempotent: yes (pure read; re-running with the same `--since` is
+ * safe).
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type HistoryEvent } from '../../api/item-history-projection.js';
+/**
+ * Argv input schema for `monday item watch <iid>`. Validates at the
+ * parse boundary; the action body consumes the validated shape
+ * directly (no defensive re-checks).
+ *
+ * Mutual-exclusion rules (superRefine):
+ *
+ *   - `--once` is incompatible with `--max-events` / `--max-duration`.
+ *     `--once` already pins the exit (drain then return); a max-event
+ *     ceiling would be redundant and a max-duration ceiling could
+ *     race the backlog drain.
+ *   - `--interval <ms>` requires the bare-integer ms form; the closure
+ *     pins ms semantics (not bare seconds) to disambiguate 30 vs
+ *     30000 unambiguously. Range 1000–3600000 (1s–1h).
+ */
+declare const inputSchema: z.ZodObject<{
+    iid: z.core.$ZodBranded<z.ZodString, "ItemId", "out">;
+    interval: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    since: z.ZodOptional<z.ZodString>;
+    once: z.ZodOptional<z.ZodBoolean>;
+    maxEvents: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    maxDuration: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    include: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodEnum<{
+        unknown: "unknown";
+        update_column_value: "update_column_value";
+        create_column: "create_column";
+        create_group: "create_group";
+        update_board_name: "update_board_name";
+        update_board_nickname: "update_board_nickname";
+        board_workspace_id_changed: "board_workspace_id_changed";
+        update_posted: "update_posted";
+        update_replied: "update_replied";
+    }>>>>;
+}, z.core.$strict>;
+export declare const itemWatchCommand: CommandModule<z.infer<typeof inputSchema>, HistoryEvent>;
+export {};
+//# sourceMappingURL=watch.d.ts.map

package/dist/commands/item/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../../src/commands/item/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAsBnE,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,sCAAsC,CAAC;AAkD9C;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;kBAsEb,CAAC;AAEL,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAC1C,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,YAAY,CA8Lb,CAAC"}