@platless/axom-cli 0.1.0 → 0.3.13

package/dist/commands/workstation.js

@@ -54,8 +54,8 @@ async function ensureRegistered(deps, serverFlag, nameFlag) {
  * that runs in `/workspace` — a container is precisely where this product runs untrusted code. What
  * would leak is not the workstation's own key pair (scoped to one workstation, on disk) but a
  * credential that authenticates *as the user*: it can register further workstations under their
- * account and, with the `mcp` scope, call every MCP tool as them, until somebody notices and revokes
- * it. Fixed once here rather than filtered at each of the two spawn sites, so the next spawn site
+ * account and, with business scopes, call granted MCP tools as them, until somebody notices and
+ * revokes it. Fixed once here rather than filtered at each of the two spawn sites, so the next spawn site
  * inherits the fix instead of having to remember it.
  *
  * Nothing after this point needs the value. The daemon authenticates with the file credential

package/dist/credentials.js

@@ -168,8 +168,8 @@ async function refreshRequest(server, refreshToken) {
         }),
     });
 }
-export async function revokeRefreshToken(server, refreshToken) {
-    await fetch(`${normalizedServer(server)}/oauth/revoke`, {
+export async function revokeRefreshToken(server, refreshToken, fetch_ = globalThis.fetch) {
+    await fetch_(`${normalizedServer(server)}/oauth/revoke`, {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({ token: refreshToken, token_type_hint: 'refresh_token', client_id: 'axom-cli' }),

package/dist/install/claude/commands.js

@@ -8,8 +8,8 @@ Use the Axomwork MCP tools to answer this structural question about the platform
 $ARGUMENTS
 
 Workflow:
-1. \`axom__struct__list_applications\` to see applications; \`axom__struct__get_application\` for one app's models and menus.
-2. \`axom__struct__list_models\` / \`axom__struct__get_model\` for a model's attributes, operations, and display metadata.
+1. \`axom__app_struct__list_applications\` to see applications; \`axom__app_struct__get_application\` for one app's models and menus.
+2. \`axom__app_struct__list_models\` / \`axom__app_struct__get_model\` for a model's attributes, operations, and display metadata.
 3. Prefer read-only struct tools here; do not mutate anything from this command.
 
 For the underlying concepts (applications, models, attributes, references), load guide \`concepts/data-model/index.md\` with \`axom__guide__load\`.
@@ -23,10 +23,10 @@ Use the Axomwork MCP record tools to fulfil this request:
 $ARGUMENTS
 
 Workflow:
-1. Discover structure first when unsure: \`axom__struct__get_model\` for attribute names and types.
-2. Query with \`axom__record__query\` (filters/sorts/page criteria — for criteria syntax, load guide \`agent-integration/mcp/record-query-criteria.md\`).
-3. Mutate with \`axom__record__create\` / \`axom__record__update\` / \`axom__record__upsert\` / \`axom__record__delete\`. Read the record first before updating; confirm with the user before deleting.
-4. \`axom__record__upsert\` needs \`identityField\` and the identity value inside \`record\`.
+1. Discover structure first when unsure: \`axom__app_struct__get_model\` for attribute names and types.
+2. Query with \`axom__record_query__query_records\` (filters/sorts/page criteria — for criteria syntax, load guide \`agent-integration/mcp/record-query-criteria.md\`).
+3. Mutate with \`axom__record_write__create_record\` / \`axom__record_write__update_record\` / \`axom__record_write__upsert_record\` / \`axom__record_write__delete_record\`. Read the record first before updating; confirm with the user before deleting.
+4. \`axom__record_write__upsert_record\` needs \`identityField\` and the identity value inside \`record\`.
 
 For safe mutation patterns, load guide \`agent-integration/operating-patterns/safe-record-mutations.md\`.
 `,
@@ -39,18 +39,18 @@ Execute the requested Axomwork operation or service:
 $ARGUMENTS
 
 Workflow:
-1. Find the operation on its model (\`axom__struct__get_model\`) or the service by name.
-2. Call \`axom__operation__execute\` (applicationName/modelName/operationName/input) or \`axom__service__execute\` (serviceName/input).
+1. Find the operation on its model (\`axom__app_struct__get_model\`) or the service by name.
+2. Call \`axom__execute__run_operation\` (applicationName/modelName/operationName/input) or \`axom__execute__run_service\` (serviceName/input).
 3. Interpret the ExecuteResult payload: \`status\` (success/failure/running), \`message\`, \`text\`, \`returnValue\`, \`runId\`/\`runType\`, \`errors[]\` ({target,code,message}).
 4. When \`status\` is \`running\`, follow \`runId\` (see \`runType\`) until a terminal state before reporting the outcome.
 
 For sync-vs-job semantics load guide \`concepts/execution/synchronous-and-task-execution.md\`; for run following load guide \`agent-integration/operating-patterns/following-runs.md\`.
 `,
     definition: `---
-description: Develop Axomwork definitions — apps, models, attributes, operations, workflows (requires ADMIN)
+description: Develop Axomwork definitions — apps, models, attributes, operations, workflows (requires app_studio scope and an admin account)
 ---
 
-You are editing Axomwork application definitions with the canonical \`axom__definition__*\` MCP tools (ADMIN token required).
+You are editing Axomwork application definitions with the canonical \`axom__app_studio__*\` MCP tools (requires the \`app_studio\` scope and an administrator account).
 
 $ARGUMENTS
 
@@ -61,16 +61,16 @@ Rules:
 4. Confirm destructive definition deletes with the user first.
 `,
     platform: `---
-description: Operate Axomwork platform configuration — AI vendors/profiles, cowork agents, datasources, platform skills and settings (requires ADMIN)
+description: Operate Axomwork platform configuration — AI providers/profiles, cowork agents, datasources, platform skills and settings (requires setting_platform scope and an admin account)
 ---
 
-You are operating Axomwork platform configuration with the canonical \`axom__platform__*\` MCP tools (skills, settings, AI vendors/profiles/memory, cowork agents, data sources; ADMIN token required).
+You are operating Axomwork platform configuration with the canonical \`axom__setting_platform__*\` MCP tools (skills, settings, AI providers/profiles/memory, cowork agents, data sources; requires the \`setting_platform\` scope and an administrator account).
 
 $ARGUMENTS
 
 Rules:
 1. Read current configuration before editing; respect ETag guards where tools expose them.
-2. For configuration semantics (AI vendors and profiles, cowork agents, datasources, platform skills and settings), load guide \`platform-operations/index.md\` first.
+2. For configuration semantics (AI providers and profiles, cowork agents, datasources, platform skills and settings), load guide \`platform-operations/index.md\` first.
 3. Confirm with the user before changes that can interrupt running workflows or agent sessions.
 `,
     guide: `---

package/dist/mcp.js

@@ -11,7 +11,7 @@ export async function callAxomTool(server, toolName, args) {
     }
     catch (error) {
         if (isInsufficientScope(error))
-            throw insufficientScopeError(normalizedServer);
+            throw insufficientScopeError(normalizedServer, toolName);
         if (!isUnauthorized(error))
             throw error;
         // An env token cannot be refreshed: `accessTokenFor` returns the same literal whatever
@@ -28,7 +28,7 @@ export async function callAxomTool(server, toolName, args) {
     }
     catch (error) {
         if (isInsufficientScope(error))
-            throw insufficientScopeError(normalizedServer);
+            throw insufficientScopeError(normalizedServer, toolName);
         if (isUnauthorized(error)) {
             throw new AuthError(`MCP authentication failed with ${normalizedServer}. Run: axom auth --server ${normalizedServer}`);
         }
@@ -45,7 +45,7 @@ async function callAxomToolOnce(server, token, toolName, args) {
     try {
         await client.connect(transport);
         const result = await client.callTool({ name: toolName, arguments: args });
-        return toToolOutcome(result);
+        return addPermissionAdvice(toolName, toToolOutcome(result));
     }
     finally {
         try {
@@ -89,12 +89,7 @@ function isUnauthorized(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /\b401\b/.test(message);
 }
-/**
- * `/mcp` returns 403 (not 401) when the bearer token is valid but lacks the `mcp` scope — this is
- * how a `workstation`-only access token (the default for a token minted without `--scope mcp`)
- * looks from the client. Retrying with a refreshed token would not help, since the new token would
- * carry the same scopes, so this is checked before the 401/refresh path, not folded into it.
- */
+/** A 403 is an authorization refusal, so refreshing the same grant cannot make it succeed. */
 export function isInsufficientScope(error) {
     const candidate = error;
     if (candidate.status === 403 || candidate.code === 403 || candidate.response?.status === 403)
@@ -102,11 +97,34 @@ export function isInsufficientScope(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /\b403\b/.test(message);
 }
-export function insufficientScopeError(server) {
-    const hint = usesEnvAccessToken()
-        ? ' Set AXOM_ACCESS_TOKEN to a token that includes the "mcp" scope, or run axom auth.'
-        : '';
-    return new AuthError(`MCP token is missing the "mcp" scope for ${server}.${hint}`);
+/** Abilities every credential has (Ability registry: BASELINE with the MCP surface). */
+const BASELINE_TOOL_SCOPES = new Set(['system', 'guide', 'app_struct']);
+const TOOL_SCOPE = /^axom__([a-z][a-z0-9]*(?:_[a-z0-9]+)*)__[a-z]/;
+const ADMIN_NOTE = ' Scopes marked "Requires an administrator account" on the consent page also need an administrator user.';
+/** An external tool's middle segment IS the OAuth scope that grants it (spec 2026-09-26 §3.5). */
+export function scopeForTool(toolName) {
+    const scope = toolName ? TOOL_SCOPE.exec(toolName)?.[1] : undefined;
+    return scope && !BASELINE_TOOL_SCOPES.has(scope) ? scope : undefined;
+}
+export function insufficientScopeError(server, toolName) {
+    const scope = scopeForTool(toolName);
+    if (!scope)
+        return new AuthError(`MCP authorization was denied by ${server}. Check this credential's approved scopes.`);
+    const remedy = usesEnvAccessToken()
+        ? ` Create or edit an access token under Settings → Security and grant ${scope}.`
+        : ` Run axom auth --server ${server} and select ${scope}.`;
+    return new AuthError(`MCP authorization was denied by ${server}. Required OAuth scope: ${scope}.${remedy}${ADMIN_NOTE}`);
+}
+function addPermissionAdvice(toolName, outcome) {
+    if (!outcome.isError || !isPermissionFailure(outcome.text))
+        return outcome;
+    const scope = scopeForTool(toolName);
+    if (!scope)
+        return outcome;
+    return { ...outcome, text: `${outcome.text}\nRequired OAuth scope: ${scope}.${ADMIN_NOTE}` };
+}
+function isPermissionFailure(message) {
+    return /permission denied|not authorized|forbidden|insufficient[_ ]scope|MCP grant is no longer valid/i.test(message);
 }
 /**
  * Is this process authenticating with `AXOM_ACCESS_TOKEN` rather than a stored login? Mirrors