@knowttl/mg-axi 0.1.0

package/dist/entra-roles.js

@@ -0,0 +1,310 @@
+import { AxiError } from "axi-sdk-js";
+// READ-09: the Entra directory-role and PIM read mapping behind
+// `mg-axi entra directory-role list/show`, `mg-axi entra role-assignment
+// list`, `mg-axi entra pim eligible list` and `mg-axi entra pim active list`.
+// 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 directoryrole-list, directoryrole-get,
+// rbacapplication-list-roleassignments,
+// rbacapplication-list-roleeligibilityscheduleinstances and
+// rbacapplication-list-roleassignmentscheduleinstances operation
+// documentation on 2026-10-04. Directory-role reads and role
+// assignments read D/A RoleManagement.Read.Directory; eligible PIM reads
+// D/A RoleEligibilitySchedule.Read.Directory; active PIM reads D/A
+// RoleAssignmentSchedule.Read.Directory. Delegated callers additionally need
+// a supported administrator role per operation. None of these collections
+// documents an advanced-query contract, so --filter passes through as plain
+// $filter with no $count or ConsistencyLevel attached.
+//
+// The four views cover: directoryRoles are activated role
+// instances only (a role appears here after activation, never before);
+// roleAssignments include direct and PIM-activated assignments; eligible schedule
+// instances are PIM-eligible but not active; active schedule instances cover
+// both directly assigned (assignmentType Assigned) and activated eligible
+// (assignmentType Activated) assignments. memberType names how the instance
+// reaches the principal (for example Direct). Activation, assignment and
+// every other PIM mutation belongs to later write slices, never to these
+// reads. Built-in roles are base inventory; custom role assignments need P1;
+// PIM reads need P2 or ID Governance.
+// Eligible and active instances need separate reviewed property sets:
+// only active instances expose assignmentType.
+export const KNOWN_ROLE_FIELDS = [
+    "id",
+    "displayName",
+    "description",
+    "roleTemplateId",
+    "deletedDateTime",
+];
+export const KNOWN_ASSIGNMENT_FIELDS = [
+    "id",
+    "principalId",
+    "roleDefinitionId",
+    "directoryScopeId",
+    "appScopeId",
+];
+export const KNOWN_ELIGIBLE_FIELDS = [
+    "id",
+    "principalId",
+    "roleDefinitionId",
+    "directoryScopeId",
+    "appScopeId",
+    "memberType",
+    "startDateTime",
+    "endDateTime",
+];
+export const KNOWN_ACTIVE_FIELDS = [...KNOWN_ELIGIBLE_FIELDS, "assignmentType"];
+const ROLE_KNOWN = new Set(KNOWN_ROLE_FIELDS);
+const ASSIGNMENT_KNOWN = new Set(KNOWN_ASSIGNMENT_FIELDS);
+const ELIGIBLE_KNOWN = new Set(KNOWN_ELIGIBLE_FIELDS);
+const ACTIVE_KNOWN = new Set(KNOWN_ACTIVE_FIELDS);
+// Compact rows: identifiers plus the correlation keys. For built-in roles
+// the unified roleDefinitionId matches the directory-role roleTemplateId.
+const DEFAULT_ROLE_LIST_SELECT = ["id", "displayName", "description", "roleTemplateId"];
+const DEFAULT_ROLE_SHOW_SELECT = [...KNOWN_ROLE_FIELDS];
+const DEFAULT_ASSIGNMENT_SELECT = ["id", "principalId", "roleDefinitionId", "directoryScopeId"];
+const DEFAULT_ELIGIBLE_SELECT = ["id", "principalId", "roleDefinitionId", "memberType"];
+const DEFAULT_ACTIVE_SELECT = ["id", "principalId", "roleDefinitionId", "assignmentType", "memberType"];
+export const DEFAULT_ROLE_SCOPES = ["https://graph.microsoft.com/RoleManagement.Read.Directory"];
+export const DEFAULT_ELIGIBLE_SCOPES = ["https://graph.microsoft.com/RoleEligibilitySchedule.Read.Directory"];
+export const DEFAULT_ACTIVE_SCOPES = ["https://graph.microsoft.com/RoleAssignmentSchedule.Read.Directory"];
+const TRUNCATE_AT = 500;
+function fieldList(raw, flag, known, knownList, 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 property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known properties: ${knownList.join(", ")}`,
+            ]);
+        }
+        if (!fields.includes(part))
+            fields.push(part);
+    }
+    return fields;
+}
+function scopesFor(flags, profile, defaults, 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) {
+    if (typeof value === "string" && !full && value.length > TRUNCATE_AT) {
+        return { value: `${value.slice(0, TRUNCATE_AT)}... (truncated, ${value.length} chars total)`, truncated: true };
+    }
+    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, known, knownList, help) {
+    const select = flags.select === undefined ? [...defaults] : fieldList(flags.select, "select", known, knownList, help);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, "fields", known, knownList, 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 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 ROLE_DENIAL_HINTS = [
+    "Directory-role reads need RoleManagement.Read.Directory plus a supported directory role (for example Global Reader, Security Reader or Privileged Role Administrator) for delegated access, or admin-consented RoleManagement.Read.Directory for application access",
+    "Built-in roles are base inventory; custom role assignments need P1",
+];
+const ASSIGNMENT_DENIAL_HINTS = [
+    "Role-assignment reads need RoleManagement.Read.Directory plus Directory Readers, Global Reader or Privileged Role Administrator for delegated access, or admin-consented RoleManagement.Read.Directory for application access",
+    "Built-in role assignments are base inventory; custom role assignments need P1",
+];
+const ELIGIBLE_DENIAL_HINTS = [
+    "Eligible PIM reads need RoleEligibilitySchedule.Read.Directory plus Global Reader, Security Operator, Security Reader, Security Administrator or Privileged Role Administrator for delegated access, or admin-consented RoleEligibilitySchedule.Read.Directory for application access",
+    "PIM reads need P2 or ID Governance, not only P2",
+];
+const ACTIVE_DENIAL_HINTS = [
+    "Active PIM reads need RoleAssignmentSchedule.Read.Directory plus Global Reader, Security Operator, Security Reader, Security Administrator or Privileged Role Administrator for delegated access, or admin-consented RoleAssignmentSchedule.Read.Directory for application access",
+    "PIM reads need P2 or ID Governance, not only P2",
+];
+const ROLE_LIST = {
+    command: "entra directory-role list",
+    key: "directoryRoles",
+    known: ROLE_KNOWN,
+    knownList: KNOWN_ROLE_FIELDS,
+    defaultSelect: DEFAULT_ROLE_LIST_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: ROLE_DENIAL_HINTS,
+    scopeNote: "Lists activated roles only; a role appears here after activation, never before",
+    emptyNote: "0 activated roles matched; the absence of results is the answer, not an error",
+};
+const ASSIGNMENT_LIST = {
+    command: "entra role-assignment list",
+    key: "roleAssignments",
+    known: ASSIGNMENT_KNOWN,
+    knownList: KNOWN_ASSIGNMENT_FIELDS,
+    defaultSelect: DEFAULT_ASSIGNMENT_SELECT,
+    defaultScopes: DEFAULT_ROLE_SCOPES,
+    denialHints: ASSIGNMENT_DENIAL_HINTS,
+    scopeNote: "Current role-assignment inventory includes direct and PIM-activated assignments; use pim active list for assignmentType Assigned versus Activated",
+    emptyNote: "0 current role assignments matched; the absence of results is the answer, not an error",
+};
+const PIM_ELIGIBLE = {
+    command: "entra pim eligible list",
+    key: "eligibleAssignments",
+    known: ELIGIBLE_KNOWN,
+    knownList: KNOWN_ELIGIBLE_FIELDS,
+    defaultSelect: DEFAULT_ELIGIBLE_SELECT,
+    defaultScopes: DEFAULT_ELIGIBLE_SCOPES,
+    denialHints: ELIGIBLE_DENIAL_HINTS,
+    scopeNote: "Eligible assignments are not active; activation is a PIM workflow outside these reads",
+    emptyNote: "0 eligible assignments matched; the absence of results is the answer, not an error",
+};
+const PIM_ACTIVE = {
+    command: "entra pim active list",
+    key: "activeAssignments",
+    known: ACTIVE_KNOWN,
+    knownList: KNOWN_ACTIVE_FIELDS,
+    defaultSelect: DEFAULT_ACTIVE_SELECT,
+    defaultScopes: DEFAULT_ACTIVE_SCOPES,
+    denialHints: ACTIVE_DENIAL_HINTS,
+    scopeNote: "Active distinguishes directly assigned (assignmentType Assigned) and activated eligible (assignmentType Activated) assignments",
+    emptyNote: "0 active assignments matched; the absence of results is the answer, not an error",
+};
+async function listCollection(shape, 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 saved = cursor === undefined ? undefined : session.cursorQuery(operation, cursor);
+    const savedSelect = saved?.$select;
+    const { select, fields } = selectedFields(flags, savedSelect === undefined ? shape.defaultSelect : fieldList(savedSelect, "select", shape.known, shape.knownList, help), shape.known, shape.knownList, help);
+    const savedFilter = saved?.$filter;
+    const filter = flags.filter === undefined ? savedFilter : String(flags.filter);
+    const scopes = scopesFor(flags, profile, shape.defaultScopes, help);
+    const full = flags.full === true;
+    // These collections document $select/$filter/$expand only, so --filter
+    // passes through as plain $filter with no $count or ConsistencyLevel.
+    const query = { $select: select.join(",") };
+    if (filter !== undefined)
+        query.$filter = 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 withGuidance(shape.denialHints, () => session.collect(args));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? shape.defaultSelect.join(",") };
+    if (result.query.$filter !== undefined)
+        effectiveFlags.filter = result.query.$filter;
+    const rows = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, fields, full);
+        rows.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = shape.key === "directoryRoles" ? `mg-axi entra directory-role show --id <role-id> ${profileHint(profileName)}` : undefined;
+    const correlateHint = shape.key === "directoryRoles"
+        ? undefined
+        : `For built-in roles, roleDefinitionId matches the directory-role roleTemplateId: mg-axi entra directory-role list ${profileHint(profileName)}`;
+    const truncationHints = truncated ? [fullHint(shape.command, effectiveFlags, profileName)] : [];
+    const standing = [shape.scopeNote, ...(showHint === undefined ? [] : [showHint]), ...(correlateHint === undefined ? [] : [correlateHint])];
+    if (!result.complete) {
+        return {
+            [shape.key]: rows,
+            count: { returned: rows.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, `Resume losslessly with the same flags plus --cursor <cursor-from-output> ${profileHint(profileName)}`, ...standing],
+        };
+    }
+    const count = { returned: rows.length, complete: true };
+    if (!rows.length) {
+        return { [shape.key]: rows, count, help: [shape.emptyNote, ...standing] };
+    }
+    return { [shape.key]: rows, count, help: [...truncationHints, ...standing] };
+}
+export async function listDirectoryRoles(session, flags, profile, operation, help, profileName) {
+    return listCollection(ROLE_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showDirectoryRole(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, DEFAULT_ROLE_SHOW_SELECT, ROLE_KNOWN, KNOWN_ROLE_FIELDS, help);
+    const scopes = scopesFor(flags, profile, DEFAULT_ROLE_SCOPES, help);
+    const full = flags.full === true;
+    const raw = await withGuidance(ROLE_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation,
+        params: { "directoryRole-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 directory-role body", "GRAPH_ERROR", [
+            "Single-role reads carry one role object; treat anything else as unknown, not empty",
+        ]);
+    }
+    const { row, truncated } = project(raw, fields, full);
+    if (truncated)
+        return { directoryRole: row, help: [fullHint("entra directory-role show", flags, profileName)] };
+    return { directoryRole: row };
+}
+export async function listRoleAssignments(session, flags, profile, operation, help, profileName) {
+    return listCollection(ASSIGNMENT_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function listPimEligible(session, flags, profile, operation, help, profileName) {
+    return listCollection(PIM_ELIGIBLE, session, flags, profile, operation, help, profileName);
+}
+export async function listPimActive(session, flags, profile, operation, help, profileName) {
+    return listCollection(PIM_ACTIVE, session, flags, profile, operation, help, profileName);
+}

package/dist/entra-subscriptions.js

@@ -0,0 +1,289 @@
+import { AxiError } from "axi-sdk-js";
+import { resolveSessionOperation } from "./graph-session.js";
+// EXT-01 directory-subscriptions subfamily: the read mapping behind
+// `mg-axi entra subscription 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 directory-list-subscriptions,
+// companysubscription-get and companySubscription resource documentation on
+// 2026-10-05. Every read takes D/A Organization.Read.All; delegated callers
+// additionally need a supported Entra role (Global Reader, Directory Readers,
+// or Dynamics 365 Business Central Administrator for read-only standard
+// properties). Personal Microsoft accounts are not supported. No P1/P2
+// prerequisite is stated for these reads. The list documents the general
+// OData query parameters, so --filter passes through as plain $filter with
+// no $count or ConsistencyLevel contract; the single GET documents $select
+// only. The $count route carries no operation-level documentation page and
+// takes no --filter/--select/--limit/--cursor. The commerceSubscriptionId
+// alternate-key lookup ships on `show --commerce-subscription-id` through
+// the allowlisted session function binding: the key arrives only as an
+// explicit CLI flag and the session validates, OData-quotes and encodes it.
+// Beta subscriptions stay out ("beta needs its own review"). No mutation
+// lives here.
+//
+// Secrecy by construction: the reviewed companySubscription set carries
+// directory identifiers and licence metadata only; ownerId and ownerTenantId
+// name the account admin and partner tenant without carrying credentials or
+// keys, and the shared session still redacts secret-shaped values before
+// buffering or output.
+// Every subscription property this slice may request or display, matching
+// the reviewed resource. Anything else fails before credentials.
+export const KNOWN_SUBSCRIPTION_FIELDS = [
+    "id",
+    "commerceSubscriptionId",
+    "createdDateTime",
+    "isTrial",
+    "nextLifecycleDateTime",
+    "ownerId",
+    "ownerTenantId",
+    "ownerType",
+    "serviceStatus",
+    "skuId",
+    "skuPartNumber",
+    "status",
+    "totalLicenses",
+];
+const KNOWN_SUBSCRIPTIONS = new Set(KNOWN_SUBSCRIPTION_FIELDS);
+// Compact list rows: identifier, SKU name, lifecycle status and the licence
+// count agents usually need next.
+const DEFAULT_LIST_SELECT = ["id", "skuPartNumber", "status", "totalLicenses"];
+// Show rows: the full reviewed subscription set.
+const DEFAULT_SHOW_SELECT = [...KNOWN_SUBSCRIPTION_FIELDS];
+// Delegated defaults are operation-specific; application profiles use their
+// configured .default audience and reject --scopes.
+export const DEFAULT_SUBSCRIPTION_SCOPES = ["https://graph.microsoft.com/Organization.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 subscription property ${part} in --${flag}`, "VALIDATION_ERROR", [
+                help,
+                `Known subscription 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.
+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, KNOWN_SUBSCRIPTIONS, KNOWN_SUBSCRIPTION_FIELDS, "select", help);
+    const fields = flags.fields === undefined ? [...select] : fieldList(flags.fields, KNOWN_SUBSCRIPTIONS, KNOWN_SUBSCRIPTION_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(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 SUBSCRIPTION_DENIAL_HINTS = [
+    "Subscription reads need Organization.Read.All plus a supported Entra role for delegated access (Global Reader, Directory Readers, or Dynamics 365 Business Central Administrator for read-only standard properties), or admin-consented Organization.Read.All for application access",
+    "Personal Microsoft accounts are not supported for subscription reads",
+    "No P1/P2 prerequisite is stated for subscription reads; never diagnose licence solely from HTTP 403",
+];
+const EMPTY_NOTE = "An empty subscription list may mean the tenant holds no commercial subscriptions; the absence of rows is the answer, not an error";
+// Restoring the saved select/filter keeps cursor resumes lossless when
+// --select or --filter is omitted. The list documents the general OData
+// query parameters, so --filter passes through as plain $filter with no
+// ConsistencyLevel contract; strict input validation still refuses unknown
+// flags before credentials.
+function collectionCommon(session, flags, operation, help, profile) {
+    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, saved?.["$select"] === undefined ? DEFAULT_LIST_SELECT : fieldList(saved["$select"], KNOWN_SUBSCRIPTIONS, KNOWN_SUBSCRIPTION_FIELDS, "select", help), help);
+    const filter = flags.filter === undefined ? saved?.["$filter"] : String(flags.filter);
+    return { cursor, select, fields, scopes: scopesFor(flags, DEFAULT_SUBSCRIPTION_SCOPES, 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 subscriptionId(flags, help) {
+    const id = String(flags.id);
+    if (!id.trim())
+        throw new AxiError("--id needs the commercial-subscription object ID", "VALIDATION_ERROR", [help]);
+    return id;
+}
+// Exactly one subscription key selects the show route: the object ID from
+// the catalogue-resolved operation, or the commerce-system alternate key
+// from the allowlisted function route. The key value itself is validated by
+// the session binding before credentials.
+function subscriptionTarget(flags, operation, help) {
+    const id = flags.id;
+    const commerceId = flags["commerce-subscription-id"];
+    if (id !== undefined && commerceId !== undefined) {
+        throw new AxiError("--id and --commerce-subscription-id cannot be combined", "VALIDATION_ERROR", [help]);
+    }
+    if (commerceId !== undefined) {
+        if (!String(commerceId).trim())
+            throw new AxiError("--commerce-subscription-id needs the commerce-system subscription ID", "VALIDATION_ERROR", [help]);
+        return {
+            operation: resolveSessionOperation("v1.0", "GET", "/directory/subscriptions(commerceSubscriptionId='{commerceSubscriptionId}')"),
+            params: { commerceSubscriptionId: String(commerceId) },
+        };
+    }
+    if (id === undefined)
+        throw new AxiError("Subscription show needs exactly one of --id or --commerce-subscription-id", "VALIDATION_ERROR", [help]);
+    return { operation, params: { "companySubscription-id": subscriptionId(flags, help) } };
+}
+function singleResult(raw, fields, full) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new AxiError("Graph returned a malformed subscription body", "GRAPH_ERROR", [
+            "Single-subscription reads carry one companySubscription object; treat anything else as unknown, not empty",
+        ]);
+    }
+    return project(raw, fields, full);
+}
+export async function listSubscriptions(session, flags, profile, operation, help, profileName) {
+    const common = collectionCommon(session, flags, operation, help, profile);
+    const result = await withGuidance(SUBSCRIPTION_DENIAL_HINTS, () => session.collect(collectArgs(profile, operation, common, flags, help)));
+    const effectiveFlags = { ...flags, select: result.query.$select ?? DEFAULT_LIST_SELECT.join(",") };
+    if (result.query.$filter !== undefined)
+        effectiveFlags.filter = result.query.$filter;
+    const subscriptions = [];
+    let truncated = false;
+    for (const row of result.value) {
+        const projected = project(row, common.fields, common.full);
+        subscriptions.push(projected.row);
+        truncated = truncated || projected.truncated;
+    }
+    const showHint = `mg-axi entra subscription show --id <subscription-id> ${profileHint(profileName)}`;
+    const truncationHints = truncated ? [fullHint("entra subscription list", effectiveFlags, profileName)] : [];
+    if (!result.complete) {
+        return {
+            subscriptions,
+            count: { returned: subscriptions.length, complete: false, reason: result.reason },
+            cursor: result.cursor,
+            help: [...truncationHints, resumeHint(profileName), showHint],
+        };
+    }
+    const count = { returned: subscriptions.length, complete: true };
+    if (!subscriptions.length) {
+        const emptyHint = common.filter === undefined ? EMPTY_NOTE : "0 subscriptions matched; the absence of results is the answer, not an error";
+        return { subscriptions, count, help: [emptyHint] };
+    }
+    return { subscriptions, count, help: [...truncationHints, showHint] };
+}
+export async function showSubscription(session, flags, profile, operation, help, profileName) {
+    const { select, fields } = selectedFields(flags, DEFAULT_SHOW_SELECT, help);
+    const scopes = scopesFor(flags, DEFAULT_SUBSCRIPTION_SCOPES, profile, help);
+    const full = flags.full === true;
+    const target = subscriptionTarget(flags, operation, help);
+    const raw = await withGuidance(SUBSCRIPTION_DENIAL_HINTS, () => session.execute({
+        profile,
+        operation: target.operation,
+        params: target.params,
+        query: { $select: select.join(",") },
+        scopes,
+    }));
+    const { row, truncated } = singleResult(raw, fields, full);
+    if (truncated)
+        return { subscription: row, help: [fullHint("entra subscription show", flags, profileName)] };
+    return { subscription: row };
+}
+// The $count route returns a text/plain integer scalar rather than a JSON
+// collection, so the leaf reads it through session.execute with scalar mode
+// and accepts only a non-negative integer. The $count route carries no
+// operation-level documentation page and takes no --filter/--select/--limit/--cursor.
+export async function countSubscriptions(session, flags, profile, operation, help, profileName) {
+    void profileName;
+    const scopes = scopesFor(flags, DEFAULT_SUBSCRIPTION_SCOPES, profile, help);
+    const raw = await withGuidance(SUBSCRIPTION_DENIAL_HINTS, () => session.execute({ profile, operation, scopes, scalar: true }));
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        throw new AxiError("Graph returned a malformed subscription count body", "GRAPH_ERROR", [
+            "Subscription counts carry one non-negative integer scalar; treat anything else as unknown, not empty",
+        ]);
+    }
+    const count = { returned: raw, complete: true };
+    return raw === 0 ? { count, help: [EMPTY_NOTE] } : { count };
+}