monday-cli 0.3.0 → 0.4.0

package/dist/commands/item/watch.js

@@ -0,0 +1,342 @@
+/**
+ * `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 { ensureSubcommand } from '../types.js';
+import { parseArgv } from '../parse-argv.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { lookupItemBoard } from '../../api/item-board-lookup.js';
+import { SourceAggregator } from '../../api/source-aggregator.js';
+import { buildStreamingTrailerMeta, startNdjsonStream, } from '../../utils/output/ndjson.js';
+import { collectSecrets } from '../../cli/envelope-out.js';
+import { ApiError } from '../../utils/errors.js';
+import { ItemIdSchema } from '../../types/ids.js';
+import { CIRCUIT_BREAKER_CONSECUTIVE_FAILS, DEFAULT_WATCH_INTERVAL_MS, MAX_WATCH_INTERVAL_MS, MIN_WATCH_INTERVAL_MS, watchItem, } from '../../api/item-watch.js';
+import { historyEventSchema, } from '../../api/item-history-projection.js';
+/**
+ * The `--include` flag accepts a comma-separated list of literal kind
+ * values from the M24 closed event-kind taxonomy (9 kinds). Mirrors
+ * `item history`'s `--kinds` enum verbatim — forward-compat at the
+ * argv boundary even though v0.4-M29 only emits activity-log-sourced
+ * kinds (the projector's `update_posted` / `update_replied` variants
+ * are from the updates source, which v0.4-M29 doesn't poll; agents
+ * passing those kinds get no events at v0.4 but the argv accepts them
+ * for v0.5+ comment-polling compatibility).
+ */
+const WATCH_KIND_LITERALS = [
+    'update_column_value',
+    'create_column',
+    'create_group',
+    'update_board_name',
+    'update_board_nickname',
+    'board_workspace_id_changed',
+    'update_posted',
+    'update_replied',
+    'unknown',
+];
+const watchKindSchema = z.enum(WATCH_KIND_LITERALS);
+/**
+ * Parses `--include <list>` (comma-separated; commander hands it over
+ * as a raw string). Empty entries filtered before validation so
+ * `--include update_column_value,` doesn't raise `usage_error`. Empty
+ * arrays after the filter raise `usage_error` rather than silently
+ * meaning "include everything" — an agent passing `--include ,,` is
+ * almost certainly bug, not intent.
+ */
+const includeListSchema = z
+    .string()
+    .transform((raw) => raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0))
+    .pipe(z.array(watchKindSchema).min(1));
+/**
+ * Event-ID validator for `--since <event-id>`. Numeric string per
+ * Monday's `ActivityLogType.id` shape (NON_NULL String at the wire
+ * level but always digits in practice per the M24 probe). Open shape
+ * (no length cap) — Monday's event IDs are typically 13+ digits.
+ */
+const eventIdSchema = z
+    .string()
+    .min(1)
+    .regex(/^\d+$/u, { message: 'must be a numeric event ID (digits only)' });
+/**
+ * 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).
+ */
+const inputSchema = z
+    .object({
+    iid: ItemIdSchema,
+    /**
+     * Polling cadence in milliseconds. Default
+     * {@link DEFAULT_WATCH_INTERVAL_MS} (30000ms / 30s) per cli-design
+     * §14.4 closure. Range {@link MIN_WATCH_INTERVAL_MS} (1000ms /
+     * 1s; faster trips Monday's request-rate concerns + the
+     * propagation-lag floor) to {@link MAX_WATCH_INTERVAL_MS}
+     * (3600000ms / 1h; slower crosses the "no longer a watch" line —
+     * use `cron + monday item history` for hourly cadences).
+     */
+    interval: z.coerce
+        .number()
+        .int()
+        .min(MIN_WATCH_INTERVAL_MS)
+        .max(MAX_WATCH_INTERVAL_MS)
+        .optional(),
+    /**
+     * Last-seen-event-id watermark for session restart. One-shot
+     * bootstrap — the runtime looks up the event's `created_at`
+     * once, sets the initial poll-from timestamp, emits any backlog
+     * past the watermark, then enters the polling loop. Distinct
+     * from a full `--resume <token>` mechanism (still open per
+     * cli-design §14.6).
+     */
+    since: eventIdSchema.optional(),
+    /**
+     * Drain backlog from `--since` (or recent N if no `--since`) and
+     * exit without polling. Distinct from `--max-events 1` which
+     * waits for the NEXT event.
+     */
+    once: z.boolean().optional(),
+    /**
+     * Cap on emitted events. Session exits with
+     * `exit_reason: 'max_events'` once the count is reached
+     * (success envelope).
+     */
+    maxEvents: z.coerce.number().int().positive().optional(),
+    /**
+     * Wall-clock ceiling in seconds. Session exits with
+     * `exit_reason: 'max_duration'` once the duration is reached
+     * (current in-flight poll completes first).
+     */
+    maxDuration: z.coerce.number().int().positive().optional(),
+    /**
+     * Comma-separated list of event kinds to retain. Filter applied
+     * at projection time (Monday doesn't expose a server-side filter
+     * on `activity_logs.event`). Accepts all 9 M24 kinds for
+     * forward-compat; v0.4-M29 only emits activity-log-sourced
+     * kinds.
+     */
+    include: includeListSchema.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.once === true && value.maxEvents !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: '--once is incompatible with --max-events (pick one)',
+            path: ['once'],
+        });
+    }
+    if (value.once === true && value.maxDuration !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: '--once is incompatible with --max-duration (pick one)',
+            path: ['once'],
+        });
+    }
+});
+export const itemWatchCommand = {
+    name: 'item.watch',
+    summary: 'Poll Monday for activity-log events on an item; stream NDJSON as they arrive',
+    examples: [
+        'monday item watch 1234567890',
+        'monday item watch 1234567890 --interval 60000        # 60s cadence',
+        'monday item watch 1234567890 --since 999999          # resume from event-id',
+        'monday item watch 1234567890 --once                  # drain backlog + exit',
+        'monday item watch 1234567890 --max-events 10',
+        'monday item watch 1234567890 --max-duration 3600     # 1h ceiling',
+        'monday item watch 1234567890 --include update_column_value,update_posted',
+    ],
+    idempotent: true,
+    inputSchema,
+    // Mirrors M24 `item history`: the output schema describes the
+    // per-event record shape an agent sees on the NDJSON stream — NOT
+    // the session-summary trailer (the trailer-meta shape is documented
+    // in output-shapes.md + cli-design §4.3, but a streaming verb has no
+    // buffered `data` payload). `monday schema item.watch` reflects
+    // the event-record shape so agents pin their per-line parsers
+    // against the same discriminated-union taxonomy `item history`
+    // uses.
+    outputSchema: historyEventSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands');
+        noun
+            .command('watch <iid>')
+            .description(itemWatchCommand.summary)
+            .option('--interval <ms>', `polling cadence in milliseconds (${String(MIN_WATCH_INTERVAL_MS)}–${String(MAX_WATCH_INTERVAL_MS)}, default ${String(DEFAULT_WATCH_INTERVAL_MS)})`)
+            .option('--since <event-id>', 'resume from a previous session\'s last-seen-event-id (numeric ID from trailer-meta)')
+            .option('--once', 'drain backlog from --since (or recent events) and exit without polling')
+            .option('--max-events <n>', 'exit cleanly after emitting N events')
+            .option('--max-duration <seconds>', 'exit cleanly after N wall-clock seconds')
+            .option('--include <list>', 'comma-separated event kinds to retain (e.g. update_column_value,update_posted)')
+            .addHelpText('after', [
+            '',
+            'Examples:',
+            ...itemWatchCommand.examples.map((e) => `  ${e}`),
+            '',
+            `NOTE: emits NDJSON only (one event per line + trailing meta).`,
+            `Default cadence ${String(DEFAULT_WATCH_INTERVAL_MS)}ms (${String(DEFAULT_WATCH_INTERVAL_MS / 1000)}s); circuit-breaker trips after`,
+            `${String(CIRCUIT_BREAKER_CONSECUTIVE_FAILS)} consecutive failed polls. Resume across sessions via`,
+            '--since <event-id> from the prior trailer-meta\'s last_seen_event_id.',
+            'SIGINT triggers a graceful drain + trailer emit + exit 130.',
+            '',
+            'Monday\'s activity_logs has an empirically-measured propagation lag',
+            '>30s on freshly-edited boards (M24 pre-flight finding 2026-05-11);',
+            'cadence faster than 30s would generate polls against unpropagated data.',
+            '',
+        ].join('\n'))
+            .action(async (iid, rawOpts) => {
+            const merged = { ...rawOpts, iid };
+            const parsed = parseArgv(itemWatchCommand.inputSchema, merged);
+            const { client, apiVersion } = resolveClient(ctx, program.opts());
+            // Item-board lookup short-circuits a missing-item watch with
+            // `not_found` before the polling loop spins up. The lookup is
+            // a single wire call; SourceAggregator records it as `'live'`
+            // so the trailer's `meta.source` stays correct if a future
+            // cache layer lifts in here.
+            const { boardId } = await lookupItemBoard({
+                client,
+                itemId: parsed.iid,
+            });
+            const aggregator = new SourceAggregator();
+            aggregator.record('live', null);
+            const stream = startNdjsonStream({
+                stream: ctx.stdout,
+                secrets: collectSecrets(ctx.env, ctx.runtimeSecrets),
+                project: (event) => event,
+            });
+            const result = await watchItem({
+                client,
+                itemId: parsed.iid,
+                boardId,
+                intervalMs: parsed.interval ?? DEFAULT_WATCH_INTERVAL_MS,
+                ...(parsed.since === undefined ? {} : { since: parsed.since }),
+                ...(parsed.once === undefined ? {} : { once: parsed.once }),
+                ...(parsed.maxEvents === undefined ? {} : { maxEvents: parsed.maxEvents }),
+                ...(parsed.maxDuration === undefined ? {} : { maxDurationSeconds: parsed.maxDuration }),
+                ...(parsed.include === undefined ? {} : { includeKinds: parsed.include }),
+                signal: ctx.signal,
+                onEvent: stream.onItem,
+            });
+            aggregator.record(result.source, null);
+            const aggregated = aggregator.result('live');
+            // `WatchSessionWarning` already structurally satisfies the
+            // §6.1 `Warning` shape (code + message + details); the
+            // trailer slot accepts the superset directly.
+            const trailerWarnings = result.warnings;
+            stream.writeTrailer(buildStreamingTrailerMeta({
+                ctx: {
+                    cliVersion: ctx.cliVersion,
+                    requestId: ctx.requestId,
+                    clock: ctx.clock,
+                },
+                apiVersion,
+                source: aggregated.source,
+                cacheAgeSeconds: aggregated.cacheAgeSeconds,
+                result: {
+                    // `has_more` reflects "the source still has events past
+                    // this session's exit point" — true for ceiling-driven
+                    // exits (max_events / max_duration / signal) where the
+                    // agent might re-invoke with --since; false for
+                    // once_complete (the backlog was the whole window) and
+                    // circuit_broken (the session failed, not the source
+                    // running out).
+                    hasMore: result.exit_reason === 'max_events' ||
+                        result.exit_reason === 'max_duration' ||
+                        result.exit_reason === 'signal',
+                    totalReturned: result.events_emitted,
+                    complexity: null,
+                },
+                session: {
+                    eventsEmitted: result.events_emitted,
+                    pollsMade: result.polls_made,
+                    failedPolls: result.failed_polls,
+                    watchDurationSeconds: result.watch_duration_seconds,
+                    lastSeenEventId: result.last_seen_event_id,
+                    circuitBrokenAt: result.circuit_broken_at,
+                    exitReason: result.exit_reason,
+                },
+                warnings: trailerWarnings,
+            }));
+            // Circuit-broken exit surfaces as a §6.5 failure envelope on
+            // stderr AFTER the trailer emitted on stdout. The Monday code
+            // that tripped the breaker lives on the last `poll_failed`
+            // warning's `details.monday_code` slot (no other source: the
+            // ApiError thrown by `client.raw` was caught + converted to a
+            // warning inside `watchItem`).
+            if (result.exit_reason === 'circuit_broken') {
+                const lastPollFailed = [...result.warnings]
+                    .reverse()
+                    .find((w) => w.code === 'poll_failed');
+                /* c8 ignore next 2 — defensive: circuit_broken always
+                   trips off a poll_failed accumulation; the find always
+                   succeeds in production. */
+                const mondayCode = lastPollFailed?.details.monday_code ??
+                    'complexity_exceeded';
+                throw new ApiError(mondayCode, `watch session tripped the circuit breaker after ${String(result.failed_polls)} failed polls (${String(CIRCUIT_BREAKER_CONSECUTIVE_FAILS)} consecutive)`, {
+                    details: {
+                        failed_polls: result.failed_polls,
+                        circuit_broken_at: result.circuit_broken_at,
+                        events_emitted: result.events_emitted,
+                    },
+                });
+            }
+        });
+    },
+};
+//# sourceMappingURL=watch.js.map

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

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

package/dist/commands/update/upload.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `monday update upload <uid> <file>` — attach a file to an Update
+ * (comment) via Monday's `add_file_to_update` 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 addFileToUpdate} against `mutation AddFileToUpdate` with
+ * `operationName: 'AddFileToUpdate'` (R-NEW-37 W2 audit-point).
+ * Same `MultipartTransport` seam as `item upload`; no column-id
+ * involved (Updates carry attachments via `Update.assets` directly,
+ * not via column values).
+ *
+ * **Argv shape.** Two positional args:
+ *
+ *   - `<uid>` — numeric update ID; brand-validated via
+ *     {@link UpdateIdSchema}.
+ *   - `<file>` — local file path (same constraints as
+ *     `monday item upload`: regular readable file; stdin not
+ *     supported at v0.4-M31).
+ *
+ * **No column-type validation needed.** Updates accept any file
+ * type Monday supports — no column-shape gating like
+ * `item upload`'s `file`-only check. Server-side validation handles
+ * the rest (size cap, filename sanity, virus scan).
+ *
+ * **Local file failures + size handling — same `details.reason`
+ * discrimination as `item upload`.** Three values:
+ *   - `'file_not_readable'` — ENOENT / EACCES / path is a
+ *     directory; fires at IMPL via `fs.stat()` pre-check.
+ *   - `'file_empty'` — zero-byte file; fires via `fs.stat()`.
+ *   - `'file_too_large'` — Monday's server-side size-cap
+ *     rejection 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
+ *     threads the locally-measured size into the details
+ *     slot for a stable agent-keyed envelope).
+ * No CLI-side hardcoded size pre-check; Monday's per-file cap
+ * is plan-tier-dependent and not exposed via the schema.
+ *
+ * **`--dry-run` shape** per §6.4 asset-upload variant — emits
+ * `{operation: 'add_file_to_update', update_id, file_path,
+ * filename, file_size_bytes}` with `meta.source: 'none'`. No wire
+ * call fires.
+ *
+ * **Idempotency: NO** — re-running uploads a second copy. Agents
+ * needing register-once dedupe on `Update.assets` reads.
+ *
+ * **Cache invalidation.** N/A — Updates aren't part of the §8
+ * cache scope (board-metadata-only); the upload changes the
+ * Update's asset collection but nothing the cache tracks.
+ *
+ * **Status: runtime body shipped at v0.4-M31 IMPL** — mirrors
+ * `item upload` minus the column-resolution + cache-invalidation
+ * legs (Updates aren't part of the §8 cache scope; no per-column
+ * type check needed because Updates accept any file type Monday
+ * supports).
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type UpdateUploadOutput } from '../../api/assets.js';
+declare const inputSchema: z.ZodObject<{
+    updateId: z.core.$ZodBranded<z.ZodString, "UpdateId", "out">;
+    file: z.ZodString;
+}, z.core.$strict>;
+export declare const updateUploadCommand: CommandModule<z.infer<typeof inputSchema>, UpdateUploadOutput>;
+export {};
+//# sourceMappingURL=upload.d.ts.map

package/dist/commands/update/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/commands/update/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAM7B,QAAA,MAAM,WAAW;;;kBAcN,CAAC;AAEZ,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAC7C,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,kBAAkB,CAuLnB,CAAC"}

package/dist/commands/update/upload.js

@@ -0,0 +1,235 @@
+/**
+ * `monday update upload <uid> <file>` — attach a file to an Update
+ * (comment) via Monday's `add_file_to_update` 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 addFileToUpdate} against `mutation AddFileToUpdate` with
+ * `operationName: 'AddFileToUpdate'` (R-NEW-37 W2 audit-point).
+ * Same `MultipartTransport` seam as `item upload`; no column-id
+ * involved (Updates carry attachments via `Update.assets` directly,
+ * not via column values).
+ *
+ * **Argv shape.** Two positional args:
+ *
+ *   - `<uid>` — numeric update ID; brand-validated via
+ *     {@link UpdateIdSchema}.
+ *   - `<file>` — local file path (same constraints as
+ *     `monday item upload`: regular readable file; stdin not
+ *     supported at v0.4-M31).
+ *
+ * **No column-type validation needed.** Updates accept any file
+ * type Monday supports — no column-shape gating like
+ * `item upload`'s `file`-only check. Server-side validation handles
+ * the rest (size cap, filename sanity, virus scan).
+ *
+ * **Local file failures + size handling — same `details.reason`
+ * discrimination as `item upload`.** Three values:
+ *   - `'file_not_readable'` — ENOENT / EACCES / path is a
+ *     directory; fires at IMPL via `fs.stat()` pre-check.
+ *   - `'file_empty'` — zero-byte file; fires via `fs.stat()`.
+ *   - `'file_too_large'` — Monday's server-side size-cap
+ *     rejection 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
+ *     threads the locally-measured size into the details
+ *     slot for a stable agent-keyed envelope).
+ * No CLI-side hardcoded size pre-check; Monday's per-file cap
+ * is plan-tier-dependent and not exposed via the schema.
+ *
+ * **`--dry-run` shape** per §6.4 asset-upload variant — emits
+ * `{operation: 'add_file_to_update', update_id, file_path,
+ * filename, file_size_bytes}` with `meta.source: 'none'`. No wire
+ * call fires.
+ *
+ * **Idempotency: NO** — re-running uploads a second copy. Agents
+ * needing register-once dedupe on `Update.assets` reads.
+ *
+ * **Cache invalidation.** N/A — Updates aren't part of the §8
+ * cache scope (board-metadata-only); the upload changes the
+ * Update's asset collection but nothing the cache tracks.
+ *
+ * **Status: runtime body shipped at v0.4-M31 IMPL** — mirrors
+ * `item upload` minus the column-resolution + cache-invalidation
+ * legs (Updates aren't part of the §8 cache scope; no per-column
+ * type check needed because Updates accept any file type Monday
+ * supports).
+ */
+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 { UpdateIdSchema } from '../../types/ids.js';
+import { updateUploadOutputSchema, addFileToUpdate, } from '../../api/assets.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { UsageError, asError, errorCode } from '../../utils/errors.js';
+import { sniffContentType } from '../../utils/mime.js';
+import { emitMutation, emitDryRun } from '../emit.js';
+const inputSchema = z
+    .object({
+    updateId: UpdateIdSchema,
+    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 updateUploadCommand = {
+    name: 'update.upload',
+    summary: 'Attach a file to an Update (comment) via add_file_to_update',
+    examples: [
+        'monday update upload 98765 ./screenshot.png',
+        'monday update upload 98765 ./report.pdf --dry-run',
+    ],
+    idempotent: false,
+    inputSchema,
+    outputSchema: updateUploadOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'update', 'Update (comment) commands (cli-design §4.3 UPDATE)');
+        noun
+            .command('upload <updateId> <file>')
+            .description(updateUploadCommand.summary)
+            .addHelpText('after', [
+            '',
+            'Examples:',
+            ...updateUploadCommand.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_update` is not idempotent.',
+            '',
+        ].join('\n'))
+            .action(async (updateIdArg, fileArg) => {
+            const parsed = parseArgv(updateUploadCommand.inputSchema, {
+                updateId: updateIdArg,
+                file: fileArg,
+            });
+            // Same fs.stat() + fs.access(R_OK) pre-check shape as
+            // `item upload` (round-1 P2-2 fix). Pre-resolveClient so a
+            // missing/unreadable-file error surfaces as usage_error
+            // (exit 1) before any token check.
+            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 mirror — dry-run is fs.stat()-backed; no
+                // wire mutation; no file bytes loaded. `update upload`
+                // dry-run carries `update_id` instead of `item_id` +
+                // `column_id`; otherwise structurally identical to the
+                // `item upload` dry-run shape. `file_path` is the
+                // argv-derived path per cli-design §6.4 sample (round-2
+                // P3-2 fix; mirrors `item upload`).
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: [
+                        {
+                            operation: 'add_file_to_update',
+                            update_id: parsed.updateId,
+                            file_path: parsed.file,
+                            filename,
+                            file_size_bytes: fileSizeBytes,
+                        },
+                    ],
+                    source: 'none',
+                    cacheAgeSeconds: null,
+                    apiVersion,
+                });
+                return;
+            }
+            const bytes = await readFile(filePath);
+            const file = new Blob([bytes], { type: sniffContentType(filename) });
+            const result = await addFileToUpdate({
+                client,
+                multipart,
+                updateId: parsed.updateId,
+                file,
+                filename,
+                signal: ctx.signal,
+                retries: globalFlags.retry,
+            });
+            // No cache invalidation per D6 — Updates aren't part of the
+            // §8 cache scope (which covers board metadata only).
+            const data = {
+                operation: 'add_file_to_update',
+                update_id: parsed.updateId,
+                filename,
+                file_size_bytes: fileSizeBytes,
+                asset: result.asset,
+            };
+            emitMutation({
+                ctx,
+                data,
+                schema: updateUploadCommand.outputSchema,
+                programOpts: program.opts(),
+                ...toEmit({
+                    data: result.asset,
+                    complexity: result.complexity,
+                    stats: { attempts: 1, totalBackoffMs: 0 },
+                }),
+                source: 'live',
+                cacheAgeSeconds: null,
+                complexity: result.complexity,
+            });
+        });
+    },
+};
+//# sourceMappingURL=upload.js.map