monday-cli 0.2.0

package/dist/api/items-page-walker.js

@@ -0,0 +1,256 @@
+/**
+ * `items_page` GraphQL helper — single-page fetcher pair
+ * (`v0.2-plan.md` §18 R34).
+ *
+ * Lifted from five sites that all hand-rolled the same
+ * `query Foo($boardId: ID!, $limit: Int!, $queryParams: ItemsQuery)
+ * { boards(ids: [$boardId]) { items_page(...) { cursor items {...} } } }`
+ * shape with per-site item-field projection + per-site
+ * `unwrapOrThrow`-wrapped malformed-response handling. The shared
+ * surface is:
+ *
+ *   - GraphQL string assembly (operation name + optional group-filter
+ *     wrapper + caller-supplied item-fields fragment).
+ *   - Response parse boundary — `boards[0]` (and `groups[0]` for the
+ *     group-filtered variant) → `items_page.{cursor, items[]}` with
+ *     the matching malformed-response context message.
+ *
+ * **Operation name as a parameter**, not a constant. The SDK threads
+ * `operationName` to Monday's request-log telemetry so a `bulk item
+ * update --where` walk is distinguishable from a `bulk item clear
+ * --where` walk in Monday's logs. Same reason §18 R33 stays deferred:
+ * collapsing operations under one name breaks attribution.
+ *
+ * **Item-fields fragment as a string**, not a typed projection. Three
+ * projections in scope today: `id` (clear / update bulk walkers),
+ * `id\n          name` (upsert lookup), `${ITEM_FIELDS_FRAGMENT}`
+ * (item list). Projections are inlined verbatim into the query
+ * source — the per-call response zod schema validates that the rows
+ * Monday returned actually match.
+ *
+ * **Group-filter variant** (`item list --group <gid>`) wraps an extra
+ * `groups(ids: [$groupId])` selection between `boards` and
+ * `items_page`. The helper switches the query shape and the response
+ * schema based on the optional `groupId` input — both the wire shape
+ * and Monday's accepted variable set diverge between the two queries
+ * (the top-level `items_page` doesn't accept `group_id` inside
+ * `query_params`, so the group-aware path is structurally distinct).
+ *
+ * **The cursor walker stays in `pagination.ts`.** All bulk consumers
+ * (item list, item update --where, item clear --where) thread these
+ * single-page fetchers through `paginate.ts`'s `fetchInitial` /
+ * `fetchNext` closures. That preserves the §3.1 #8 per-page
+ * ascending-by-ID sort and the §5.6 `stale_cursor` enrichment
+ * (`cursor_age_seconds` / `items_returned_so_far` / `last_item_id`)
+ * across every site post-lift. Codex round-1 F1 + F2 caught the
+ * variant where a thin generator dropped both — pure refactor must
+ * match pre-lift behavior, not just pre-lift error code.
+ *
+ * **stale_cursor fail-fast.** `cli-design.md` §5.6 — Monday's cursor
+ * lifetime is 60 min, expired cursors return `INVALID_CURSOR_EXCEPTION`
+ * which `api/errors.ts` maps to `error.code === 'stale_cursor'`. The
+ * helper bubbles the error unchanged so `paginate.ts` can layer its
+ * §5.6 details enrichment on top.
+ */
+import { z } from 'zod';
+import { ApiError } from '../utils/errors.js';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+const buildItemsPageQuery = (inputs) => {
+    const itemsPage = `items_page(limit: $limit, query_params: $queryParams) {
+        cursor
+        items {
+          ${inputs.itemFields}
+        }
+      }`;
+    if (inputs.hasGroup) {
+        return `
+  query ${inputs.operationName}(
+    $boardId: ID!
+    $groupId: String!
+    $limit: Int!
+    $queryParams: ItemsQuery
+  ) {
+    boards(ids: [$boardId]) {
+      groups(ids: [$groupId]) {
+        ${itemsPage}
+      }
+    }
+  }
+`;
+    }
+    return `
+  query ${inputs.operationName}(
+    $boardId: ID!
+    $limit: Int!
+    $queryParams: ItemsQuery
+  ) {
+    boards(ids: [$boardId]) {
+      ${itemsPage}
+    }
+  }
+`;
+};
+const buildNextItemsPageQuery = (inputs) => `
+  query ${inputs.operationName}($cursor: String!, $limit: Int!) {
+    next_items_page(limit: $limit, cursor: $cursor) {
+      cursor
+      items {
+        ${inputs.itemFields}
+      }
+    }
+  }
+`;
+// Schema builders are inlined per call site so the generic-instance
+// types stay narrow per fetcher (the lint
+// `explicit-function-return-type` rule combined with zod's deeply
+// nested ZodObject<...> inferred return type makes a top-level
+// builder ergonomically infeasible without massive annotations —
+// the inlined versions infer cleanly from each call site's `T`).
+/**
+ * Fires one `items_page(query_params:)` query and returns the parsed
+ * `{items, cursor}` payload as `MondayResponse.data`. The wider
+ * `MondayResponse` shape (complexity, stats) passes through untouched
+ * so callers can spread it into `toEmit(response)` for `meta`.
+ *
+ * Malformed responses surface as typed `internal_error` carrying
+ * `details.issues` (per-field zod failure path) — same parse-boundary
+ * contract as the standalone `unwrapOrThrow` helper.
+ */
+export const fetchItemsPage = async (inputs) => {
+    const hasGroup = inputs.groupId !== undefined;
+    const query = buildItemsPageQuery({
+        operationName: inputs.operationName,
+        hasGroup,
+        itemFields: inputs.itemFields,
+    });
+    const variables = {
+        boardId: inputs.boardId,
+        limit: inputs.limit,
+    };
+    if (hasGroup) {
+        variables.groupId = inputs.groupId;
+    }
+    if (inputs.queryParams !== undefined) {
+        variables.queryParams = inputs.queryParams;
+    }
+    else {
+        variables.queryParams = null;
+    }
+    const response = await inputs.client.raw(query, variables, {
+        operationName: inputs.operationName,
+    });
+    const context = `Monday returned a malformed ${inputs.operationName} response for board ${inputs.boardId}`;
+    const details = { board_id: inputs.boardId };
+    const itemsPage = hasGroup
+        ? extractGroupedItemsPage(response.data, inputs.itemSchema, {
+            context,
+            details,
+            operationName: inputs.operationName,
+        })
+        : extractTopLevelItemsPage(response.data, inputs.itemSchema, {
+            context,
+            details,
+            operationName: inputs.operationName,
+        });
+    return {
+        ...response,
+        data: { items: itemsPage.items, cursor: itemsPage.cursor },
+    };
+};
+const extractTopLevelItemsPage = (data, itemSchema, ctx) => {
+    const schema = z
+        .object({
+        boards: z
+            .array(z
+            .object({
+            items_page: z.object({
+                cursor: z.string().nullable(),
+                items: z.array(itemSchema),
+            }),
+        })
+            .loose())
+            .min(1),
+    })
+        .loose();
+    const parsed = unwrapOrThrow(schema.safeParse(data), {
+        context: ctx.context,
+        details: ctx.details,
+    });
+    // Schema's `.min(1)` already rejected empty boards arrays; the
+    // guard satisfies `noUncheckedIndexedAccess`.
+    const board = parsed.boards[0];
+    /* c8 ignore next 6 */
+    if (board === undefined) {
+        throw new ApiError('internal_error', `${ctx.operationName}: empty boards array`);
+    }
+    return board.items_page;
+};
+const extractGroupedItemsPage = (data, itemSchema, ctx) => {
+    const schema = z
+        .object({
+        boards: z
+            .array(z
+            .object({
+            groups: z
+                .array(z
+                .object({
+                items_page: z.object({
+                    cursor: z.string().nullable(),
+                    items: z.array(itemSchema),
+                }),
+            })
+                .loose())
+                .min(1),
+        })
+            .loose())
+            .min(1),
+    })
+        .loose();
+    const parsed = unwrapOrThrow(schema.safeParse(data), {
+        context: ctx.context,
+        details: ctx.details,
+    });
+    const board = parsed.boards[0];
+    /* c8 ignore next 6 */
+    if (board === undefined) {
+        throw new ApiError('internal_error', `${ctx.operationName}: empty boards array`);
+    }
+    const group = board.groups[0];
+    /* c8 ignore next 6 */
+    if (group === undefined) {
+        throw new ApiError('internal_error', `${ctx.operationName}: empty groups array`);
+    }
+    return group.items_page;
+};
+/**
+ * Fires one `next_items_page(cursor:)` continuation and returns the
+ * parsed `{items, cursor}` payload. Same parse-boundary contract as
+ * {@link fetchItemsPage}.
+ */
+export const fetchNextItemsPage = async (inputs) => {
+    const query = buildNextItemsPageQuery({
+        operationName: inputs.operationName,
+        itemFields: inputs.itemFields,
+    });
+    const response = await inputs.client.raw(query, { cursor: inputs.cursor, limit: inputs.limit }, { operationName: inputs.operationName });
+    const schema = z
+        .object({
+        next_items_page: z.object({
+            cursor: z.string().nullable(),
+            items: z.array(inputs.itemSchema),
+        }),
+    })
+        .loose();
+    const data = unwrapOrThrow(schema.safeParse(response.data), {
+        context: `Monday returned a malformed ${inputs.operationName} response`,
+        details: { cursor: inputs.cursor },
+    });
+    return {
+        ...response,
+        data: {
+            items: data.next_items_page.items,
+            cursor: data.next_items_page.cursor,
+        },
+    };
+};
+//# sourceMappingURL=items-page-walker.js.map

package/dist/api/items-page-walker.js.map

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

package/dist/api/links.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure link-resolution helpers for the `link` column-value translator
+ * (`cli-design.md` §5.3 step 3 v0.2 expansion, `v0.2-plan.md` §3 M8).
+ *
+ * Surface:
+ *   - `parseLinkInput` — accepts the two pipe-form shapes cli-design
+ *     §5.3 enumerates: `<url>` (text defaults to the URL) and
+ *     `<url>|<text>` (both segments trimmed; pipe-split max 1 split).
+ *     URL validated via `z.string().url()`.
+ *
+ * **Why a separate module.** Same template `dates.ts` / `people.ts`
+ * follow — column-values.ts owns translator dispatch; the per-type
+ * grammar machinery + zod boundary lives one module deeper. Split
+ * keeps column-values.ts at one screen of dispatch logic and each
+ * translator's tests + corner-case coverage isolated.
+ *
+ * **Pipe-form max 1 split.** `<url>|<text>` allows `|` inside the
+ * `<text>` segment because `splitOnFirstPipe` only splits on the
+ * first `|`. So `https://example.com|foo|bar` parses as
+ * `{url: "https://example.com", text: "foo|bar"}`. Cli-design
+ * doesn't pin this — but pinning here means agents who want a `|`
+ * literal in their link text get it without reaching for `--set-raw`.
+ *
+ * **Empty trailer rejected.** `<url>|` (pipe with empty trailer) is
+ * rejected with `usage_error`. Cli-design §5.3 line 810-811: "Pipe-
+ * form with empty trailer rejected (usage_error); use --set-raw
+ * (below) to write a link with empty text." A user who wants empty
+ * text takes the escape hatch.
+ */
+/**
+ * Wire payload shape for a `link` column. Matches Monday's
+ * `change_column_value(value: JSON!)` JSON scalar:
+ *   `{url: <url>, text: <text>}`
+ *
+ * cli-design.md §5.3 step 3 v0.2 expansion line 806-811 pins the
+ * shape. `text` defaults to the URL when the pipe form is absent —
+ * Monday's link-column UI shows the `text` segment as the visible
+ * label, so a missing text would render as an empty hyperlink.
+ */
+export interface LinkPayload {
+    readonly url: string;
+    readonly text: string;
+}
+/**
+ * Parses a `link` column input per cli-design.md §5.3 step 3 v0.2
+ * expansion.
+ *
+ * Accepted inputs:
+ *   - **Single URL** `https://example.com` → `{url, text: <url>}`.
+ *     The URL doubles as the visible text — Monday's link UI shows
+ *     `text` as the hyperlink label.
+ *   - **Pipe form** `https://example.com|Site` → `{url, text}`.
+ *     Both segments trimmed; pipe-split max 1 (so `text` may
+ *     contain literal `|` characters).
+ *
+ * Throws `UsageError(usage_error)`:
+ *   - URL fails `z.string().url()` validation. The error names the
+ *     failing URL so the agent can see what they sent.
+ *   - Pipe form with empty trailer (`https://x|` or `https://x|   `).
+ *     Cli-design §5.3 line 810-811 names this rule explicitly: "use
+ *     --set-raw to write a link with empty text".
+ *   - Empty input after trim.
+ *   - Pipe form with empty leader (`|Site` after trim). Same shape
+ *     as the empty-input branch — there's no URL to validate.
+ *
+ * @param raw - The raw user-supplied value (post-`--set` parsing).
+ * @param columnId - Column ID for error messages.
+ */
+export declare const parseLinkInput: (raw: string, columnId: string) => LinkPayload;
+//# sourceMappingURL=links.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/api/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc,GACzB,KAAK,MAAM,EACX,UAAU,MAAM,KACf,WAmEF,CAAC"}

package/dist/api/links.js

@@ -0,0 +1,128 @@
+/**
+ * Pure link-resolution helpers for the `link` column-value translator
+ * (`cli-design.md` §5.3 step 3 v0.2 expansion, `v0.2-plan.md` §3 M8).
+ *
+ * Surface:
+ *   - `parseLinkInput` — accepts the two pipe-form shapes cli-design
+ *     §5.3 enumerates: `<url>` (text defaults to the URL) and
+ *     `<url>|<text>` (both segments trimmed; pipe-split max 1 split).
+ *     URL validated via `z.string().url()`.
+ *
+ * **Why a separate module.** Same template `dates.ts` / `people.ts`
+ * follow — column-values.ts owns translator dispatch; the per-type
+ * grammar machinery + zod boundary lives one module deeper. Split
+ * keeps column-values.ts at one screen of dispatch logic and each
+ * translator's tests + corner-case coverage isolated.
+ *
+ * **Pipe-form max 1 split.** `<url>|<text>` allows `|` inside the
+ * `<text>` segment because `splitOnFirstPipe` only splits on the
+ * first `|`. So `https://example.com|foo|bar` parses as
+ * `{url: "https://example.com", text: "foo|bar"}`. Cli-design
+ * doesn't pin this — but pinning here means agents who want a `|`
+ * literal in their link text get it without reaching for `--set-raw`.
+ *
+ * **Empty trailer rejected.** `<url>|` (pipe with empty trailer) is
+ * rejected with `usage_error`. Cli-design §5.3 line 810-811: "Pipe-
+ * form with empty trailer rejected (usage_error); use --set-raw
+ * (below) to write a link with empty text." A user who wants empty
+ * text takes the escape hatch.
+ */
+import { z } from 'zod';
+import { UsageError } from '../utils/errors.js';
+const URL_SCHEMA = z.url();
+/**
+ * Parses a `link` column input per cli-design.md §5.3 step 3 v0.2
+ * expansion.
+ *
+ * Accepted inputs:
+ *   - **Single URL** `https://example.com` → `{url, text: <url>}`.
+ *     The URL doubles as the visible text — Monday's link UI shows
+ *     `text` as the hyperlink label.
+ *   - **Pipe form** `https://example.com|Site` → `{url, text}`.
+ *     Both segments trimmed; pipe-split max 1 (so `text` may
+ *     contain literal `|` characters).
+ *
+ * Throws `UsageError(usage_error)`:
+ *   - URL fails `z.string().url()` validation. The error names the
+ *     failing URL so the agent can see what they sent.
+ *   - Pipe form with empty trailer (`https://x|` or `https://x|   `).
+ *     Cli-design §5.3 line 810-811 names this rule explicitly: "use
+ *     --set-raw to write a link with empty text".
+ *   - Empty input after trim.
+ *   - Pipe form with empty leader (`|Site` after trim). Same shape
+ *     as the empty-input branch — there's no URL to validate.
+ *
+ * @param raw - The raw user-supplied value (post-`--set` parsing).
+ * @param columnId - Column ID for error messages.
+ */
+export const parseLinkInput = (raw, columnId) => {
+    const trimmedRaw = raw.trim();
+    if (trimmedRaw.length === 0) {
+        throw emptyLinkInputError(columnId, raw);
+    }
+    const pipeIdx = trimmedRaw.indexOf('|');
+    let urlSegment;
+    let textSegment;
+    if (pipeIdx === -1) {
+        // Single-segment form: text defaults to URL.
+        urlSegment = trimmedRaw;
+        textSegment = trimmedRaw;
+    }
+    else {
+        urlSegment = trimmedRaw.slice(0, pipeIdx).trim();
+        textSegment = trimmedRaw.slice(pipeIdx + 1).trim();
+        if (urlSegment.length === 0) {
+            throw emptyLinkInputError(columnId, raw);
+        }
+        if (textSegment.length === 0) {
+            // Cli-design §5.3 line 810-811: "Pipe-form with empty trailer
+            // rejected (usage_error); use --set-raw to write a link with
+            // empty text." Agents who genuinely want an empty visible label
+            // take the escape hatch.
+            throw new UsageError(`Link column "${columnId}" got pipe-form input with an empty ` +
+                `text segment ("${raw}"). The friendly translator requires ` +
+                `non-empty text after "|"; pass a single URL (text defaults ` +
+                `to the URL) or use --set-raw to write a link with empty text.`, {
+                details: {
+                    column_id: columnId,
+                    column_type: 'link',
+                    raw_input: raw,
+                    hint: `pass a single URL (--set ${columnId}=https://example.com) ` +
+                        `or pipe-form (--set ${columnId}='https://example.com|Site'). ` +
+                        `For empty text, use --set-raw ${columnId}=` +
+                        `'{"url":"https://example.com","text":""}'.`,
+                },
+            });
+        }
+    }
+    const urlResult = URL_SCHEMA.safeParse(urlSegment);
+    if (!urlResult.success) {
+        throw new UsageError(`Link column "${columnId}" got invalid URL "${urlSegment}". ` +
+            `Monday's link column requires a well-formed absolute URL ` +
+            `(e.g. https://example.com).`, {
+            details: {
+                column_id: columnId,
+                column_type: 'link',
+                raw_input: raw,
+                url_segment: urlSegment,
+                hint: `pass an absolute URL (e.g. --set ${columnId}=` +
+                    `https://example.com). The pipe form (--set ${columnId}=` +
+                    `'https://example.com|Site') sets a custom visible label.`,
+            },
+        });
+    }
+    return { url: urlResult.data, text: textSegment };
+};
+const emptyLinkInputError = (columnId, raw) => new UsageError(`Link column "${columnId}" needs a URL. Got "${raw}". To clear a ` +
+    `link column, use \`monday item clear <iid> ${columnId} ` +
+    `[--board <bid>]\` instead.`, {
+    details: {
+        column_id: columnId,
+        column_type: 'link',
+        raw_input: raw,
+        hint: `pass an absolute URL (--set ${columnId}=https://example.com) ` +
+            `or pipe-form with a visible label (--set ${columnId}=` +
+            `'https://example.com|Site').`,
+    },
+});
+//# sourceMappingURL=links.js.map

package/dist/api/links.js.map

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

package/dist/api/me-token.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared `me`-token detection (`cli-design.md` §5.3 step 3 line
+ * 704-707).
+ *
+ * Three CLI surfaces resolve `me` to the connected user's ID, all
+ * with the same case-insensitive matching rule:
+ *
+ *   1. **`--where Owner=me`** (read filter) — `src/api/filters.ts`.
+ *   2. **`item search --where Owner=me`** (search filter) —
+ *      `src/commands/item/search.ts`.
+ *   3. **`--set Owner=me`** (write translator) — `src/api/people.ts`.
+ *
+ * Pre-extraction, all three sites carried a verbatim copy of the
+ * same expression (`value.trim().toLowerCase() === 'me'`) — added
+ * one-by-one across the people-session Codex passes as the parity
+ * gap between the three was discovered. A single helper here
+ * prevents the next drift outright; if v0.2 extends the grammar
+ * (e.g. `i` / `@me` aliases) the change lands in one place.
+ *
+ * **Why a separate module.** The helper has no dependencies and
+ * three structurally-distinct consumers; folding it into
+ * `people.ts` would bind the read-side filter modules to the
+ * write-side translator's import graph, which is the wrong
+ * ordering. Keeping it standalone matches the seam every
+ * resolver-shaped helper in `src/api/` already follows.
+ */
+/**
+ * The set of tokens that resolve to the connected user. Exposed as
+ * a frozen array so a future v0.2 extension (e.g. `i`, `@me`) lands
+ * by adding one entry; the type-guard contract is unchanged.
+ *
+ * Lowercase canonical forms — callers lowercase the input via
+ * `isMeToken` before checking, so adding a token in mixed case
+ * here would silently drop matching for the lowercase form. Pin
+ * via test (`me-token.test.ts`).
+ */
+export declare const ME_TOKENS: readonly string[];
+/**
+ * Returns `true` if the given token is one of the recognised `me`
+ * aliases. Case-insensitive after trim — `me` / `ME` / `Me` /
+ * `mE` / `" me "` all match. cli-design.md §5.3 step 3 line
+ * 704-707 doesn't pin case-sensitivity explicitly, but the people
+ * session's Codex passes settled on case-insensitive across all
+ * three surfaces (logged as a v0.1-plan §3 M5a spec gap for
+ * cli-design backfill).
+ *
+ * Returns `false` for any other input — including empty strings
+ * (`""` doesn't trim to a `me` token; the empty-input branch in
+ * each call site handles that path before reaching the helper).
+ */
+export declare const isMeToken: (token: string) => boolean;
+//# sourceMappingURL=me-token.d.ts.map

package/dist/api/me-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"me-token.d.ts","sourceRoot":"","sources":["../../src/api/me-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAW,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,OAGzC,CAAC"}

package/dist/api/me-token.js

@@ -0,0 +1,55 @@
+/**
+ * Shared `me`-token detection (`cli-design.md` §5.3 step 3 line
+ * 704-707).
+ *
+ * Three CLI surfaces resolve `me` to the connected user's ID, all
+ * with the same case-insensitive matching rule:
+ *
+ *   1. **`--where Owner=me`** (read filter) — `src/api/filters.ts`.
+ *   2. **`item search --where Owner=me`** (search filter) —
+ *      `src/commands/item/search.ts`.
+ *   3. **`--set Owner=me`** (write translator) — `src/api/people.ts`.
+ *
+ * Pre-extraction, all three sites carried a verbatim copy of the
+ * same expression (`value.trim().toLowerCase() === 'me'`) — added
+ * one-by-one across the people-session Codex passes as the parity
+ * gap between the three was discovered. A single helper here
+ * prevents the next drift outright; if v0.2 extends the grammar
+ * (e.g. `i` / `@me` aliases) the change lands in one place.
+ *
+ * **Why a separate module.** The helper has no dependencies and
+ * three structurally-distinct consumers; folding it into
+ * `people.ts` would bind the read-side filter modules to the
+ * write-side translator's import graph, which is the wrong
+ * ordering. Keeping it standalone matches the seam every
+ * resolver-shaped helper in `src/api/` already follows.
+ */
+/**
+ * The set of tokens that resolve to the connected user. Exposed as
+ * a frozen array so a future v0.2 extension (e.g. `i`, `@me`) lands
+ * by adding one entry; the type-guard contract is unchanged.
+ *
+ * Lowercase canonical forms — callers lowercase the input via
+ * `isMeToken` before checking, so adding a token in mixed case
+ * here would silently drop matching for the lowercase form. Pin
+ * via test (`me-token.test.ts`).
+ */
+export const ME_TOKENS = ['me'];
+/**
+ * Returns `true` if the given token is one of the recognised `me`
+ * aliases. Case-insensitive after trim — `me` / `ME` / `Me` /
+ * `mE` / `" me "` all match. cli-design.md §5.3 step 3 line
+ * 704-707 doesn't pin case-sensitivity explicitly, but the people
+ * session's Codex passes settled on case-insensitive across all
+ * three surfaces (logged as a v0.1-plan §3 M5a spec gap for
+ * cli-design backfill).
+ *
+ * Returns `false` for any other input — including empty strings
+ * (`""` doesn't trim to a `me` token; the empty-input branch in
+ * each call site handles that path before reaching the helper).
+ */
+export const isMeToken = (token) => {
+    const normalised = token.trim().toLowerCase();
+    return ME_TOKENS.includes(normalised);
+};
+//# sourceMappingURL=me-token.js.map

package/dist/api/me-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"me-token.js","sourceRoot":"","sources":["../../src/api/me-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAsB,CAAC,IAAI,CAAC,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAW,EAAE;IAClD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAO,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC,CAAC"}