monday-cli 0.2.0 → 0.4.0

package/dist/api/notifications.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Notification send surface for the v0.3-M27 `monday notification
+ * send` verb (`cli-design.md` §2.7 + §4.3 + §13 v0.3 entry;
+ * `v0.3-plan.md` §3 M27).
+ *
+ * **Wire surface (empirical probe 2026-05-12, API `2026-01`).** One
+ * Monday GraphQL operation lands here:
+ *
+ *   - `Mutation.create_notification(user_id: ID!, target_id: ID!,
+ *     target_type: NotificationTargetType!, text: String!)` — returns
+ *     the created `Notification { id, text }`.
+ *
+ * **`NotificationTargetType` is a 2-value wire enum: `Post` / `Project`.**
+ * Monday's `Post` value targets an Update (sending a notification
+ * about a specific post); `Project` targets an Item OR a Board (the
+ * wire enum doesn't distinguish). The CLI surface keeps the
+ * documented `--target-type item|board` argv vocabulary from
+ * cli-design §4.3 — both CLI values map to wire `Project`. The CLI
+ * preserves the item-vs-board distinction at the parse boundary
+ * for argv-validation discipline and to echo the agent-supplied
+ * kind in the output envelope; the CLI does NOT pre-verify that
+ * the supplied `--target <id>` actually names the declared kind,
+ * and Monday cannot either (the wire enum collapses both kinds to
+ * `Project`). Invisible / non-existent targets surface `not_found`
+ * at mutation time, but a passing `--target-type item` with a
+ * board-shaped ID succeeds and echoes the CLI-declared kind even
+ * though the record is a board. Monday's `Post` variant is
+ * unreachable at v0.3 — a v0.3.x / v0.4 contract-extension may add
+ * `--target-type update` once a clean argv-discriminator design is
+ * pinned (cli-design §13 v0.3 entry M27 sub-block carries the
+ * deferred note).
+ *
+ * **`Notification` read shape is minimal (2 fields).** `id` (ID,
+ * non-null), `text` (String, nullable). The CLI echoes the input
+ * fields (`user_id`, `target_id`, `target_type`) alongside the
+ * Monday-side fields so an agent verifies what was sent from a
+ * single envelope read.
+ *
+ * **No new ERROR_CODES (29 stays).** Notification send failures
+ * route through the existing codes: `not_found` (target user /
+ * `Project` invisible to the token or non-existent — Monday's
+ * visibility check; CLI-declared kind vs underlying record is NOT
+ * verified), `usage_error` (text empty / malformed argv — invalid
+ * `--target-type` enum value or non-numeric `--target` ID),
+ * `unauthorized` (token lacks notification scope), `forbidden`
+ * (account permissions), `validation_failed` (Monday-side rejection).
+ *
+ * **Notification send is single-recipient at v0.3** per cli-design
+ * §4.3 — the `--user <uid>` flag accepts one ID. Multi-recipient
+ * fan-out is a v0.3.x / v0.4 contract-extension (agents needing
+ * fan-out call `notification send` N times).
+ *
+ * **Notification send is not idempotent.** Re-running the verb
+ * produces a fresh notification with a new `id` (Monday treats
+ * each `create_notification` call as a discrete send). Agents
+ * needing send-once-semantics dedup on the CLI side; the verb
+ * does not enforce idempotency.
+ *
+ * **Runtime body (M27 IMPL).** Single `client.raw` round-trip
+ * against `mutation CreateNotification` with `operationName:
+ * 'CreateNotification'` (R-NEW-37 W2 audit-point). The CLI's
+ * 2-value `--target-type` enum collapses to wire `Project` at the
+ * runtime boundary; the CLI-side echo (`user_id` / `target_id` /
+ * `target_type`) is composed at the parse boundary so the envelope
+ * carries both the Monday-minted `id` + the agent-supplied inputs.
+ */
+import { z } from 'zod';
+import type { MondayClient } from './client.js';
+import type { Complexity } from '../utils/output/envelope.js';
+/**
+ * CLI-side `target_type` vocabulary for `monday notification send
+ * --target-type <type>`. Both values map to Monday's wire
+ * `NotificationTargetType.Project` (which represents both items and
+ * boards) — the CLI keeps the item-vs-board distinction for argv
+ * validation discipline AND to echo the agent-supplied kind in the
+ * output envelope. The pairing of `--target-type` with `--target
+ * <id>` is **trusted, not verified**: the CLI validates the enum +
+ * numeric ID shape; Monday validates that the target is a visible
+ * `Project` (surfacing invisible / non-existent targets as
+ * `not_found`); but neither side verifies that the CLI-declared
+ * kind matches what the ID actually names — the wire enum
+ * collapses both kinds to `Project`. A CLI-side pre-read is
+ * deferred (v0.3.x / v0.4 contract-extension if agents need
+ * strict-kind enforcement).
+ *
+ * Monday's wire enum has only two values (`Post` / `Project`); the
+ * `Post` value targets Updates and is intentionally not surfaced
+ * at v0.3 per cli-design §4.3. A v0.3.x / v0.4 contract-extension
+ * may add a CLI third target-type `update` that dispatches to wire
+ * `Post`.
+ */
+export declare const NOTIFICATION_TARGET_TYPES: readonly ["item", "board"];
+export type NotificationTargetType = (typeof NOTIFICATION_TARGET_TYPES)[number];
+export declare const notificationTargetTypeSchema: z.ZodEnum<{
+    board: "board";
+    item: "item";
+}>;
+/**
+ * Output shape for `monday notification send --user <uid> --target
+ * <iid|bid> --target-type item|board --text <t>`. Carries both the
+ * Monday-side fields (`id` of the minted notification, server-echo
+ * `text`) and the CLI-side inputs (`user_id`, `target_id`,
+ * `target_type`) so an agent verifies what was sent from a single
+ * envelope read.
+ *
+ * `text` is nullable on the wire (Monday's `Notification.text` is
+ * `String` not `String!`); we preserve nullability for fidelity even
+ * though `create_notification`'s input `text` is non-null. In
+ * practice it round-trips the input value.
+ */
+export declare const notificationSendOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodNullable<z.ZodString>;
+    user_id: z.ZodString;
+    target_id: z.ZodString;
+    target_type: z.ZodEnum<{
+        board: "board";
+        item: "item";
+    }>;
+}, z.core.$strict>;
+export type NotificationSendOutput = z.infer<typeof notificationSendOutputSchema>;
+export interface SendNotificationInputs {
+    readonly client: MondayClient;
+    readonly userId: string;
+    readonly targetId: string;
+    readonly targetType: NotificationTargetType;
+    readonly text: string;
+}
+export interface SendNotificationResult {
+    readonly notification: NotificationSendOutput;
+    readonly source: 'live';
+    readonly cacheAgeSeconds: null;
+    readonly complexity: Complexity | null;
+}
+/**
+ * Fires Monday's `create_notification` mutation. Both CLI
+ * `--target-type` values (`item`/`board`) map to the wire enum
+ * `NotificationTargetType.Project` — Monday's wire surface doesn't
+ * distinguish items from boards at the enum level. Monday
+ * validates that `target_id` is a visible `Project` (invisible /
+ * non-existent targets surface `not_found`) but does NOT verify
+ * that the kind matches the CLI-declared `target_type`; the
+ * pairing is trusted and echoed but not enforced.
+ *
+ * The wire payload returns only `{id, text}`; the CLI-side echo
+ * (`user_id` / `target_id` / `target_type`) is composed at the
+ * caller's parse boundary so the resulting envelope carries both the
+ * Monday-minted `id` and the agent-supplied inputs in one read.
+ *
+ * `operationName: 'CreateNotification'` stays in sync with the named
+ * operation in {@link CREATE_NOTIFICATION_MUTATION} (R-NEW-37 W2
+ * audit-point). Not idempotent — re-running mints a fresh
+ * notification with a new ID.
+ */
+export declare const sendNotification: (inputs: SendNotificationInputs) => Promise<SendNotificationResult>;
+//# sourceMappingURL=notifications.d.ts.map

package/dist/api/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/api/notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB,4BAA6B,CAAC;AAEpE,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7C,eAAO,MAAM,4BAA4B;;;EAAoC,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;kBAQ9B,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AAgCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,sBAAsB,KAC7B,OAAO,CAAC,sBAAsB,CA6DhC,CAAC"}

package/dist/api/notifications.js

@@ -0,0 +1,215 @@
+/**
+ * Notification send surface for the v0.3-M27 `monday notification
+ * send` verb (`cli-design.md` §2.7 + §4.3 + §13 v0.3 entry;
+ * `v0.3-plan.md` §3 M27).
+ *
+ * **Wire surface (empirical probe 2026-05-12, API `2026-01`).** One
+ * Monday GraphQL operation lands here:
+ *
+ *   - `Mutation.create_notification(user_id: ID!, target_id: ID!,
+ *     target_type: NotificationTargetType!, text: String!)` — returns
+ *     the created `Notification { id, text }`.
+ *
+ * **`NotificationTargetType` is a 2-value wire enum: `Post` / `Project`.**
+ * Monday's `Post` value targets an Update (sending a notification
+ * about a specific post); `Project` targets an Item OR a Board (the
+ * wire enum doesn't distinguish). The CLI surface keeps the
+ * documented `--target-type item|board` argv vocabulary from
+ * cli-design §4.3 — both CLI values map to wire `Project`. The CLI
+ * preserves the item-vs-board distinction at the parse boundary
+ * for argv-validation discipline and to echo the agent-supplied
+ * kind in the output envelope; the CLI does NOT pre-verify that
+ * the supplied `--target <id>` actually names the declared kind,
+ * and Monday cannot either (the wire enum collapses both kinds to
+ * `Project`). Invisible / non-existent targets surface `not_found`
+ * at mutation time, but a passing `--target-type item` with a
+ * board-shaped ID succeeds and echoes the CLI-declared kind even
+ * though the record is a board. Monday's `Post` variant is
+ * unreachable at v0.3 — a v0.3.x / v0.4 contract-extension may add
+ * `--target-type update` once a clean argv-discriminator design is
+ * pinned (cli-design §13 v0.3 entry M27 sub-block carries the
+ * deferred note).
+ *
+ * **`Notification` read shape is minimal (2 fields).** `id` (ID,
+ * non-null), `text` (String, nullable). The CLI echoes the input
+ * fields (`user_id`, `target_id`, `target_type`) alongside the
+ * Monday-side fields so an agent verifies what was sent from a
+ * single envelope read.
+ *
+ * **No new ERROR_CODES (29 stays).** Notification send failures
+ * route through the existing codes: `not_found` (target user /
+ * `Project` invisible to the token or non-existent — Monday's
+ * visibility check; CLI-declared kind vs underlying record is NOT
+ * verified), `usage_error` (text empty / malformed argv — invalid
+ * `--target-type` enum value or non-numeric `--target` ID),
+ * `unauthorized` (token lacks notification scope), `forbidden`
+ * (account permissions), `validation_failed` (Monday-side rejection).
+ *
+ * **Notification send is single-recipient at v0.3** per cli-design
+ * §4.3 — the `--user <uid>` flag accepts one ID. Multi-recipient
+ * fan-out is a v0.3.x / v0.4 contract-extension (agents needing
+ * fan-out call `notification send` N times).
+ *
+ * **Notification send is not idempotent.** Re-running the verb
+ * produces a fresh notification with a new `id` (Monday treats
+ * each `create_notification` call as a discrete send). Agents
+ * needing send-once-semantics dedup on the CLI side; the verb
+ * does not enforce idempotency.
+ *
+ * **Runtime body (M27 IMPL).** Single `client.raw` round-trip
+ * against `mutation CreateNotification` with `operationName:
+ * 'CreateNotification'` (R-NEW-37 W2 audit-point). The CLI's
+ * 2-value `--target-type` enum collapses to wire `Project` at the
+ * runtime boundary; the CLI-side echo (`user_id` / `target_id` /
+ * `target_type`) is composed at the parse boundary so the envelope
+ * carries both the Monday-minted `id` + the agent-supplied inputs.
+ */
+import { z } from 'zod';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+import { assertResponseFieldPresent } from './response-root.js';
+import { ApiError } from '../utils/errors.js';
+/**
+ * CLI-side `target_type` vocabulary for `monday notification send
+ * --target-type <type>`. Both values map to Monday's wire
+ * `NotificationTargetType.Project` (which represents both items and
+ * boards) — the CLI keeps the item-vs-board distinction for argv
+ * validation discipline AND to echo the agent-supplied kind in the
+ * output envelope. The pairing of `--target-type` with `--target
+ * <id>` is **trusted, not verified**: the CLI validates the enum +
+ * numeric ID shape; Monday validates that the target is a visible
+ * `Project` (surfacing invisible / non-existent targets as
+ * `not_found`); but neither side verifies that the CLI-declared
+ * kind matches what the ID actually names — the wire enum
+ * collapses both kinds to `Project`. A CLI-side pre-read is
+ * deferred (v0.3.x / v0.4 contract-extension if agents need
+ * strict-kind enforcement).
+ *
+ * Monday's wire enum has only two values (`Post` / `Project`); the
+ * `Post` value targets Updates and is intentionally not surfaced
+ * at v0.3 per cli-design §4.3. A v0.3.x / v0.4 contract-extension
+ * may add a CLI third target-type `update` that dispatches to wire
+ * `Post`.
+ */
+export const NOTIFICATION_TARGET_TYPES = ['item', 'board'];
+export const notificationTargetTypeSchema = z.enum(NOTIFICATION_TARGET_TYPES);
+/**
+ * Output shape for `monday notification send --user <uid> --target
+ * <iid|bid> --target-type item|board --text <t>`. Carries both the
+ * Monday-side fields (`id` of the minted notification, server-echo
+ * `text`) and the CLI-side inputs (`user_id`, `target_id`,
+ * `target_type`) so an agent verifies what was sent from a single
+ * envelope read.
+ *
+ * `text` is nullable on the wire (Monday's `Notification.text` is
+ * `String` not `String!`); we preserve nullability for fidelity even
+ * though `create_notification`'s input `text` is non-null. In
+ * practice it round-trips the input value.
+ */
+export const notificationSendOutputSchema = z
+    .object({
+    id: z.string().min(1),
+    text: z.string().nullable(),
+    user_id: z.string().min(1),
+    target_id: z.string().min(1),
+    target_type: notificationTargetTypeSchema,
+})
+    .strict();
+const CREATE_NOTIFICATION_MUTATION = `
+  mutation CreateNotification(
+    $userId: ID!,
+    $targetId: ID!,
+    $targetType: NotificationTargetType!,
+    $text: String!
+  ) {
+    create_notification(
+      user_id: $userId,
+      target_id: $targetId,
+      target_type: $targetType,
+      text: $text
+    ) {
+      id
+      text
+    }
+  }
+`;
+const wireNotificationSchema = z
+    .object({
+    id: z.string().min(1),
+    text: z.string().nullable(),
+})
+    .strict();
+/**
+ * Fires Monday's `create_notification` mutation. Both CLI
+ * `--target-type` values (`item`/`board`) map to the wire enum
+ * `NotificationTargetType.Project` — Monday's wire surface doesn't
+ * distinguish items from boards at the enum level. Monday
+ * validates that `target_id` is a visible `Project` (invisible /
+ * non-existent targets surface `not_found`) but does NOT verify
+ * that the kind matches the CLI-declared `target_type`; the
+ * pairing is trusted and echoed but not enforced.
+ *
+ * The wire payload returns only `{id, text}`; the CLI-side echo
+ * (`user_id` / `target_id` / `target_type`) is composed at the
+ * caller's parse boundary so the resulting envelope carries both the
+ * Monday-minted `id` and the agent-supplied inputs in one read.
+ *
+ * `operationName: 'CreateNotification'` stays in sync with the named
+ * operation in {@link CREATE_NOTIFICATION_MUTATION} (R-NEW-37 W2
+ * audit-point). Not idempotent — re-running mints a fresh
+ * notification with a new ID.
+ */
+export const sendNotification = async (inputs) => {
+    // CLI's 2-value enum collapses to wire `Project` (Monday's wire
+    // surface has no item-vs-board distinction). The `Post` wire value
+    // is unreachable at v0.3 per cli-design §4.3.
+    const wireTargetType = 'Project';
+    const response = await inputs.client.raw(CREATE_NOTIFICATION_MUTATION, {
+        userId: inputs.userId,
+        targetId: inputs.targetId,
+        targetType: wireTargetType,
+        text: inputs.text,
+    }, { operationName: 'CreateNotification' });
+    assertResponseFieldPresent({
+        data: response.data,
+        key: 'create_notification',
+        operationLabel: 'CreateNotification',
+        details: {
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        nullHandling: 'caller_handles',
+    });
+    const raw = response.data.create_notification;
+    if (raw === null || raw === undefined) {
+        throw new ApiError('not_found', `Monday returned no notification payload from create_notification for user ${inputs.userId} on target ${inputs.targetId}`, {
+            details: {
+                user_id: inputs.userId,
+                target_id: inputs.targetId,
+                target_type: inputs.targetType,
+            },
+        });
+    }
+    const wire = unwrapOrThrow(wireNotificationSchema.safeParse(raw), {
+        context: 'Monday `create_notification` response',
+        details: {
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        hint: 'Monday may have amended the `Notification` selection — re-probe and amend `src/api/notifications.ts` if so',
+    });
+    return {
+        notification: {
+            id: wire.id,
+            text: wire.text,
+            user_id: inputs.userId,
+            target_id: inputs.targetId,
+            target_type: inputs.targetType,
+        },
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: response.complexity,
+    };
+};
+//# sourceMappingURL=notifications.js.map

package/dist/api/notifications.js.map

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

package/dist/api/oauth-test-helper.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `__test_oauth_helper` test seam per cli-design §7.3.4.
+ *
+ * Substitutes for {@link bindOAuthListener} when the env var
+ * `__test_oauth_helper` is set; production code paths never see this
+ * helper. The substitution lives in `src/commands/auth/login.ts` —
+ * this module exposes the construction primitive.
+ *
+ * **Fixture file shape** (read from the path the env var holds):
+ *
+ * ```json
+ * {
+ *   "code": "fixture-code",
+ *   "force_csrf_mismatch": true,
+ *   "force_user_denied": true,
+ *   "force_authorization_failed": {
+ *     "error": "invalid_scope",
+ *     "error_description": "requested scope `boards:write` not granted"
+ *   },
+ *   "force_listener_timeout": true
+ * }
+ * ```
+ *
+ * All four `force_*` flags are mutually exclusive; the first
+ * non-undefined slot wins. The fixture **does not** carry `state` —
+ * it's randomly generated per invocation; the helper synthesises the
+ * redirect with the CLI's own generated `state` echoed back so CSRF
+ * verification passes by default.
+ *
+ * The fixture's PATH (the env var's value) is never echoed to the
+ * output envelope, never logged at any verbosity level, and is
+ * scrubbed from `--debug` output the same way `MONDAY_API_TOKEN` is.
+ */
+import { z } from 'zod';
+import type { OAuthListenerHandle } from './oauth.js';
+/** Env var name the test seam checks. The leading double-underscore
+ * discourages production use; tests set it explicitly. */
+export declare const TEST_OAUTH_HELPER_ENV_VAR = "__test_oauth_helper";
+declare const fixtureSchema: z.ZodObject<{
+    code: z.ZodString;
+    force_csrf_mismatch: z.ZodOptional<z.ZodLiteral<true>>;
+    force_user_denied: z.ZodOptional<z.ZodLiteral<true>>;
+    force_authorization_failed: z.ZodOptional<z.ZodObject<{
+        error: z.ZodString;
+        error_description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    force_listener_timeout: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type TestOAuthFixture = z.infer<typeof fixtureSchema>;
+/**
+ * Reads the test-helper fixture file and parses it. Surfaces
+ * `config_error` for any failure (file missing, malformed JSON,
+ * schema mismatch); a misconfigured test seam should fail loud,
+ * not silently fall back to the real listener.
+ */
+export declare const readTestOAuthFixture: (fixturePath: string) => Promise<TestOAuthFixture>;
+/**
+ * Builds a synthetic {@link OAuthListenerHandle} from the fixture +
+ * the CLI's generated `state`. No real socket bind; `awaitRedirect`
+ * resolves (or rejects) based on the fixture's `force_*` flags.
+ */
+export declare const buildTestOAuthListener: (fixture: TestOAuthFixture, generatedState: string) => OAuthListenerHandle;
+export {};
+//# sourceMappingURL=oauth-test-helper.d.ts.map

package/dist/api/oauth-test-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-test-helper.d.ts","sourceRoot":"","sources":["../../src/api/oauth-test-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,YAAY,CAAC;AAEvE;0DAC0D;AAC1D,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,QAAA,MAAM,aAAa;;;;;;;;;kBAcR,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,aAAa,MAAM,KAClB,OAAO,CAAC,gBAAgB,CA6C1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,gBAAgB,EACzB,gBAAgB,MAAM,KACrB,mBA8FF,CAAC"}

package/dist/api/oauth-test-helper.js

@@ -0,0 +1,179 @@
+/**
+ * `__test_oauth_helper` test seam per cli-design §7.3.4.
+ *
+ * Substitutes for {@link bindOAuthListener} when the env var
+ * `__test_oauth_helper` is set; production code paths never see this
+ * helper. The substitution lives in `src/commands/auth/login.ts` —
+ * this module exposes the construction primitive.
+ *
+ * **Fixture file shape** (read from the path the env var holds):
+ *
+ * ```json
+ * {
+ *   "code": "fixture-code",
+ *   "force_csrf_mismatch": true,
+ *   "force_user_denied": true,
+ *   "force_authorization_failed": {
+ *     "error": "invalid_scope",
+ *     "error_description": "requested scope `boards:write` not granted"
+ *   },
+ *   "force_listener_timeout": true
+ * }
+ * ```
+ *
+ * All four `force_*` flags are mutually exclusive; the first
+ * non-undefined slot wins. The fixture **does not** carry `state` —
+ * it's randomly generated per invocation; the helper synthesises the
+ * redirect with the CLI's own generated `state` echoed back so CSRF
+ * verification passes by default.
+ *
+ * The fixture's PATH (the env var's value) is never echoed to the
+ * output envelope, never logged at any verbosity level, and is
+ * scrubbed from `--debug` output the same way `MONDAY_API_TOKEN` is.
+ */
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { ApiError, ConfigError, asError } from '../utils/errors.js';
+/** Env var name the test seam checks. The leading double-underscore
+ * discourages production use; tests set it explicitly. */
+export const TEST_OAUTH_HELPER_ENV_VAR = '__test_oauth_helper';
+const fixtureSchema = z
+    .object({
+    code: z.string().min(1),
+    force_csrf_mismatch: z.literal(true).optional(),
+    force_user_denied: z.literal(true).optional(),
+    force_authorization_failed: z
+        .object({
+        error: z.string().min(1),
+        error_description: z.string().optional(),
+    })
+        .strict()
+        .optional(),
+    force_listener_timeout: z.literal(true).optional(),
+})
+    .strict();
+/**
+ * Reads the test-helper fixture file and parses it. Surfaces
+ * `config_error` for any failure (file missing, malformed JSON,
+ * schema mismatch); a misconfigured test seam should fail loud,
+ * not silently fall back to the real listener.
+ */
+export const readTestOAuthFixture = async (fixturePath) => {
+    let raw;
+    try {
+        raw = await readFile(fixturePath, 'utf8');
+    }
+    catch (err) {
+        throw new ConfigError(`cannot read __test_oauth_helper fixture at ${fixturePath}`, {
+            cause: asError(err),
+            details: {
+                path: fixturePath,
+                hint: 'set __test_oauth_helper to the path of a valid fixture file or unset the env var to use the real OAuth listener',
+            },
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`__test_oauth_helper fixture at ${fixturePath} is not valid JSON`, {
+            cause: asError(err),
+            details: { path: fixturePath },
+        });
+    }
+    const result = fixtureSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConfigError(`__test_oauth_helper fixture at ${fixturePath} does not match the documented shape`, {
+            cause: result.error,
+            details: {
+                path: fixturePath,
+                issues: result.error.issues.map((i) => ({
+                    path: i.path.join('.'),
+                    message: i.message,
+                })),
+            },
+        });
+    }
+    return result.data;
+};
+/**
+ * Builds a synthetic {@link OAuthListenerHandle} from the fixture +
+ * the CLI's generated `state`. No real socket bind; `awaitRedirect`
+ * resolves (or rejects) based on the fixture's `force_*` flags.
+ */
+export const buildTestOAuthListener = (fixture, generatedState) => {
+    let resolved = false;
+    const handle = {
+        port: 0,
+        awaitRedirect: () => new Promise((resolve, reject) => {
+            if (resolved) {
+                // Idempotent — repeat awaits are a programmer error in
+                // production, but the test seam guards explicitly so a
+                // double-await fails loud rather than hanging forever.
+                reject(new ApiError('internal_error', '__test_oauth_helper.awaitRedirect called twice'));
+                return;
+            }
+            resolved = true;
+            if (fixture.force_listener_timeout === true) {
+                // Mirror the real listener's timeout payload exactly so the
+                // command-level error mapping treats both surfaces
+                // identically.
+                reject(new ApiError('oauth_failed', 'OAuth listener timed out before the redirect arrived (test fixture)', {
+                    details: {
+                        reason: 'timeout',
+                        hint: 're-run `monday auth login` and complete the consent flow within 5 minutes',
+                    },
+                    retryable: true,
+                }));
+                return;
+            }
+            if (fixture.force_csrf_mismatch === true) {
+                // Substitute a different state so the caller's verifyCsrf
+                // call fails. Length-equal so the timing-safe path runs
+                // (mirrors the production CSRF code path; not just a
+                // length-mismatch shortcut).
+                const sameLengthDifferentState = generatedState
+                    .split('')
+                    .reverse()
+                    .join('');
+                // Ensure it's actually different — if `generatedState` is
+                // a palindrome (vanishingly rare), flip the first byte.
+                const echoed = sameLengthDifferentState === generatedState
+                    ? `${String.fromCharCode((generatedState.charCodeAt(0) ^ 1) & 0x7f)}${generatedState.slice(1)}`
+                    : sameLengthDifferentState;
+                resolve({ kind: 'code', code: fixture.code, state: echoed });
+                return;
+            }
+            if (fixture.force_user_denied === true) {
+                resolve({
+                    kind: 'error',
+                    error: 'access_denied',
+                    errorDescription: undefined,
+                    state: generatedState,
+                });
+                return;
+            }
+            if (fixture.force_authorization_failed !== undefined) {
+                resolve({
+                    kind: 'error',
+                    error: fixture.force_authorization_failed.error,
+                    errorDescription: fixture.force_authorization_failed.error_description,
+                    state: generatedState,
+                });
+                return;
+            }
+            // Default: success path with the CLI's own state echoed back.
+            resolve({
+                kind: 'code',
+                code: fixture.code,
+                state: generatedState,
+            });
+        }),
+        close: () => {
+            // No-op — no socket to close.
+        },
+    };
+    return handle;
+};
+//# sourceMappingURL=oauth-test-helper.js.map

package/dist/api/oauth-test-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-test-helper.js","sourceRoot":"","sources":["../../src/api/oauth-test-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGpE;0DAC0D;AAC1D,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAE/D,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC/C,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC7C,0BAA0B,EAAE,CAAC;SAC1B,MAAM,CAAC;QACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACzC,CAAC;SACD,MAAM,EAAE;SACR,QAAQ,EAAE;IACb,sBAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,WAAmB,EACQ,EAAE;IAC7B,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,8CAA8C,WAAW,EAAE,EAC3D;YACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;YACnB,OAAO,EAAE;gBACP,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,iHAAiH;aACxH;SACF,CACF,CAAC;IACJ,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,kCAAkC,WAAW,oBAAoB,EACjE;YACE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC;YACnB,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;SAC/B,CACF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,WAAW,CACnB,kCAAkC,WAAW,sCAAsC,EACnF;YACE,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE;gBACP,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACtC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;oBACtB,OAAO,EAAE,CAAC,CAAC,OAAO;iBACnB,CAAC,CAAC;aACJ;SACF,CACF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,OAAyB,EACzB,cAAsB,EACD,EAAE;IACvB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,MAAM,GAAwB;QAClC,IAAI,EAAE,CAAC;QACP,aAAa,EAAE,GAAG,EAAE,CAClB,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC/C,IAAI,QAAQ,EAAE,CAAC;gBACb,uDAAuD;gBACvD,uDAAuD;gBACvD,uDAAuD;gBACvD,MAAM,CACJ,IAAI,QAAQ,CACV,gBAAgB,EAChB,gDAAgD,CACjD,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;YAEhB,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;gBAC5C,4DAA4D;gBAC5D,mDAAmD;gBACnD,eAAe;gBACf,MAAM,CACJ,IAAI,QAAQ,CACV,cAAc,EACd,qEAAqE,EACrE;oBACE,OAAO,EAAE;wBACP,MAAM,EAAE,SAAS;wBACjB,IAAI,EAAE,2EAA2E;qBAClF;oBACD,SAAS,EAAE,IAAI;iBAChB,CACF,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;gBACzC,0DAA0D;gBAC1D,wDAAwD;gBACxD,qDAAqD;gBACrD,6BAA6B;gBAC7B,MAAM,wBAAwB,GAAG,cAAc;qBAC5C,KAAK,CAAC,EAAE,CAAC;qBACT,OAAO,EAAE;qBACT,IAAI,CAAC,EAAE,CAAC,CAAC;gBACZ,0DAA0D;gBAC1D,wDAAwD;gBACxD,MAAM,MAAM,GACV,wBAAwB,KAAK,cAAc;oBACzC,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY,CACpB,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAC1C,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;oBAC/B,CAAC,CAAC,wBAAwB,CAAC;gBAC/B,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC7D,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;gBACvC,OAAO,CAAC;oBACN,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,eAAe;oBACtB,gBAAgB,EAAE,SAAS;oBAC3B,KAAK,EAAE,cAAc;iBACtB,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,0BAA0B,KAAK,SAAS,EAAE,CAAC;gBACrD,OAAO,CAAC;oBACN,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,OAAO,CAAC,0BAA0B,CAAC,KAAK;oBAC/C,gBAAgB,EACd,OAAO,CAAC,0BAA0B,CAAC,iBAAiB;oBACtD,KAAK,EAAE,cAAc;iBACtB,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAED,8DAA8D;YAC9D,OAAO,CAAC;gBACN,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,KAAK,EAAE,cAAc;aACtB,CAAC,CAAC;QACL,CAAC,CAAC;QACJ,KAAK,EAAE,GAAG,EAAE;YACV,8BAA8B;QAChC,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}