monday-cli 0.4.0 → 0.5.0

package/dist/commands/user/team-remove-members.js

@@ -0,0 +1,176 @@
+/**
+ * `monday user team-remove-members <tid> --users <id,...>
+ * [--dry-run]` — remove one or more users from a team
+ * (`cli-design.md` §4.3 USER section + §13 v0.5 entry;
+ * `v0.5-plan.md` §3 M34).
+ *
+ * **Wire shape.** Single `remove_users_from_team(team_id,
+ * user_ids)` round-trip via {@link removeUsersFromTeam}
+ * against `mutation RemoveUsersFromTeam` with `operationName:
+ * 'RemoveUsersFromTeam'` (R-NEW-37 W2 audit-point). Monday
+ * returns `ChangeTeamMembershipsResult { failed_users:
+ * [User!], successful_users: [User!] }` — same wire-level
+ * partial-success envelope as add-members. The action body
+ * wraps this into the §6.1 universal partial-success shape
+ * `data: { operation: "remove_users_from_team", team_id,
+ * results: [{ok, user_id, ...}] }` (D5 closure).
+ *
+ * **Argv shape.**
+ *
+ *   - `<teamId>` — positional `TeamId`. Required, brand-
+ *     validated at parse boundary.
+ *   - `--users <id,...>` — required, comma-separated numeric
+ *     user IDs (maps to wire `user_ids: [ID!]!`). Each entry
+ *     brand-validated via {@link UserIdSchema} through the
+ *     lifted {@link parseBrandedListArg} helper (R-NEW-70
+ *     consumer #4 post-lift).
+ *
+ * **Output envelope.** Same shape as
+ * {@link teamAddMembersCommand} but with `operation:
+ * 'remove_users_from_team'` so agents that key off the
+ * operation literal can dispatch the right post-mutation
+ * recovery flow.
+ *
+ * **Wire-vs-CLI semantics asymmetry.** Same generic-
+ * `membership_failed`-code asymmetry as team-add-members; see
+ * `teamMembershipResultSchema` JSDoc in `src/api/teams.ts` for
+ * the canonical note + cross-link to `docs/architecture.md`'s
+ * "Wire-vs-CLI semantics documentation conventions" section.
+ *
+ * **Dry-run shape** per cli-design §6.4 mutation-dry-run
+ * variant. SINGLE planned operation entry `{operation:
+ * 'remove_users_from_team', team_id, user_ids: [...]}` with
+ * `user_ids` echoing the input argv order — Monday's wire is
+ * a single-shot bulk call (`remove_users_from_team(team_id,
+ * user_ids: [ID!]!)`), NOT a per-user fan-out like
+ * `monday workspace remove-users`. No preflight read fires;
+ * argv-derived. `meta.source: 'none'`.
+ *
+ * **Idempotent: yes** — Monday is no-op on a re-remove (the
+ * user already being out of the team surfaces in
+ * `successful_users[]` per Monday's wire convention).
+ *
+ * **Admin-permission-sensitive.** Non-admin callers surface
+ * `forbidden`.
+ *
+ * **Runtime body landed at v0.5-M34 IMPL.** Mirrors the
+ * `team-add-members` cadence verbatim modulo the `operation`
+ * literal — argv + `--users` parse → resolveClient → dry-run
+ * or live dispatch via {@link removeUsersFromTeam} → shared
+ * {@link projectMembershipResults} → `emitMutation`.
+ */
+import { z } from 'zod';
+import { ensureSubcommand } from '../types.js';
+import { parseArgv } from '../parse-argv.js';
+import { emitDryRun, emitMutation } from '../emit.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { TeamIdSchema, UserIdSchema } from '../../types/ids.js';
+import { parseBrandedListArg } from '../../utils/parse-brand-list.js';
+import { removeUsersFromTeam, teamRemoveMembersOutputSchema, } from '../../api/teams.js';
+import { projectMembershipResults } from './_team-membership.js';
+const inputSchema = z
+    .object({
+    teamId: TeamIdSchema,
+    users: z.string().min(1, '--users must not be empty'),
+})
+    .strict();
+export const teamRemoveMembersCommand = {
+    name: 'user.team-remove-members',
+    summary: 'Remove users from a team (partial-success envelope)',
+    examples: [
+        'monday user team-remove-members 12345 --users 67890',
+        'monday user team-remove-members 12345 --users 67890,67891',
+        'monday user team-remove-members 12345 --users 67890 --dry-run --json',
+    ],
+    // Re-removing an already-removed user is a no-op on Monday's
+    // wire; mark idempotent so agents can retry on transient
+    // failure.
+    idempotent: true,
+    inputSchema,
+    outputSchema: teamRemoveMembersOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'user', 'User commands');
+        noun
+            .command('team-remove-members <teamId>')
+            .description(teamRemoveMembersCommand.summary)
+            .requiredOption('--users <list>', 'Comma-separated numeric user IDs to remove (maps to wire `user_ids: [ID!]!`).')
+            .addHelpText('after', [
+            '',
+            'Examples:',
+            ...teamRemoveMembersCommand.examples.map((e) => `  ${e}`),
+            '',
+            'Notes:',
+            '  - Envelope is per-cli-design §6.1 partial-success (`results: [{user_id, ok, ...}]`).',
+            '  - Re-removing an absent member is a no-op (surfaces as `successful_users[]`).',
+            '',
+        ].join('\n'))
+            .action(async (teamIdArg, opts) => {
+            const parsed = parseArgv(teamRemoveMembersCommand.inputSchema, {
+                teamId: teamIdArg,
+                ...opts,
+            });
+            // Parse `--users` once at the boundary so a malformed
+            // user ID surfaces `usage_error` ahead of any wire call.
+            // Lifted helper at R-NEW-70 (consumer #4 post-lift).
+            const userIds = parseBrandedListArg(parsed.users, UserIdSchema, {
+                flagName: '--users',
+                entryDescription: 'numeric user ID',
+                hint: 'user IDs are numeric (e.g. 67890)',
+                emptyEntryHint: 'e.g. --users 67890,67891 — no leading, trailing, or ' +
+                    'duplicate commas',
+            });
+            const { client, globalFlags, apiVersion } = resolveClient(ctx, program.opts());
+            if (globalFlags.dryRun) {
+                // Minimal dry-run shape per cli-design §6.4 — single
+                // planned operation echoing what the live wire call
+                // would send. No preflight read fires; `meta.source:
+                // 'none'`.
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: [
+                        {
+                            operation: 'remove_users_from_team',
+                            team_id: parsed.teamId,
+                            user_ids: [...userIds],
+                        },
+                    ],
+                    source: 'none',
+                    cacheAgeSeconds: null,
+                    warnings: [],
+                    apiVersion,
+                });
+                return;
+            }
+            const result = await removeUsersFromTeam({
+                client,
+                teamId: parsed.teamId,
+                userIds,
+            });
+            const results = projectMembershipResults({
+                inputUserIds: userIds,
+                failedUsers: result.failedUsers,
+                successfulUsers: result.successfulUsers,
+                operation: 'remove_users_from_team',
+                teamId: parsed.teamId,
+            });
+            const data = {
+                operation: 'remove_users_from_team',
+                team_id: parsed.teamId,
+                results: [...results],
+            };
+            emitMutation({
+                ctx,
+                data,
+                schema: teamRemoveMembersCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings: [],
+                source: result.source,
+                cacheAgeSeconds: result.cacheAgeSeconds,
+                complexity: result.complexity,
+                apiVersion,
+            });
+        });
+    },
+};
+//# sourceMappingURL=team-remove-members.js.map

package/dist/commands/user/team-remove-members.js.map

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

package/dist/types/ids.d.ts

@@ -28,8 +28,11 @@ export declare const WorkspaceIdSchema: z.core.$ZodBranded<z.ZodString, "Workspa
 export declare const UpdateIdSchema: z.core.$ZodBranded<z.ZodString, "UpdateId", "out">;
 export declare const WebhookIdSchema: z.core.$ZodBranded<z.ZodString, "WebhookId", "out">;
 export declare const DocIdSchema: z.core.$ZodBranded<z.ZodString, "DocId", "out">;
+export declare const TeamIdSchema: z.core.$ZodBranded<z.ZodString, "TeamId", "out">;
+export declare const DocFolderIdSchema: z.core.$ZodBranded<z.ZodString, "DocFolderId", "out">;
 export declare const ColumnIdSchema: z.core.$ZodBranded<z.ZodString, "ColumnId", "out">;
 export declare const GroupIdSchema: z.core.$ZodBranded<z.ZodString, "GroupId", "out">;
+export declare const DocBlockIdSchema: z.core.$ZodBranded<z.ZodString, "DocBlockId", "out">;
 export type BoardId = z.infer<typeof BoardIdSchema>;
 export type ItemId = z.infer<typeof ItemIdSchema>;
 export type ColumnId = z.infer<typeof ColumnIdSchema>;
@@ -39,4 +42,7 @@ export type WorkspaceId = z.infer<typeof WorkspaceIdSchema>;
 export type UpdateId = z.infer<typeof UpdateIdSchema>;
 export type WebhookId = z.infer<typeof WebhookIdSchema>;
 export type DocId = z.infer<typeof DocIdSchema>;
+export type TeamId = z.infer<typeof TeamIdSchema>;
+export type DocFolderId = z.infer<typeof DocFolderIdSchema>;
+export type DocBlockId = z.infer<typeof DocBlockIdSchema>;
 //# sourceMappingURL=ids.d.ts.map

package/dist/types/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/types/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD,eAAO,MAAM,aAAa,mDAAqC,CAAC;AAChE,eAAO,MAAM,YAAY,kDAAoC,CAAC;AAC9D,eAAO,MAAM,YAAY,kDAAoC,CAAC;AAC9D,eAAO,MAAM,iBAAiB,uDAAyC,CAAC;AACxE,eAAO,MAAM,cAAc,oDAAsC,CAAC;AAClE,eAAO,MAAM,eAAe,qDAAuC,CAAC;AAOpE,eAAO,MAAM,WAAW,iDAAmC,CAAC;AAI5D,eAAO,MAAM,cAAc,oDAAmC,CAAC;AAC/D,eAAO,MAAM,aAAa,mDAAkC,CAAC;AAE7D,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/types/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiCxB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD,eAAO,MAAM,aAAa,mDAAqC,CAAC;AAChE,eAAO,MAAM,YAAY,kDAAoC,CAAC;AAC9D,eAAO,MAAM,YAAY,kDAAoC,CAAC;AAC9D,eAAO,MAAM,iBAAiB,uDAAyC,CAAC;AACxE,eAAO,MAAM,cAAc,oDAAsC,CAAC;AAClE,eAAO,MAAM,eAAe,qDAAuC,CAAC;AAOpE,eAAO,MAAM,WAAW,iDAAmC,CAAC;AAQ5D,eAAO,MAAM,YAAY,kDAAoC,CAAC;AAS9D,eAAO,MAAM,iBAAiB,uDAAyC,CAAC;AAIxE,eAAO,MAAM,cAAc,oDAAmC,CAAC;AAC/D,eAAO,MAAM,aAAa,mDAAkC,CAAC;AAc7D,eAAO,MAAM,gBAAgB,sDAAqC,CAAC;AAEnE,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/types/ids.js

@@ -1,16 +1,26 @@
 import { z } from 'zod';
 /**
- * Branded zod schemas for the nine ID kinds Monday surfaces (M32
- * adds `DocId` alongside the eight v0.1+M27 brands). Brands make
+ * Branded zod schemas for the twelve ID kinds Monday surfaces
+ * (v0.5-M36 adds `DocBlockId` alongside the v0.5-M35 `DocFolderId`,
+ * the v0.5-M34 `TeamId`, and nine v0.1+M27+M32 brands). Brands make
  * `BoardId`/`ItemId`/etc. nominally distinct at the type level even
- * though they're all numeric strings on the wire — passing a
- * `BoardId` where an `ItemId` is wanted becomes a compile error,
- * which is the whole point.
+ * though most are numeric strings on the wire — passing a `BoardId`
+ * where an `ItemId` is wanted becomes a compile error, which is the
+ * whole point.
  *
  * Monday's numeric IDs exceed `Number.MAX_SAFE_INTEGER` for older
  * accounts, so we keep them as decimal strings everywhere — argv
  * already arrives as strings, GraphQL responses already arrive as
  * strings, and the wire format stays stable through the CLI.
+ *
+ * Three ID kinds are non-numeric (opaque string IDs): `ColumnId`,
+ * `GroupId`, and `DocBlockId`. These use a non-empty-string base
+ * regex (`slugIdSchema`) rather than the numeric `^\d+$` regex.
+ * Column IDs and group IDs are lower-snake-case slugs (`status_4`,
+ * `topics`); doc-block IDs are opaque strings minted by Monday's
+ * workdocs surface — pin only "non-empty" at the brand boundary so
+ * the type system catches absence without mis-matching Monday's
+ * actual character class (UUID, base62, or any other future shape).
  */
 const numericIdSchema = z
     .string()
@@ -53,8 +63,39 @@ export const WebhookIdSchema = numericIdSchema.brand();
 // `BoardId`/`ItemId`/etc. so the type system catches an `--workspace
 // <did>` slip at compile time.
 export const DocIdSchema = numericIdSchema.brand();
+// M34 (v0.5) — team writer surface (`monday user team-*`). Monday's
+// `Team.id` is `ID!` on the wire (numeric on every observed account
+// at API `2026-01`; empirical probe at `scripts/probe/v0.5-team-
+// mutations.ts` 2026-05-15). Brand keeps `TeamId` distinct from
+// `UserId` so the type system catches a `--users <tid>` slip at
+// compile time (an easy mistake to make against `team-add-members
+// <tid> --users <id,...>` where both args are numeric).
+export const TeamIdSchema = numericIdSchema.brand();
+// M35 (v0.5) — doc-level CRUD surface (`monday doc create-in-
+// workspace --folder <fid>`). Monday's `Document.doc_folder_id` is
+// `ID, nullable` on the wire (M32 probe) + `CreateDocWorkspaceInput.
+// folder_id` accepts the same `ID` shape. Brand keeps `DocFolderId`
+// distinct from `WorkspaceId` so the type system catches a slip at
+// the `create-in-workspace --workspace <wid> --folder <fid>` call
+// site at compile time (both args are numeric IDs but address
+// distinct Monday entities — workspace vs nested-folder).
+export const DocFolderIdSchema = numericIdSchema.brand();
 // Column and group IDs are stable lower-snake-case slugs ("status_4",
 // "topics") — not numeric. Validate as non-empty strings only.
 export const ColumnIdSchema = slugIdSchema.brand();
 export const GroupIdSchema = slugIdSchema.brand();
+// M36 (v0.5) — per-block CRUD surface (`monday doc block-create` /
+// `block-update` / `block-delete`). Monday's `DocumentBlock.id` is
+// `String!` on the wire (NOT `ID` — empirical probe at
+// `scripts/probe/v0.5-doc-mutations.ts` + `v0.5-inputs-and-results.ts`
+// 2026-05-15; the same `String!` shape applies to the `block_id`
+// arg slot on `update_doc_block` / `delete_doc_block` and to
+// `DocumentBlockIdOnly.id`). The block IDs Monday mints are opaque
+// — UUID-shaped in practice today, but the wire contract pins only
+// "non-empty string", so the brand uses `slugIdSchema` like
+// `ColumnId` / `GroupId` rather than the numeric `^\d+$` regex.
+// Distinct from `DocId` (numeric — wire `ID!`) so the type system
+// catches a `--parent <did>` slip at compile time (e.g.
+// `block-create <docId> --parent <bidNotDid>`).
+export const DocBlockIdSchema = slugIdSchema.brand();
 //# sourceMappingURL=ids.js.map

package/dist/types/ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/types/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,MAAM,eAAe,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,KAAK,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAEzD,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE;IACrC,OAAO,EAAE,yBAAyB;CACnC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC,KAAK,EAAa,CAAC;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,EAAY,CAAC;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,EAAY,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC,KAAK,EAAiB,CAAC;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC,KAAK,EAAc,CAAC;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC,KAAK,EAAe,CAAC;AACpE,uEAAuE;AACvE,gEAAgE;AAChE,mEAAmE;AACnE,0DAA0D;AAC1D,qEAAqE;AACrE,+BAA+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,EAAW,CAAC;AAE5D,sEAAsE;AACtE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC,KAAK,EAAc,CAAC;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,EAAa,CAAC"}
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/types/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,eAAe,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,KAAK,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAEzD,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE;IACrC,OAAO,EAAE,yBAAyB;CACnC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC,KAAK,EAAa,CAAC;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,EAAY,CAAC;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,EAAY,CAAC;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC,KAAK,EAAiB,CAAC;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC,KAAK,EAAc,CAAC;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC,KAAK,EAAe,CAAC;AACpE,uEAAuE;AACvE,gEAAgE;AAChE,mEAAmE;AACnE,0DAA0D;AAC1D,qEAAqE;AACrE,+BAA+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,EAAW,CAAC;AAC5D,oEAAoE;AACpE,oEAAoE;AACpE,iEAAiE;AACjE,gEAAgE;AAChE,gEAAgE;AAChE,kEAAkE;AAClE,wDAAwD;AACxD,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC,KAAK,EAAY,CAAC;AAC9D,8DAA8D;AAC9D,mEAAmE;AACnE,qEAAqE;AACrE,oEAAoE;AACpE,mEAAmE;AACnE,kEAAkE;AAClE,8DAA8D;AAC9D,0DAA0D;AAC1D,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC,KAAK,EAAiB,CAAC;AAExE,sEAAsE;AACtE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC,KAAK,EAAc,CAAC;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,EAAa,CAAC;AAC7D,mEAAmE;AACnE,mEAAmE;AACnE,uDAAuD;AACvD,uEAAuE;AACvE,iEAAiE;AACjE,6DAA6D;AAC7D,mEAAmE;AACnE,mEAAmE;AACnE,4DAA4D;AAC5D,gEAAgE;AAChE,kEAAkE;AAClE,wDAAwD;AACxD,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,KAAK,EAAgB,CAAC"}

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

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

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

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

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

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

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

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

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

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

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

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