monday-cli 0.3.0 → 0.5.0

package/dist/utils/parse-brand-list.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Comma-separated branded-ID list argv parser (R-NEW-70 lift,
+ * v0.5-M34 pre-flight kickoff — ahead-of-feat per R-NEW-29 M25
+ * cadence; `v0.5-plan.md` §22 R-NEW-70 entry).
+ *
+ * Three sites in `src/commands/*` consume a `--<flag> <id,...>`
+ * comma-separated list of branded IDs at the argv-parse boundary +
+ * reject malformed entries as `usage_error`:
+ *
+ *   - `monday workspace add-users` / `workspace remove-users` /
+ *     `board add-users` already use the mixed numeric-or-email
+ *     {@link parseUsersArg} helper (different shape — accepts
+ *     emails + numeric IDs; NOT a consumer of this helper).
+ *   - `monday doc list --workspace <wid,...>`
+ *     (`src/commands/doc/list.ts`, M32 pre-flight — 1st pure-brand-list
+ *     consumer; pre-lift `parseWorkspaceListArg` inline copy).
+ *   - `monday user team-create --users <id,...>` / `team-add-members
+ *     <tid> --users <id,...>` / `team-remove-members <tid> --users
+ *     <id,...>` (`src/commands/user/team-*.ts`, M34 pre-flight —
+ *     3rd-5th consumers; would each duplicate the ~35-line inline
+ *     pattern without this lift).
+ *
+ * Each pre-lift site shared the outer-split + trim + empty-entry +
+ * per-entry brand-validation outline; the per-call sites carried
+ * verb-specific error-message strings + detail keys + hint text. M34
+ * pre-flight pushed the count to 4 (1 migrated + 3 new), crossing the
+ * R7/R8 3-consumer threshold; this lift ships AHEAD of the M34
+ * pre-flight feat commit mirroring R-NEW-29's M25 cadence (lift
+ * commit lands first, feat commit consumes the lifted helper, Codex
+ * review then sees the lifted shape).
+ *
+ * **Why this is NOT folded into {@link parseUsersArg}.** The mixed
+ * numeric-or-email shape inflates the helper's signature with an
+ * `email_kind` discriminator + a directory-cache leg's source-
+ * aggregator coupling that's load-bearing in the fan-out path but
+ * irrelevant to a pure brand-list parse. Keeping the two shapes as
+ * sibling helpers keeps the pure-brand-list call sites readable and
+ * the mixed-mode fan-out call sites tightly typed.
+ */
+import type { z } from 'zod';
+export interface ParseBrandedListArgOptions {
+    /**
+     * The argv flag name including the leading dashes (e.g.
+     * `'--workspace'`, `'--users'`). Surfaces verbatim into
+     * `error.message` so the agent sees which flag rejected.
+     */
+    readonly flagName: string;
+    /**
+     * Short noun phrase describing one entry (e.g. `'numeric workspace
+     * ID'`, `'numeric user ID'`). Surfaces into the per-entry
+     * rejection message: `"--<flag> entry "<token>" is not a
+     * <entryDescription>"`.
+     */
+    readonly entryDescription: string;
+    /**
+     * Free-form hint surfaced into `error.details.hint` on per-entry
+     * brand-validation failure (e.g. `'workspace IDs are numeric
+     * (e.g. 12345)'`). Same hint used for both the empty-entry
+     * rejection (where it falls back to a generic "no leading,
+     * trailing, or duplicate commas" message if {@link emptyEntryHint}
+     * is unset) and the per-entry rejection.
+     */
+    readonly hint: string;
+    /**
+     * Optional hint override for the empty-entry rejection path
+     * (trailing comma / leading comma / double comma). Defaults to
+     * `"e.g. ${flagName} <id-or-token>,<id-or-token> — no leading,
+     * trailing, or duplicate commas"` when unset, which matches the
+     * pre-lift `parseWorkspaceListArg` shape verbatim.
+     */
+    readonly emptyEntryHint?: string;
+}
+/**
+ * Splits a comma-separated argv string into an array of brand-
+ * validated typed IDs. Whitespace around commas is trimmed. Empty
+ * entries (trailing comma, leading comma, double comma) reject
+ * with `usage_error.details.hint`; non-conforming entries reject
+ * via the supplied zod brand schema (`details.issues[]` carries
+ * the per-issue path/message + `details.argv_value` echoes the
+ * raw input so agents can correlate retries against the original
+ * argv).
+ *
+ * The brand-validation step uses `safeParse` so the zod error
+ * doesn't bubble through the runner's catch-all as
+ * `internal_error` (per `validation.md`'s "Never bubble raw
+ * ZodError out of a parse boundary" rule). Caller wraps with the
+ * verb's outer `parseArgv` for the rest of the argv surface.
+ *
+ * Empty input strings (`raw === ''`) reject at the per-verb input
+ * schema's `.min(1)` check BEFORE reaching this helper — the
+ * helper assumes a non-empty raw string. The empty-`raw` defensive
+ * branch is c8-ignored as unreachable from production.
+ */
+export declare const parseBrandedListArg: <T>(raw: string, brandSchema: z.ZodType<T>, options: ParseBrandedListArgOptions) => readonly T[];
+//# sourceMappingURL=parse-brand-list.d.ts.map

package/dist/utils/parse-brand-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-brand-list.d.ts","sourceRoot":"","sources":["../../src/utils/parse-brand-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,EACnC,KAAK,MAAM,EACX,aAAa,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACzB,SAAS,0BAA0B,KAClC,SAAS,CAAC,EAwCZ,CAAC"}

package/dist/utils/parse-brand-list.js

@@ -0,0 +1,96 @@
+/**
+ * Comma-separated branded-ID list argv parser (R-NEW-70 lift,
+ * v0.5-M34 pre-flight kickoff — ahead-of-feat per R-NEW-29 M25
+ * cadence; `v0.5-plan.md` §22 R-NEW-70 entry).
+ *
+ * Three sites in `src/commands/*` consume a `--<flag> <id,...>`
+ * comma-separated list of branded IDs at the argv-parse boundary +
+ * reject malformed entries as `usage_error`:
+ *
+ *   - `monday workspace add-users` / `workspace remove-users` /
+ *     `board add-users` already use the mixed numeric-or-email
+ *     {@link parseUsersArg} helper (different shape — accepts
+ *     emails + numeric IDs; NOT a consumer of this helper).
+ *   - `monday doc list --workspace <wid,...>`
+ *     (`src/commands/doc/list.ts`, M32 pre-flight — 1st pure-brand-list
+ *     consumer; pre-lift `parseWorkspaceListArg` inline copy).
+ *   - `monday user team-create --users <id,...>` / `team-add-members
+ *     <tid> --users <id,...>` / `team-remove-members <tid> --users
+ *     <id,...>` (`src/commands/user/team-*.ts`, M34 pre-flight —
+ *     3rd-5th consumers; would each duplicate the ~35-line inline
+ *     pattern without this lift).
+ *
+ * Each pre-lift site shared the outer-split + trim + empty-entry +
+ * per-entry brand-validation outline; the per-call sites carried
+ * verb-specific error-message strings + detail keys + hint text. M34
+ * pre-flight pushed the count to 4 (1 migrated + 3 new), crossing the
+ * R7/R8 3-consumer threshold; this lift ships AHEAD of the M34
+ * pre-flight feat commit mirroring R-NEW-29's M25 cadence (lift
+ * commit lands first, feat commit consumes the lifted helper, Codex
+ * review then sees the lifted shape).
+ *
+ * **Why this is NOT folded into {@link parseUsersArg}.** The mixed
+ * numeric-or-email shape inflates the helper's signature with an
+ * `email_kind` discriminator + a directory-cache leg's source-
+ * aggregator coupling that's load-bearing in the fan-out path but
+ * irrelevant to a pure brand-list parse. Keeping the two shapes as
+ * sibling helpers keeps the pure-brand-list call sites readable and
+ * the mixed-mode fan-out call sites tightly typed.
+ */
+import { UsageError } from './errors.js';
+/**
+ * Splits a comma-separated argv string into an array of brand-
+ * validated typed IDs. Whitespace around commas is trimmed. Empty
+ * entries (trailing comma, leading comma, double comma) reject
+ * with `usage_error.details.hint`; non-conforming entries reject
+ * via the supplied zod brand schema (`details.issues[]` carries
+ * the per-issue path/message + `details.argv_value` echoes the
+ * raw input so agents can correlate retries against the original
+ * argv).
+ *
+ * The brand-validation step uses `safeParse` so the zod error
+ * doesn't bubble through the runner's catch-all as
+ * `internal_error` (per `validation.md`'s "Never bubble raw
+ * ZodError out of a parse boundary" rule). Caller wraps with the
+ * verb's outer `parseArgv` for the rest of the argv surface.
+ *
+ * Empty input strings (`raw === ''`) reject at the per-verb input
+ * schema's `.min(1)` check BEFORE reaching this helper — the
+ * helper assumes a non-empty raw string. The empty-`raw` defensive
+ * branch is c8-ignored as unreachable from production.
+ */
+export const parseBrandedListArg = (raw, brandSchema, options) => {
+    const tokens = raw.split(',').map((t) => t.trim());
+    const ids = [];
+    for (const token of tokens) {
+        if (token === '') {
+            throw new UsageError(`${options.flagName} contains an empty entry (trailing comma ` +
+                `or double comma); pass a comma-separated list of ` +
+                `${options.entryDescription}s.`, {
+                details: {
+                    hint: options.emptyEntryHint ??
+                        `e.g. ${options.flagName} <id>,<id> — no leading, ` +
+                            `trailing, or duplicate commas`,
+                    argv_value: raw,
+                },
+            });
+        }
+        const parsed = brandSchema.safeParse(token);
+        if (!parsed.success) {
+            throw new UsageError(`${options.flagName} entry ${JSON.stringify(token)} is not a ${options.entryDescription}`, {
+                cause: parsed.error,
+                details: {
+                    issues: parsed.error.issues.map((i) => ({
+                        path: i.path.map((p) => String(p)).join('.'),
+                        message: i.message,
+                    })),
+                    argv_value: raw,
+                    hint: options.hint,
+                },
+            });
+        }
+        ids.push(parsed.data);
+    }
+    return ids;
+};
+//# sourceMappingURL=parse-brand-list.js.map

package/dist/utils/parse-brand-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-brand-list.js","sourceRoot":"","sources":["../../src/utils/parse-brand-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAmCzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,GAAW,EACX,WAAyB,EACzB,OAAmC,EACrB,EAAE;IAChB,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,UAAU,CAClB,GAAG,OAAO,CAAC,QAAQ,2CAA2C;gBAC5D,mDAAmD;gBACnD,GAAG,OAAO,CAAC,gBAAgB,IAAI,EACjC;gBACE,OAAO,EAAE;oBACP,IAAI,EACF,OAAO,CAAC,cAAc;wBACtB,QAAQ,OAAO,CAAC,QAAQ,2BAA2B;4BACjD,+BAA+B;oBACnC,UAAU,EAAE,GAAG;iBAChB;aACF,CACF,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,UAAU,CAClB,GAAG,OAAO,CAAC,QAAQ,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,OAAO,CAAC,gBAAgB,EAAE,EACzF;gBACE,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,OAAO,EAAE;oBACP,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBACtC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;wBAC5C,OAAO,EAAE,CAAC,CAAC,OAAO;qBACnB,CAAC,CAAC;oBACH,UAAU,EAAE,GAAG;oBACf,IAAI,EAAE,OAAO,CAAC,IAAI;iBACnB;aACF,CACF,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC"}

package/dist/utils/signal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AbortSignal utilities shared across dispatchers + streaming verbs
+ * (R-NEW-55).
+ *
+ * Three consumers today share the "extract `signal.reason` as an
+ * Error, fall back to a fresh `Error('aborted')`" pattern:
+ *
+ *   1. `src/api/partial-success-mutation.ts:dispatchSequential` —
+ *      iteration-boundary signal check; re-throws the reason
+ *      whole-call.
+ *   2. `src/api/parallel-dispatch.ts:dispatchParallel` — worker-
+ *      loop signal check; re-throws + sets the pool's `aborted`
+ *      flag so other workers stop scheduling new dispatches.
+ *   3. `src/api/item-watch.ts:sleepWithSignal` — both the
+ *      race-window guard (sync `signal.aborted` check before
+ *      listener registration) and the abort-listener path
+ *      reject the sleep promise with the extracted reason.
+ *
+ * `src/api/retry.ts:signalAbortError` is semantically adjacent but
+ * DELIBERATELY divergent: retry.ts assigns `name = 'AbortError'` to
+ * match the Web Platform's DOMException-style surface so callers
+ * can branch on `err.name === 'AbortError'`. Stays inline to
+ * preserve the DOMException naming. {@link extractSignalReason}
+ * below matches the dispatcher / sleep-helper semantics (no
+ * `AbortError` rename); retry.ts carries its own naming-preserving
+ * variant.
+ */
+/**
+ * Reads `signal.reason` and returns it as an `Error` instance the
+ * caller can `throw` directly. When the abort reason is already an
+ * `Error`, return it verbatim — preserves cause chains, error
+ * classes (`UsageError`, `ApiError`, etc.), and any
+ * caller-attached details. When the reason is anything else (a
+ * bare string, `undefined`, a non-Error object), wrap in a fresh
+ * `Error('aborted')` so the caller always has a throwable shape.
+ *
+ * Used by `dispatchSequential` + `dispatchParallel` (iteration /
+ * worker-loop signal check) and `sleepWithSignal` (race-window
+ * abort + listener-fired abort).
+ */
+export declare const extractSignalReason: (signal: AbortSignal) => Error;
+//# sourceMappingURL=signal.d.ts.map

package/dist/utils/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/utils/signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,WAAW,KAAG,KAGzD,CAAC"}

package/dist/utils/signal.js

@@ -0,0 +1,45 @@
+/**
+ * AbortSignal utilities shared across dispatchers + streaming verbs
+ * (R-NEW-55).
+ *
+ * Three consumers today share the "extract `signal.reason` as an
+ * Error, fall back to a fresh `Error('aborted')`" pattern:
+ *
+ *   1. `src/api/partial-success-mutation.ts:dispatchSequential` —
+ *      iteration-boundary signal check; re-throws the reason
+ *      whole-call.
+ *   2. `src/api/parallel-dispatch.ts:dispatchParallel` — worker-
+ *      loop signal check; re-throws + sets the pool's `aborted`
+ *      flag so other workers stop scheduling new dispatches.
+ *   3. `src/api/item-watch.ts:sleepWithSignal` — both the
+ *      race-window guard (sync `signal.aborted` check before
+ *      listener registration) and the abort-listener path
+ *      reject the sleep promise with the extracted reason.
+ *
+ * `src/api/retry.ts:signalAbortError` is semantically adjacent but
+ * DELIBERATELY divergent: retry.ts assigns `name = 'AbortError'` to
+ * match the Web Platform's DOMException-style surface so callers
+ * can branch on `err.name === 'AbortError'`. Stays inline to
+ * preserve the DOMException naming. {@link extractSignalReason}
+ * below matches the dispatcher / sleep-helper semantics (no
+ * `AbortError` rename); retry.ts carries its own naming-preserving
+ * variant.
+ */
+/**
+ * Reads `signal.reason` and returns it as an `Error` instance the
+ * caller can `throw` directly. When the abort reason is already an
+ * `Error`, return it verbatim — preserves cause chains, error
+ * classes (`UsageError`, `ApiError`, etc.), and any
+ * caller-attached details. When the reason is anything else (a
+ * bare string, `undefined`, a non-Error object), wrap in a fresh
+ * `Error('aborted')` so the caller always has a throwable shape.
+ *
+ * Used by `dispatchSequential` + `dispatchParallel` (iteration /
+ * worker-loop signal check) and `sleepWithSignal` (race-window
+ * abort + listener-fired abort).
+ */
+export const extractSignalReason = (signal) => {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error('aborted');
+};
+//# sourceMappingURL=signal.js.map

package/dist/utils/signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/utils/signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAmB,EAAS,EAAE;IAChE,MAAM,MAAM,GAAY,MAAM,CAAC,MAAM,CAAC;IACtC,OAAO,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;AACjE,CAAC,CAAC"}

package/dist/utils/source-content.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Generic file-or-stdin-or-inline-string source-content reader
+ * (R-v0.5-NEW-18 lift, v0.5-M37 IMPL kickoff — ahead-of-feat per
+ * R-NEW-29 M25 + R-NEW-70 M34 cadence; `v0.5-plan.md` §22 R-v0.5-NEW-18
+ * entry).
+ *
+ * Five sites consume the same shape post-lift:
+ *
+ *   - `src/commands/update/create.ts` (M13; `--body <md>` /
+ *     `--body-file <path|->`).
+ *   - `src/commands/update/reply.ts` (M13).
+ *   - `src/commands/update/edit.ts` (M13).
+ *   - `src/commands/doc/import-html.ts` (M37; `--html-string <s>` /
+ *     `--html <file|->`).
+ *   - `src/commands/doc/append-markdown.ts` (M37; `--markdown-string
+ *     <s>` / `--markdown <file|->`).
+ *
+ * All five materialise a content payload from one of three mutually-
+ * exclusive sources:
+ *
+ *   1. `inline` — literal content via an inline-string flag (e.g.
+ *      `--body <md>`, `--html-string <s>`, `--markdown-string <s>`).
+ *   2. `file` — file path via a file-source flag (e.g.
+ *      `--body-file <path>`, `--html <file>`, `--markdown <file>`).
+ *   3. `file === '-'` — stdin (requires the `stdin` slot wired by
+ *      the runner).
+ *
+ * Mutex of (1) vs (2) is typically enforced at the parse boundary via
+ * a cross-field `.refine()` on the argv schema (see R-v0.5-NEW-20);
+ * the helper rejects the both-set case defensively. Inline byte-length
+ * cap is enforced at the parse boundary via `.refine()` (see
+ * R-v0.5-NEW-21); when {@link ReadSourceContentInputs.maxBytes} is
+ * supplied here, the same cap is applied at the runtime read boundary
+ * for the file / stdin path (file content size isn't known at argv-
+ * parse time).
+ *
+ * Throws `UsageError` for:
+ *   - Both `inline` and `file` set (pre-parse-boundary drift).
+ *   - Neither set (no source).
+ *   - `file === '-'` with no `stdin` (programmer wiring bug).
+ *   - Empty (or whitespace-only) result after read.
+ *   - File-read failure (ENOENT / EACCES / etc.) wrapped with the
+ *     underlying error message.
+ *   - Oversized payload (when `maxBytes` is set) with
+ *     `details.size_bytes` + `details.limit_bytes` + `details.source`
+ *     ('inline' / 'file' / 'stdin') for agent introspection.
+ */
+export interface ReadSourceContentInputs {
+    /** Inline-string flag value (e.g. `--body <md>` / `--html-string`). */
+    readonly inline: string | undefined;
+    /** File-source flag value (e.g. `--body-file <path>` / `--html <file>`). */
+    readonly file: string | undefined;
+    /** stdin slot wired by the runner — required for `<file-flag> -`. */
+    readonly stdin: NodeJS.ReadableStream | undefined;
+    /**
+     * Inline-flag display name for error messages (e.g. `'--body'`,
+     * `'--html-string'`). Surfaces verbatim into `error.message`.
+     */
+    readonly inlineFlagName: string;
+    /**
+     * File-source flag display name for error messages (e.g.
+     * `'--body-file'`, `'--html'`).
+     */
+    readonly fileFlagName: string;
+    /**
+     * Verb-specific "neither set" error message. Omit for a generic
+     * `${inlineFlagName} or ${fileFlagName}` phrasing. Callers usually
+     * supply a verb-named hint (e.g. "monday update create requires
+     * either --body <md> or --body-file <path>. Use --body-file - to
+     * read from stdin.").
+     */
+    readonly verbHint?: string;
+    /**
+     * Optional UTF-8 byte-length cap applied to the resolved content.
+     * When set, the helper rejects oversized payloads as `usage_error`
+     * with structured `details.size_bytes` / `details.limit_bytes` /
+     * `details.source`. M37 supplies `MAX_DOC_IMPORT_PAYLOAD_BYTES`
+     * (`256_000`) per D13 closure; M13 supplies nothing (no wire-side
+     * cap on `update` body payloads).
+     */
+    readonly maxBytes?: number;
+    /**
+     * Trim trailing whitespace from file / stdin content. Default
+     * `true` (matches M13 behaviour — a trailing newline from `cat
+     * foo.md` doesn't surface as a literal `\n` in the posted
+     * comment / doc payload). Inline content is always returned
+     * verbatim (post empty-trim rejection); the parameter only
+     * affects file / stdin paths.
+     */
+    readonly trimTrailingWhitespace?: boolean;
+}
+export declare const readSourceContent: (inputs: ReadSourceContentInputs) => Promise<string>;
+//# sourceMappingURL=source-content.d.ts.map

package/dist/utils/source-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-content.d.ts","sourceRoot":"","sources":["../../src/utils/source-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,SAAS,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AA8BD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,uBAAuB,KAC9B,OAAO,CAAC,MAAM,CA+EhB,CAAC"}

package/dist/utils/source-content.js

@@ -0,0 +1,120 @@
+/**
+ * Generic file-or-stdin-or-inline-string source-content reader
+ * (R-v0.5-NEW-18 lift, v0.5-M37 IMPL kickoff — ahead-of-feat per
+ * R-NEW-29 M25 + R-NEW-70 M34 cadence; `v0.5-plan.md` §22 R-v0.5-NEW-18
+ * entry).
+ *
+ * Five sites consume the same shape post-lift:
+ *
+ *   - `src/commands/update/create.ts` (M13; `--body <md>` /
+ *     `--body-file <path|->`).
+ *   - `src/commands/update/reply.ts` (M13).
+ *   - `src/commands/update/edit.ts` (M13).
+ *   - `src/commands/doc/import-html.ts` (M37; `--html-string <s>` /
+ *     `--html <file|->`).
+ *   - `src/commands/doc/append-markdown.ts` (M37; `--markdown-string
+ *     <s>` / `--markdown <file|->`).
+ *
+ * All five materialise a content payload from one of three mutually-
+ * exclusive sources:
+ *
+ *   1. `inline` — literal content via an inline-string flag (e.g.
+ *      `--body <md>`, `--html-string <s>`, `--markdown-string <s>`).
+ *   2. `file` — file path via a file-source flag (e.g.
+ *      `--body-file <path>`, `--html <file>`, `--markdown <file>`).
+ *   3. `file === '-'` — stdin (requires the `stdin` slot wired by
+ *      the runner).
+ *
+ * Mutex of (1) vs (2) is typically enforced at the parse boundary via
+ * a cross-field `.refine()` on the argv schema (see R-v0.5-NEW-20);
+ * the helper rejects the both-set case defensively. Inline byte-length
+ * cap is enforced at the parse boundary via `.refine()` (see
+ * R-v0.5-NEW-21); when {@link ReadSourceContentInputs.maxBytes} is
+ * supplied here, the same cap is applied at the runtime read boundary
+ * for the file / stdin path (file content size isn't known at argv-
+ * parse time).
+ *
+ * Throws `UsageError` for:
+ *   - Both `inline` and `file` set (pre-parse-boundary drift).
+ *   - Neither set (no source).
+ *   - `file === '-'` with no `stdin` (programmer wiring bug).
+ *   - Empty (or whitespace-only) result after read.
+ *   - File-read failure (ENOENT / EACCES / etc.) wrapped with the
+ *     underlying error message.
+ *   - Oversized payload (when `maxBytes` is set) with
+ *     `details.size_bytes` + `details.limit_bytes` + `details.source`
+ *     ('inline' / 'file' / 'stdin') for agent introspection.
+ */
+import { readFile } from 'node:fs/promises';
+import { UsageError, errorMessage } from './errors.js';
+const enforceMaxBytes = (content, source, maxBytes, inputs) => {
+    const size = Buffer.byteLength(content, 'utf8');
+    if (size <= maxBytes)
+        return;
+    const flagName = source === 'inline' ? inputs.inlineFlagName : inputs.fileFlagName;
+    const details = {
+        source,
+        size_bytes: size,
+        limit_bytes: maxBytes,
+    };
+    if (source === 'file' && inputs.file !== undefined) {
+        details.file_path = inputs.file;
+    }
+    throw new UsageError(`${flagName}: payload (${String(size)} bytes) exceeds the ${String(maxBytes)}-byte wire-side limit. Pass a smaller payload, or split the call.`, { details });
+};
+export const readSourceContent = async (inputs) => {
+    const { inline, file, stdin, inlineFlagName, fileFlagName, maxBytes, } = inputs;
+    const trimTrailing = inputs.trimTrailingWhitespace ?? true;
+    if (inline !== undefined && file !== undefined) {
+        throw new UsageError(`${inlineFlagName} and ${fileFlagName} are mutually exclusive; pick one.`, { details: { [`has_inline_value`]: true, file_path: file } });
+    }
+    if (inline !== undefined) {
+        if (inline.trim().length === 0) {
+            throw new UsageError(`${inlineFlagName} cannot be empty (or whitespace-only). Pass content or use ${fileFlagName} <path> to read from disk / stdin.`);
+        }
+        if (maxBytes !== undefined) {
+            enforceMaxBytes(inline, 'inline', maxBytes, inputs);
+        }
+        return inline;
+    }
+    if (file === undefined) {
+        const verbHint = inputs.verbHint ??
+            `requires either ${inlineFlagName} <s> or ${fileFlagName} <file>. Use ${fileFlagName} - to read from stdin.`;
+        throw new UsageError(verbHint);
+    }
+    if (file === '-') {
+        if (stdin === undefined) {
+            throw new UsageError(`${fileFlagName} - requested stdin, but no stdin is wired into the runner. This is a programmer wiring bug.`);
+        }
+        const chunks = [];
+        for await (const chunk of stdin) {
+            chunks.push(Buffer.from(chunk));
+        }
+        const raw = Buffer.concat(chunks).toString('utf8');
+        const body = trimTrailing ? raw.trimEnd() : raw;
+        if (body.length === 0) {
+            throw new UsageError(`stdin produced an empty payload. Pipe non-empty content into ${fileFlagName} - or pass ${inlineFlagName} <s> inline.`, { details: { source: 'stdin' } });
+        }
+        if (maxBytes !== undefined) {
+            enforceMaxBytes(body, 'stdin', maxBytes, inputs);
+        }
+        return body;
+    }
+    // File on disk. UTF-8 always; binary content would corrupt the
+    // markdown / HTML payload anyway.
+    const raw = await readFile(file, 'utf8').catch((err) => {
+        throw new UsageError(`${fileFlagName}: failed to read ${JSON.stringify(file)} (${errorMessage(err)}).`, {
+            cause: err,
+            details: { file_path: file },
+        });
+    });
+    const body = trimTrailing ? raw.trimEnd() : raw;
+    if (body.length === 0) {
+        throw new UsageError(`${fileFlagName}: ${JSON.stringify(file)} is empty (after trim). Pass non-empty content.`, { details: { file_path: file } });
+    }
+    if (maxBytes !== undefined) {
+        enforceMaxBytes(body, 'file', maxBytes, inputs);
+    }
+    return body;
+};
+//# sourceMappingURL=source-content.js.map

package/dist/utils/source-content.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monday-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Agent-first CLI for Monday.com — read boards, file backlog items, transition statuses, and post comments from the terminal. Built for AI coding agents (Claude Code, Codex) with humans as a welcome second audience.",
   "type": "module",
   "engines": {