@knowttl/mg-axi 0.1.0

package/dist/entra-group-lifecycle.js

@@ -0,0 +1,349 @@
+import { AxiError } from "axi-sdk-js";
+// EXT-01 group lifecycle subfamily: the read mapping behind
+// `mg-axi entra group-lifecycle-policy list/show/count` and
+// `mg-axi entra group-setting-template list/show/count`. Operation
+// construction stays beside its command; the shared session owns URLs,
+// credentials, paging, retries and error translation, and the SDK owns TOON
+// rendering. This module only maps flags to session calls and projects rows
+// for compact output.
+//
+// Reviewed against the v1.0 grouplifecyclepolicy-list,
+// grouplifecyclepolicy-get, groupsettingtemplate-list,
+// groupsettingtemplate-get and groupsettingtemplate resource documentation
+// on 2026-10-05. Lifecycle-policy reads take D/A Directory.Read.All; the
+// operation pages state no delegated role prerequisite and no P1/P2
+// prerequisite. Setting-template reads take D/A GroupSettings.Read.All;
+// delegated callers additionally need a supported Entra role (Directory
+// Readers or Global Reader are the least-privileged roles). Personal
+// Microsoft accounts are not supported on either family, and no P1/P2
+// prerequisite is stated for either. Lifecycle-policy lists document the
+// general OData query parameters, so --filter passes through as plain
+// $filter with no $count or ConsistencyLevel contract. Template lists
+// document $select only ($filter is not supported), so the template list
+// offers no --filter. The $count routes carry no operation-level
+// documentation page and take no --filter/--select/--limit/--cursor.
+// groupSettingTemplates/delta() stays out: delta-token sync needs its own
+// paging and change-tracking contract. Beta policies and templates and the
+// POST lookup actions (getByIds, validateProperties, membership checks)
+// belong to later EXT-01 subfamilies. No lifecycle or template mutation
+// exists in this slice.
+// Every lifecycle-policy property this slice may request or display,
+// matching the reviewed resource. Anything else fails before credentials.
+export const KNOWN_LIFECYCLE_FIELDS = [
+    "id",
+    "alternateNotificationEmails",
+    "groupLifetimeInDays",
+    "managedGroupTypes",
+];
+const KNOWN_LIFECYCLE = new Set(KNOWN_LIFECYCLE_FIELDS);
+// Every setting-template property this slice may request or display,
+// matching the reviewed resource. Anything else fails before credentials.
+export const KNOWN_TEMPLATE_FIELDS = [
+    "id",
+    "deletedDateTime",
+    "displayName",
+    "description",
+    "values",
+];
+const KNOWN_TEMPLATES = new Set(KNOWN_TEMPLATE_FIELDS);
+// Compact lifecycle rows: the policy id, the expiry window and the group
+// types the policy governs.
+const DEFAULT_LIFECYCLE_LIST_SELECT = ["id", "groupLifetimeInDays", "managedGroupTypes"];
+// Show rows: the full reviewed lifecycle set.
+const DEFAULT_LIFECYCLE_SHOW_SELECT = [...KNOWN_LIFECYCLE_FIELDS];
+// Compact template rows: the template id and the display name/description
+// that decide which template a setting is built from.
+const DEFAULT_TEMPLATE_LIST_SELECT = ["id", "displayName", "description"];
+// Show rows: the full reviewed template set, including the values
+// collection carrying setting names, types and defaults.
+const DEFAULT_TEMPLATE_SHOW_SELECT = [...KNOWN_TEMPLATE_FIELDS];
+// Delegated defaults are operation-specific; application profiles use their
+// configured .default audience and reject --scopes.
+export const DEFAULT_LIFECYCLE_SCOPES = ["https://graph.microsoft.com/Directory.Read.All"];
+export const DEFAULT_TEMPLATE_SCOPES = ["https://graph.microsoft.com/GroupSettings.Read.All"];
+const TRUNCATE_AT = 500;
+function fieldList(raw, known, knownList, flag, help) {
+    const parts = String(raw)
+        .split(",")
+        .map(part => part.trim())
+        .filter(part => part.length > 0);
+    if (!parts.length)
+        throw new AxiError(`--${flag} needs at least one property`, "VALIDATION_ERROR", [help]);
+    const fields = [];
+    for (const part of parts) {
+        if (!known.has(part)) {
+            throw new AxiError(`Unknown group lifecycle property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known properties: ${knownList.join(", ")}`,
+            ]);
+        }
+        if (!fields.includes(part))
+            fields.push(part);
+    }
+    return fields;
+}
+function scopesFor(flags, defaults, profile, help) {
+    if (profile.mode === "application") {
+        if (flags.scopes !== undefined) {
+            throw new AxiError("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [help, "mg-axi profile show --profile <name>"]);
+        }
+        return undefined;
+    }
+    if (flags.scopes === undefined)
+        return [...defaults];
+    const scopes = String(flags.scopes)
+        .split(",")
+        .map(scope => scope.trim())
+        .filter(scope => scope.length > 0);
+    return scopes;
+}
+function truncateValue(value, full) {
+    const truncate = (text) => full || text.length <= TRUNCATE_AT
+        ? { value: text, truncated: false }
+        : { value: `${text.slice(0, TRUNCATE_AT)}... (truncated, ${text.length} chars total)`, truncated: true };
+    if (typeof value === "string")
+        return truncate(value);
+    if (Array.isArray(value) && value.every(entry => typeof entry === "string")) {
+        const projected = value.map(truncate);
+        return { value: projected.map(entry => entry.value), truncated: projected.some(entry => entry.truncated) };
+    }
+    return { value, truncated: false };
+}
+// Local projection preserves Graph's null/missing distinction: an explicit
+// null stays null, an absent property stays absent and is never synthesized.
+// Template `values` rows are objects, so they pass through untruncated;
+// long descriptions still truncate with a --full escape hatch.
+function project(row, fields, full) {
+    const source = row !== null && typeof row === "object" && !Array.isArray(row) ? row : {};
+    const projected = {};
+    let truncated = false;
+    for (const field of fields) {
+        if (!Object.hasOwn(source, field))
+            continue;
+        const result = truncateValue(source[field], full);
+        projected[field] = result.value;
+        truncated = truncated || result.truncated;
+    }
+    return { row: projected, truncated };
+}
+function selectedFields(flags, known, knownList, defaults, help) {
+    const select = flags.select === undefined ? [...defaults] : fieldList(flags.select, known, knownList, "select", help);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, known, knownList, "fields", help);
+    const missing = fields.find(field => !select.includes(field));
+    if (missing) {
+        throw new AxiError(`--fields ${missing} was not fetched; request it with --select`, "VALIDATION_ERROR", [help]);
+    }
+    return { select, fields };
+}
+function profileHint(profileName) {
+    return `--profile ${shellValue(profileName)}`;
+}
+function shellValue(value) {
+    return /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function fullHint(command, flags, profileName) {
+    const args = Object.entries({ ...flags, profile: profileName, full: true })
+        .map(([name, value]) => value === true ? `--${name}` : `--${name} ${shellValue(String(value))}`);
+    return `mg-axi ${command} ${args.join(" ")}`;
+}
+// Denials carry the session's generic grant/role/licence cause; each
+// operation adds the scope, roles and licensing that actually unlock it,
+// because a 403 alone never says which prerequisite is missing.
+function withGuidance(hints, run) {
+    return run().catch(error => {
+        if (error instanceof AxiError && error.code === "GRAPH_ERROR" && /\(403\)/.test(error.message)) {
+            throw new AxiError(error.message, "GRAPH_ERROR", [...hints, ...error.suggestions]);
+        }
+        throw error;
+    });
+}
+const LIFECYCLE_DENIAL_HINTS = [
+    "Lifecycle-policy reads need Directory.Read.All for delegated or application access; delegated callers pass it as --scopes",
+    "Personal Microsoft accounts are not supported for lifecycle-policy reads",
+    "No delegated role or P1/P2 prerequisite is stated for lifecycle-policy reads; never diagnose role or licence solely from HTTP 403",
+];
+const TEMPLATE_DENIAL_HINTS = [
+    "Setting-template reads need GroupSettings.Read.All plus a supported Entra role for delegated access (Directory Readers or Global Reader are the least-privileged roles), or admin-consented GroupSettings.Read.All for application access",
+    "Personal Microsoft accounts are not supported for setting-template reads",
+    "No P1/P2 prerequisite is stated for setting-template reads; never diagnose licence solely from HTTP 403",
+];
+// Restoring the saved select/filter keeps cursor resumes lossless when
+// --select or --filter is omitted. The lifecycle list passes --filter
+// through as plain $filter with no $count or ConsistencyLevel contract;
+// the template list documents $select only and offers no --filter flag, so
+// strict input validation refuses the flag before credentials instead of
+// forwarding a misleading request.
+function collectionCommon(session, flags, known, knownList, defaults, defaultScopes, operation, help, profile, withFilter) {
+    const cursor = flags.cursor === undefined ? undefined : String(flags.cursor);
+    if (cursor !== undefined && !cursor.trim())
+        throw new AxiError("--cursor needs the opaque cursor from a partial result", "VALIDATION_ERROR", [help]);
+    const saved = cursor === undefined ? undefined : session.cursorQuery(operation, cursor);
+    const { select, fields } = selectedFields(flags, known, knownList, saved?.["$select"] === undefined ? defaults : fieldList(saved["$select"], known, knownList, "select", help), help);
+    const filter = withFilter
+        ? (flags.filter === undefined ? saved?.["$filter"] : String(flags.filter))
+        : undefined;
+    return { cursor, select, fields, scopes: scopesFor(flags, defaultScopes, profile, help), full: flags.full === true, filter };
+}
+function collectArgs(profile, operation, common, flags, help) {
+    const query = { $select: common.select.join(",") };
+    if (common.filter !== undefined)
+        query.$filter = common.filter;
+    const args = { profile, operation, query, scopes: common.scopes };
+    if (common.cursor !== undefined)
+        args.cursor = common.cursor;
+    if (flags.all === true) {
+        if (flags.limit !== undefined)
+            throw new AxiError("--limit and --all cannot be combined", "VALIDATION_ERROR", [help]);
+    }
+    else {
+        args.limit = flags.limit === undefined ? 100 : Number(flags.limit);
+    }
+    return args;
+}
+function resumeHint(profileName) {
+    return `Resume losslessly with the same flags plus --cursor <cursor-from-output> ${profileHint(profileName)}`;
+}
+function policyId(flags, help) {
+    const id = String(flags.id);
+    if (!id.trim())
+        throw new AxiError("--id needs the lifecycle policy identifier", "VALIDATION_ERROR", [help]);
+    return id;
+}
+function templateId(flags, help) {
+    const id = String(flags.id);
+    if (!id.trim())
+        throw new AxiError("--id needs the setting template identifier", "VALIDATION_ERROR", [help]);
+    return id;
+}
+function singleResult(raw, fields, full, kind) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError(`Graph returned a malformed ${kind} body`, "GRAPH_ERROR", [
+            `Single-${kind} reads carry one ${kind} object; treat anything else as unknown, not empty`,
+        ]);
+    }
+    return project(raw, fields, full);
+}
+export async function listLifecyclePolicies(session, flags, profile, operation, help, profileName) {
+    const common = collectionCommon(session, flags, KNOWN_LIFECYCLE, KNOWN_LIFECYCLE_FIELDS, DEFAULT_LIFECYCLE_LIST_SELECT, DEFAULT_LIFECYCLE_SCOPES, operation, help, profile, true);
+    const result = await withGuidance(LIFECYCLE_DENIAL_HINTS, () => session.collect(collectArgs(profile, operation, common, flags, help)));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_LIFECYCLE_LIST_SELECT.join(",") };
+    if (result.query.$filter !== undefined)
+        effectiveFlags.filter = result.query.$filter;
+    const policies = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, common.fields, common.full);
+        policies.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra group-lifecycle-policy show --id <policy-id> ${profileHint(profileName)}`;
+    const truncationHints = truncated ? [fullHint("entra group-lifecycle-policy list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            groupLifecyclePolicies: policies,
+            count: { returned: policies.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resumeHint(profileName), showHint],
+        };
+    }
+    const count = { returned: policies.length, complete: true };
+    if (!policies.length) {
+        return {
+            groupLifecyclePolicies: policies,
+            count,
+            help: ["0 lifecycle policies matched; the absence of results is the answer, not an error"],
+        };
+    }
+    return { groupLifecyclePolicies: policies, count, help: [...truncationHints, showHint] };
+}
+export async function showLifecyclePolicy(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, KNOWN_LIFECYCLE, KNOWN_LIFECYCLE_FIELDS, DEFAULT_LIFECYCLE_SHOW_SELECT, help);
+    const scopes = scopesFor(flags, DEFAULT_LIFECYCLE_SCOPES, profile, help);
+    const full = flags.full === true;
+    const raw = await withGuidance(LIFECYCLE_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "groupLifecyclePolicy-id": policyId(flags, help) },
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full, "lifecycle policy");
+    if (truncated)
+        return { groupLifecyclePolicy: row, help: [fullHint("entra group-lifecycle-policy show", flags, profileName)] };
+    return { groupLifecyclePolicy: row };
+}
+// The $count route returns a text/plain integer scalar rather than a JSON
+// collection, so the leaf reads it through session.execute and accepts only
+// a non-negative integer. There is no --filter/--select/--limit contract on
+// the count: the catalogue declares no such flags and strict input
+// validation refuses them before credentials.
+export async function countLifecyclePolicies(session, flags, profile, operation, help, profileName) {
+    void profileName;
+    const scopes = scopesFor(flags, DEFAULT_LIFECYCLE_SCOPES, profile, help);
+    const raw = await withGuidance(LIFECYCLE_DENIAL_HINTS, () => session.execute({ profile, operation, scopes }));
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new AxiError("Graph returned a malformed lifecycle-policy count body", "GRAPH_ERROR", [
+            "Lifecycle-policy counts carry one non-negative integer scalar; treat anything else as unknown, not empty",
+        ]);
+    }
+    return { groupLifecyclePolicyCount: raw };
+}
+export async function listSettingTemplates(session, flags, profile, operation, help, profileName) {
+    const common = collectionCommon(session, flags, KNOWN_TEMPLATES, KNOWN_TEMPLATE_FIELDS, DEFAULT_TEMPLATE_LIST_SELECT, DEFAULT_TEMPLATE_SCOPES, operation, help, profile, false);
+    const result = await withGuidance(TEMPLATE_DENIAL_HINTS, () => session.collect(collectArgs(profile, operation, common, flags, help)));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_TEMPLATE_LIST_SELECT.join(",") };
+    const templates = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, common.fields, common.full);
+        templates.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra group-setting-template show --id <template-id> ${profileHint(profileName)}`;
+    const filterNote = "Template lists offer no --filter: Graph documents $select only for /groupSettingTemplates";
+    const truncationHints = truncated ? [fullHint("entra group-setting-template list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            groupSettingTemplates: templates,
+            count: { returned: templates.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resumeHint(profileName), showHint, filterNote],
+        };
+    }
+    const count = { returned: templates.length, complete: true };
+    if (!templates.length) {
+        return {
+            groupSettingTemplates: templates,
+            count,
+            help: [filterNote, "0 setting templates matched; the absence of results is the answer, not an error"],
+        };
+    }
+    return { groupSettingTemplates: templates, count, help: [...truncationHints, showHint, filterNote] };
+}
+export async function showSettingTemplate(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, KNOWN_TEMPLATES, KNOWN_TEMPLATE_FIELDS, DEFAULT_TEMPLATE_SHOW_SELECT, help);
+    const scopes = scopesFor(flags, DEFAULT_TEMPLATE_SCOPES, profile, help);
+    const full = flags.full === true;
+    const raw = await withGuidance(TEMPLATE_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "groupSettingTemplate-id": templateId(flags, help) },
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full, "setting template");
+    if (truncated)
+        return { groupSettingTemplate: row, help: [fullHint("entra group-setting-template show", flags, profileName)] };
+    return { groupSettingTemplate: row };
+}
+export async function countSettingTemplates(session, flags, profile, operation, help, profileName) {
+    void profileName;
+    const scopes = scopesFor(flags, DEFAULT_TEMPLATE_SCOPES, profile, help);
+    const raw = await withGuidance(TEMPLATE_DENIAL_HINTS, () => session.execute({ profile, operation, scopes }));
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new AxiError("Graph returned a malformed setting-template count body", "GRAPH_ERROR", [
+            "Setting-template counts carry one non-negative integer scalar; treat anything else as unknown, not empty",
+        ]);
+    }
+    return { groupSettingTemplateCount: raw };
+}

package/dist/entra-group-member-add.js

@@ -0,0 +1,278 @@
+import { AxiError } from "axi-sdk-js";
+import { resolveSessionOperation } from "./graph-session.js";
+import { createMutationCoordinator, mutationGraphFault, mutationHttpStatus } from "./mutations.js";
+// WRITE-01: the first named mutation, `mg-axi entra group member add`, behind
+// the WRITE-00 coordinator. One user joins one group through
+// POST /groups/{group-id}/members/$ref with a directoryObjects $ref target.
+//
+// Reviewed against the v1.0 group-post-members operation documentation on
+// 2026-10-04. Success is 204 No Content with an empty body. Graph returns
+// 400 when the object is already a member, when the member type is
+// unsupported, or when a recently created group has not finished replicating
+// ("the source resource object or one of the objects being referenced don't
+// exist" - retry later as a new command, never by replaying the intent).
+// It returns 404 when the referenced object does not exist and 403 for
+// unmanageable group types, missing permission, or role-assignable groups
+// without role-management grants. Only the already-member 400 is a no-op;
+// every other 400 stays a failure.
+//
+// Supported scope is deliberately narrow: non-role-assignable security and
+// Microsoft 365 groups, user members only. User members take D/A
+// GroupMember.ReadWrite.All; every other member type needs additional
+// permissions and belongs to WRITE-N, never to this slice. Delegated callers
+// additionally need an Entra role carrying
+// microsoft.directory/groups/members/update (least-privileged choices include
+// group owner, Directory Writers, Groups Administrator, Identity Governance
+// Administrator and User Administrator). Role-assignable groups need
+// RoleManagement.ReadWrite.Directory plus Privileged Role Administrator and
+// are refused before sending, as are dynamic-membership and distribution
+// groups, which Graph cannot add members to.
+// Profile write-scope operation name. Hand-edit this exact string into the
+// profile's writes.operations allowlist; no command writes that object.
+export const GROUP_MEMBER_ADD_OPERATION = "mg.entra.group.member.add";
+// The only delegated scope this slice requests for the mutation itself.
+export const GROUP_MEMBER_ADD_SCOPES = ["https://graph.microsoft.com/GroupMember.ReadWrite.All"];
+// Preview reads travel the READ-02 route with its standard read scope.
+const PREVIEW_SCOPES = ["https://graph.microsoft.com/GroupMember.Read.All"];
+const GROUP_SELECT = [
+    "id",
+    "displayName",
+    "isAssignableToRole",
+    "securityEnabled",
+    "groupTypes",
+    "mailEnabled",
+    "membershipRule",
+    "membershipRuleProcessingState",
+];
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function fail(message, code, suggestions) {
+    throw new AxiError(message, code, suggestions);
+}
+function groupRef(groupId) {
+    return `https://graph.microsoft.com/v1.0/groups/${groupId}`;
+}
+function memberRef(userId) {
+    return `https://graph.microsoft.com/v1.0/directoryObjects/${userId}`;
+}
+function executeHint(groupId, userId, profileName) {
+    return `mg-axi entra group member add --group ${groupId} --user ${userId} --profile ${profileName} --execute --confirm ${groupId}`;
+}
+function readBackHint(groupId, profileName) {
+    return `mg-axi entra group member list --group ${groupId} --profile ${profileName}`;
+}
+// Pre-send target refusal. Runs inside the preview read so the group is
+// rechecked on the fresh read before the single send. An initial refusal
+// journals nothing; a refusal after intent reservation records NOT_SENT.
+function assertGroupWritable(group, groupId) {
+    if (group === null || typeof group !== "object" || Array.isArray(group)) {
+        fail("Graph returned a malformed group body", "GRAPH_ERROR", [
+            "Single-group reads carry one group object; treat anything else as unknown, not empty",
+        ]);
+    }
+    const row = group;
+    if (row["isAssignableToRole"] === true) {
+        fail(`Refusing role-assignable group ${groupId}: this command adds users to non-role-assignable groups only`, "OPERATION_BLOCKED", [
+            "Role-assignable membership needs RoleManagement.ReadWrite.Directory and Privileged Role Administrator; that grant belongs to a later slice, never to this command",
+            "Verify the group with mg-axi entra group show --id <group-id>",
+        ]);
+    }
+    if (row["isAssignableToRole"] !== false && row["isAssignableToRole"] !== null) {
+        fail(`Refusing group ${groupId}: its role-assignable state is unknown`, "OPERATION_BLOCKED", [
+            "Read back the group with mg-axi entra group show --id <group-id> before doing anything else",
+        ]);
+    }
+    if (typeof row["membershipRule"] === "string" && row["membershipRule"].trim() !== "") {
+        fail(`Refusing dynamic-membership group ${groupId}: members come from its rule, not manual adds`, "OPERATION_BLOCKED", [
+            "Manage membership through the group's membershipRule instead",
+        ]);
+    }
+    const groupTypes = Array.isArray(row["groupTypes"]) ? row["groupTypes"] : [];
+    if (row["securityEnabled"] !== true && !groupTypes.includes("Unified")) {
+        fail(`Refusing group ${groupId}: Graph manages members of security and Microsoft 365 groups only`, "OPERATION_BLOCKED", [
+            "Verify the group with mg-axi entra group show --id <group-id>",
+        ]);
+    }
+    return { id: groupId, displayName: row["displayName"] };
+}
+function isDuplicateReference(error) {
+    if (mutationHttpStatus(error) !== 400)
+        return false;
+    const fault = mutationGraphFault(error);
+    return fault !== null && /already exist/i.test(`${fault.code} ${fault.message}`);
+}
+function failedResult(status, groupId, userId, profileName) {
+    const readBack = readBackHint(groupId, profileName);
+    if (status === 400) {
+        fail(`Graph refused the membership add (400) without applying it`, "GRAPH_ERROR", [
+            "Verify the user object ID exists: an unknown user reports 404, while an unsupported member type or an unreplicated recently created group reports 400",
+            "If the group was created moments ago, wait for replication and retry as a new command with a new intent; never replay a reserved intent",
+            readBack,
+        ]);
+    }
+    if (status === 403) {
+        fail(`Graph denied the membership add (403): the grant, role, licence or policy prerequisite is missing and Graph does not say which`, "GRAPH_ERROR", [
+            "User members need D/A GroupMember.ReadWrite.All; other member types need additional permissions and belong to a later slice",
+            "Delegated callers additionally need an Entra role with microsoft.directory/groups/members/update (for example Groups Administrator, User Administrator, Directory Writers, Identity Governance Administrator, or group owner)",
+            "A 403 never proves which prerequisite is missing; do not retry blindly",
+            readBack,
+        ]);
+    }
+    if (status === 404) {
+        fail(`Graph reports the group or user as not found or inaccessible (404); Graph does not distinguish missing from hidden`, "GRAPH_ERROR", [
+            "Verify both object IDs; --user takes the user object ID, never a UPN",
+            readBack,
+        ]);
+    }
+    fail(`Graph membership add returned status ${status}`, "GRAPH_ERROR", [
+        `Read back the membership with ${readBack} before doing anything else; never replay this intent`,
+    ]);
+}
+export async function addGroupMember(args) {
+    const { session, profile, delegated, application, transport, flags, profileName, help } = args;
+    // Strict flag validation runs before any credential or HTTP.
+    const apiVersion = String(flags["api-version"] ?? "v1.0");
+    if (apiVersion !== "v1.0") {
+        fail(`No reviewed ${apiVersion} membership write: this command binds to v1.0 only`, "VALIDATION_ERROR", [help]);
+    }
+    const groupId = String(flags.group ?? "").trim();
+    if (!groupId)
+        fail("--group needs the group object ID", "VALIDATION_ERROR", [help]);
+    const userId = String(flags.user ?? "").trim();
+    if (!userId)
+        fail("--user needs the user object ID", "VALIDATION_ERROR", [help]);
+    if (!GUID.test(groupId)) {
+        fail(`--group ${groupId} is not a group object ID`, "VALIDATION_ERROR", [help, "Pass the group object ID (GUID); names and mail addresses are not accepted"]);
+    }
+    if (!GUID.test(userId)) {
+        fail(`--user ${userId} is not a user object ID`, "VALIDATION_ERROR", [help, "Pass the user object ID (GUID); UPNs are not resolved by this command"]);
+    }
+    if (profile.mode === "application" && flags.scopes !== undefined) {
+        fail("Application profiles use the configured Graph .default audience; delegated scopes are unavailable", "VALIDATION_ERROR", [
+            help,
+            "mg-axi profile show --profile <name>",
+        ]);
+    }
+    let writeScopes;
+    if (profile.mode === "delegated") {
+        if (flags.scopes === undefined)
+            writeScopes = [...GROUP_MEMBER_ADD_SCOPES];
+        else {
+            writeScopes = String(flags.scopes).split(",").map(scope => scope.trim()).filter(scope => scope.length > 0);
+            if (!writeScopes.length)
+                fail("--scopes needs at least one Graph scope", "VALIDATION_ERROR", [help]);
+        }
+    }
+    const readScopes = profile.mode === "delegated" ? [...PREVIEW_SCOPES] : undefined;
+    const userReadScopes = profile.mode === "delegated" ? ["https://graph.microsoft.com/User.ReadBasic.All"] : undefined;
+    const groupOperation = resolveSessionOperation("v1.0", "GET", "/groups/{group-id}");
+    const userOperation = resolveSessionOperation("v1.0", "GET", "/users/{user-id}");
+    const membersOperation = resolveSessionOperation("v1.0", "GET", "/groups/{group-id}/members");
+    // Desired-state read through the READ-02 route. An incomplete page window
+    // cannot prove absence, so a missed member proceeds to the POST and lands
+    // as a duplicate no-op instead of a failure.
+    const readState = async () => {
+        const group = await session.execute({
+            profile,
+            operation: groupOperation,
+            params: { "group-id": groupId },
+            query: { $select: GROUP_SELECT.join(",") },
+            scopes: readScopes,
+        });
+        const writable = assertGroupWritable(group, groupId);
+        const user = await session.execute({
+            profile,
+            operation: userOperation,
+            params: { "user-id": userId },
+            query: { $select: "id" },
+            scopes: userReadScopes,
+        });
+        const userRow = user;
+        if (userRow === null || typeof userRow !== "object" || Array.isArray(userRow)
+            || typeof userRow["id"] !== "string" || userRow["id"].toLowerCase() !== userId.toLowerCase()
+            || (userRow["@odata.type"] !== undefined && userRow["@odata.type"] !== "#microsoft.graph.user")) {
+            fail(`Graph did not establish user identity for ${userId}`, "GRAPH_ERROR", [
+                "Verify --user is an accessible user object ID; non-user objects cannot be added by this command",
+            ]);
+        }
+        const collected = await session.collect({
+            profile,
+            operation: membersOperation,
+            params: { "group-id": groupId },
+            query: { $select: "id" },
+            scopes: readScopes,
+        });
+        const wanted = userId.toLowerCase();
+        let alreadyMember = false;
+        let checked = 0;
+        for (const row of collected.value) {
+            if (row === null || typeof row !== "object" || Array.isArray(row))
+                continue;
+            const id = row["id"];
+            checked += 1;
+            if (typeof id === "string" && id.toLowerCase() === wanted)
+                alreadyMember = true;
+        }
+        return { group: writable, membersChecked: checked, membersComplete: collected.complete, alreadyMember };
+    };
+    const coordinator = createMutationCoordinator({
+        profile,
+        delegated,
+        application,
+        transport,
+        ...(args.clock === undefined ? {} : { clock: args.clock }),
+        ...(args.journalPath === undefined ? {} : { journalPath: args.journalPath }),
+    });
+    const definition = {
+        operation: GROUP_MEMBER_ADD_OPERATION,
+        method: "POST",
+        version: "v1.0",
+        path: `/v1.0/groups/${groupId}/members/$ref`,
+        effect: "disruptive",
+        target: groupId,
+        payload: { "@odata.id": memberRef(userId) },
+    };
+    const result = await coordinator.execute(definition, {
+        ...(flags.execute === true ? { execute: true } : {}),
+        ...(flags.confirm === undefined ? {} : { confirm: String(flags.confirm) }),
+        ...(writeScopes === undefined ? {} : { scopes: writeScopes }),
+        readState,
+        isNoop: current => current.alreadyMember === true,
+        isDuplicate: isDuplicateReference,
+    });
+    const membership = { group: groupRef(groupId), user: memberRef(userId) };
+    if (result.kind === "dry-run") {
+        return {
+            membership: { ...membership, status: "preview" },
+            preview: result.preview,
+            help: [executeHint(groupId, userId, profileName), readBackHint(groupId, profileName)],
+        };
+    }
+    if (result.kind === "noop") {
+        if (result.duplicate === true) {
+            return {
+                membership: { ...membership, status: "already-member" },
+                noop: true,
+                auditId: result.auditId,
+                note: "Graph reported the membership already exists; no change was made",
+            };
+        }
+        return { membership: { ...membership, status: "already-member" }, noop: true };
+    }
+    if (result.kind === "success") {
+        return {
+            membership: { ...membership, status: "added" },
+            auditId: result.auditId,
+            help: [readBackHint(groupId, profileName)],
+        };
+    }
+    if (result.kind === "failed") {
+        failedResult(result.status, groupId, userId, profileName);
+    }
+    return {
+        membership: { ...membership, status: "unknown" },
+        auditId: result.auditId,
+        httpStatus: result.httpStatus,
+        guidance: result.guidance,
+        help: [readBackHint(groupId, profileName)],
+    };
+}