@knowttl/mg-axi 0.1.0

package/dist/entra-user-revoke-sessions.js

@@ -0,0 +1,170 @@
+import { AxiError } from "axi-sdk-js";
+import { encodeGraphPathSegment } from "./graph-session.js";
+// WRITE-03: revoke one user's sign-in sessions through an action write leaf
+// (`mg-axi entra user revoke-sessions --user <id>`), via
+// POST /users/{id}/revokeSignInSessions with no request body. Graph resets
+// the user's signInSessionsValidFromDateTime, invalidating issued refresh
+// tokens and browser session cookies so the user must sign in again, and
+// normally answers 2xx with {"value": true}; acceptance is based on status,
+// not response-body validation, so
+// unlike the 204 account update there is no verification reread.
+//
+// Reviewed against the v1.0 user-revokeSignInSessions operation
+// documentation on REVIEWED_ON. The least-privileged permission is
+// User.RevokeSessions.All in both delegated and application modes; the
+// documentation names no administrator-role prerequisite for this action, so
+// denial guidance names only the action permission. This is an action, not a
+// desired-state write: the preview says what will happen and that it cannot
+// be undone (there is no rollback), never a state diff. Two Microsoft-stated
+// limits ride along in the preview: token revocation can lag a few minutes
+// after the call returns, and external users are unaffected because they
+// sign in through their home tenant. A timeout or 5xx after send is
+// OUTCOME_UNKNOWN with no automatic replay. Every gate in src/mutations.ts
+// stays in force through the coordinator: hand-enabled profile, immutable
+// scope, preview, --execute, typed confirmation, durable journal
+// intent/outcome, no replay, coordinator-only authorization and read-only
+// enforced at send time.
+export const REVIEWED_ON = "2026-10-04";
+// Scope name a profile hand-enables in its writes.operations allowlist.
+export const USER_REVOKE_SESSIONS_OPERATION = "entra.user.revokeSessions";
+export const USER_REVOKE_SESSIONS_SCOPES = [
+    "https://graph.microsoft.com/User.RevokeSessions.All",
+];
+export const USER_REVOKE_READ_SCOPES = ["https://graph.microsoft.com/User.ReadBasic.All"];
+const PERMISSION_GUIDANCE = "Needs D/A User.RevokeSessions.All (least-privileged per user-revokeSignInSessions v1.0, rechecked 2026-10-04)";
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function userRevokeSessionsDefinition(user) {
+    const target = user.trim();
+    return {
+        operation: USER_REVOKE_SESSIONS_OPERATION,
+        method: "POST",
+        version: "v1.0",
+        path: `/v1.0/users/${encodeGraphPathSegment(target)}/revokeSignInSessions`,
+        effect: "disruptive",
+        target,
+    };
+}
+// The target must be an accessible user before preview and again before the
+// single send; anything else blocks the operation. Returns the bound object
+// ID for the mutation path.
+async function verifyUserTarget(session, profile, readOperation, user) {
+    const raw = await session.execute({
+        profile,
+        operation: readOperation,
+        params: { "user-id": user },
+        query: { $select: "id" },
+        ...(profile.mode === "application" ? {} : { scopes: [...USER_REVOKE_READ_SCOPES] }),
+    });
+    const row = raw;
+    if (row === null || typeof row !== "object" || Array.isArray(row)
+        || typeof row["id"] !== "string" || row["id"].toLowerCase() !== user.toLowerCase()
+        || (row["@odata.type"] !== undefined && row["@odata.type"] !== "#microsoft.graph.user")) {
+        throw new AxiError(`Graph did not establish user identity for ${user}`, "GRAPH_ERROR", [
+            "Verify --user is an accessible user object ID; non-user objects have no sessions to revoke",
+        ]);
+    }
+    return row["id"];
+}
+function executeHint(user, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra user revoke-sessions --user ${shell(user)} --execute`
+        + ` --confirm ${shell(user)}`
+        + ` --profile ${shell(profileName)}`;
+}
+function showHint(user, profileName, profile) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra user show --id ${shell(user)} --profile ${shell(profileName)} --select id`
+        + (profile.mode === "application" ? "" : ` --scopes ${USER_REVOKE_READ_SCOPES.join(",")}`);
+}
+const ACTION_TEXT = "Revoke every sign-in session for the target user: Graph resets signInSessionsValidFromDateTime, "
+    + "invalidating issued refresh tokens and browser session cookies, and the user must sign in again to every consented application.";
+const LIMITATIONS = [
+    "Token revocation can lag a few minutes after the call returns; a 2xx response does not promise immediate universal session termination",
+    "External users are unaffected: they sign in through their home tenant, which this call cannot revoke",
+    "This action cannot be undone; there is no rollback",
+];
+export async function revokeUserSessions(args) {
+    const { session, coordinator, flags, profile, profileName, readOperation, help } = args;
+    const user = String(flags.user ?? "").trim();
+    if (!user)
+        throw new AxiError("--user needs the user object ID", "VALIDATION_ERROR", [help]);
+    if (!GUID.test(user)) {
+        throw new AxiError(`--user ${user} is not a user object ID`, "VALIDATION_ERROR", [
+            help,
+            "Pass the user object ID (GUID); UPNs are not resolved by this command",
+        ]);
+    }
+    const version = String(flags["api-version"] ?? "v1.0");
+    if (version !== "v1.0") {
+        throw new AxiError(`--api-version ${version} cannot mutate: WRITE-03 binds POST /users/{id}/revokeSignInSessions to v1.0; beta writes stay blocked`, "VALIDATION_ERROR", [help]);
+    }
+    if (flags.scopes !== undefined) {
+        throw new AxiError("This command requests only its documented write scope; caller-supplied --scopes is unavailable", "VALIDATION_ERROR", [help, "Delegated revocation requests https://graph.microsoft.com/User.RevokeSessions.All"]);
+    }
+    const requestedDefinition = userRevokeSessionsDefinition(user);
+    const execute = flags.execute === true;
+    // Gates first: preview refuses read-only, unscoped and beta-bound profiles
+    // before any read, credential or transport.
+    coordinator.preview(requestedDefinition);
+    if (execute) {
+        if (flags.confirm === undefined) {
+            throw new AxiError(`blocked: disruptive POST needs --confirm '${requestedDefinition.target}'`, "CONFIRM_REQUIRED", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+        if (String(flags.confirm) !== requestedDefinition.target) {
+            throw new AxiError(`blocked: --confirm '${flags.confirm}' does not match target '${requestedDefinition.target}'`, "CONFIRM_MISMATCH", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+    }
+    const id = await verifyUserTarget(session, profile, readOperation, user);
+    const definition = { ...requestedDefinition, path: `/v1.0/users/${encodeGraphPathSegment(id)}/revokeSignInSessions` };
+    const preview = coordinator.preview(definition);
+    const state = {
+        operation: definition.operation,
+        target: definition.target,
+        method: definition.method,
+        url: preview.url,
+        effect: definition.effect,
+        action: ACTION_TEXT,
+        reversible: false,
+        limitations: [...LIMITATIONS],
+        noop: false,
+    };
+    if (!execute) {
+        return {
+            preview: state,
+            help: [
+                executeHint(user, profileName),
+                `Revoking sessions is disruptive: the --execute run needs the typed --confirm value shown above`,
+                showHint(user, profileName, profile),
+            ],
+        };
+    }
+    const result = await coordinator.execute(definition, {
+        execute: true,
+        confirm: String(flags.confirm),
+        ...(profile.mode === "application" ? {} : { scopes: [...USER_REVOKE_SESSIONS_SCOPES] }),
+        // An action always sends: no desired state exists to satisfy early, and
+        // the fresh read below re-verifies the user before the single send.
+        readState: async () => verifyUserTarget(session, profile, readOperation, id),
+    });
+    if (result.kind === "failed") {
+        throw new AxiError(`Graph refused the session revocation (status ${result.status})`, "GRAPH_ERROR", [
+            ...(result.status === 403 ? [PERMISSION_GUIDANCE] : []),
+            `Audit ${result.auditId} recorded the refusal; read back '${id}' and never replay this intent`,
+        ]);
+    }
+    if (result.kind === "unknown") {
+        throw new AxiError(`Revocation for '${id}' may or may not have been applied (audit ${result.auditId}); never replay this intent`, "OUTCOME_UNKNOWN", [
+            `Audit ${result.auditId} recorded the uncertain outcome; read back '${id}' with ${showHint(id, profileName, profile)} before doing anything else`,
+            "Never replay this intent",
+        ]);
+    }
+    if (result.kind !== "success") {
+        // Unreachable: execute is always true above (no dry-run) and no
+        // desired-state check exists to report a no-op. Fail closed rather than
+        // inventing an outcome.
+        throw new AxiError(`Revocation for '${id}' returned an unexpected outcome; read back the target before doing anything else`, "OUTCOME_UNKNOWN", [
+            "Never replay this intent",
+        ]);
+    }
+    return { user: { id, sessionsRevoked: true }, auditId: result.auditId };
+}

package/dist/entra-user-update.js

@@ -0,0 +1,170 @@
+import { AxiError } from "axi-sdk-js";
+import { encodeGraphPathSegment } from "./graph-session.js";
+// WRITE-02: enable or disable one user's account through a desired-state
+// write leaf (`mg-axi entra user update --user <id> --account-enabled
+// true|false`), via PATCH /users/{id} with only { accountEnabled } sent.
+// Preview reads the current value through the READ-01 user route and shows
+// the diff; an already-desired value is a no-op; after the PATCH a reread
+// reports a conflict when the value is not what was sent.
+//
+// Reviewed against the v1.0 user-update operation documentation on
+// REVIEWED_ON: PATCH /users/{id | userPrincipalName} carries only the
+// properties to update and answers 204 No Content, so the reread is the only
+// proof the change landed. The least-privileged pair for accountEnabled is
+// User.EnableDisableAccount.All plus User.Read.All in both delegated and
+// application modes. Sensitive-target hierarchy: delegated callers need
+// Privileged Authentication Administrator for admin targets and generally
+// must hold a higher-privileged administrator role than the target; app-only
+// callers need the pair plus a higher-privileged admin role assignment (Who
+// can perform sensitive actions). Graph enforces that hierarchy and a 403
+// never says which prerequisite is missing, so this module surfaces the pair
+// and the hierarchy as denial guidance and never invents a local role
+// verdict. Every gate in src/mutations.ts stays in force through the
+// coordinator: hand-enabled profile, immutable scope, preview, --execute,
+// durable journal intent/outcome, no replay, coordinator-only authorization
+// and read-only enforced at send time.
+export const REVIEWED_ON = "2026-10-04";
+// Scope name a profile hand-enables in its writes.operations allowlist.
+export const USER_ACCOUNT_UPDATE_OPERATION = "entra.user.update";
+export const USER_ACCOUNT_WRITE_SCOPES = [
+    "https://graph.microsoft.com/User.EnableDisableAccount.All",
+    "https://graph.microsoft.com/User.Read.All",
+];
+export const USER_ACCOUNT_READ_SCOPES = ["https://graph.microsoft.com/User.Read.All"];
+const PERMISSION_GUIDANCE = "Needs D/A User.EnableDisableAccount.All plus User.Read.All for accountEnabled (least-privileged pair per user-update v1.0, rechecked 2026-10-04)";
+const ROLE_GUIDANCE = "Sensitive-target hierarchy: delegated callers need Privileged Authentication Administrator for admin targets and must generally outrank the target; app-only callers need the pair plus a higher-privileged admin role assignment (Who can perform sensitive actions)";
+export function parseAccountEnabled(raw, help) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    throw new AxiError("--account-enabled must be true or false", "VALIDATION_ERROR", [help]);
+}
+export function userAccountDefinition(user, desired) {
+    const target = user.trim();
+    return {
+        operation: USER_ACCOUNT_UPDATE_OPERATION,
+        method: "PATCH",
+        version: "v1.0",
+        path: `/v1.0/users/${encodeGraphPathSegment(target)}`,
+        effect: "disruptive",
+        target,
+        payload: { accountEnabled: desired },
+    };
+}
+async function readUserAccount(session, profile, readOperation, user) {
+    const raw = await session.execute({
+        profile,
+        operation: readOperation,
+        params: { "user-id": user },
+        query: { $select: "id,accountEnabled" },
+        ...(profile.mode === "application" ? {} : { scopes: [...USER_ACCOUNT_READ_SCOPES] }),
+    });
+    if (raw !== null && typeof raw === "object" && !Array.isArray(raw) && "id" in raw && typeof raw.id === "string" && raw.id.length > 0) {
+        const value = raw.accountEnabled;
+        // Null, missing or malformed is unverifiable, never a desired state.
+        return { id: raw.id, accountEnabled: typeof value === "boolean" ? value : null };
+    }
+    throw new AxiError("Graph returned a user without an object ID", "GRAPH_ERROR", [
+        "Read back the user before attempting an account update",
+    ]);
+}
+function executeHint(user, desired, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra user update --user ${shell(user)} --account-enabled ${desired} --execute`
+        + ` --confirm ${shell(user)}`
+        + ` --profile ${shell(profileName)}`;
+}
+function showHint(user, profileName) {
+    const shell = (value) => /^[A-Za-z0-9_.,:/@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+    return `mg-axi entra user show --id ${shell(user)} --select id,accountEnabled --profile ${shell(profileName)}`;
+}
+export async function updateUserAccount(args) {
+    const { session, coordinator, flags, profile, profileName, readOperation, help } = args;
+    const user = String(flags.user ?? "").trim();
+    if (!user)
+        throw new AxiError("--user needs a user ID or UPN", "VALIDATION_ERROR", [help]);
+    const desired = parseAccountEnabled(flags["account-enabled"], help);
+    const version = String(flags["api-version"] ?? "v1.0");
+    if (version !== "v1.0") {
+        throw new AxiError(`--api-version ${version} cannot mutate: WRITE-02 binds PATCH /users/{id} to v1.0; beta writes stay blocked`, "VALIDATION_ERROR", [help]);
+    }
+    const requestedDefinition = userAccountDefinition(user, desired);
+    const execute = flags.execute === true;
+    // Gates first: preview refuses read-only, unscoped and beta-bound profiles
+    // before any read, credential or transport.
+    coordinator.preview(requestedDefinition);
+    if (execute) {
+        if (flags.confirm === undefined) {
+            throw new AxiError(`blocked: disruptive PATCH needs --confirm '${requestedDefinition.target}'`, "CONFIRM_REQUIRED", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+        if (String(flags.confirm) !== requestedDefinition.target) {
+            throw new AxiError(`blocked: --confirm '${flags.confirm}' does not match target '${requestedDefinition.target}'`, "CONFIRM_MISMATCH", [`Re-run with --confirm '${requestedDefinition.target}'`]);
+        }
+    }
+    const account = await readUserAccount(session, profile, readOperation, user);
+    const id = account.id;
+    const definition = { ...requestedDefinition, path: `/v1.0/users/${encodeGraphPathSegment(id)}` };
+    const preview = coordinator.preview(definition);
+    const current = account.accountEnabled;
+    const state = {
+        operation: definition.operation,
+        target: definition.target,
+        method: definition.method,
+        url: preview.url,
+        effect: definition.effect,
+        current,
+        desired,
+        noop: current === desired,
+    };
+    if (!execute) {
+        return {
+            preview: state,
+            help: [
+                state.noop
+                    ? "Already in the desired state; no update is needed"
+                    : executeHint(user, desired, profileName),
+                ...(!state.noop
+                    ? ["Changing account access is disruptive: the --execute run needs the typed --confirm value shown above"]
+                    : []),
+            ],
+        };
+    }
+    const result = await coordinator.execute(definition, {
+        execute: true,
+        confirm: String(flags.confirm),
+        ...(profile.mode === "application" ? {} : { scopes: [...USER_ACCOUNT_WRITE_SCOPES] }),
+        readState: async () => (await readUserAccount(session, profile, readOperation, id)).accountEnabled,
+        isNoop: currentState => currentState === desired,
+    });
+    if (result.kind === "failed") {
+        throw new AxiError(`Graph refused the account update (status ${result.status})`, "GRAPH_ERROR", [
+            ...(result.status === 403 ? [PERMISSION_GUIDANCE, ROLE_GUIDANCE] : []),
+            `Audit ${result.auditId} recorded the refusal; read back '${id}' and never replay this intent`,
+        ]);
+    }
+    if (result.kind === "unknown") {
+        throw new AxiError(`Update of '${id}' may or may not have been applied (audit ${result.auditId}); never replay this intent`, "OUTCOME_UNKNOWN", [
+            `Audit ${result.auditId} recorded the uncertain outcome; read back '${id}' with ${showHint(id, profileName)} before doing anything else`,
+            "Never replay this intent",
+        ]);
+    }
+    // Anything but success, failure or uncertainty is the verified no-op:
+    // dry-run needs execute !== true, always set above.
+    if (result.kind !== "success") {
+        return { noop: true, user: { id, accountEnabled: desired } };
+    }
+    // Success carries no proof: user-update answers 204 with an empty body, so
+    // only the reread decides between updated and conflict.
+    let verified;
+    try {
+        verified = (await readUserAccount(session, profile, readOperation, id)).accountEnabled;
+    }
+    catch {
+        throw new AxiError(`Update of '${user}' was sent (audit ${result.auditId}) but the verification read failed; the outcome is unknown`, "OUTCOME_UNKNOWN", [`Read back '${id}' before doing anything else; never replay this intent`]);
+    }
+    if (verified !== desired) {
+        throw new AxiError(`Update of '${user}' conflicts: the reread shows accountEnabled ${verified === null ? "unreadable" : String(verified)} instead of the sent ${String(desired)} (audit ${result.auditId})`, "WRITE_CONFLICT", [`Read back '${id}' with ${showHint(id, profileName)} before doing anything else`, "Never replay this intent"]);
+    }
+    return { user: { id, accountEnabled: desired }, auditId: result.auditId };
+}

package/dist/entra-users.js

@@ -0,0 +1,211 @@
+import { AxiError } from "axi-sdk-js";
+// READ-01: the Entra user read mapping behind `mg-axi entra user list/show`.
+// 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 user-list and user-get operation documentation on
+// 2026-10-04. List and get return the same default property set without
+// $select; accountEnabled is never default and needs User.EnableDisableAccount.All
+// with User.Read.All. Delegated list reads User.ReadBasic.All for basics and
+// User.Read.All for richer data; application reads User.Read.All.
+// Every property this slice may request or display. Anything else fails
+// before credentials so typos never become misleading server queries.
+export const KNOWN_USER_FIELDS = [
+    "businessPhones",
+    "displayName",
+    "givenName",
+    "id",
+    "jobTitle",
+    "mail",
+    "mobilePhone",
+    "officeLocation",
+    "preferredLanguage",
+    "surname",
+    "userPrincipalName",
+    "accountEnabled",
+    "department",
+    "userType",
+];
+const KNOWN = new Set(KNOWN_USER_FIELDS);
+// Compact list rows: identifier, display name and addresses, all
+// readable with basic consent.
+const DEFAULT_LIST_SELECT = ["id", "displayName", "userPrincipalName", "mail"];
+// Show rows: the full default server set, a richer view of the same user.
+const DEFAULT_SHOW_SELECT = [
+    "businessPhones",
+    "displayName",
+    "givenName",
+    "id",
+    "jobTitle",
+    "mail",
+    "mobilePhone",
+    "officeLocation",
+    "preferredLanguage",
+    "surname",
+    "userPrincipalName",
+];
+// Default consent covers the basic list and richer show defaults;
+// accountEnabled additionally needs the permission noted above.
+export const DEFAULT_DELEGATED_SCOPES = ["https://graph.microsoft.com/User.Read.All"];
+const TRUNCATE_AT = 500;
+function fieldList(raw, 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 user property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known user properties: ${KNOWN_USER_FIELDS.join(", ")}`,
+            ]);
+        }
+        if (!fields.includes(part))
+            fields.push(part);
+    }
+    return fields;
+}
+function scopesFor(flags, 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 [...DEFAULT_DELEGATED_SCOPES];
+    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.
+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, defaults, help) {
+    const select = flags.select === undefined ? [...defaults] : fieldList(flags.select, "select", help);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, "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(action, flags, profileName) {
+    const args = Object.entries({ ...flags, profile: profileName, full: true })
+        .map(([name, value]) => value === true ? `--${name}` : `--${name} ${shellValue(String(value))}`);
+    return `mg-axi entra user ${action} ${args.join(" ")}`;
+}
+export async function listUsers(session, flags, profile, operation, help, profileName) {
+    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 savedSelect = cursor === undefined ? undefined : session.cursorQuery(operation, cursor).$select;
+    const { select, fields } = selectedFields(flags, savedSelect === undefined ? DEFAULT_LIST_SELECT : fieldList(savedSelect, "select", help), help);
+    const scopes = scopesFor(flags, profile, help);
+    const full = flags.full === true;
+    const query = { $select: select.join(",") };
+    if (flags.filter !== undefined)
+        query.$filter = String(flags.filter);
+    const args = { profile, operation, query, scopes };
+    if (cursor !== undefined)
+        args.cursor = 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);
+    }
+    const result = await session.collect(args);
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_LIST_SELECT.join(",") };
+    if (result.query.$filter !== undefined)
+        effectiveFlags.filter = result.query.$filter;
+    const users = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, fields, full);
+        users.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra user show --id <user-id-or-upn> ${profileHint(profileName)}`;
+    const truncationHints = truncated ? [fullHint("list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            users,
+            count: { returned: users.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, `Resume losslessly with the same flags plus --cursor <cursor-from-output> ${profileHint(profileName)}`, showHint],
+        };
+    }
+    const count = { returned: users.length, complete: true };
+    if (!users.length) {
+        return {
+            users,
+            count,
+            help: [
+                `mg-axi entra user list --filter <odata-filter> ${profileHint(profileName)}`,
+                "0 users matched; the absence of results is the answer, not an error",
+            ],
+        };
+    }
+    const helpHints = [...truncationHints, showHint];
+    return { users, count, help: helpHints };
+}
+export async function showUser(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, DEFAULT_SHOW_SELECT, help);
+    const scopes = scopesFor(flags, profile, help);
+    const full = flags.full === true;
+    const raw = await session.execute({
+        profile,
+        operation,
+        params: { "user-id": String(flags.id) },
+        query: { $select: select.join(",") },
+        scopes,
+    });
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError("Graph returned a malformed user body", "GRAPH_ERROR", [
+            "Single-user reads carry one user object; treat anything else as unknown, not empty",
+        ]);
+    }
+    const { row, truncated } = project(raw, fields, full);
+    if (truncated)
+        return { user: row, help: [fullHint("show", flags, profileName)] };
+    return { user: row };
+}