@knowttl/mg-axi 0.1.1 → 0.1.3

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-terms-of-use.js

@@ -1,4 +1,5 @@
 import { AxiError } from "axi-sdk-js";
+import { listTotals } from "./list-totals.js";
 // EXT-01 terms-of-use subfamily: the read mapping behind
 // `mg-axi entra agreement list/show`,
 // `mg-axi entra agreement acceptance list/show --agreement <agreement-id>`
@@ -264,20 +265,22 @@ export async function listAgreements(session, flags, profile, operation, help, p
     if (!result.complete) {
         return {
             agreements,
-            count: { returned: agreements.length, complete: false, reason: result.reason },
+            ...listTotals(agreements.length, result.total, "agreements", false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, resumeHint(profileName), showHint],
         };
     }
-    const count = { returned: agreements.length, complete: true };
     if (!agreements.length) {
         return {
             agreements,
-            count,
+            ...listTotals(agreements.length, result.total, "agreements", true),
+            complete: true,
             help: ["0 agreements matched; no terms-of-use agreements are configured for the tenant, or no row passed --filter"],
         };
     }
-    return { agreements, count, help: [...truncationHints, showHint] };
+    return { agreements, ...listTotals(agreements.length, result.total, "agreements", true), complete: true, help: [...truncationHints, showHint] };
 }
 export async function showAgreement(session, flags, profile, operation, help, profileName) {
     const { select, fields } = selectedFields(flags, KNOWN_AGREEMENTS, KNOWN_AGREEMENT_FIELDS, DEFAULT_AGREEMENT_SHOW_SELECT, help, "agreement");
@@ -325,20 +328,22 @@ async function collectAcceptances(session, flags, profile, operation, help, prof
     if (!result.complete) {
         return {
             agreementAcceptances: acceptances,
-            count: { returned: acceptances.length, complete: false, reason: result.reason },
+            ...listTotals(acceptances.length, result.total, "agreement acceptances", false),
+            complete: false,
+            reason: result.reason,
             cursor: result.cursor,
             help: [...truncationHints, resumeHint(profileName), showHint],
         };
     }
-    const count = { returned: acceptances.length, complete: true };
     if (!acceptances.length) {
         return {
             agreementAcceptances: acceptances,
-            count,
+            ...listTotals(acceptances.length, result.total, "agreement acceptances", true),
+            complete: true,
             help: ["0 agreement acceptances matched; nobody recorded an acceptance in scope yet, or no row passed --filter"],
         };
     }
-    return { agreementAcceptances: acceptances, count, help: [...truncationHints, showHint] };
+    return { agreementAcceptances: acceptances, ...listTotals(acceptances.length, result.total, "agreement acceptances", true), complete: true, help: [...truncationHints, showHint] };
 }
 async function showAcceptanceById(session, flags, profile, operation, help, profileName, command, agreement) {
     const { select, fields } = selectedFields(flags, KNOWN_ACCEPTANCES, KNOWN_ACCEPTANCE_FIELDS, DEFAULT_ACCEPTANCE_SELECT, help, "agreement-acceptance");

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

@@ -25,6 +25,7 @@ const READ_SCOPES = new Set([
     "AdministrativeUnit.Read.All",
     "Application.Read.All",
     "AuditLog.Read.All",
+    "AuthenticationContext.Read.All",
     "CustomSecAttributeDefinition.Read.All",
     "CrossTenantInformation.ReadBasic.All",
     "DelegatedAdminRelationship.Read.All",
@@ -38,6 +39,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 +56,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 +555,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 +578,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 +596,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 +717,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 +766,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 +859,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` };
+}

package/dist/setup.js

@@ -15,7 +15,9 @@ const READ_FAMILY_PREFIXES = [
     ["entra user", "user"],
     ["entra registration", "registration"],
     ["entra group", "group"],
+    ["entra directory-role-template", "directory-role/PIM"],
     ["entra directory-role", "directory-role/PIM"],
+    ["entra scoped-role-membership", "directory-role/PIM"],
     ["entra role-assignment", "directory-role/PIM"],
     ["entra pim", "directory-role/PIM"],
     ["entra device", "device"],
@@ -49,14 +51,20 @@ const READ_FAMILY_PREFIXES = [
     ["entra tenant-information", "tenant information"],
     ["entra sign-in", "sign-in/directory-audit"],
     ["entra directory-audit", "sign-in/directory-audit"],
+    ["entra provisioning", "sign-in/directory-audit"],
     ["entra application", "application/service-principal and consent grants"],
     ["entra service-principal", "application/service-principal and consent grants"],
     ["entra risky-user", "risk"],
     ["entra risk-detection", "risk"],
+    ["entra risky-service-principal", "risk"],
+    ["entra service-principal-risk-detection", "risk"],
     ["entra conditional-access", "Conditional Access"],
     ["entra identity-provider", "identity-provider"],
     ["entra federation-configuration", "federation configurations"],
     ["entra data-policy-operation", "data policy operations"],
+    ["entra fraud-protection-provider", "risk prevention"],
+    ["entra web-application-firewall-provider", "risk prevention"],
+    ["entra web-application-firewall-verification", "risk prevention"],
     ["entra access-review", "access-review"],
     ["entra entitlement catalog", "entitlement catalogs and access packages"],
     ["entra entitlement access-package", "entitlement catalogs and access packages"],
@@ -107,7 +115,7 @@ export function setupView(store) {
             reads,
             writes,
             local: implemented.length - reads - writes,
-            api: `Entra ${families.slice(0, -1).join(", ")} and ${families.at(-1)} reads plus reviewed raw api get, one gated group-membership write, one gated account enable/disable write, one gated session-revocation write and one gated risky-user dismissal write; every other operation is scheduled, blocked, deprecated or excluded`,
+            api: `Entra ${families.slice(0, -1).join(", ")} and ${families.at(-1)} reads plus reviewed raw api get, one gated group-membership write, one gated account enable/disable write, one gated session-revocation write and one gated risky-user dismissal write; every other v1.0 operation is deferred out of v1, and every other beta operation remains scheduled (never agreed for v1), blocked, deprecated, unavailable or excluded`,
             report: "docs/coverage.md",
         },
         integration: "Install skills/mg-axi/SKILL.md explicitly through your agent's skill installation mechanism; setup only shows guidance and installs no skills or hooks",