@knowttl/mg-axi 0.1.8 → 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 knowttl and mg-axi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -294,7 +294,7 @@ Only explicit login persists credentials; silent refresh keeps refreshed credent
 Access tokens are excluded from the persisted MSAL cache.
 `auth logout` deletes the selected profile's cache and is idempotent; MSAL exposes no upstream token revocation API, so organizational revocation remains separate.
 `auth status` reports the selected identity, Graph endpoint, secret source names or paths, and local availability without signing in or making a live request.
-The old top-level `login` remains an alias for one minor release.
+The old top-level `login` remains an alias for one minor release; see [Versioning and releases](#versioning-and-releases).
 Tokens remain opaque and never appear in profile views, stdout or authentication diagnostics.
 Credential acquisition is bound to the configured tenant/client and refreshes at a 60-second expiry margin.
 
@@ -336,7 +336,7 @@ Prefer certificates or federation over bearer client secrets, and rotate secrets
 
 Federation reads the assertion file on every acquisition so projected tokens can rotate.
 Use `--federated-token-file <absolute-path>` for a projected assertion file, or set the default `MG_AXI_TOKEN` assertion value through the environment.
-When the token reference is the default `MG_AXI_TOKEN` env holder and that variable is unset, `AZURE_FEDERATED_TOKEN_FILE` stays accepted as a deprecated alias for one minor release with a stderr notice; `MG_AXI_TOKEN` takes precedence and the alias must name an absolute file path.
+When the token reference is the default `MG_AXI_TOKEN` env holder and that variable is unset, `AZURE_FEDERATED_TOKEN_FILE` stays accepted as a deprecated alias for one minor release with a stderr notice; see [Versioning and releases](#versioning-and-releases). `MG_AXI_TOKEN` takes precedence and the alias must name an absolute file path.
 References, rather than values, are stored in configuration; rotation updates the environment or file without changing the profile.
 Application credentials remain in process memory and are reacquired at a 60-second expiry margin.
 See [headless credential guidance](docs/headless-credentials.md) for holder examples.
@@ -358,9 +358,22 @@ corepack pnpm run docs:check
 
 Tests use fixture credentials and transports without signing in or contacting real tenants.
 The test script limits concurrency to four files.
+Pull requests rely on local validation; there is no GitHub test CI.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for isolated dependency installation, focused tests and contribution checks.
 To use the built checkout binary on PATH, run `npm link --ignore-scripts` from the checkout root.
 Otherwise substitute `node dist/bin/mg-axi.js` for `mg-axi` in examples.
 
 The agent skill and capability report are generated from the command catalogue, documentation template and discovery inventory.
 After changing their sources, run `corepack pnpm run docs:generate`, then `corepack pnpm run docs:check`.
 The [implementation plan](PLAN.md), [operation inventory](docs/inventory.md) and [execution contract](docs/execution.md) describe design and coverage boundaries.
+
+## Versioning and releases
+
+During 0.x development, feature changes continue to produce patch releases under the existing release configuration.
+A minor version is cut only intentionally.
+The deprecated top-level `login` and `AZURE_FEDERATED_TOKEN_FILE` aliases remain supported through the next intentionally cut minor release and become eligible for removal after that release.
+Patch releases do not expire either alias.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/catalogue.js

@@ -2875,9 +2875,10 @@ export function operationFor(leaf, version) {
     const inventory = JSON.parse(readFileSync(new URL("../inventory/operations.json", import.meta.url), "utf8"));
     return inventory.operations.find((row) => row.id === `${version}:${leaf.operation}`);
 }
-// Next-step hints shared by the no-args home view and the installable
+// Base next-step hints shared by the no-args home view and the installable
 // skill, so the two cannot drift apart. home() prints them alongside live
-// profile status; skillDocument() in docs.ts reprints them.
+// profile status; skillDocument() in docs.ts reprints them. localHome() in
+// cli.ts may append one conditional skill install hint (see skill-hint.ts).
 export const HOME_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"];
 // A useful local status, without treating unavailable tenant summaries as zeros.
 export function home() {

package/dist/cli.js

@@ -6,6 +6,7 @@ import { AxiError, installSessionStartHooks, runAxiCli } from "axi-sdk-js";
 import { LEAVES, home, leafHelp, operationFor, resolveCommand, DESCRIPTION, TOP_LEVEL_HELP } from "./catalogue.js";
 import { VERSION } from "./version.js";
 import { Profiles } from "./profiles.js";
+import { skillHint } from "./skill-hint.js";
 import { authStatus } from "./auth-status.js";
 import { redactSecrets } from "./redact.js";
 import { GraphSession, MAX_CURSOR_BYTES } from "./graph-session.js";
@@ -66,6 +67,10 @@ function localHome(name, config) {
             output.profile = "unavailable: no default profile selected";
     }
     output.help.unshift("npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help");
+    // Point agents at the installable skill until it is installed for their host.
+    const hint = skillHint();
+    if (hint !== undefined)
+        output.help.push(hint);
     return output;
 }
 // One dispatch for the hook installer: resolve the sibling hook entry point

package/dist/docs.js

@@ -135,9 +135,11 @@ export function skillDescription() {
     const writes = skillWriteLabels();
     return `Inspect Microsoft Entra ${areas.join(", ")} and run ${writes.length} gated writes (${writes.join(", ")}) through token-efficient TOON output.`;
 }
-// Next-step hints printed by the no-args home view. The two leading entries mirror the
+// Base next-step hints printed by the no-args home view. The two leading entries mirror the
 // profile/login hints localHome() in cli.ts prepends to HOME_HELP; the
 // rest is HOME_HELP verbatim, so skill and home view cannot drift apart.
+// localHome() may append one conditional skill install hint from skill-hint.ts
+// when the skill is missing for the current host; the installed skill omits it.
 export function skillHomeHints() {
     return ["npx -y @knowttl/mg-axi profile list", "npx -y @knowttl/mg-axi auth login --help", ...HOME_HELP];
 }

package/dist/skill-hint.js

@@ -0,0 +1,138 @@
+// One-line skill install hint for the no-args home view. Detects the agent
+// host from its documented environment marker and checks whether the mg-axi
+// skill is already installed for that host, at user, project (working
+// directory upwards) and system level. File-existence checks only: this never
+// installs, writes, fails or touches the network.
+//
+// The check looks only at the detected host's row, so one host's copy never
+// hides another host's hint. Each row lists every documented skill folder
+// that host loads, verified against the real hosts:
+// - Claude Code reads its config directory ($CLAUDE_CONFIG_DIR or ~/.claude,
+//   per its binary) plus ~/.agents/skills and .agents/skills (per its
+//   binary); project .claude/skills loads from the working directory up to
+//   the repository root (per https://code.claude.com/docs/en/skills). When
+//   the working directory is inside a linked git worktree whose root has no
+//   .claude/skills directory, Claude Code (v2.1.277+) falls back to the main
+//   checkout's project skills (per https://code.claude.com/docs/en/worktrees).
+// - Codex reads $HOME/.agents/skills and .agents/skills (cwd to repo root)
+//   per https://learn.chatgpt.com/docs/build-skills.md, plus
+//   $CODEX_HOME/skills (default ~/.codex/skills, per its binary and the
+//   skills-CLI registry) and the documented /etc/codex/skills admin folder.
+// - Pi reads its user/project skills directories plus the Agent Skills
+//   locations ~/.agents/skills/ and .agents/skills/ (ancestors to the repo
+//   root) per its skills.md.
+// - OpenCode reads its config directory ($OPENCODE_CONFIG_DIR,
+//   $XDG_CONFIG_HOME or ~/.config, per its binary and CLI docs) plus
+//   ~/.claude/skills, ~/.agents/skills, .opencode/skills, .claude/skills and
+//   .agents/skills (project paths walk up to the git worktree) per
+//   https://opencode.ai/docs/skills/.
+//
+// Only a direct-child <folder>/mg-axi/SKILL.md counts as installed. Folders
+// listed in host settings files (for example Pi settings.json) and recursive
+// nested layouts are a documented limitation and are deliberately not
+// implemented.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export const SKILL_NAME = "mg-axi";
+export const SKILL_INSTALL_COMMAND = `npx skills add knowttl/${SKILL_NAME} --skill ${SKILL_NAME}`;
+function skillFile(dir) {
+    return join(dir, SKILL_NAME, "SKILL.md");
+}
+function resolveHome(env) {
+    return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+export function skillHostRows(env, home) {
+    const agentsUser = join(home, ".agents", "skills");
+    const agentsProject = join(".agents", "skills");
+    return [
+        {
+            name: "claude-code",
+            userDirs: [join(env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills"), agentsUser],
+            projectDirs: [join(".claude", "skills"), agentsProject],
+            systemDirs: [],
+        },
+        {
+            name: "codex",
+            userDirs: [join(env.CODEX_HOME ?? join(home, ".codex"), "skills"), agentsUser],
+            projectDirs: [agentsProject],
+            systemDirs: ["/etc/codex/skills"],
+        },
+        {
+            name: "pi",
+            userDirs: [join(home, ".pi", "agent", "skills"), agentsUser],
+            projectDirs: [join(".pi", "skills"), agentsProject],
+            systemDirs: [],
+        },
+        {
+            name: "opencode",
+            userDirs: [
+                join(env.OPENCODE_CONFIG_DIR ?? env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode", "skills"),
+                join(home, ".claude", "skills"),
+                agentsUser,
+            ],
+            projectDirs: [join(".opencode", "skills"), join(".claude", "skills"), agentsProject],
+            systemDirs: [],
+        },
+    ];
+}
+// Marker variables each host sets for its own child processes, verified
+// against the real hosts: CLAUDECODE (Claude Code docs), CODEX_THREAD_ID /
+// CODEX_SESSION_ID (codex shell_environment.rs), PI_CODING_AGENT (pi docs),
+// OPENCODE (opencode startup middleware, inherited by its shell children).
+export function detectSkillHost(env, home) {
+    const rows = skillHostRows(env, home);
+    if (env.CLAUDECODE !== undefined)
+        return rows.find(row => row.name === "claude-code");
+    if (env.CODEX_THREAD_ID !== undefined || env.CODEX_SESSION_ID !== undefined)
+        return rows.find(row => row.name === "codex");
+    if (env.PI_CODING_AGENT !== undefined)
+        return rows.find(row => row.name === "pi");
+    if (env.OPENCODE !== undefined)
+        return rows.find(row => row.name === "opencode");
+    return undefined;
+}
+// Main-checkout fallback for a linked git worktree: <worktree>/.git is a file
+// reading "gitdir: <main>/.git/worktrees/<name>". Applies only when the
+// worktree root has no .claude/skills directory of its own.
+function claudeWorktreeSkill(fromDir) {
+    for (let dir = resolve(fromDir);; dir = dirname(dir)) {
+        let gitdir;
+        try {
+            const text = readFileSync(join(dir, ".git"), "utf8");
+            const prefix = "gitdir: ";
+            if (text.startsWith(prefix))
+                gitdir = resolve(dir, text.slice(prefix.length).trim());
+        }
+        catch {
+            gitdir = undefined;
+        }
+        if (gitdir !== undefined) {
+            const splitAt = gitdir.replace(/\\/g, "/").indexOf("/.git/worktrees/");
+            if (splitAt === -1 || existsSync(join(dir, ".claude", "skills")))
+                return false;
+            return existsSync(skillFile(join(gitdir.slice(0, splitAt), ".claude", "skills")));
+        }
+        if (existsSync(join(dir, ".git")) || dirname(dir) === dir)
+            return false;
+    }
+}
+export function skillInstalled(row, fromDir) {
+    if ([...row.userDirs, ...row.systemDirs].some(dir => existsSync(skillFile(dir))))
+        return true;
+    for (let dir = resolve(fromDir);; dir = dirname(dir)) {
+        if (row.projectDirs.some(projectDir => existsSync(skillFile(join(dir, projectDir)))))
+            return true;
+        if (dirname(dir) === dir)
+            break;
+    }
+    if (row.name === "claude-code")
+        return claudeWorktreeSkill(fromDir);
+    return false;
+}
+export function skillHint(env = process.env, fromDir = process.cwd()) {
+    const host = detectSkillHost(env, resolveHome(env));
+    if (host === undefined || skillInstalled(host, fromDir))
+        return undefined;
+    return SKILL_INSTALL_COMMAND;
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@knowttl/mg-axi",
-  "version": "0.1.8",
+  "version": "0.1.10",
+  "license": "MIT",
   "description": "Agent-facing Microsoft Graph CLI, read-only by default",
   "type": "module",
   "bin": {