@knowttl/mg-axi 0.1.0

package/inventory/operations.json

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/inventory/operations.json
+size: 75857800 bytes
+sha256: bf8b0cdd323b9f6fbdd2803f7964e15545bbcc4b779e8e8d6cc6068b11324d95

package/inventory/schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "INV-01 Entra discovery inventory",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "repository", "revision", "checkedOn", "sources", "operations"],
+  "properties": {
+    "schemaVersion": {"const": 2},
+    "repository": {"const": "microsoftgraph/msgraph-metadata"},
+    "revision": {"type": "string", "pattern": "^[a-f0-9]{40}$"},
+    "checkedOn": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"},
+    "sources": {
+      "type": "array", "minItems": 2, "maxItems": 2,
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["version", "path", "sha256", "bytes", "discoveredOperations", "excludedByRoot"],
+        "properties": {
+          "version": {"$ref": "#/$defs/version"},
+          "path": {"type": "string", "pattern": "^openapi/(v1\\.0|beta)/openapi\\.yaml$"},
+          "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "bytes": {"type": "integer", "minimum": 1},
+          "discoveredOperations": {"type": "integer", "minimum": 1},
+          "excludedByRoot": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 1}}
+        }
+      }
+    },
+    "operations": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/operation"}}
+  },
+  "$defs": {
+    "version": {"enum": ["v1.0", "beta"]},
+    "text": {"type": "string", "minLength": 1},
+    "source": {"type": "string", "pattern": "^https://learn\\.microsoft\\.com/"},
+    "evidence": {
+      "type": "object", "additionalProperties": false,
+      "required": ["status", "sources"],
+      "properties": {
+        "status": {"const": "not-reviewed"},
+        "sources": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/source"}}
+      }
+    },
+    "operation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "operationId", "version", "method", "path", "cloud", "tenantType", "documentation", "authModes", "permissions", "roles", "licences", "cloudAvailability", "disposition", "reason", "owningSlice"],
+      "properties": {
+        "id": {"$ref": "#/$defs/text"},
+        "operationId": {"$ref": "#/$defs/text"},
+        "version": {"$ref": "#/$defs/version"},
+        "method": {"enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]},
+        "path": {"type": "string", "pattern": "^/"},
+        "cloud": {"const": "commercial"},
+        "tenantType": {"const": "workforce"},
+        "documentation": {"anyOf": [{"$ref": "#/$defs/source"}, {"type": "null"}]},
+        "authModes": {
+          "type": "object", "additionalProperties": false,
+          "required": ["delegated", "application"],
+          "properties": {"delegated": {"$ref": "#/$defs/evidence"}, "application": {"$ref": "#/$defs/evidence"}}
+        },
+        "permissions": {"$ref": "#/$defs/evidence"},
+        "roles": {"$ref": "#/$defs/evidence"},
+        "licences": {"$ref": "#/$defs/evidence"},
+        "cloudAvailability": {"$ref": "#/$defs/evidence"},
+        "disposition": {"enum": ["named-command", "reviewed-raw-read", "scheduled", "intentionally-blocked", "deprecated", "unavailable", "excluded"]},
+        "reason": {"$ref": "#/$defs/text"},
+        "owningSlice": {"enum": [null, "READ-01", "READ-02", "READ-03", "READ-04", "READ-05", "READ-06", "READ-07", "READ-08", "READ-09", "READ-10", "EXT-01", "EXT-02", "EXT-02c", "EXT-03", "EXT-04", "WRITE-01", "WRITE-02", "WRITE-03", "WRITE-04", "WRITE-05", "WRITE-N"]}
+      },
+      "if": {"properties": {"disposition": {"const": "excluded"}}},
+      "then": {"properties": {"owningSlice": {"type": "null"}}},
+      "else": {"properties": {"owningSlice": {"type": "string"}}}
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@knowttl/mg-axi",
+  "version": "0.1.0",
+  "description": "Agent-facing Microsoft Graph CLI, read-only by default",
+  "type": "module",
+  "bin": { "mg-axi": "dist/bin/mg-axi.js" },
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/knowttl/mg-axi.git" },
+  "files": ["dist", "inventory/schema.json", "inventory/operations.json", "skills/mg-axi", "docs/coverage.md", "README.md"],
+  "engines": { "node": ">=22.12.0" },
+  "packageManager": "pnpm@10.34.6",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "docs:generate": "node tools/generate-docs.mjs",
+    "docs:check": "node tools/generate-docs.mjs --check"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^7.0.1",
+    "@toon-format/toon": "^2.3.0",
+    "axi-sdk-js": "^0.1.13",
+    "open": "^11.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^7.0.2"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  }
+}

package/skills/mg-axi/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: mg-axi
+description: >
+  Inspect Microsoft Entra users, authentication methods, groups, roles, devices, administrative units, organization and branding, domains and DNS records, certificate authentication, commercial subscriptions, on-premises synchronization, terms-of-use agreements and acceptances, directory objects, organizational contacts, group lifecycle policies, group setting templates, attribute sets and custom security attributes, partner contracts, delegated administration, multi-tenant organization, tenant information, sign-ins and audit logs, applications and consent grants, risk, Conditional Access, identity providers, federation configurations, deleted directory items, data policy operations, access reviews, entitlement catalogs and access packages, entitlement assignments and requests, lifecycle workflows, templates, task definitions, settings, runs, processing results and task reports, reviewed raw reads and run 5 gated writes (account enable/disable, session revocation, group-membership add, risky-user dismissal, CA policy update) through token-efficient TOON output.
+user-invocable: false
+---
+
+<!-- Generated by tools/generate-docs.mjs from src/catalogue.ts. Do not hand-edit. -->
+
+# mg-axi
+
+Agent-ergonomic CLI for Microsoft Graph. Inspect Microsoft Graph capabilities, read-only by default.
+Entra SOC reads through token-efficient TOON output.
+The generated [command table](#orientation) lists supported named writes through the gated mutation coordinator; raw API remains read-only and every other mutation is refused.
+See [README.md](../../README.md) for write usage, execution gates, identity pinning, permissions, target-role hierarchy and write configuration.
+
+Run commands non-interactively as `npx -y @knowttl/mg-axi ...`: no global install needed and no interactive prompts.
+Version pinning is the installer's choice: use `npx -y @knowttl/mg-axi@<version> ...` to select a specific release.
+Run `npx -y @knowttl/mg-axi doctor` first.
+See [README.md](../../README.md#release) for doctor profile selection, checks and failure behavior.
+
+## Orientation
+
+The exact current leaf registry is `src/catalogue.ts`.
+Its capability label is `native` (implemented by an mg-axi handler).
+Its effect is `read` for Graph read leaves and the doctor health check, `write` for the gated named writes, or `local` for home, profile, login and setup views.
+Doctor acquires credentials silently and contacts Graph; only its help view stays offline.
+The list below records current executable leaves; it makes no coverage claim for other Graph operations.
+See `docs/coverage.md` for the per-operation disposition records.
+`docs/coverage.md` and this file are generated from the same catalogue and inventory sources; `node tools/generate-docs.mjs --check` fails when they are stale.
+
+<!-- command-registry:start -->
+| Command | Capability | Effect |
+|---|---|---|
+| `mg-axi home` | native | local |
+| `mg-axi profile create` | native | local |
+| `mg-axi profile list` | native | local |
+| `mg-axi profile show` | native | local |
+| `mg-axi login` | native | local |
+| `mg-axi setup` | native | local |
+| `mg-axi doctor` | native | read |
+| `mg-axi entra user list` | native | read |
+| `mg-axi entra user show` | native | read |
+| `mg-axi entra user update` | native | write |
+| `mg-axi entra user revoke-sessions` | native | write |
+| `mg-axi entra user authentication-method list` | native | read |
+| `mg-axi entra registration list` | native | read |
+| `mg-axi entra group list` | native | read |
+| `mg-axi entra group show` | native | read |
+| `mg-axi entra group member list` | native | read |
+| `mg-axi entra group member-of list` | native | read |
+| `mg-axi entra group member add` | native | write |
+| `mg-axi entra directory-role list` | native | read |
+| `mg-axi entra directory-role show` | native | read |
+| `mg-axi entra role-assignment list` | native | read |
+| `mg-axi entra pim eligible list` | native | read |
+| `mg-axi entra pim active list` | native | read |
+| `mg-axi entra device list` | native | read |
+| `mg-axi entra device show` | native | read |
+| `mg-axi entra administrative-unit list` | native | read |
+| `mg-axi entra administrative-unit show` | native | read |
+| `mg-axi entra administrative-unit member list` | native | read |
+| `mg-axi entra organization list` | native | read |
+| `mg-axi entra organization show` | native | read |
+| `mg-axi entra organization branding show` | native | read |
+| `mg-axi entra organization branding-localization list` | native | read |
+| `mg-axi entra organization branding-localization show` | native | read |
+| `mg-axi entra domain list` | native | read |
+| `mg-axi entra domain show` | native | read |
+| `mg-axi entra domain verification-dns-record list` | native | read |
+| `mg-axi entra domain verification-dns-record show` | native | read |
+| `mg-axi entra domain service-configuration-record list` | native | read |
+| `mg-axi entra domain service-configuration-record show` | native | read |
+| `mg-axi entra domain-dns-record list` | native | read |
+| `mg-axi entra domain-dns-record show` | native | read |
+| `mg-axi entra certificate-auth-pki list` | native | read |
+| `mg-axi entra certificate-auth-pki show` | native | read |
+| `mg-axi entra certificate-auth-pki count` | native | read |
+| `mg-axi entra certificate-authority list` | native | read |
+| `mg-axi entra certificate-authority show` | native | read |
+| `mg-axi entra certificate-authority count` | native | read |
+| `mg-axi entra subscription list` | native | read |
+| `mg-axi entra subscription show` | native | read |
+| `mg-axi entra subscription count` | native | read |
+| `mg-axi entra on-premises-synchronization list` | native | read |
+| `mg-axi entra on-premises-synchronization show` | native | read |
+| `mg-axi entra agreement list` | native | read |
+| `mg-axi entra agreement show` | native | read |
+| `mg-axi entra agreement acceptance list` | native | read |
+| `mg-axi entra agreement acceptance show` | native | read |
+| `mg-axi entra agreement-acceptance list` | native | read |
+| `mg-axi entra agreement-acceptance show` | native | read |
+| `mg-axi entra directory-object list` | native | read |
+| `mg-axi entra directory-object show` | native | read |
+| `mg-axi entra directory-object count` | native | read |
+| `mg-axi entra contact list` | native | read |
+| `mg-axi entra contact show` | native | read |
+| `mg-axi entra contact count` | native | read |
+| `mg-axi entra contact show-manager` | native | read |
+| `mg-axi entra contact list-direct-reports` | native | read |
+| `mg-axi entra contact show-direct-report` | native | read |
+| `mg-axi entra contact count-direct-reports` | native | read |
+| `mg-axi entra contact list-member-of` | native | read |
+| `mg-axi entra contact show-member-of` | native | read |
+| `mg-axi entra contact count-member-of` | native | read |
+| `mg-axi entra group-lifecycle-policy list` | native | read |
+| `mg-axi entra group-lifecycle-policy show` | native | read |
+| `mg-axi entra group-lifecycle-policy count` | native | read |
+| `mg-axi entra group-setting-template list` | native | read |
+| `mg-axi entra group-setting-template show` | native | read |
+| `mg-axi entra group-setting-template count` | native | read |
+| `mg-axi entra attribute-set list` | native | read |
+| `mg-axi entra attribute-set show` | native | read |
+| `mg-axi entra attribute-set count` | native | read |
+| `mg-axi entra custom-security-attribute-definition list` | native | read |
+| `mg-axi entra custom-security-attribute-definition show` | native | read |
+| `mg-axi entra custom-security-attribute-definition count` | native | read |
+| `mg-axi entra allowed-value list` | native | read |
+| `mg-axi entra allowed-value show` | native | read |
+| `mg-axi entra allowed-value count` | native | read |
+| `mg-axi entra contract list` | native | read |
+| `mg-axi entra contract show` | native | read |
+| `mg-axi entra contract count` | native | read |
+| `mg-axi entra delegated-admin-customer list` | native | read |
+| `mg-axi entra delegated-admin-customer show` | native | read |
+| `mg-axi entra delegated-admin-relationship list` | native | read |
+| `mg-axi entra delegated-admin-relationship show` | native | read |
+| `mg-axi entra delegated-admin-relationship list-access-assignments` | native | read |
+| `mg-axi entra delegated-admin-relationship show-access-assignment` | native | read |
+| `mg-axi entra delegated-admin-relationship list-operations` | native | read |
+| `mg-axi entra delegated-admin-relationship show-operation` | native | read |
+| `mg-axi entra delegated-admin-relationship list-requests` | native | read |
+| `mg-axi entra delegated-admin-relationship show-request` | native | read |
+| `mg-axi entra delegated-admin-customer list-service-management-details` | native | read |
+| `mg-axi entra delegated-admin-customer show-service-management-detail` | native | read |
+| `mg-axi entra multi-tenant-organization show` | native | read |
+| `mg-axi entra multi-tenant-organization join-request show` | native | read |
+| `mg-axi entra multi-tenant-organization tenant list` | native | read |
+| `mg-axi entra multi-tenant-organization tenant count` | native | read |
+| `mg-axi entra tenant-information show` | native | read |
+| `mg-axi entra sign-in list` | native | read |
+| `mg-axi entra sign-in show` | native | read |
+| `mg-axi entra directory-audit list` | native | read |
+| `mg-axi entra directory-audit show` | native | read |
+| `mg-axi entra application list` | native | read |
+| `mg-axi entra application show` | native | read |
+| `mg-axi entra service-principal list` | native | read |
+| `mg-axi entra service-principal show` | native | read |
+| `mg-axi entra application owner list` | native | read |
+| `mg-axi entra service-principal owner list` | native | read |
+| `mg-axi entra service-principal oauth2-grant list` | native | read |
+| `mg-axi entra service-principal app-role-assignment list` | native | read |
+| `mg-axi entra risky-user list` | native | read |
+| `mg-axi entra risky-user show` | native | read |
+| `mg-axi entra risky-user dismiss` | native | write |
+| `mg-axi entra risk-detection list` | native | read |
+| `mg-axi entra risk-detection show` | native | read |
+| `mg-axi entra conditional-access policy list` | native | read |
+| `mg-axi entra conditional-access policy show` | native | read |
+| `mg-axi entra conditional-access policy update` | native | write |
+| `mg-axi entra conditional-access named-location list` | native | read |
+| `mg-axi entra conditional-access named-location show` | native | read |
+| `mg-axi entra identity-provider list` | native | read |
+| `mg-axi entra identity-provider show` | native | read |
+| `mg-axi entra identity-provider count` | native | read |
+| `mg-axi entra identity-provider available-types` | native | read |
+| `mg-axi entra federation-configuration list` | native | read |
+| `mg-axi entra federation-configuration show` | native | read |
+| `mg-axi entra federation-configuration count` | native | read |
+| `mg-axi entra federation-configuration available-types` | native | read |
+| `mg-axi entra deleted-user list` | native | read |
+| `mg-axi entra deleted-user count` | native | read |
+| `mg-axi entra deleted-group list` | native | read |
+| `mg-axi entra deleted-group count` | native | read |
+| `mg-axi entra deleted-application list` | native | read |
+| `mg-axi entra deleted-application count` | native | read |
+| `mg-axi entra deleted-service-principal list` | native | read |
+| `mg-axi entra deleted-service-principal count` | native | read |
+| `mg-axi entra deleted-administrative-unit list` | native | read |
+| `mg-axi entra deleted-administrative-unit count` | native | read |
+| `mg-axi entra deleted-item show` | native | read |
+| `mg-axi entra data-policy-operation list` | native | read |
+| `mg-axi entra data-policy-operation show` | native | read |
+| `mg-axi entra data-policy-operation count` | native | read |
+| `mg-axi entra access-review definition list` | native | read |
+| `mg-axi entra access-review definition show` | native | read |
+| `mg-axi entra access-review instance list` | native | read |
+| `mg-axi entra access-review instance show` | native | read |
+| `mg-axi entra access-review decision list` | native | read |
+| `mg-axi entra access-review decision show` | native | read |
+| `mg-axi entra access-review contacted-reviewer list` | native | read |
+| `mg-axi entra access-review contacted-reviewer show` | native | read |
+| `mg-axi entra access-review stage list` | native | read |
+| `mg-axi entra access-review stage show` | native | read |
+| `mg-axi entra entitlement catalog list` | native | read |
+| `mg-axi entra entitlement catalog show` | native | read |
+| `mg-axi entra entitlement catalog count` | native | read |
+| `mg-axi entra entitlement access-package list` | native | read |
+| `mg-axi entra entitlement access-package show` | native | read |
+| `mg-axi entra entitlement access-package count` | native | read |
+| `mg-axi entra entitlement assignment-policy list` | native | read |
+| `mg-axi entra entitlement assignment-policy show` | native | read |
+| `mg-axi entra entitlement assignment-policy count` | native | read |
+| `mg-axi entra entitlement resource-role-scope list` | native | read |
+| `mg-axi entra entitlement resource-role-scope show` | native | read |
+| `mg-axi entra entitlement resource-role-scope count` | native | read |
+| `mg-axi entra entitlement assignment list` | native | read |
+| `mg-axi entra entitlement assignment show` | native | read |
+| `mg-axi entra entitlement assignment count` | native | read |
+| `mg-axi entra entitlement assignment-request list` | native | read |
+| `mg-axi entra entitlement assignment-request show` | native | read |
+| `mg-axi entra entitlement assignment-request count` | native | read |
+| `mg-axi entra lifecycle workflow list` | native | read |
+| `mg-axi entra lifecycle workflow show` | native | read |
+| `mg-axi entra lifecycle workflow count` | native | read |
+| `mg-axi entra lifecycle workflow-template list` | native | read |
+| `mg-axi entra lifecycle workflow-template show` | native | read |
+| `mg-axi entra lifecycle workflow-template count` | native | read |
+| `mg-axi entra lifecycle task-definition list` | native | read |
+| `mg-axi entra lifecycle task-definition show` | native | read |
+| `mg-axi entra lifecycle task-definition count` | native | read |
+| `mg-axi entra lifecycle settings show` | native | read |
+| `mg-axi entra lifecycle run list` | native | read |
+| `mg-axi entra lifecycle run show` | native | read |
+| `mg-axi entra lifecycle run count` | native | read |
+| `mg-axi entra lifecycle user-processing-result list` | native | read |
+| `mg-axi entra lifecycle user-processing-result show` | native | read |
+| `mg-axi entra lifecycle user-processing-result count` | native | read |
+| `mg-axi entra lifecycle subject-processing-result list` | native | read |
+| `mg-axi entra lifecycle subject-processing-result show` | native | read |
+| `mg-axi entra lifecycle subject-processing-result count` | native | read |
+| `mg-axi entra lifecycle task-report list` | native | read |
+| `mg-axi entra lifecycle task-report show` | native | read |
+| `mg-axi entra lifecycle task-report count` | native | read |
+| `mg-axi entra lifecycle task-report task show` | native | read |
+| `mg-axi entra lifecycle task-report task-definition show` | native | read |
+| `mg-axi api get` | native | read |
+<!-- command-registry:end -->
+
+Run `npx -y @knowttl/mg-axi <leaf-path> --help` for that leaf's accepted flags and reference.
+Unknown flags fail before any credential or HTTP work.
+
+## Next steps
+
+The no-args home view prints these hints alongside live profile status:
+
+```sh
+npx -y @knowttl/mg-axi profile list
+npx -y @knowttl/mg-axi login --help
+npx -y @knowttl/mg-axi setup
+npx -y @knowttl/mg-axi doctor
+npx -y @knowttl/mg-axi entra user list --help
+npx -y @knowttl/mg-axi entra user show --help
+npx -y @knowttl/mg-axi entra group list --help
+npx -y @knowttl/mg-axi entra group member list --help
+npx -y @knowttl/mg-axi entra application list --help
+npx -y @knowttl/mg-axi entra service-principal list --help
+npx -y @knowttl/mg-axi entra conditional-access policy list --help
+npx -y @knowttl/mg-axi api get --help
+```
+
+## Setup (explicit only)
+
+Follow [release guidance](../../README.md#release) for npm installation and explicit skill installation; [README.md](../../README.md#mg-axi) also documents checkout builds.
+Create profiles explicitly and keep secrets out of argv and config files:
+
+```sh
+npx -y @knowttl/mg-axi setup                    # build steps, config path and capabilities; writes nothing
+npx -y @knowttl/mg-axi profile create --name soc --tenant <tenant-id> --client <client-id> --cloud commercial
+npx -y @knowttl/mg-axi login --profile soc --scopes https://graph.microsoft.com/User.Read.All
+npx -y @knowttl/mg-axi doctor                   # one bounded read per selected profile
+npx -y @knowttl/mg-axi entra user list --profile soc --limit 10
+```
+
+Configuration defaults to `~/.mg-axi/config.json`; `MG_AXI_CONFIG` selects a separate file.
+`mg-axi setup` shows the selected path and writes nothing.
+
+## Selecting a profile
+
+Read leaves accept `--profile <name>`.
+Selection uses `--profile` or the configured default.
+Without either, read leaves report `AUTH_REQUIRED`, even if only one profile exists.
+Doctor selection is documented in [README.md](../../README.md#release).
+Without profiles, home, setup and profile list show unconfigured state; Graph read leaves report `AUTH_REQUIRED`.
+
+## Safety
+
+Reads run through a session that authorizes only catalogued operations before silent credential acquisition; only explicit `login` opens a browser or prints a device-code challenge.
+Writes preview before sending and need `--execute` plus a typed `--confirm` repeating the target; an already-desired value is a no-op with exit 0, never an error.
+Output is TOON on stdout; diagnostics use stderr.
+Text truncates at 500 characters (`--full` restores text, never redaction); row caps resume through opaque cursors.
+Secrets stay in protected storage references, never in argv, config files or output; credential fields carry expiry metadata only.
+Tests run offline with fixture credentials; never point tests at a real tenant.