monday-cli 0.2.0

package/dist/commands/item/duplicate.js

@@ -0,0 +1,238 @@
+/**
+ * `monday item duplicate <iid> [--with-updates] [--dry-run]` —
+ * duplicate an item (`cli-design.md` §4.3 line 531, `v0.2-plan.md`
+ * §3 M10).
+ *
+ * Third sibling of M10's lifecycle cluster — joins `archive` + `delete`
+ * to round out the four-verb set Monday's API exposes (`archive_item`
+ * / `delete_item` / `duplicate_item`; the fourth, `move_item_to_*`,
+ * lands in M11). Unlike its M10 siblings duplicate is **creative**,
+ * not destructive, so it skips the `--yes` gate (cli-design §3.1 #7
+ * is for destructive ops only — `monday item create` sets the
+ * precedent for creative verbs without confirmation).
+ *
+ * **`board_id` derivation.** Monday's `duplicate_item` mutation requires
+ * `board_id: ID!` (the SDK signature, verified at
+ * `node_modules/@mondaydotcomorg/api/dist/esm/index.d.ts:2130`). Unlike
+ * archive + delete (which only take `item_id`) the live path here is
+ * **two-leg**: a `lookupItemBoard` round-trip first to derive the
+ * source item's `board_id`, then the mutation. Both legs are
+ * guaranteed live — no cache plays a role — so `meta.source: "live"`
+ * directly without invoking `mergeSource` (the aggregator is for
+ * paths that mix cache + live).
+ *
+ * **`--dry-run` shape.** Reads the source item via the same
+ * `ITEM_FIELDS_FRAGMENT` projection archive + delete use, then emits
+ * the §6.4 dry-run envelope with `operation: "duplicate_item"`,
+ * `item_id`, `with_updates`, and `item: <projected source snapshot>`.
+ * The dry-run is **single-leg** (no separate board-id lookup needed —
+ * the source-item read carries everything we'd display, and the
+ * mutation isn't fired). `meta.source: "live"` because the read
+ * leg fired (mirrors archive's dry-run shape).
+ *
+ * **Live path.** Two round-trips: `ItemBoardLookup($ids)` →
+ * `ItemDuplicate($itemId, $boardId, $withUpdates)`. Monday's
+ * `duplicate_item` returns the new `Item` directly with a fresh
+ * `id` (and the same `board_id`, because Monday duplicates onto the
+ * source's board); a null result surfaces as `not_found` matching
+ * the dry-run path's null-handling so agents key off one stable code
+ * regardless of which path they took.
+ *
+ * **Mutation envelope** (cli-design §6.4 line 1827-1831 precedent).
+ * `data` extends `projectedItemSchema` with one field —
+ * `duplicated_from_id: <source-iid>`. The lineage is a meaningful
+ * relationship of the new item, mirroring upsert's `created: true |
+ * false` flag pattern: a per-verb `data` extension for a
+ * business-signal an agent reading the envelope needs to thread into
+ * subsequent operations. v0.2-plan §3 M10's binding requirement
+ * ("Returns the new item's ID + the source item's ID") is satisfied
+ * by `data.id` (new) + `data.duplicated_from_id` (source).
+ *
+ * **Idempotent: false.** Re-running with the same args creates a
+ * second duplicate. Same shape `monday item create`'s idempotency
+ * marker uses (cli-design §9.1 idempotency table — `duplicate_item`
+ * inherits `create_item`'s "every call creates a new item" semantics,
+ * which is why the table doesn't list it separately). Agents
+ * needing idempotent duplicate-or-update use `monday item upsert`
+ * (M12).
+ *
+ * **Not_found semantics.** A missing source item or one the token
+ * can't read surfaces as `not_found` with `details.item_id`. Mirrors
+ * archive + delete + `monday item get` — same code, same details
+ * key, same agent-recovery story.
+ */
+import { z } from 'zod';
+import { ensureSubcommand } from '../types.js';
+import { emitDryRun, emitMutation } from '../emit.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { ItemIdSchema } from '../../types/ids.js';
+import { parseArgv } from '../parse-argv.js';
+import { ITEM_FIELDS_FRAGMENT } from '../../api/item-helpers.js';
+import { projectMutationItem } from '../../api/item-mutation-result.js';
+import { lookupItemBoard } from '../../api/item-board-lookup.js';
+import { readSourceItemForDryRun } from '../../api/item-source-read.js';
+import { projectedItemSchema } from '../../api/item-projection.js';
+// The live mutation returns an `Item` shape — same fragment as
+// `item get`. The dry-run source-item read goes through
+// `readSourceItemForDryRun` (R27) so the query string + null-handling
+// stay one-source-of-truth across the M10 lifecycle verbs (archive
+// + delete + duplicate).
+const DUPLICATE_ITEM_MUTATION = `
+  mutation ItemDuplicate($itemId: ID!, $boardId: ID!, $withUpdates: Boolean) {
+    duplicate_item(item_id: $itemId, board_id: $boardId, with_updates: $withUpdates) {
+      ${ITEM_FIELDS_FRAGMENT}
+    }
+  }
+`;
+/**
+ * The mutation envelope's `data` extends `projectedItemSchema` with
+ * one field — `duplicated_from_id` — pointing at the source item ID
+ * the agent passed positionally. v0.2-plan §3 M10 commits the CLI to
+ * "Returns the new item's ID + the source item's ID"; the new ID is
+ * `data.id` (already in the projection), the source ID lands here.
+ *
+ * Why the extension lives in `data` rather than as a top-level
+ * envelope slot: cli-design §6.4 (line 1827-1831) sets the precedent
+ * with upsert's `data.created: true | false` flag — verb-specific
+ * business signals extend `data`; top-level slots are reserved for
+ * cross-verb shapes (`resolved_ids`, `side_effects`). `duplicated_
+ * from_id` is duplicate-specific lineage, so it belongs with the
+ * resource it describes. JSON-schema (`monday schema`) reflects the
+ * extended shape automatically because the registry walks
+ * `outputSchema`.
+ */
+export const itemDuplicateOutputSchema = projectedItemSchema.extend({
+    duplicated_from_id: ItemIdSchema,
+});
+const inputSchema = z
+    .object({
+    itemId: ItemIdSchema,
+    // Commander emits `{ withUpdates: true }` when the flag is
+    // present, omits the key otherwise (per cli.md "Commander's
+    // runtime option shape"). The schema defaults to `false` so the
+    // GraphQL variable always has a defined boolean — matches Monday's
+    // optional-flag-defaults-false behaviour.
+    withUpdates: z.boolean().optional().default(false),
+})
+    .strict();
+export const itemDuplicateCommand = {
+    name: 'item.duplicate',
+    summary: 'Duplicate an item (optionally including its updates)',
+    examples: [
+        'monday item duplicate 12345',
+        'monday item duplicate 12345 --with-updates',
+        'monday item duplicate 12345 --dry-run',
+        'monday item duplicate 12345 --with-updates --json',
+    ],
+    // Re-running with the same args creates a second duplicate. Mirrors
+    // `monday item create`'s idempotency marker — Monday's
+    // `duplicate_item` shares `create_item`'s "every call creates a
+    // new item" semantics (cli-design §9.1: the idempotency table
+    // doesn't list `duplicate_item` separately because it inherits
+    // create's behaviour). Agents needing idempotent dup-or-update
+    // use `monday item upsert` (M12).
+    idempotent: false,
+    inputSchema,
+    outputSchema: itemDuplicateOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands');
+        noun
+            .command('duplicate <itemId>')
+            .description(itemDuplicateCommand.summary)
+            .option('--with-updates', "include the source item's updates (Monday's `with_updates` flag)")
+            .addHelpText('after', ['', 'Examples:', ...itemDuplicateCommand.examples.map((e) => `  ${e}`), ''].join('\n'))
+            .action(async (itemId, opts) => {
+            const parsed = parseArgv(itemDuplicateCommand.inputSchema, {
+                itemId,
+                ...opts,
+            });
+            // Unlike archive + delete, no confirmation gate fires —
+            // duplicate is creative (cli-design §3.1 #7 reserves the
+            // gate for destructive verbs). resolveClient runs first so
+            // a missing token surfaces as config_error before any wire
+            // attempt, matching `monday item create`'s ordering.
+            const { client, globalFlags, apiVersion, toEmit } = resolveClient(ctx, program.opts());
+            if (globalFlags.dryRun) {
+                // Dry-run path: single round-trip. Read the source item so
+                // the agent can verify the ID before re-running without
+                // `--dry-run`. The dry-run shape carries `with_updates` so
+                // the agent reading the planned change knows whether they
+                // requested update copying. No board lookup needed — we
+                // aren't firing the mutation. Lifted to
+                // `readSourceItemForDryRun` (R27) — same query body archive
+                // + delete share.
+                const projected = await readSourceItemForDryRun({
+                    client,
+                    itemId: parsed.itemId,
+                    operationName: 'ItemDuplicateRead',
+                });
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: [
+                        {
+                            operation: 'duplicate_item',
+                            item_id: parsed.itemId,
+                            with_updates: parsed.withUpdates,
+                            item: projected,
+                        },
+                    ],
+                    // Source-item read fired — `'live'` reflects the wire
+                    // round-trip (same shape archive's + delete's dry-runs use).
+                    source: 'live',
+                    cacheAgeSeconds: null,
+                    warnings: [],
+                    apiVersion,
+                });
+                return;
+            }
+            // Live path: two round-trips. duplicate_item requires a
+            // `board_id: ID!` parameter (SDK signature line 2131), so we
+            // look up the source item's board before firing the mutation.
+            // Both legs are guaranteed live — `lookupItemBoard` doesn't
+            // touch the cache and the mutation always hits the wire — so
+            // `meta.source: "live"` directly without `mergeSource`
+            // (the aggregator is for cache + live combinations).
+            const { boardId } = await lookupItemBoard({
+                client,
+                itemId: parsed.itemId,
+            });
+            const response = await client.raw(DUPLICATE_ITEM_MUTATION, {
+                itemId: parsed.itemId,
+                boardId,
+                withUpdates: parsed.withUpdates,
+            }, { operationName: 'ItemDuplicate' });
+            // Defence-in-depth — `lookupItemBoard` already verified the
+            // source item exists, so a null `duplicate_item` here implies
+            // a permission edge case (token can read but not duplicate)
+            // or a transient Monday-side rejection. `projectMutationItem`
+            // (R28) surfaces it as `not_found` matching the dry-run
+            // path's shape so agents key off one stable code regardless
+            // of which leg failed.
+            const projected = projectMutationItem({
+                raw: response.data.duplicate_item,
+                itemId: parsed.itemId,
+                errorCode: 'not_found',
+                errorMessage: `Monday returned no item from duplicate_item for id ${parsed.itemId}`,
+            });
+            emitMutation({
+                ctx,
+                // Extend the projection with the lineage echo — see the
+                // outputSchema header comment for why this lives in `data`
+                // rather than at envelope top-level (cli-design §6.4 line
+                // 1827-1831 precedent: upsert's `data.created`).
+                data: { ...projected, duplicated_from_id: parsed.itemId },
+                schema: itemDuplicateCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings: [],
+                ...toEmit(response),
+                // Both legs (lookup + mutation) fire live — `'live'` is
+                // the only correct value here. `cacheAgeSeconds` stays null
+                // because no cache leg participated.
+                source: 'live',
+                cacheAgeSeconds: null,
+            });
+        });
+    },
+};
+//# sourceMappingURL=duplicate.js.map

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * `monday item find <name> --board <bid>` — name-based item lookup
+ * (`cli-design.md` §5.7, `v0.1-plan.md` §3 M4).
+ *
+ * Why a client-side walk: Monday's `items_page` filter rules are
+ * column-based, and item name isn't a column. The only way to find
+ * an item by name is to read the board's items and match
+ * client-side. Same trade-off `board find` makes for the same
+ * reason. The walk caps at `--limit-pages × pageSize` to keep the
+ * per-call cost bounded; agents that need to search a giant board
+ * narrow the scope with `--group` first.
+ *
+ * Idempotent: yes.
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type ProjectedItem } from '../../api/item-projection.js';
+export declare const itemFindOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    board_id: z.ZodNullable<z.ZodString>;
+    group_id: z.ZodNullable<z.ZodString>;
+    parent_item_id: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    columns: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        text: z.ZodNullable<z.ZodString>;
+        value: z.ZodUnknown;
+        label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        index: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        time: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        people: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$strict>;
+export type ItemFindOutput = ProjectedItem;
+declare const inputSchema: z.ZodObject<{
+    name: z.ZodString;
+    board: z.core.$ZodBranded<z.ZodString, "BoardId", "out">;
+    group: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "GroupId", "out">>;
+    first: z.ZodOptional<z.ZodBoolean>;
+    pageSize: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limitPages: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export declare const itemFindCommand: CommandModule<z.infer<typeof inputSchema>, ItemFindOutput>;
+export {};
+//# sourceMappingURL=find.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/commands/item/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAQnE,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,8BAA8B,CAAC;AAoEtC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;kBAAsB,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC;AAE3C,QAAA,MAAM,WAAW;;;;;;;kBASN,CAAC;AAkDZ,eAAO,MAAM,eAAe,EAAE,aAAa,CACzC,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,cAAc,CA0If,CAAC"}

package/dist/commands/item/find.js

@@ -0,0 +1,231 @@
+/**
+ * `monday item find <name> --board <bid>` — name-based item lookup
+ * (`cli-design.md` §5.7, `v0.1-plan.md` §3 M4).
+ *
+ * Why a client-side walk: Monday's `items_page` filter rules are
+ * column-based, and item name isn't a column. The only way to find
+ * an item by name is to read the board's items and match
+ * client-side. Same trade-off `board find` makes for the same
+ * reason. The walk caps at `--limit-pages × pageSize` to keep the
+ * per-call cost bounded; agents that need to search a giant board
+ * narrow the scope with `--group` first.
+ *
+ * Idempotent: yes.
+ */
+import { z } from 'zod';
+import { ensureSubcommand } from '../types.js';
+import { emitSuccess } from '../emit.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { findOne } from '../../api/resolvers.js';
+import { BoardIdSchema, GroupIdSchema } from '../../types/ids.js';
+import { parseArgv } from '../parse-argv.js';
+import { ApiError } from '../../utils/errors.js';
+import { paginate } from '../../api/pagination.js';
+import { idFromRawItem, projectItem, projectedItemSchema, } from '../../api/item-projection.js';
+import { ITEM_FIELDS_FRAGMENT, parseRawItem, } from '../../api/item-helpers.js';
+const ITEM_FIND_QUERY = `
+  query ItemFind(
+    $boardId: ID!
+    $limit: Int!
+  ) {
+    boards(ids: [$boardId]) {
+      items_page(limit: $limit) {
+        cursor
+        items {
+          ${ITEM_FIELDS_FRAGMENT}
+        }
+      }
+    }
+  }
+`;
+const ITEM_FIND_BY_GROUP_QUERY = `
+  query ItemFindByGroup(
+    $boardId: ID!
+    $groupId: String!
+    $limit: Int!
+  ) {
+    boards(ids: [$boardId]) {
+      groups(ids: [$groupId]) {
+        items_page(limit: $limit) {
+          cursor
+          items {
+            ${ITEM_FIELDS_FRAGMENT}
+          }
+        }
+      }
+    }
+  }
+`;
+const ITEM_FIND_NEXT_QUERY = `
+  query ItemFindNext($cursor: String!, $limit: Int!) {
+    next_items_page(limit: $limit, cursor: $cursor) {
+      cursor
+      items {
+        ${ITEM_FIELDS_FRAGMENT}
+      }
+    }
+  }
+`;
+export const itemFindOutputSchema = projectedItemSchema;
+const inputSchema = z
+    .object({
+    name: z.string().min(1),
+    board: BoardIdSchema,
+    group: GroupIdSchema.optional(),
+    first: z.boolean().optional(),
+    pageSize: z.coerce.number().int().positive().max(500).optional(),
+    limitPages: z.coerce.number().int().positive().max(500).optional(),
+})
+    .strict();
+const PAGE_SIZE = 100;
+const DEFAULT_PAGES = 5;
+const initialFetcher = (client, boardId, group) => {
+    return (effectiveLimit) => {
+        const variables = { boardId, limit: effectiveLimit };
+        if (group !== undefined) {
+            variables.groupId = group;
+            return client.raw(ITEM_FIND_BY_GROUP_QUERY, variables, {
+                operationName: 'ItemFindByGroup',
+            });
+        }
+        return client.raw(ITEM_FIND_QUERY, variables, {
+            operationName: 'ItemFind',
+        });
+    };
+};
+const nextFetcher = (client) => {
+    return (cursor, effectiveLimit) => client.raw(ITEM_FIND_NEXT_QUERY, { cursor, limit: effectiveLimit }, { operationName: 'ItemFindNext' });
+};
+const extractInitial = (r) => {
+    const board = r.data.boards?.[0];
+    const page = board?.groups?.[0]?.items_page ?? board?.items_page;
+    /* c8 ignore next 2 — defensive nullish-coalescing for missing
+       items_page; same rationale as item/list.ts. */
+    return { cursor: page?.cursor ?? null, items: page?.items ?? [] };
+};
+const extractNext = (r) => {
+    const page = r.data.next_items_page;
+    /* c8 ignore next 2 — defensive nullish-coalescing for missing
+       next_items_page; same rationale as item/list.ts. */
+    return { cursor: page?.cursor ?? null, items: page?.items ?? [] };
+};
+export const itemFindCommand = {
+    name: 'item.find',
+    summary: 'Find a single item on a board by name (uses findOne semantics)',
+    examples: [
+        'monday item find "Refactor login" --board 12345',
+        'monday item find "Many matches" --board 12345 --first',
+        'monday item find "In group" --board 12345 --group topics',
+    ],
+    idempotent: true,
+    inputSchema,
+    outputSchema: itemFindOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands');
+        noun
+            .command('find <name>')
+            .description(itemFindCommand.summary)
+            .requiredOption('--board <bid>', 'board ID (required)')
+            .option('--group <gid>', 'restrict scan to one group')
+            .option('--first', 'on multiple matches, pick the lowest-ID match')
+            .option('--page-size <n>', `page size (default ${String(PAGE_SIZE)})`)
+            .option('--limit-pages <n>', `max pages to scan (default ${String(DEFAULT_PAGES)})`)
+            .addHelpText('after', ['', 'Examples:', ...itemFindCommand.examples.map((e) => `  ${e}`), ''].join('\n'))
+            .action(async (name, opts) => {
+            const parsed = parseArgv(itemFindCommand.inputSchema, {
+                name,
+                ...opts,
+            });
+            const { client, toEmit } = resolveClient(ctx, program.opts());
+            const pageSize = parsed.pageSize ?? PAGE_SIZE;
+            const cap = parsed.limitPages ?? DEFAULT_PAGES;
+            // Walk up to `cap` pages, collecting items for the client-
+            // side findOne match. paginate honours --all + --limit; we
+            // approximate "scan up to cap pages" by passing
+            // limit = cap × pageSize.
+            const result = await paginate({
+                fetchInitial: initialFetcher(client, parsed.board, parsed.group),
+                fetchNext: nextFetcher(client),
+                now: ctx.clock,
+                extractPage: (r) => {
+                    if ('next_items_page' in r.data)
+                        return extractNext(r);
+                    return extractInitial(r);
+                },
+                getId: idFromRawItem,
+                all: true,
+                limit: cap * pageSize,
+                pageSize,
+            });
+            // Project the haystack — findOne reads name + id only, so the
+            // raw shape is enough; full projection happens once a winner
+            // is selected.
+            // R18 parse-boundary wrap: malformed haystack item surfaces
+            // as typed `internal_error` carrying `details.issues` and
+            // the find-scope `query`/`board_id` for triage.
+            const haystack = result.items.map((raw) => parseRawItem(raw, { query: parsed.name, board_id: parsed.board }));
+            let found;
+            try {
+                found = findOne(haystack, parsed.name, (i) => ({ id: i.id, name: i.name }), {
+                    kind: 'item',
+                    ...(parsed.first === undefined ? {} : { first: parsed.first }),
+                });
+            }
+            catch (err) {
+                // Cap-hit before findOne resolved → re-throw with the cap
+                // information so agents can widen --limit-pages or narrow
+                // the query (Codex M4 §6: a partial scan can produce a
+                // false not_found / false uniqueness, must surface).
+                if (err instanceof ApiError && err.code === 'not_found' && result.hasMore) {
+                    throw new ApiError('not_found', `No item matched ${JSON.stringify(parsed.name)} in the scanned ${String(result.totalReturned)} item(s); scan was capped at ${String(cap)} pages — widen --limit-pages or narrow with --group / --where.`, {
+                        details: {
+                            query: parsed.name,
+                            kind: 'item',
+                            scan_truncated: true,
+                            pages_scanned: result.pagesFetched,
+                            cap_pages: cap,
+                            items_scanned: result.totalReturned,
+                        },
+                    });
+                }
+                throw err;
+            }
+            const data = projectItem({ raw: found.resource });
+            const warnings = [];
+            if (result.hasMore) {
+                // Match resolved within the cap, but the scan was
+                // truncated — uniqueness isn't guaranteed. Surface a
+                // warning so agents can widen the cap if they need
+                // certainty.
+                warnings.push({
+                    code: 'pagination_cap_reached',
+                    message: `find scan capped at ${String(cap)} pages; uniqueness not verified — widen --limit-pages to confirm.`,
+                    details: {
+                        pages_scanned: result.pagesFetched,
+                        items_scanned: result.totalReturned,
+                        cap_pages: cap,
+                        hint: 'pass --limit-pages <larger> or narrow the query with --group / --where',
+                    },
+                });
+            }
+            if (found.firstOfMany) {
+                warnings.push({
+                    code: 'first_of_many',
+                    message: `--first picked one of ${String(found.candidates.length)} matches`,
+                    details: {
+                        candidates: found.candidates.map((c) => ({ id: c.id, name: c.name })),
+                    },
+                });
+            }
+            emitSuccess({
+                ctx,
+                data,
+                schema: itemFindCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings,
+                ...toEmit(result.lastResponse),
+            });
+        });
+    },
+};
+//# sourceMappingURL=find.js.map

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

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

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

@@ -0,0 +1,47 @@
+/**
+ * `monday item get <iid>` — single item by ID (`cli-design.md` §6.2).
+ *
+ * GraphQL: `items(ids: [<iid>])` with full column_values inline. The
+ * Monday `items` query is the only way to fetch a single item;
+ * passing exactly one ID returns at most one element. A null result
+ * (item archived to a board the token can't read, or genuinely
+ * non-existent) surfaces as `not_found`.
+ *
+ * Idempotent: yes — pure read.
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type ProjectedItem } from '../../api/item-projection.js';
+export declare const itemGetOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    board_id: z.ZodNullable<z.ZodString>;
+    group_id: z.ZodNullable<z.ZodString>;
+    parent_item_id: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    columns: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        text: z.ZodNullable<z.ZodString>;
+        value: z.ZodUnknown;
+        label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        index: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        time: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        people: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$strict>;
+export type ItemGetOutput = ProjectedItem;
+declare const inputSchema: z.ZodObject<{
+    itemId: z.core.$ZodBranded<z.ZodString, "ItemId", "out">;
+}, z.core.$strict>;
+export declare const itemGetCommand: CommandModule<z.infer<typeof inputSchema>, ItemGetOutput>;
+export {};
+//# sourceMappingURL=get.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../../src/commands/item/get.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AActC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAAsB,CAAC;AACvD,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC;AAE1C,QAAA,MAAM,WAAW;;kBAA8C,CAAC;AAEhE,eAAO,MAAM,cAAc,EAAE,aAAa,CACxC,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,aAAa,CA0Cd,CAAC"}