@knowttl/mg-axi 0.1.1 → 0.1.2

package/dist/entra-risk.js

@@ -1,18 +1,29 @@
 import { AxiError } from "axi-sdk-js";
 // READ-06: the Entra risky-user and risk-detection read mapping behind
 // `mg-axi entra risky-user list/show` and `mg-axi entra risk-detection
-// list/show`. Operation construction stays beside its command; the shared
+// list/show`, extended with the workload-identity surface behind
+// `mg-axi entra risky-service-principal list/show`,
+// `mg-axi entra risky-service-principal history list/show` and
+// `mg-axi entra service-principal-risk-detection 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,
 // bounds detection queries in time, and projects rows for compact output.
 //
 // Reviewed against the v1.0 riskyuser-list/get and riskdetection-list/get
-// operation documentation on 2026-10-04. Risky-user reads take D/A
+// operation documentation on 2026-10-04, and against the v1.0
+// riskyserviceprincipal-list/get, history-list and
+// serviceprincipalriskdetection-list/get operation documentation on
+// 2026-10-06. Risky-user reads take D/A
 // IdentityRiskyUser.Read.All and risk-detection reads take D/A
-// IdentityRiskEvent.Read.All; delegated callers additionally need Global
+// IdentityRiskEvent.Read.All; risky-service-principal reads (including
+// history) take D/A IdentityRiskyServicePrincipal.Read.All while
+// service-principal risk detections reuse D/A IdentityRiskEvent.Read.All.
+// Delegated callers additionally need Global
 // Reader, Security Operator, Security Reader or Security Administrator. The
 // riskyUsers API requires a P2 licence, while risk detection permits P1 or
-// P2. Limited views stay limited: a premium detection without P2 detail
+// P2; the workload-identity APIs require a Microsoft Entra Workload
+// Identities Premium licence, and service-principal detections report
+// riskDetail and riskLevel hidden without it. Limited views stay limited: a premium detection without P2 detail
 // reports riskEventType generic, hidden risk levels report the licence
 // boundary instead of the level, and a null detection correlationId means no
 // sign-in is associated. None of these is ever reinterpreted as empty or
@@ -54,8 +65,67 @@ export const KNOWN_RISK_DETECTION_FIELDS = [
     "userPrincipalName",
     "additionalInfo",
 ];
+// Workload-identity surface. History items inherit every risky-service-
+// principal property and add the service-principal identifier plus the
+// actor/activity of the risk change. Service-principal detections carry the
+// service-principal join keys (servicePrincipalId, servicePrincipalDisplayName,
+// appId, keyIds) instead of user keys; keyIds are key-credential identifiers,
+// never secret material. tokenIssuerType stays absent for the same redaction
+// reason as above.
+export const KNOWN_RISKY_SP_FIELDS = [
+    "id",
+    "isEnabled",
+    "isProcessing",
+    "riskDetail",
+    "riskLastUpdatedDateTime",
+    "riskLevel",
+    "riskState",
+    "displayName",
+    "appId",
+    "servicePrincipalType",
+];
+export const KNOWN_RISKY_SP_HISTORY_FIELDS = [
+    "id",
+    "isEnabled",
+    "isProcessing",
+    "riskDetail",
+    "riskLastUpdatedDateTime",
+    "riskLevel",
+    "riskState",
+    "displayName",
+    "appId",
+    "servicePrincipalType",
+    "servicePrincipalId",
+    "initiatedBy",
+    "activity",
+];
+export const KNOWN_SP_DETECTION_FIELDS = [
+    "id",
+    "requestId",
+    "correlationId",
+    "riskEventType",
+    "riskState",
+    "riskLevel",
+    "riskDetail",
+    "source",
+    "detectionTimingType",
+    "activity",
+    "ipAddress",
+    "location",
+    "activityDateTime",
+    "detectedDateTime",
+    "lastUpdatedDateTime",
+    "servicePrincipalId",
+    "servicePrincipalDisplayName",
+    "appId",
+    "keyIds",
+    "additionalInfo",
+];
 const RISKY_USER_KNOWN = new Set(KNOWN_RISKY_USER_FIELDS);
 const RISK_DETECTION_KNOWN = new Set(KNOWN_RISK_DETECTION_FIELDS);
+const RISKY_SP_KNOWN = new Set(KNOWN_RISKY_SP_FIELDS);
+const RISKY_SP_HISTORY_KNOWN = new Set(KNOWN_RISKY_SP_HISTORY_FIELDS);
+const SP_DETECTION_KNOWN = new Set(KNOWN_SP_DETECTION_FIELDS);
 // Compact list rows: identifier, who is at risk, and the triage state.
 const DEFAULT_RISKY_USER_LIST_SELECT = ["id", "userPrincipalName", "riskLevel", "riskState"];
 const DEFAULT_RISK_DETECTION_LIST_SELECT = ["id", "detectedDateTime", "userPrincipalName", "riskLevel"];
@@ -64,6 +134,7 @@ const DEFAULT_RISKY_USER_SHOW_SELECT = [...KNOWN_RISKY_USER_FIELDS];
 const DEFAULT_RISK_DETECTION_SHOW_SELECT = [...KNOWN_RISK_DETECTION_FIELDS];
 export const DEFAULT_RISKY_USER_SCOPES = ["https://graph.microsoft.com/IdentityRiskyUser.Read.All"];
 export const DEFAULT_RISK_DETECTION_SCOPES = ["https://graph.microsoft.com/IdentityRiskEvent.Read.All"];
+export const DEFAULT_RISKY_SP_SCOPES = ["https://graph.microsoft.com/IdentityRiskyServicePrincipal.Read.All"];
 const TRUNCATE_AT = 500;
 function fieldList(raw, flag, known, knownList, help) {
     const parts = String(raw)
@@ -222,6 +293,23 @@ const RISK_DETECTION_DENIAL_HINTS = [
     "Risk-detection reads need IdentityRiskEvent.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskEvent.Read.All for application access",
     "Risk detection needs a P1 or P2 licence; premium detections report riskEventType generic without P2 detail, so generic is the server's limited view rather than the real type",
 ];
+const RISKY_SP_DENIAL_HINTS = [
+    "Risky-service-principal reads need IdentityRiskyServicePrincipal.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskyServicePrincipal.Read.All for application access",
+    "The riskyServicePrincipals API requires a Microsoft Entra Workload Identities Premium licence; data availability follows Entra retention policies",
+];
+const SP_DETECTION_DENIAL_HINTS = [
+    "Service-principal-risk-detection reads need IdentityRiskEvent.Read.All plus a supported directory role: Global Reader, Security Operator, Security Reader or Security Administrator for delegated access, or admin-consented IdentityRiskEvent.Read.All for application access",
+    "The servicePrincipalRiskDetection API requires a Microsoft Entra Workload Identities Premium licence; riskDetail and riskLevel report hidden without it, so hidden is the server's limited view rather than no risk",
+];
+// Nested history routes bind the parent risky-service-principal id before
+// credentials; a missing or empty parent fails as usage, never as Graph 404.
+function parentServicePrincipal(flags, help) {
+    const parent = flags["service-principal"];
+    if (parent === undefined || !String(parent).trim()) {
+        throw new AxiError("--service-principal needs the risky-service-principal object ID owning this history", "VALIDATION_ERROR", [help]);
+    }
+    return { "riskyServicePrincipal-id": String(parent) };
+}
 const RISKY_USER_LIST = {
     noun: "risky-user",
     key: "riskyUsers",
@@ -257,6 +345,62 @@ const RISK_DETECTION_LIST = {
         "Limited views stay limited: riskEventType generic can hide a premium detection without P2 detail, and hidden risk levels report the licence boundary instead of the level - never read them as none",
     ],
 };
+// Compact workload rows: identifier, which workload, and the triage state.
+const DEFAULT_RISKY_SP_LIST_SELECT = ["id", "displayName", "riskLevel", "riskState"];
+const DEFAULT_SP_DETECTION_LIST_SELECT = ["id", "detectedDateTime", "servicePrincipalDisplayName", "riskLevel"];
+const DEFAULT_RISKY_SP_SHOW_SELECT = [...KNOWN_RISKY_SP_FIELDS];
+const DEFAULT_RISKY_SP_HISTORY_SHOW_SELECT = [...KNOWN_RISKY_SP_HISTORY_FIELDS];
+const DEFAULT_SP_DETECTION_SHOW_SELECT = [...KNOWN_SP_DETECTION_FIELDS];
+const RISKY_SP_LIST = {
+    noun: "risky-service-principal",
+    key: "riskyServicePrincipals",
+    known: RISKY_SP_KNOWN,
+    knownList: KNOWN_RISKY_SP_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_LIST_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    showHint: "mg-axi entra risky-service-principal show --id <risky-service-principal-id>",
+    emptyHints: profileName => [
+        `mg-axi entra risky-service-principal list --filter <odata-filter> ${profileHint(profileName)}`,
+        "0 risky service principals matched; the absence of results is the answer, not an error",
+        "Limited results stay limited: without Workload Identities Premium detail the service reports what the caller may see, so never read a short list as no risk",
+    ],
+    extraHelp: () => [],
+};
+const RISKY_SP_HISTORY_LIST = {
+    noun: "risky-service-principal history",
+    key: "riskyServicePrincipalHistory",
+    pathParams: parentServicePrincipal,
+    known: RISKY_SP_HISTORY_KNOWN,
+    knownList: KNOWN_RISKY_SP_HISTORY_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_LIST_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    showHint: "mg-axi entra risky-service-principal history show --service-principal <risky-service-principal-id> --id <history-item-id>",
+    emptyHints: profileName => [
+        `mg-axi entra risky-service-principal history list --service-principal <risky-service-principal-id> ${profileHint(profileName)}`,
+        "0 history items matched; the absence of results is the answer, not an error",
+    ],
+    extraHelp: () => [],
+};
+const SP_DETECTION_LIST = {
+    noun: "service-principal-risk-detection",
+    key: "servicePrincipalRiskDetections",
+    dateField: "detectedDateTime",
+    known: SP_DETECTION_KNOWN,
+    knownList: KNOWN_SP_DETECTION_FIELDS,
+    defaultSelect: DEFAULT_SP_DETECTION_LIST_SELECT,
+    defaultScopes: DEFAULT_RISK_DETECTION_SCOPES,
+    denialHints: SP_DETECTION_DENIAL_HINTS,
+    showHint: "mg-axi entra service-principal-risk-detection show --id <service-principal-risk-detection-id>",
+    emptyHints: profileName => [
+        `mg-axi entra service-principal-risk-detection list --since <earlier-iso-time> ${profileHint(profileName)}`,
+        "0 service-principal risk detections matched in this window; widen --since/--until or loosen --filter - the absence of results is the answer, not an error",
+    ],
+    extraHelp: () => [
+        "Limited views stay limited: riskDetail and riskLevel report hidden without Workload Identities Premium detail - never read hidden as none",
+    ],
+};
 async function listRisk(shape, session, flags, profile, operation, help, profileName) {
     const cursor = flags.cursor === undefined ? undefined : String(flags.cursor);
     if (cursor !== undefined && !cursor.trim())
@@ -292,6 +436,8 @@ async function listRisk(shape, session, flags, profile, operation, help, profile
         query.$filter = String(flags.filter);
     }
     const args = { profile, operation, query, scopes };
+    if (shape.pathParams !== undefined)
+        args.params = shape.pathParams(flags, help);
     if (cursor !== undefined)
         args.cursor = cursor;
     if (flags.all === true) {
@@ -363,6 +509,50 @@ const RISK_DETECTION_SHOW = {
     ],
     noSignInNote: "This detection carries no associated sign-in (correlationId is null); sign-in correlation does not apply",
 };
+const RISKY_SP_SHOW = {
+    noun: "risky-service-principal",
+    key: "riskyServicePrincipal",
+    param: "riskyServicePrincipal-id",
+    known: RISKY_SP_KNOWN,
+    knownList: KNOWN_RISKY_SP_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<risky-service-principal-id>'" ${profileHint(profileName)}`,
+        `List this workload's risk history with mg-axi entra risky-service-principal history list --service-principal <risky-service-principal-id> ${profileHint(profileName)}`,
+        "Confirming compromise and dismissing risk are separately reviewed writes; this read never confirms, dismisses or remediates risk",
+    ],
+};
+const RISKY_SP_HISTORY_SHOW = {
+    noun: "risky-service-principal history",
+    key: "riskyServicePrincipalHistoryItem",
+    param: "riskyServicePrincipalHistoryItem-id",
+    parentParams: parentServicePrincipal,
+    known: RISKY_SP_HISTORY_KNOWN,
+    knownList: KNOWN_RISKY_SP_HISTORY_FIELDS,
+    defaultSelect: DEFAULT_RISKY_SP_HISTORY_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISKY_SP_SCOPES,
+    denialHints: RISKY_SP_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<risky-service-principal-id>'" ${profileHint(profileName)}`,
+    ],
+};
+const SP_DETECTION_SHOW = {
+    noun: "service-principal-risk-detection",
+    key: "servicePrincipalRiskDetection",
+    param: "servicePrincipalRiskDetection-id",
+    known: SP_DETECTION_KNOWN,
+    knownList: KNOWN_SP_DETECTION_FIELDS,
+    defaultSelect: DEFAULT_SP_DETECTION_SHOW_SELECT,
+    defaultScopes: DEFAULT_RISK_DETECTION_SCOPES,
+    denialHints: SP_DETECTION_DENIAL_HINTS,
+    correlationHelp: profileName => [
+        `List this workload's detections with mg-axi entra service-principal-risk-detection list --since <iso-time> --filter "servicePrincipalId eq '<service-principal-id>'" ${profileHint(profileName)}`,
+        "Limited views stay limited: riskDetail and riskLevel report hidden without Workload Identities Premium detail - never read hidden as none",
+    ],
+    noSignInNote: "This detection carries no associated sign-in (correlationId is null); sign-in correlation does not apply",
+};
 async function showRisk(shape, session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, shape.defaultSelect, shape.known, shape.knownList, help);
     const scopes = scopesFor(flags, profile, shape.defaultScopes, help);
@@ -370,7 +560,7 @@ async function showRisk(shape, session, flags, profile, operation, help, profile
     const raw = await withGuidance(shape.denialHints, () => session.execute({
         profile,
         operation,
-        params: { [shape.param]: String(flags.id) },
+        params: { ...(shape.parentParams === undefined ? {} : shape.parentParams(flags, help)), [shape.param]: String(flags.id) },
         query: { $select: select.join(",") },
         scopes,
     }));
@@ -402,3 +592,21 @@ export async function listRiskDetections(session, flags, profile, operation, hel
 export async function showRiskDetection(session, flags, profile, operation, help, profileName) {
     return showRisk(RISK_DETECTION_SHOW, session, flags, profile, operation, help, profileName);
 }
+export async function listRiskyServicePrincipals(session, flags, profile, operation, help, profileName) {
+    return listRisk(RISKY_SP_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showRiskyServicePrincipal(session, flags, profile, operation, help, profileName) {
+    return showRisk(RISKY_SP_SHOW, session, flags, profile, operation, help, profileName);
+}
+export async function listRiskyServicePrincipalHistory(session, flags, profile, operation, help, profileName) {
+    return listRisk(RISKY_SP_HISTORY_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showRiskyServicePrincipalHistory(session, flags, profile, operation, help, profileName) {
+    return showRisk(RISKY_SP_HISTORY_SHOW, session, flags, profile, operation, help, profileName);
+}
+export async function listServicePrincipalRiskDetections(session, flags, profile, operation, help, profileName) {
+    return listRisk(SP_DETECTION_LIST, session, flags, profile, operation, help, profileName);
+}
+export async function showServicePrincipalRiskDetection(session, flags, profile, operation, help, profileName) {
+    return showRisk(SP_DETECTION_SHOW, session, flags, profile, operation, help, profileName);
+}

package/dist/entra-roles.js

@@ -1,4 +1,5 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.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`.
@@ -177,6 +178,7 @@ const ACTIVE_DENIAL_HINTS = [
 const ROLE_LIST = {
     command: "entra directory-role list",
     key: "directoryRoles",
+    noun: "directory roles",
     known: ROLE_KNOWN,
     knownList: KNOWN_ROLE_FIELDS,
     defaultSelect: DEFAULT_ROLE_LIST_SELECT,
@@ -188,6 +190,7 @@ const ROLE_LIST = {
 const ASSIGNMENT_LIST = {
     command: "entra role-assignment list",
     key: "roleAssignments",
+    noun: "role assignments",
     known: ASSIGNMENT_KNOWN,
     knownList: KNOWN_ASSIGNMENT_FIELDS,
     defaultSelect: DEFAULT_ASSIGNMENT_SELECT,
@@ -199,6 +202,7 @@ const ASSIGNMENT_LIST = {
 const PIM_ELIGIBLE = {
     command: "entra pim eligible list",
     key: "eligibleAssignments",
+    noun: "eligible assignments",
     known: ELIGIBLE_KNOWN,
     knownList: KNOWN_ELIGIBLE_FIELDS,
     defaultSelect: DEFAULT_ELIGIBLE_SELECT,
@@ -210,6 +214,7 @@ const PIM_ELIGIBLE = {
 const PIM_ACTIVE = {
     command: "entra pim active list",
     key: "activeAssignments",
+    noun: "active assignments",
     known: ACTIVE_KNOWN,
     knownList: KNOWN_ACTIVE_FIELDS,
     defaultSelect: DEFAULT_ACTIVE_SELECT,
@@ -264,16 +269,17 @@ async function listCollection(shape, session, flags, profile, operation, help, p
     if (!result.complete) {
         return {
             [shape.key]: rows,
-            count: { returned: rows.length, complete: false, reason: result.reason },
+            ...listTotals(rows.length, result.total, shape.noun, false),
+            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, ...listTotals(rows.length, result.total, shape.noun, true), complete: true, help: [shape.emptyNote, ...standing] };
     }
-    return { [shape.key]: rows, count, help: [...truncationHints, ...standing] };
+    return { [shape.key]: rows, ...listTotals(rows.length, result.total, shape.noun, true), complete: true, help: [...truncationHints, ...standing] };
 }
 export async function listDirectoryRoles(session, flags, profile, operation, help, profileName) {
     return listCollection(ROLE_LIST, session, flags, profile, operation, help, profileName);

package/dist/entra-subscriptions.js

@@ -1,5 +1,6 @@
 import { AxiError } from "axi-sdk-js";
 import { resolveSessionOperation } from "./graph-session.js";
+import { listTotals } from "./list-totals.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,
@@ -242,17 +243,18 @@ export async function listSubscriptions(session, flags, profile, operation, help
     if (!result.complete) {
         return {
             subscriptions,
-            count: { returned: subscriptions.length, complete: false, reason: result.reason },
+            ...listTotals(subscriptions.length, result.total, "subscriptions", false),
+            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, ...listTotals(subscriptions.length, result.total, "subscriptions", true), complete: true, help: [emptyHint] };
     }
-    return { subscriptions, count, help: [...truncationHints, showHint] };
+    return { subscriptions, ...listTotals(subscriptions.length, result.total, "subscriptions", true), complete: true, help: [...truncationHints, showHint] };
 }
 export async function showSubscription(session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, DEFAULT_SHOW_SELECT, help);

package/dist/entra-users.js

@@ -1,4 +1,5 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.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
@@ -169,16 +170,18 @@ export async function listUsers(session, flags, profile, operation, help, profil
     if (!result.complete) {
         return {
             users,
-            count: { returned: users.length, complete: false, reason: result.reason },
+            ...listTotals(users.length, result.total, "users", false),
+            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,
+            ...listTotals(users.length, result.total, "users", true),
+            complete: true,
             help: [
                 `mg-axi entra user list --filter <odata-filter> ${profileHint(profileName)}`,
                 "0 users matched; the absence of results is the answer, not an error",
@@ -186,7 +189,7 @@ export async function listUsers(session, flags, profile, operation, help, profil
         };
     }
     const helpHints = [...truncationHints, showHint];
-    return { users, count, help: helpHints };
+    return { users, ...listTotals(users.length, result.total, "users", true), complete: true, help: helpHints };
 }
 export async function showUser(session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, DEFAULT_SHOW_SELECT, help);

package/dist/graph-session.js

@@ -38,6 +38,7 @@ const READ_SCOPES = new Set([
     "GroupMember.ReadBasic.All",
     "IdentityProvider.Read.All",
     "IdentityRiskEvent.Read.All",
+    "IdentityRiskyServicePrincipal.Read.All",
     "IdentityRiskyUser.Read.All",
     "LicenseAssignment.Read.All",
     "LifecycleWorkflows-Reports.Read.All",
@@ -54,8 +55,10 @@ const READ_SCOPES = new Set([
     "Policy.Read.All",
     "Policy.Read.AuthenticationMethod",
     "Policy.Read.ConditionalAccess",
+    "PrivilegedAssignmentSchedule.Read.AzureADGroup",
     "PrivilegedEligibilitySchedule.Read.AzureADGroup",
     "PublicKeyInfrastructure.Read.All",
+    "RiskPreventionProviders.Read.All",
     "RoleAssignmentSchedule.Read.Directory",
     "RoleEligibilitySchedule.Read.Directory",
     "RoleManagement.Read.Directory",
@@ -551,7 +554,7 @@ function bodyBytes(body) {
     return Buffer.byteLength(body, "utf8");
 }
 function encodeCursor(operation, state) {
-    const payload = { v: 3, op: operation.id, next: state.next ?? null, buffered: state.buffered, seen: state.seen.slice(-MAX_SEEN), query: state.query, consistencyLevel: state.consistencyLevel ?? null, context: state.context, identity: state.identity };
+    const payload = { v: 3, op: operation.id, next: state.next ?? null, buffered: state.buffered, seen: state.seen.slice(-MAX_SEEN), query: state.query, consistencyLevel: state.consistencyLevel ?? null, context: state.context, identity: state.identity, total: state.total };
     return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
 }
 function decodeCursor(operation, cursor) {
@@ -574,13 +577,17 @@ function decodeCursor(operation, cursor) {
     }
     if (record.buffered.length > 5000)
         throw new AxiError("Invalid collection cursor", "VALIDATION_ERROR", ["The cursor buffers at most one fetched page"]);
+    const total = record.total === undefined ? null : record.total;
+    if (!(total === null || (typeof total === "number" && Number.isSafeInteger(total) && total >= 0))) {
+        throw new AxiError("Invalid collection cursor", "VALIDATION_ERROR", ["Resume with the cursor from a partial result of the same operation"]);
+    }
     if (record.identity === null && (record.buffered.length > 0 || record.seen.length > 0))
         throw new AxiError("Invalid collection cursor", "VALIDATION_ERROR", ["Fetched rows and consumed pages require a bound credential identity"]);
     const query = record.query;
     const consistencyLevel = record.consistencyLevel ?? undefined;
     buildQuery(query);
     checkQueryContext(query, consistencyLevel);
-    return { next: record.next ?? undefined, buffered: record.buffered.map(redact), seen: [...record.seen], query, consistencyLevel, context: record.context, identity: record.identity };
+    return { next: record.next ?? undefined, buffered: record.buffered.map(redact), seen: [...record.seen], query, consistencyLevel, context: record.context, identity: record.identity, total };
 }
 function nextLinkOf(body) {
     if (!body || typeof body !== "object" || Array.isArray(body))
@@ -588,6 +595,16 @@ function nextLinkOf(body) {
     const value = body["@odata.nextLink"];
     return typeof value === "string" && value ? value : undefined;
 }
+// The total Graph already supplies on collection pages when the query
+// carries $count=true. Only a valid non-negative integer becomes a total;
+// anything else stays unknown rather than failing the read or inventing
+// a number.
+function countOf(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const count = body["@odata.count"];
+    return typeof count === "number" && Number.isSafeInteger(count) && count >= 0 ? count : null;
+}
 function valuesOf(operation, body) {
     if (!body || typeof body !== "object" || Array.isArray(body) || !Object.hasOwn(body, "value")) {
         throw new AxiError(`Graph returned a malformed collection body for ${operation.id}`, "GRAPH_ERROR", ["Collections carry a value array; treat anything else as unknown, not empty"]);
@@ -699,14 +716,18 @@ export class GraphSession {
         let requests = 0;
         let bytes = 0;
         let identity = resumed?.identity ?? null;
+        // First known server total wins across pages and resumes; later pages
+        // repeat the same query total, so disagreement keeps the first.
+        let total = resumed?.total ?? null;
         const partial = (reason, next, buffered) => ({
             value: results,
             query,
             complete: false,
             reason,
-            cursor: encodeCursor(operation, { next, buffered, seen: [...seenList], query, consistencyLevel, context, identity }),
+            cursor: encodeCursor(operation, { next, buffered, seen: [...seenList], query, consistencyLevel, context, identity, total }),
             requests,
             bytes,
+            total,
         });
         let token;
         try {
@@ -744,11 +765,11 @@ export class GraphSession {
                 return partial("deadline exceeded", current, pending);
             if (args.limit !== undefined && results.length >= args.limit) {
                 if (pending.length === 0 && !current)
-                    return { value: results, query, complete: true, requests, bytes };
+                    return { value: results, query, complete: true, requests, bytes, total };
                 return partial("row limit reached; buffered remainder is preserved in the cursor", current, pending);
             }
             if (!current)
-                return { value: results, query, complete: true, requests, bytes };
+                return { value: results, query, complete: true, requests, bytes, total };
             if (requests >= budget.maxRequests)
                 return partial(`request budget exhausted after ${requests} requests`, current, pending);
             const cycleKey = digestUrl(current);
@@ -837,6 +858,9 @@ export class GraphSession {
                     throw new AxiError(`Graph returned a non-JSON success body for ${operation.id}`, "GRAPH_ERROR", ["Successful reads are JSON; anything else is malformed"]);
                 }
                 const rows = valuesOf(operation, parsed);
+                const pageTotal = countOf(parsed);
+                if (total === null && pageTotal !== null)
+                    total = pageTotal;
                 const rawNext = nextLinkOf(parsed);
                 const nextUrl = rawNext ? authorizeUrl(operation, params, rawNext, fetchUrl, consistencyLevel) : undefined;
                 remember(current);

package/dist/hook.js

@@ -0,0 +1,84 @@
+import { encode } from "@toon-format/toon";
+import { Profiles } from "./profiles.js";
+// Session-start ambient summary behind the mg-axi-hook entry point.
+// Local configuration state only: every configured profile name with its
+// tenant label, auth-cache presence and effective write posture, plus the
+// package version and one next-step hint. No session, transport, Graph or
+// sign-in call of any kind; every failure collapses to a short record with
+// exit code 0, so a missing or broken config never breaks agent startup.
+//
+// Auth-cache presence reads the OS credential store directly: delegated
+// profiles keep their MSAL session blob under the "mg-axi" service with the
+// session key below, so presence means a previous explicit login happened on
+// this machine. Only presence is reported; tokens and key material never
+// reach the output. Application profiles acquire tokens silently per run, so
+// they report the client-credentials mechanism instead of cache state.
+// Session cache key mirrors MsalProvider.application() in
+// src/msal-provider.ts; change both together.
+function delegatedSessionKey(profile) {
+    return JSON.stringify([profile.credentialRef.key, profile.tenantId, profile.clientId, profile.cloud]);
+}
+async function probeAuthPresence(profile) {
+    if (profile.mode !== "delegated")
+        return "client-credentials";
+    let store;
+    try {
+        store = await import("keytar").then(module => module.default).catch(() => undefined);
+    }
+    catch {
+        return "unknown";
+    }
+    if (!store)
+        return "unknown";
+    try {
+        return typeof await store.getPassword("mg-axi", delegatedSessionKey(profile)) === "string" ? "cached" : "sign-in required";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// Next-step hints name real catalogue leaves; test/hook.test.mjs asserts
+// every `mg-axi ...` command mentioned here exists in the catalogue, so the
+// hook text cannot drift from the single source.
+const CONFIGURED_HINT = "Run npx -y @knowttl/mg-axi doctor --profile <name> to check a profile";
+const SETUP_HINT = "Run npx -y @knowttl/mg-axi setup to find the config path and example";
+export async function hookSummary(options) {
+    try {
+        return await renderHookSummary(options);
+    }
+    catch {
+        return "mg: status unavailable\n";
+    }
+}
+async function renderHookSummary({ version, env = process.env, configPath, authPresence = probeAuthPresence }) {
+    let store;
+    let names;
+    try {
+        store = new Profiles(configPath ?? env.MG_AXI_CONFIG);
+        names = store.list().map(item => item.name);
+    }
+    catch {
+        return `${encode({ mg: "configuration invalid", help: ["Check the selected config file's path, permissions and JSON syntax"] })}\n`;
+    }
+    if (names.length === 0) {
+        return `${encode({ mg: "not configured", help: [SETUP_HINT] })}\n`;
+    }
+    const profiles = [];
+    for (const name of names) {
+        const profile = store.resolve(name).profile;
+        let auth = "unknown";
+        try {
+            auth = await authPresence(profile);
+        }
+        catch {
+            auth = "unknown";
+        }
+        profiles.push({
+            name,
+            tenant: profile.tenantId,
+            auth,
+            writes: profile.writes?.allowWrites === true ? profile.writes.operations.join(",") : "disabled",
+        });
+    }
+    return `${encode({ mg: "configured", version, profiles, help: [CONFIGURED_HINT] })}\n`;
+}

package/dist/list-totals.js

@@ -0,0 +1,52 @@
+// LIST-TOTALS: the one shared helper behind every list command's uniform
+// "N of M" total line (AXI principle: pre-computed aggregates).
+//
+// A list line names rows returned of total available. The total is the one
+// Graph already supplies on the fetched pages (@odata.count, captured by the
+// shared session when the query carries $count=true); it is never fetched
+// with an extra request and never invented. Where the pages carry no usable
+// total, the line stays honest: a complete read names its rows, a partial
+// read says more is available.
+//
+// The shape matches az-axi's countLine and vectra-axi's collection counts:
+// a `total` field (number when known, null when not) beside a `count`
+// string. The noun is always plural ("groups", never "group"); the helper
+// never inflects, so "1 groups" reads exactly like az-axi's "1 of N" lines.
+import { AxiError } from "axi-sdk-js";
+function checkShown(shown) {
+    if (!Number.isSafeInteger(shown) || shown < 0) {
+        throw new AxiError(`Invalid list row count ${shown}`, "VALIDATION_ERROR", [
+            "List totals count the projected rows actually returned",
+        ]);
+    }
+}
+function checkTotal(total) {
+    if (total === undefined)
+        return null;
+    if (total === null)
+        return null;
+    if (!Number.isSafeInteger(total) || total < 0) {
+        throw new AxiError(`Invalid list total ${total}`, "VALIDATION_ERROR", [
+            "A list total is the server-supplied @odata.count or null when unknown; never fabricate one",
+        ]);
+    }
+    return total;
+}
+export function listTotals(shown, total, noun, complete) {
+    checkShown(shown);
+    const known = checkTotal(total);
+    if (typeof noun !== "string" || !noun) {
+        throw new AxiError("Invalid list noun for totals", "VALIDATION_ERROR", [
+            "Name the listed collection in the plural, e.g. groups, members, memberships",
+        ]);
+    }
+    // A partial read always names more: the known total stays visible even
+    // when the window happens to match it (az-axi countLine parity), while
+    // an unknown total says more is available. A complete read collapses a
+    // matching total to the row count.
+    if (known !== null && (known !== shown || !complete))
+        return { total: known, count: `${shown} of ${known} ${noun}` };
+    if (complete)
+        return { total: known, count: `${shown} ${noun}` };
+    return { total: known, count: `${shown} ${noun} shown, more available` };
+}