@agentxm/client-core 0.4.2 → 0.4.3

package/README.md

@@ -0,0 +1,11 @@
+# @agentxm/client-core
+
+> ⚠️ **Unstable, unsupported library.** This package exists to support the
+> [`axm.sh`](https://www.npmjs.com/package/axm.sh) CLI. Its APIs live under
+> `./unstable/*` and can change or disappear in any release without notice.
+>
+> **Use the [`axm.sh`](https://www.npmjs.com/package/axm.sh) CLI instead.**
+>
+> See https://axm.sh.
+
+MIT © 2025-2026 AgentXM, Inc.

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@agentxm/client-core",
-  "version": "0.4.2",
-  "description": "Core library for the axm agent extension manager",
+  "version": "0.4.3",
+  "description": "Core library for the axm agent extension manager. Unstable and unsupported — use the axm.sh CLI.",
   "type": "module",
   "license": "MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
   "repository": {
     "type": "git",
     "url": "https://github.com/agentxm/axm.git",
@@ -11,175 +16,176 @@
   },
   "exports": {
     "./unstable/app-error": {
-      "types": "./src/unstable/app-error/index.ts",
+      "types": "./dist/src/unstable/app-error/index.d.ts",
       "default": "./dist/src/unstable/app-error/index.js"
     },
     "./unstable/prompt-cancelled": {
-      "types": "./src/unstable/cli-prompt/prompt-cancelled.ts",
+      "types": "./dist/src/unstable/cli-prompt/prompt-cancelled.d.ts",
       "default": "./dist/src/unstable/cli-prompt/prompt-cancelled.js"
     },
     "./unstable/version-constraints": {
-      "types": "./src/unstable/version-constraints/version-constraints.ts",
+      "types": "./dist/src/unstable/version-constraints/version-constraints.d.ts",
       "default": "./dist/src/unstable/version-constraints/version-constraints.js"
     },
     "./unstable/branding": {
-      "types": "./src/unstable/branding.ts",
+      "types": "./dist/src/unstable/branding.d.ts",
       "default": "./dist/src/unstable/branding.js"
     },
     "./unstable/date-time": {
-      "types": "./src/unstable/date-time.ts",
+      "types": "./dist/src/unstable/date-time.d.ts",
       "default": "./dist/src/unstable/date-time.js"
     },
     "./unstable/utils": {
-      "types": "./src/unstable/utils/index.ts",
+      "types": "./dist/src/unstable/utils/index.d.ts",
       "default": "./dist/src/unstable/utils/index.js"
     },
     "./unstable/agents": {
-      "types": "./src/unstable/agents/index.ts",
+      "types": "./dist/src/unstable/agents/index.d.ts",
       "default": "./dist/src/unstable/agents/index.js"
     },
     "./unstable/extensions": {
-      "types": "./src/unstable/extensions/index.ts",
+      "types": "./dist/src/unstable/extensions/index.d.ts",
       "default": "./dist/src/unstable/extensions/index.js"
     },
     "./unstable/extensions/common": {
-      "types": "./src/unstable/extensions/common.ts",
+      "types": "./dist/src/unstable/extensions/common.d.ts",
       "default": "./dist/src/unstable/extensions/common.js"
     },
     "./unstable/extensions/fqn": {
-      "types": "./src/unstable/extensions/fqn.ts",
+      "types": "./dist/src/unstable/extensions/fqn.d.ts",
       "default": "./dist/src/unstable/extensions/fqn.js"
     },
     "./unstable/extensions/handle": {
-      "types": "./src/unstable/extensions/handle.ts",
+      "types": "./dist/src/unstable/extensions/handle.d.ts",
       "default": "./dist/src/unstable/extensions/handle.js"
     },
     "./unstable/extensions/registry-source": {
-      "types": "./src/unstable/extensions/registry-source.ts",
+      "types": "./dist/src/unstable/extensions/registry-source.d.ts",
       "default": "./dist/src/unstable/extensions/registry-source.js"
     },
     "./unstable/lockfile": {
-      "types": "./src/unstable/lockfile/index.ts",
+      "types": "./dist/src/unstable/lockfile/index.d.ts",
       "default": "./dist/src/unstable/lockfile/index.js"
     },
     "./unstable/schema": {
-      "types": "./src/unstable/schema/index.ts",
+      "types": "./dist/src/unstable/schema/index.d.ts",
       "default": "./dist/src/unstable/schema/index.js"
     },
     "./unstable/settings": {
-      "types": "./src/unstable/settings/index.ts",
+      "types": "./dist/src/unstable/settings/index.d.ts",
       "default": "./dist/src/unstable/settings/index.js"
     },
     "./unstable/sources": {
-      "types": "./src/unstable/sources/index.ts",
+      "types": "./dist/src/unstable/sources/index.d.ts",
       "default": "./dist/src/unstable/sources/index.js"
     },
     "./unstable/cli-flags": {
-      "types": "./src/unstable/cli-flags/index.ts",
+      "types": "./dist/src/unstable/cli-flags/index.d.ts",
       "default": "./dist/src/unstable/cli-flags/index.js"
     },
     "./unstable/cli-runtime": {
-      "types": "./src/unstable/cli-runtime/index.ts",
+      "types": "./dist/src/unstable/cli-runtime/index.d.ts",
       "default": "./dist/src/unstable/cli-runtime/index.js"
     },
     "./unstable/telemetry": {
-      "types": "./src/unstable/telemetry/index.ts",
+      "types": "./dist/src/unstable/telemetry/index.d.ts",
       "default": "./dist/src/unstable/telemetry/index.js"
     },
     "./unstable/cli-renderer": {
-      "types": "./src/unstable/cli-renderer/index.ts",
+      "types": "./dist/src/unstable/cli-renderer/index.d.ts",
       "default": "./dist/src/unstable/cli-renderer/index.js"
     },
     "./unstable/git": {
-      "types": "./src/unstable/git/index.ts",
+      "types": "./dist/src/unstable/git/index.d.ts",
       "default": "./dist/src/unstable/git/index.js"
     },
     "./unstable/registry": {
-      "types": "./src/unstable/registry/index.ts",
+      "types": "./dist/src/unstable/registry/index.d.ts",
       "default": "./dist/src/unstable/registry/index.js"
     },
     "./unstable/auth": {
-      "types": "./src/unstable/auth/index.ts",
+      "types": "./dist/src/unstable/auth/index.d.ts",
       "default": "./dist/src/unstable/auth/index.js"
     },
     "./unstable/plan": {
-      "types": "./src/unstable/plan/index.ts",
+      "types": "./dist/src/unstable/plan/index.d.ts",
       "default": "./dist/src/unstable/plan/index.js"
     },
     "./unstable/lint": {
-      "types": "./src/unstable/lint/index.ts",
+      "types": "./dist/src/unstable/lint/index.d.ts",
       "default": "./dist/src/unstable/lint/index.js"
     },
     "./unstable/workspace": {
-      "types": "./src/unstable/workspace/index.ts",
+      "types": "./dist/src/unstable/workspace/index.d.ts",
       "default": "./dist/src/unstable/workspace/index.js"
     },
     "./unstable/source-resolution": {
-      "types": "./src/unstable/source-resolution/index.ts",
+      "types": "./dist/src/unstable/source-resolution/index.d.ts",
       "default": "./dist/src/unstable/source-resolution/index.js"
     },
     "./unstable/skills": {
-      "types": "./src/unstable/skills/index.ts",
+      "types": "./dist/src/unstable/skills/index.d.ts",
       "default": "./dist/src/unstable/skills/index.js"
     },
     "./unstable/packs": {
-      "types": "./src/unstable/packs/index.ts",
+      "types": "./dist/src/unstable/packs/index.d.ts",
       "default": "./dist/src/unstable/packs/index.js"
     },
     "./unstable/commands": {
-      "types": "./src/unstable/commands/index.ts",
+      "types": "./dist/src/unstable/commands/index.d.ts",
       "default": "./dist/src/unstable/commands/index.js"
     },
     "./unstable/mcp-servers": {
-      "types": "./src/unstable/mcp-servers/index.ts",
+      "types": "./dist/src/unstable/mcp-servers/index.d.ts",
       "default": "./dist/src/unstable/mcp-servers/index.js"
     },
     "./unstable/workflows": {
-      "types": "./src/unstable/workflows/index.ts",
+      "types": "./dist/src/unstable/workflows/index.d.ts",
       "default": "./dist/src/unstable/workflows/index.js"
     },
     "./unstable/publish": {
-      "types": "./src/unstable/publish/index.ts",
+      "types": "./dist/src/unstable/publish/index.d.ts",
       "default": "./dist/src/unstable/publish/index.js"
     },
     "./unstable/site-content/schemas/*": "./site-content/__generated__/schemas/*",
     "./unstable/site-content/*": "./site-content/*",
     "./unstable/install-method": {
-      "types": "./src/unstable/install-method/install-method.ts",
+      "types": "./dist/src/unstable/install-method/install-method.d.ts",
       "default": "./dist/src/unstable/install-method/install-method.js"
     },
     "./unstable/install-meta": {
-      "types": "./src/unstable/install-meta/install-meta.ts",
+      "types": "./dist/src/unstable/install-meta/install-meta.d.ts",
       "default": "./dist/src/unstable/install-meta/install-meta.js"
     },
     "./unstable/update-check": {
-      "types": "./src/unstable/update-check/update-check.ts",
+      "types": "./dist/src/unstable/update-check/update-check.d.ts",
       "default": "./dist/src/unstable/update-check/update-check.js"
     },
     "./unstable/version-resolution": {
-      "types": "./src/unstable/version-resolution/version-resolution.ts",
+      "types": "./dist/src/unstable/version-resolution/version-resolution.d.ts",
       "default": "./dist/src/unstable/version-resolution/version-resolution.js"
     },
     "./unstable/packaging": {
-      "types": "./src/unstable/packaging/index.ts",
+      "types": "./dist/src/unstable/packaging/index.d.ts",
       "default": "./dist/src/unstable/packaging/index.js"
     },
     "./unstable/discover": {
-      "types": "./src/unstable/discover/index.ts",
+      "types": "./dist/src/unstable/discover/index.d.ts",
       "default": "./dist/src/unstable/discover/index.js"
     },
     "./unstable/subagents": {
-      "types": "./src/unstable/subagents/index.ts",
+      "types": "./dist/src/unstable/subagents/index.d.ts",
       "default": "./dist/src/unstable/subagents/index.js"
     },
     "./unstable/cli/prompt": {
-      "types": "./src/unstable/cli/prompt/index.ts",
+      "types": "./dist/src/unstable/cli/prompt/index.d.ts",
       "default": "./dist/src/unstable/cli/prompt/index.js"
     }
   },
   "files": [
     "dist/src/",
-    "site-content/"
+    "site-content/",
+    "!**/*.map"
   ],
   "publishConfig": {
     "access": "public"
@@ -209,6 +215,6 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",
     "yaml": "^2.8.2",
-    "@agentxm/client-utils": "0.4.2"
+    "@agentxm/client-utils": "^0.4.3"
   }
 }

package/site-content/install.md

@@ -1,14 +1,24 @@
 # Install axm
 
-**DONE WHEN:** `axm --version && axm whoami` both succeed.
+**DONE WHEN:** `axm --version` succeeds and (if the user chose workspace setup)
+`axm setup` has completed.
 
 ---
 
 ## TODO
 
-- [ ] Install axm CLI
-- [ ] Authenticate
-- [ ] Verify
+- [ ] Detect existing install (`axm --version`)
+- [ ] If installed: `axm upgrade`. Otherwise: detect available package
+      managers (brew, npm) and pick the install method
+- [ ] If multiple install methods are available: ask the user which to use
+- [ ] Run the chosen installer
+- [ ] Verify `axm --version`
+- [ ] Check sign-in state with `axm whoami --json`
+- [ ] If not signed in: ask the user to choose between signing in to
+      AgentXM.ai or going directly to workspace setup
+- [ ] If the user chose to sign in: hand off signup/login, then re-check
+      `axm whoami`
+- [ ] Run `axm setup --yes` to initialize the project workspace
 
 ---
 
@@ -16,12 +26,106 @@
 
 axm is the open extension manager for AI coding agents. It lets you discover,
 install, publish, and manage skills, commands, subagents, MCP servers, and
-extension packs across your AI agents from a single CLI.
+extension packs across your AI agents from a single CLI. axm is the CLI;
+[AgentXM.ai](https://agentxm.ai) is the extension registry it connects to —
+accounts, publishing, and extension discovery live there. An AgentXM.ai
+account is only required for publishing extensions or installing private
+extensions; public extensions install without an account.
 
-## Step 1: Install
+## Detect existing install
 
-Each method below installs a persistent `axm` binary on the machine. Pick the
-one that matches the environment (operating system or package manager).
+Before installing, check whether axm is already on the machine:
+
+```bash
+axm --version
+```
+
+- **Succeeds** (prints `X.Y.Z`) → axm is installed. Upgrade it to the latest
+  version and skip the Install section:
+
+  ```bash
+  axm upgrade
+  ```
+
+  `axm upgrade` auto-detects how axm was installed. For script installs it
+  downloads and swaps the binary in place. For Homebrew or npm installs it
+  prints the exact command to run (`brew upgrade agentxm/tap/axm` or
+  `npm update -g axm.sh`) — run whichever it emits, then re-run
+  `axm --version`. Continue to **Verify** when done.
+
+- **Fails** with `command not found` → axm is not installed. Continue to
+  **Install**.
+- **Fails** with any other error → treat as not installed and reinstall via
+  the Install section.
+
+## Choose install method
+
+axm can be installed via a standalone binary script, Homebrew, or npm. Pick
+based on what's already on the machine — don't install a new package manager
+just to install axm.
+
+### 1. Detect available package managers
+
+Check which package managers are installed. A manager is "available" if the
+`--version` command exits successfully.
+
+On macOS / Linux:
+
+```bash
+brew --version >/dev/null 2>&1 && echo "brew: available"
+npm --version >/dev/null 2>&1 && echo "npm: available"
+```
+
+On Windows (PowerShell):
+
+```powershell
+if (Get-Command brew -ErrorAction SilentlyContinue) { "brew: available" }
+if (Get-Command npm  -ErrorAction SilentlyContinue) { "npm: available"  }
+```
+
+### 2. Pick the method
+
+Use this decision table — same logic on every platform:
+
+| Detected managers              | Chosen method                                                 |
+| ------------------------------ | ------------------------------------------------------------- |
+| Neither                        | Install script (Option A on macOS/Linux, Option B on Windows) |
+| Homebrew only                  | Homebrew (Option D)                                           |
+| npm only                       | npm (Option E)                                                |
+| Homebrew and npm (two or more) | **STOP AND ASK** the user — see the prompt below              |
+
+The install script is always a valid fallback. If a package-manager install
+fails, retry with Option A or B.
+
+### 3. Ask the user when multiple managers are available
+
+All three options install the same axm binary. **The main difference is how
+you'll update it later.** Frame the choice that way when asking.
+
+**STOP HERE AND ASK THE USER:**
+
+> Multiple install methods are available on this machine. The main
+> difference is how you'll update axm later — pick the update path that
+> matches how you manage other tools.
+>
+> 1. **Install script** (recommended) — Updates via `axm upgrade`
+>    (self-managed, independent of any package manager). Standalone binary
+>    installed to `~/.axm/bin` (macOS/Linux) or `%LOCALAPPDATA%\axm`
+>    (Windows). No extra tools required.
+> 2. **Homebrew** — Updates via `brew upgrade agentxm/tap/axm`, alongside
+>    your other brew packages. Choose this if you already manage most CLIs
+>    with brew.
+> 3. **npm** — Updates via `npm update -g axm.sh`, alongside your other
+>    global npm packages. Choose this if axm is part of a Node.js-heavy
+>    environment. Requires Node.js.
+
+Wait for the user's response before continuing. Then run the corresponding
+option below.
+
+## Install
+
+Each option below installs a persistent `axm` binary on the machine. Run the
+option selected in **Choose install method**.
 
 ### Option A: macOS / Linux (install script)
 
@@ -74,67 +178,155 @@ PATH:
 export PATH="$(npm config get prefix)/bin:$PATH"
 ```
 
-**Verify:**
+## Verify
 
 ```bash
 axm --version
 # Expected: X.Y.Z
 ```
 
-## Step 2: Authenticate
+---
 
-### Non-interactive (agents, CI, scripts)
+EXECUTE NOW: Run `axm --version`. If it succeeds, run `axm upgrade`. If it
+fails, detect available package managers per **Choose install method**, ask
+the user if more than one is available, and run the chosen installer. Stop
+when `axm --version` succeeds, then proceed to **Check sign-in state**.
 
-Set the `AXM_TOKEN` environment variable with a pre-provisioned token:
+---
 
-```bash
-export AXM_TOKEN=<your-token>
-```
+## Check sign-in state
 
-If you have already completed an interactive login in another session, you can
-extract a reusable token:
+axm is installed. Before continuing, detect whether this machine is already
+signed in to AgentXM.ai — the result decides whether to ask the user about
+signing in or skip straight to workspace setup.
 
 ```bash
-export AXM_TOKEN=$(axm auth token)
+axm whoami --json
 ```
 
-### Interactive (terminals with a browser)
+- **Exit 0 with an identity** → already signed in. Skip to **Workspace setup**.
+- **Exit non-zero** (for example, error code `AUTH_LOGIN_REQUIRED`) → not
+  signed in. Continue to **Ask the user what to do next**.
 
-```bash
-axm auth login
-```
+## Ask the user what to do next
 
-Opens a browser for OAuth device code authorization. Grant access when prompted.
+This machine is not signed in to AgentXM.ai.
 
-**Verify:**
+Before asking, tell the user why the choice matters: signing in is only
+needed to publish extensions or install private extensions, so the workspace
+can still be set up without it. The choice is about whether to do that
+sign-in now or defer it.
 
-```bash
-axm whoami
-# Expected: displays your handle and account
-```
+**STOP HERE AND ASK THE USER:**
 
----
+> axm is installed. Before setting up the project workspace, would you like
+> to sign in to AgentXM.ai? Signing in is only needed if you plan to
+> publish extensions or install private extensions — public extensions
+> install without an account.
+>
+> 1. **Sign up or log in to AgentXM.ai** (recommended if you plan to
+>    publish extensions or install private extensions)
+> 2. **Proceed to setting up your project workspace** (you can sign in
+>    later with `axm login`)
 
-EXECUTE NOW: Start with Step 1. Mark TODO items complete as you go. Stop when
-`axm --version && axm whoami` both succeed.
+Wait for the user's response before continuing.
+
+- **Option 1** → continue with **Sign up or log in to AgentXM.ai** below,
+  then **Workspace setup**.
+- **Option 2** → skip to **Workspace setup**.
 
 ---
 
-## Optional: Set Up a Project
+## Sign up or log in to AgentXM.ai
+
+AgentXM.ai is the extension registry that axm connects to. Accounts live on
+AgentXM.ai, not in the CLI — `axm login` signs this machine in to an
+AgentXM.ai account.
+
+### If the user does not have an AgentXM.ai account
+
+You cannot create an account for the user. Hand off:
 
-**Do not execute this section unless explicitly requested.**
+1. Tell the user to open https://agentxm.ai/signup and create an account —
+   explain that this sets up the AgentXM.ai account that `axm login` will
+   later authenticate against, and that axm can't create the account
+   because signup happens through the web.
+2. Wait for the user to confirm signup is complete.
+3. Continue to **Log in** below.
+
+### Log in
+
+Explain to the user what logging in will do before handing off: it proves
+to AgentXM.ai that this machine belongs to their account, and stores a
+local token so subsequent `axm` commands can reach the registry.
+
+Offer both paths and let the user pick:
+
+- **Interactive (recommended):** ask the user to run `axm login` in their
+  terminal. Tell them this opens a browser for a one-time OAuth device
+  flow; axm can't run it on their behalf because the browser step requires
+  them to be present.
+- **Non-interactive:** ask the user to export `AXM_TOKEN` in the
+  environment where axm will run. Explain that `AXM_TOKEN` is a
+  pre-generated credential that skips the browser step; you must not
+  paste a token the user has not shared with you.
+
+Wait for the user to confirm sign-in is complete. Tell them you're about to
+re-run `axm whoami --json` to verify the sign-in succeeded before moving
+on:
 
 ```bash
-# Initialize axm in your project directory
-axm setup --non-interactive --yes
+axm whoami --json
+```
+
+If it returns an identity, continue to **Workspace setup**. If not, the
+sign-in did not complete — explain which check failed and ask the user to
+retry the same path or switch paths.
+
+---
 
-# Install a skill
-axm skills install @acme/skills/code-review --yes --non-interactive
+## Workspace setup
 
-# See what's installed
-axm skills list --json
+Before running the command, tell the user what it will do to their project:
+create `.axm/` configuration files, install default extensions (including
+`@agentxm/skills/axm`), and register agent discovery symlinks in the
+current working directory.
+
+Run:
+
+```bash
+axm setup --yes
 ```
 
+Once it succeeds, consult the installed `@agentxm/skills/axm` skill for
+day-to-day operations — workspace scenarios (greenfield, brownfield,
+unmanaged skills), extension management, and publishing.
+
+## Invariants
+
+- **Explain why you're asking.** Whenever you need the user's consent, input,
+  or out-of-band action — picking an install method, running `axm login`,
+  opening a signup URL, approving a command you'd otherwise run yourself —
+  state the purpose first: what you're about to do, why it's needed for
+  this install, and what the user should do next. No yes/no prompts without
+  context; no command handoffs without explaining the effect.
+- **Never** run `axm login` without explicit user consent. The device flow
+  opens a browser and requires the user to be present. When requesting
+  consent, tell the user that `axm login` will open a browser, complete an
+  OAuth device flow with AgentXM.ai, and store a local token so axm can
+  talk to the registry on their behalf.
+- **Never** set or paste an `AXM_TOKEN` the user has not shared. If the
+  user is providing a token, explain that it authenticates the CLI against
+  the user's AgentXM.ai account for the current shell session.
+- **Always** re-run `axm whoami` after any user-driven sign-in step before
+  running `axm setup`. Tell the user you're verifying the sign-in succeeded
+  before moving on.
+- **Resume, do not restart.** If the user completes sign-in out-of-band and
+  returns, skip to **Workspace setup** — do not re-ask which option they
+  picked.
+
+---
+
 ## Troubleshooting
 
 **`axm: command not found`**
@@ -157,26 +349,3 @@ The fix depends on how you installed:
   ```bash
   export PATH="$(npm config get prefix)/bin:$PATH"
   ```
-
-**Not authenticated / `AUTH_LOGIN_REQUIRED`**
-
-```bash
-axm auth login
-# Or for non-interactive: export AXM_TOKEN=<token>
-```
-
-**Wrong account**
-
-```bash
-axm auth logout && axm auth login
-```
-
-**Registry unreachable**
-
-```bash
-# Check connectivity to the default registry
-curl -sf https://registry.agentxm.ai/v1/health || echo "Registry unreachable"
-# Or override the built-in default source for development/testing:
-export AXM_REGISTRY_LOCATION=http://localhost:4300
-# AXM_REGISTRY_LOCATION may also be a file path or file:// URL
-```