monday-cli 0.2.0

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

@@ -0,0 +1,81 @@
+/**
+ * `monday item archive <iid> --yes [--dry-run]` — archive an item
+ * (`cli-design.md` §4.3 line 532, `v0.2-plan.md` §3 M10).
+ *
+ * The smaller of the two M10 destructive verbs. `archive_item` hides
+ * the item from default queries; Monday retains it for a 30-day
+ * recovery window but exposes no `unarchive` mutation — see
+ * cli-design §5.4 for why "restore" is intentionally absent in v0.1.
+ *
+ * **Confirmation gate** (cli-design §3.1 #7). `--yes` is mandatory
+ * for the live path; without `--yes` (and without `--dry-run`) the
+ * command fails fast with `confirmation_required` carrying
+ * `details.item_id` so an agent re-running with `--yes` knows which
+ * item it just gated. `--dry-run` takes precedence over the gate
+ * when both are absent — agents can preview without committing,
+ * which mirrors §10.2's "dry-run takes precedence over --yes" rule.
+ *
+ * **`--dry-run` shape.** Reads the source item via the same
+ * `ITEM_FIELDS_FRAGMENT` projection the live mutation uses, then
+ * emits the §6.4 dry-run envelope with `operation: "archive_item"`,
+ * `item_id`, and `item: <projected snapshot>` so the agent can
+ * verify they targeted the right ID before re-running with `--yes`.
+ * `meta.source: "live"` because the source-item read fired (mirrors
+ * `monday item get`).
+ *
+ * **Live path.** Single round-trip — Monday's `archive_item`
+ * mutation returns the archived item directly, so no separate
+ * pre-mutation read is needed. The mutation response is projected
+ * through `projectItem` against the v0.1 `projectedItemSchema`
+ * (same shape as `item set` / `item clear` / `item update` so an
+ * agent's "archive then re-read locally" loop has a stable shape).
+ * `meta.source: "live"` always; cache plays no role here because
+ * archive doesn't resolve columns.
+ *
+ * **Idempotent: true.** Re-archiving an already-archived item is a
+ * no-op on Monday's side (cli-design §9.1 idempotency table) — the
+ * mutation succeeds and returns the item unchanged. Agents can
+ * safely retry on transient transport failures.
+ *
+ * **Not_found semantics.** A missing item or one the token can't
+ * read surfaces as `not_found` with `details.item_id`. Mirrors
+ * `runByIdLookup`'s pattern so the error shape is identical to a
+ * read-side `monday item get` against the same ID — agents key off
+ * the stable code per cli-design §6.5.
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+import { type ProjectedItem } from '../../api/item-projection.js';
+export declare const itemArchiveOutputSchema: 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 ItemArchiveOutput = ProjectedItem;
+declare const inputSchema: z.ZodObject<{
+    itemId: z.core.$ZodBranded<z.ZodString, "ItemId", "out">;
+}, z.core.$strict>;
+export declare const itemArchiveCommand: CommandModule<z.infer<typeof inputSchema>, ItemArchiveOutput>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/item/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAUnE,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAkBtC,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;kBAAsB,CAAC;AAC3D,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAE9C,QAAA,MAAM,WAAW;;kBAA8C,CAAC;AAEhE,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAC5C,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAC3B,iBAAiB,CAqIlB,CAAC"}

package/dist/commands/item/archive.js

@@ -0,0 +1,187 @@
+/**
+ * `monday item archive <iid> --yes [--dry-run]` — archive an item
+ * (`cli-design.md` §4.3 line 532, `v0.2-plan.md` §3 M10).
+ *
+ * The smaller of the two M10 destructive verbs. `archive_item` hides
+ * the item from default queries; Monday retains it for a 30-day
+ * recovery window but exposes no `unarchive` mutation — see
+ * cli-design §5.4 for why "restore" is intentionally absent in v0.1.
+ *
+ * **Confirmation gate** (cli-design §3.1 #7). `--yes` is mandatory
+ * for the live path; without `--yes` (and without `--dry-run`) the
+ * command fails fast with `confirmation_required` carrying
+ * `details.item_id` so an agent re-running with `--yes` knows which
+ * item it just gated. `--dry-run` takes precedence over the gate
+ * when both are absent — agents can preview without committing,
+ * which mirrors §10.2's "dry-run takes precedence over --yes" rule.
+ *
+ * **`--dry-run` shape.** Reads the source item via the same
+ * `ITEM_FIELDS_FRAGMENT` projection the live mutation uses, then
+ * emits the §6.4 dry-run envelope with `operation: "archive_item"`,
+ * `item_id`, and `item: <projected snapshot>` so the agent can
+ * verify they targeted the right ID before re-running with `--yes`.
+ * `meta.source: "live"` because the source-item read fired (mirrors
+ * `monday item get`).
+ *
+ * **Live path.** Single round-trip — Monday's `archive_item`
+ * mutation returns the archived item directly, so no separate
+ * pre-mutation read is needed. The mutation response is projected
+ * through `projectItem` against the v0.1 `projectedItemSchema`
+ * (same shape as `item set` / `item clear` / `item update` so an
+ * agent's "archive then re-read locally" loop has a stable shape).
+ * `meta.source: "live"` always; cache plays no role here because
+ * archive doesn't resolve columns.
+ *
+ * **Idempotent: true.** Re-archiving an already-archived item is a
+ * no-op on Monday's side (cli-design §9.1 idempotency table) — the
+ * mutation succeeds and returns the item unchanged. Agents can
+ * safely retry on transient transport failures.
+ *
+ * **Not_found semantics.** A missing item or one the token can't
+ * read surfaces as `not_found` with `details.item_id`. Mirrors
+ * `runByIdLookup`'s pattern so the error shape is identical to a
+ * read-side `monday item get` against the same ID — agents key off
+ * the stable code per cli-design §6.5.
+ */
+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 { parseGlobalFlags } from '../../types/global-flags.js';
+import { enforceDestructiveGate } from '../../api/destructive-gate.js';
+import { ITEM_FIELDS_FRAGMENT } from '../../api/item-helpers.js';
+import { projectMutationItem } from '../../api/item-mutation-result.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.
+const ARCHIVE_ITEM_MUTATION = `
+  mutation ItemArchive($itemId: ID!) {
+    archive_item(item_id: $itemId) {
+      ${ITEM_FIELDS_FRAGMENT}
+    }
+  }
+`;
+export const itemArchiveOutputSchema = projectedItemSchema;
+const inputSchema = z.object({ itemId: ItemIdSchema }).strict();
+export const itemArchiveCommand = {
+    name: 'item.archive',
+    summary: 'Archive an item (--yes required)',
+    examples: [
+        'monday item archive 12345 --yes',
+        'monday item archive 12345 --dry-run',
+        'monday item archive 12345 --yes --json',
+    ],
+    // Re-archiving an already-archived item is a no-op on Monday's side
+    // per cli-design §9.1; safe to retry on transient transport failures.
+    idempotent: true,
+    inputSchema,
+    outputSchema: itemArchiveOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands');
+        noun
+            .command('archive <itemId>')
+            .description(itemArchiveCommand.summary)
+            // `--yes` and `--dry-run` are global flags (`src/cli/program.ts`)
+            // — read via `globalFlags` rather than redeclaring per-command
+            // so the gate stays single-source-of-truth across every
+            // destructive verb.
+            .addHelpText('after', ['', 'Examples:', ...itemArchiveCommand.examples.map((e) => `  ${e}`), ''].join('\n'))
+            .action(async (itemId) => {
+            const parsed = parseArgv(itemArchiveCommand.inputSchema, { itemId });
+            // Confirmation gate fires BEFORE `resolveClient()` so a
+            // missing `--yes` always surfaces as `confirmation_required`
+            // — never masked by `config_error` from `loadConfig()`'s
+            // missing-token check. Codex M10 round-1 P2: cli-design
+            // §3.1 #7 makes the gate unconditional, but pre-fix the
+            // ordering let `monday item archive 12345 --json` (no `--yes`,
+            // no token) exit 3 with `config_error` instead of exit 1
+            // with `confirmation_required`. `raw` already had this
+            // pre-network ordering precedent (commands/raw/index.ts:435).
+            // As a side-benefit, the gate-error envelope's `meta.source`
+            // stays at the runner's `'none'` default rather than the
+            // `live` `resolveClient` would have committed via
+            // `ctx.meta.setSource('live')` — agents reading provenance
+            // see `'none'` because no wire call fired (cli-design §6.1).
+            const globalFlags = parseGlobalFlags(program.opts(), ctx.env);
+            // R29 lift (v0.2-plan §20): the parsed flags + the gate
+            // helper preserve the M10 round-1 P2 ordering — gate fires
+            // before any `resolveClient()` call so a missing token
+            // doesn't mask `confirmation_required` as `config_error`.
+            enforceDestructiveGate({
+                globalFlags,
+                verb: 'item archive',
+                target: parsed.itemId,
+                detailKey: 'item_id',
+                action: 'archive the item',
+                hint: 'archive is destructive — Monday retains archived ' +
+                    'items for 30 days but exposes no unarchive mutation ' +
+                    '(cli-design §5.4).',
+            });
+            // Gate cleared — now resolve the client. Both the dry-run
+            // read and the live mutation need a `MondayClient`, so a
+            // missing token here legitimately surfaces as `config_error`
+            // (the user opted into the wire path via `--yes` or `--dry-run`).
+            const { client, apiVersion, toEmit } = resolveClient(ctx, program.opts());
+            if (globalFlags.dryRun) {
+                // Dry-run path: read the source item so the agent can
+                // verify the ID before re-running with --yes. Lifted to
+                // `readSourceItemForDryRun` (R27) — same query body all
+                // three M10 lifecycle verbs share; null result → `not_found`
+                // (mirrors the live path's null-handling so the error shape
+                // matches).
+                const projected = await readSourceItemForDryRun({
+                    client,
+                    itemId: parsed.itemId,
+                    operationName: 'ItemArchiveRead',
+                });
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: [
+                        {
+                            operation: 'archive_item',
+                            item_id: parsed.itemId,
+                            item: projected,
+                        },
+                    ],
+                    // Source-item read fired — `'live'` reflects the wire
+                    // round-trip. Mirrors `item get`'s success envelope.
+                    source: 'live',
+                    cacheAgeSeconds: null,
+                    warnings: [],
+                    apiVersion,
+                });
+                return;
+            }
+            // Live path. The `archive_item` mutation returns the archived
+            // item directly — no pre-mutation read needed; null result
+            // means the item didn't exist or the token has no access,
+            // which surfaces as `not_found` (matches the dry-run path's
+            // shape so agents key off the same code regardless of which
+            // path they took).
+            const response = await client.raw(ARCHIVE_ITEM_MUTATION, { itemId: parsed.itemId }, { operationName: 'ItemArchive' });
+            const projected = projectMutationItem({
+                raw: response.data.archive_item,
+                itemId: parsed.itemId,
+                errorCode: 'not_found',
+                errorMessage: `Monday returned no item from archive_item for id ${parsed.itemId}`,
+            });
+            emitMutation({
+                ctx,
+                data: projected,
+                schema: itemArchiveCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings: [],
+                ...toEmit(response),
+                source: 'live',
+                cacheAgeSeconds: null,
+            });
+        });
+    },
+};
+//# sourceMappingURL=archive.js.map

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

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

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

@@ -0,0 +1,140 @@
+/**
+ * `monday item clear` — column-clear with single-item + bulk shapes.
+ * (cli-design.md §4.3 line 489 + §10.2; v0.1-plan.md §3 M5b for the
+ * single-item path, v0.2-plan.md §3 M12 for bulk `--where`).
+ *
+ * The dedicated "clear" verb. Per cli-design §5.3 step 3 + the
+ * dropdown empty-input rejection in `column-values.ts`, `--set X=`
+ * does NOT mean "clear" — it means "set to the empty-string value"
+ * which is type-dependent (e.g. `{label: ""}` for status). The
+ * dedicated verb is the documented escape and produces the per-type
+ * "clear" wire payload:
+ *
+ *   - `text` / `long_text` / `numbers` → simple bare empty string
+ *     (`change_simple_column_value(value: "")`).
+ *   - `status` / `dropdown` / `date` / `people` → empty JSON object
+ *     `{}` via `change_column_value(value: JSON!)`. Monday's
+ *     "clear all column values" pattern.
+ *
+ * Two argv shapes:
+ *
+ *   1. **Single-item** (M5b): `monday item clear <iid> <col>
+ *      [--board <bid>]`. Positional `<iid>` plus required `<col>`.
+ *      `--board` skips the implicit item-board lookup.
+ *
+ *   2. **Bulk** (M12): `monday item clear --board <bid> <col>
+ *      (--where <c>=<v>... | --filter-json <json>) [--yes]
+ *      [--dry-run]`. No positional `<iid>` — page-walks `items_page`
+ *      with the supplied filter and clears the named column on every
+ *      matched item. Mirrors `item update --where`'s shape: bulk
+ *      mutations without `--yes` (and without `--dry-run`) surface
+ *      `confirmation_required` per cli-design §10.2.
+ *
+ * **Two paths.** `--dry-run` orchestrates `api/dry-run.ts planClear`
+ * (single-token shape — symmetric with planChanges' multi-token shape
+ * but one token in / one PlannedChange out). Live writes resolve the
+ * column + build the clear payload + select the mutation + fire.
+ *
+ * **Resolver-warning preservation + cache-stale archived remap.**
+ * Identical pattern to `item set` (R19 lift) — translator failures
+ * and live `validation_failed` after cache-sourced resolution flow
+ * through `foldResolverWarningsIntoError` +
+ * `maybeRemapValidationFailedToArchived`. clear has no value-side
+ * translator (the payload is `""` / `{}` per type, no user-supplied
+ * value to interpret), so the only typed failure path on the live
+ * side is Monday's mutation-time rejection — which still benefits
+ * from the F4 cache-archived remap.
+ *
+ * Idempotent: yes — clearing an already-empty cell is a no-op write.
+ */
+import { z } from 'zod';
+import { type CommandModule } from '../types.js';
+/**
+ * `item clear`'s `data` is a discriminated union — single-item path
+ * emits the §6.2 projected item; bulk path emits `{summary, items}`.
+ * `monday schema item.clear` reads this schema, so agents can plan
+ * against either shape without surprises (Codex round-1 F4 — pre-fix
+ * the schema only described the single-item shape, leaving the bulk
+ * surface invisible to schema-driven agents).
+ */
+export declare const itemClearOutputSchema: z.ZodUnion<readonly [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>, z.ZodObject<{
+    summary: z.ZodObject<{
+        matched_count: z.ZodNumber;
+        applied_count: z.ZodNumber;
+        board_id: z.ZodString;
+    }, z.core.$strip>;
+    items: z.ZodArray<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>>;
+}, z.core.$strip>]>;
+export type ItemClearOutput = z.infer<typeof itemClearOutputSchema>;
+/**
+ * Input shape — supports both single-item and bulk shapes.
+ *
+ *   - Single-item: `itemId` positional required; `where` empty.
+ *   - Bulk:        `itemId` positional omitted; `where` non-empty
+ *                  AND `board` required.
+ *
+ * Schema accepts both shapes; the dispatch lives in
+ * `validateInputShape` below so the action layer reads the
+ * discriminator and dispatches.
+ */
+declare const inputSchema: z.ZodObject<{
+    itemId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "ItemId", "out">>;
+    column: z.ZodString;
+    board: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "BoardId", "out">>;
+    where: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    filterJson: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ParsedInput = z.infer<typeof inputSchema>;
+export declare const itemClearCommand: CommandModule<ParsedInput, ItemClearOutput>;
+export {};
+//# sourceMappingURL=clear.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/item/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AA2HnE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAGhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,QAAA,MAAM,WAAW;;;;;;kBAoBN,CAAC;AAEZ,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAuD/C,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,WAAW,EAAE,eAAe,CA0KxE,CAAC"}