@kweaver-ai/kweaver-sdk 0.5.0 → 0.5.2

package/dist/auth/oauth.js

@@ -1,10 +1,31 @@
-import { getCurrentPlatform, loadClientConfig, loadTokenConfig, saveClientConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
+import { deleteClientConfig, getCurrentPlatform, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveUserId, saveClientConfig, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
 import { HttpError, NetworkRequestError } from "../utils/http.js";
 const TOKEN_TTL_SECONDS = 3600;
 /** Seconds before access token expiry to trigger refresh (matches Python ConfigAuth). */
 const REFRESH_THRESHOLD_SEC = 60;
 const DEFAULT_REDIRECT_PORT = 9010;
 const DEFAULT_SCOPE = "openid offline all";
+/** Best-effort fetch of display name via EACP userinfo (ShareServer). */
+async function fetchDisplayName(baseUrl, accessToken, tlsInsecure) {
+    try {
+        const res = await runWithTlsInsecure(tlsInsecure, () => fetch(`${baseUrl}/api/eacp/v1/user/get`, {
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
+        }));
+        if (!res.ok)
+            return null;
+        const info = (await res.json());
+        if (typeof info.account === "string")
+            return info.account;
+        if (typeof info.name === "string")
+            return info.name;
+        if (typeof info.mail === "string")
+            return info.mail;
+    }
+    catch {
+        /* Non-critical — displayName will be absent. */
+    }
+    return null;
+}
 /** POSIX shell single-quote escaping for copy-paste commands. */
 export function shellQuoteForShell(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -118,11 +139,132 @@ async function generatePkce() {
     const challenge = createHash("sha256").update(verifier).digest("base64url");
     return { verifier, challenge };
 }
+/**
+ * Pre-flight check: verify that a cached OAuth2 client is still recognised
+ * by the server. Fetches the authorization endpoint with `redirect: "manual"`
+ * and inspects the Location header. Returns false when Hydra redirects to an
+ * error page containing `invalid_client` or similar indicators.
+ */
+async function isClientStillValid(baseUrl, clientId, redirectUri) {
+    try {
+        const params = new URLSearchParams({
+            client_id: clientId,
+            response_type: "code",
+            scope: "openid",
+            redirect_uri: redirectUri,
+            state: "preflight",
+        });
+        const resp = await fetch(`${baseUrl}/oauth2/auth?${params}`, {
+            redirect: "manual",
+        });
+        if (resp.status === 302) {
+            const location = resp.headers.get("location") ?? "";
+            if (location.includes("error=invalid_client") ||
+                location.includes("error=error")) {
+                return false;
+            }
+            return true;
+        }
+        // Non-redirect — Hydra might serve an error page directly
+        if (resp.status >= 400)
+            return false;
+        return true;
+    }
+    catch {
+        // Network error — cannot pre-validate; let the real flow proceed
+        return true;
+    }
+}
+/**
+ * Resolve a cached client or register a new one. When a cached client fails
+ * pre-flight validation (stale registration after server reset), the local
+ * client.json is deleted and a fresh registration is performed.
+ */
+async function resolveOrRegisterClient(baseUrl, redirectUri, scope, options) {
+    if (options?.clientId) {
+        const client = {
+            baseUrl,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret ?? "",
+            redirectUri,
+            logoutRedirectUri: redirectUri.replace("/callback", "/successful-logout"),
+            scope,
+            lang: "zh-cn",
+            product: "adp",
+            xForwardedPrefix: "",
+        };
+        saveClientConfig(baseUrl, client);
+        return client;
+    }
+    let client = loadClientConfig(baseUrl);
+    if (client?.clientId) {
+        const valid = await isClientStillValid(baseUrl, client.clientId, redirectUri);
+        if (valid)
+            return client;
+        process.stderr.write("Cached OAuth2 client is no longer valid on the server. Re-registering…\n");
+        deleteClientConfig(baseUrl);
+        client = null;
+    }
+    const registered = await registerOAuth2Client(baseUrl, redirectUri, scope);
+    saveClientConfig(baseUrl, registered);
+    return registered;
+}
+/**
+ * Parse a redirect URI to extract host, port, and pathname.
+ * Returns null if the URI is not a valid HTTP(S) URL.
+ */
+function parseRedirectUri(uri) {
+    try {
+        const parsed = new URL(uri);
+        const host = parsed.hostname;
+        const port = parsed.port ? Number(parsed.port) : (parsed.protocol === "https:" ? 443 : 80);
+        const isLocalhost = host === "127.0.0.1" || host === "localhost" || host === "::1";
+        return { host, port, pathname: parsed.pathname, isLocalhost };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Manual code flow for non-localhost redirect URIs.
+ * Prints the auth URL, then reads the full callback URL from stdin
+ * to extract the authorization code.
+ */
+async function waitForManualCode(authUrl, state) {
+    const { createInterface } = await import("node:readline");
+    process.stderr.write("\nSince the redirect URI is not localhost, you need to complete login manually.\n" +
+        "1. Open this URL in your browser:\n\n" +
+        `   ${authUrl}\n\n` +
+        "2. After login, the browser will redirect to your callback URL.\n" +
+        "3. Copy the full callback URL and paste it here:\n\n");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const callbackUrl = await new Promise((resolve) => {
+        rl.question("Callback URL> ", (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+    const parsed = new URL(callbackUrl);
+    const receivedState = parsed.searchParams.get("state");
+    if (receivedState !== state) {
+        throw new Error("OAuth2 state mismatch — possible CSRF attack.");
+    }
+    const error = parsed.searchParams.get("error");
+    if (error) {
+        const desc = parsed.searchParams.get("error_description") ?? "";
+        throw new Error(desc ? `Authorization failed: ${error} — ${desc}` : `Authorization failed: ${error}`);
+    }
+    const code = parsed.searchParams.get("code");
+    if (!code) {
+        throw new Error("No authorization code found in the callback URL.");
+    }
+    return code;
+}
 /**
  * OAuth2 Authorization Code login flow.
  * 1. Register client (if not already registered), OR use a provided client ID
  * 2. Open browser to /oauth2/auth
- * 3. Receive authorization code via local HTTP callback
+ * 3. Receive authorization code via local HTTP callback (or manual paste for non-localhost)
  * 4. Exchange code for access_token + refresh_token
  * 5. Save token.json + client.json to ~/.kweaver/
  */
@@ -133,29 +275,14 @@ export async function oauth2Login(baseUrl, options) {
         const base = normalizeBaseUrl(baseUrl);
         const port = options?.port ?? DEFAULT_REDIRECT_PORT;
         const scope = options?.scope ?? DEFAULT_SCOPE;
-        const redirectUri = `http://127.0.0.1:${port}/callback`;
+        // Determine redirect URI: explicit option > port-based default
+        const redirectUri = options?.redirectUri ?? `http://127.0.0.1:${port}/callback`;
+        const parsedRedirect = parseRedirectUri(redirectUri);
+        const isLocalRedirect = parsedRedirect?.isLocalhost ?? true;
+        const listenPort = parsedRedirect?.port ?? port;
+        const callbackPathname = parsedRedirect?.pathname ?? "/callback";
         // Step 1: Determine client — use provided client ID or fall back to dynamic registration
-        let client = loadClientConfig(base);
-        if (options?.clientId) {
-            // Use the platform's existing client (e.g. the web app client).
-            // Persist it so future logins reuse it without re-registering.
-            client = {
-                baseUrl: base,
-                clientId: options.clientId,
-                clientSecret: options.clientSecret ?? "",
-                redirectUri,
-                logoutRedirectUri: redirectUri.replace("/callback", "/successful-logout"),
-                scope,
-                lang: "zh-cn",
-                product: "adp",
-                xForwardedPrefix: "",
-            };
-            saveClientConfig(base, client);
-        }
-        else if (!client?.clientId) {
-            client = await registerOAuth2Client(base, redirectUri, scope);
-            saveClientConfig(base, client);
-        }
+        let client = await resolveOrRegisterClient(base, redirectUri, scope, options);
         // Use PKCE when no client secret is available (public client / platform client).
         const usePkce = !client.clientSecret;
         const pkce = usePkce ? await generatePkce() : null;
@@ -177,71 +304,91 @@ export async function oauth2Login(baseUrl, options) {
             authParams.set("code_challenge_method", "S256");
         }
         const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
-        // Step 4: Start local callback server; exchange code inside handler, then show credentials HTML
-        const token = await new Promise((resolve, reject) => {
-            let server;
-            const timeoutId = setTimeout(() => {
-                server?.close();
-                reject(new Error("OAuth2 login timed out (120s). No authorization code received."));
-            }, 120_000);
-            server = createServer((req, res) => {
-                void (async () => {
-                    try {
-                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
-                        if (url.pathname !== "/callback") {
-                            res.writeHead(404);
-                            res.end();
-                            return;
-                        }
-                        const receivedState = url.searchParams.get("state");
-                        const receivedCode = url.searchParams.get("code");
-                        if (receivedState !== state) {
-                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-                            res.end(buildCallbackExchangeErrorHtml("OAuth2 state mismatch — possible CSRF attack."));
+        let token;
+        if (isLocalRedirect) {
+            // Step 4a: Local callback — start HTTP server to receive the authorization code
+            token = await new Promise((resolve, reject) => {
+                let server;
+                const timeoutId = setTimeout(() => {
+                    server?.close();
+                    reject(new Error("OAuth2 login timed out (120s). No authorization code received."));
+                }, 120_000);
+                server = createServer((req, res) => {
+                    void (async () => {
+                        try {
+                            const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
+                            if (url.pathname !== callbackPathname) {
+                                res.writeHead(404);
+                                res.end();
+                                return;
+                            }
+                            const receivedState = url.searchParams.get("state");
+                            const code = url.searchParams.get("code");
+                            const callbackError = url.searchParams.get("error");
+                            const callbackErrorDesc = url.searchParams.get("error_description");
+                            if (receivedState !== state) {
+                                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                                res.end(buildCallbackExchangeErrorHtml("OAuth2 state mismatch — possible CSRF attack."));
+                                clearTimeout(timeoutId);
+                                server.close();
+                                reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
+                                return;
+                            }
+                            if (callbackError) {
+                                const msg = callbackErrorDesc
+                                    ? `Authorization failed: ${callbackError} — ${callbackErrorDesc}`
+                                    : `Authorization failed: ${callbackError}`;
+                                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                                res.end(buildCallbackExchangeErrorHtml(msg));
+                                clearTimeout(timeoutId);
+                                server.close();
+                                reject(new Error(msg));
+                                return;
+                            }
+                            if (!code) {
+                                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                                res.end(buildCallbackExchangeErrorHtml("No authorization code received in callback."));
+                                clearTimeout(timeoutId);
+                                server.close();
+                                reject(new Error("No authorization code received in callback."));
+                                return;
+                            }
+                            const exchanged = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
+                            const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, exchanged.refreshToken, options?.tlsInsecure);
+                            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackHtml(copyCommand));
                             clearTimeout(timeoutId);
                             server.close();
-                            reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
-                            return;
+                            resolve(exchanged);
                         }
-                        if (!receivedCode) {
-                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-                            res.end(buildCallbackExchangeErrorHtml("No authorization code received in callback."));
+                        catch (err) {
+                            const message = err instanceof Error ? err.message : String(err);
+                            try {
+                                res.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+                                res.end(buildCallbackExchangeErrorHtml(message));
+                            }
+                            catch {
+                                /* response may already be sent */
+                            }
                             clearTimeout(timeoutId);
                             server.close();
-                            reject(new Error("No authorization code received in callback."));
-                            return;
-                        }
-                        const exchanged = await exchangeCodeForToken(base, receivedCode, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
-                        const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, exchanged.refreshToken, options?.tlsInsecure);
-                        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                        res.end(buildCallbackHtml(copyCommand));
-                        clearTimeout(timeoutId);
-                        server.close();
-                        resolve(exchanged);
-                    }
-                    catch (err) {
-                        const message = err instanceof Error ? err.message : String(err);
-                        try {
-                            res.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
-                            res.end(buildCallbackExchangeErrorHtml(message));
-                        }
-                        catch {
-                            /* response may already be sent */
+                            reject(err instanceof Error ? err : new Error(message));
                         }
-                        clearTimeout(timeoutId);
-                        server.close();
-                        reject(err instanceof Error ? err : new Error(message));
-                    }
-                })();
-            });
-            server.listen(port, "127.0.0.1", () => {
-                // Step 5: Open browser (uses spawn with proper Windows quoting)
-                import("../utils/browser.js").then(({ openBrowser }) => {
-                    openBrowser(authUrl);
+                    })();
+                });
+                server.listen(listenPort, "127.0.0.1", () => {
+                    import("../utils/browser.js").then(({ openBrowser }) => {
+                        openBrowser(authUrl);
+                    });
+                    process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
                 });
-                process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
             });
-        });
+        }
+        else {
+            // Step 4b: Non-localhost redirect — manual code entry flow
+            const code = await waitForManualCode(authUrl, state);
+            token = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
+        }
         setCurrentPlatform(base);
         return token;
     });
@@ -329,6 +476,9 @@ async function exchangeCodeForToken(baseUrl, code, clientId, clientSecret, redir
         obtainedAt: now.toISOString(),
         ...(tlsInsecure ? { tlsInsecure: true } : {}),
     };
+    const displayName = await fetchDisplayName(baseUrl, data.access_token, tlsInsecure);
+    if (displayName)
+        token.displayName = displayName;
     saveTokenConfig(token);
     return token;
 }
@@ -359,14 +509,13 @@ export async function playwrightLogin(baseUrl, options) {
         const base = normalizeBaseUrl(baseUrl);
         const port = options?.port ?? DEFAULT_REDIRECT_PORT;
         const scope = options?.scope ?? DEFAULT_SCOPE;
-        const redirectUri = `http://127.0.0.1:${port}/callback`;
+        const redirectUri = options?.redirectUri ?? `http://127.0.0.1:${port}/callback`;
+        const parsedRedirect = parseRedirectUri(redirectUri);
+        const listenPort = parsedRedirect?.port ?? port;
+        const callbackPathname = parsedRedirect?.pathname ?? "/callback";
         const hasCredentials = !!(options?.username && options?.password);
-        // Step 1: Ensure registered OAuth2 client
-        let client = loadClientConfig(base);
-        if (!client?.clientId) {
-            client = await registerOAuth2Client(base, redirectUri, scope);
-            saveClientConfig(base, client);
-        }
+        // Step 1: Ensure registered OAuth2 client (with stale-client auto-recovery)
+        let client = await resolveOrRegisterClient(base, redirectUri, scope);
         // Step 2: Generate CSRF state
         const state = randomBytes(12).toString("hex");
         // Step 3: Build authorization URL
@@ -394,14 +543,16 @@ export async function playwrightLogin(baseUrl, options) {
             server = createServer((req, res) => {
                 void (async () => {
                     try {
-                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
-                        if (url.pathname !== "/callback") {
+                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
+                        if (url.pathname !== callbackPathname) {
                             res.writeHead(404);
                             res.end();
                             return;
                         }
                         const receivedState = url.searchParams.get("state");
                         const receivedCode = url.searchParams.get("code");
+                        const callbackError = url.searchParams.get("error");
+                        const callbackErrorDesc = url.searchParams.get("error_description");
                         if (receivedState !== state) {
                             res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
                             res.end(buildCallbackExchangeErrorHtml("OAuth2 state mismatch — possible CSRF attack."));
@@ -411,6 +562,18 @@ export async function playwrightLogin(baseUrl, options) {
                             reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
                             return;
                         }
+                        if (callbackError) {
+                            const msg = callbackErrorDesc
+                                ? `Authorization failed: ${callbackError} — ${callbackErrorDesc}`
+                                : `Authorization failed: ${callbackError}`;
+                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml(msg));
+                            clearTimeout(timeoutId);
+                            server.close();
+                            browser?.close();
+                            reject(new Error(msg));
+                            return;
+                        }
                         if (!receivedCode) {
                             res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
                             res.end(buildCallbackExchangeErrorHtml("No authorization code received in callback."));
@@ -445,7 +608,7 @@ export async function playwrightLogin(baseUrl, options) {
                     }
                 })();
             });
-            server.listen(port, "127.0.0.1", async () => {
+            server.listen(listenPort, "127.0.0.1", async () => {
                 try {
                     browser = await chromium.launch({ headless: hasCredentials });
                     const context = await browser.newContext({ ignoreHTTPSErrors: !!options?.tlsInsecure });
@@ -577,6 +740,10 @@ export async function refreshAccessToken(token) {
     }
     const now = new Date();
     const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    let displayName = token.displayName;
+    if (!displayName) {
+        displayName = (await fetchDisplayName(baseUrl, data.access_token, token.tlsInsecure)) ?? undefined;
+    }
     const newToken = {
         baseUrl,
         accessToken: data.access_token,
@@ -588,6 +755,7 @@ export async function refreshAccessToken(token) {
         idToken: data.id_token ?? token.idToken ?? "",
         obtainedAt: now.toISOString(),
         ...(token.tlsInsecure ? { tlsInsecure: true } : {}),
+        ...(displayName ? { displayName } : {}),
     };
     saveTokenConfig(newToken);
     return newToken;
@@ -618,7 +786,20 @@ export async function ensureValidToken(opts) {
     if (!currentPlatform) {
         throw new Error("No active platform selected. Run `kweaver auth login <platform-url>` first.");
     }
-    let token = loadTokenConfig(currentPlatform);
+    // KWEAVER_USER: load a specific user's token without switching active user
+    const envUser = process.env.KWEAVER_USER;
+    let token;
+    if (envUser) {
+        const userId = resolveUserId(currentPlatform, envUser);
+        if (!userId) {
+            throw new Error(`User '${envUser}' not found for ${currentPlatform}. ` +
+                "Run `kweaver auth users` to see available users.");
+        }
+        token = loadUserTokenConfig(currentPlatform, userId);
+    }
+    else {
+        token = loadTokenConfig(currentPlatform);
+    }
     if (!token) {
         throw new Error(`No saved token for ${currentPlatform}. Run \`kweaver auth login ${currentPlatform}\` first.`);
     }
@@ -652,7 +833,15 @@ export async function with401RefreshRetry(fn) {
                 throw error;
             }
             const platformUrl = normalizeBaseUrl(currentPlatform);
-            const latest = loadTokenConfig(platformUrl);
+            const envUser = process.env.KWEAVER_USER;
+            let latest;
+            if (envUser) {
+                const userId = resolveUserId(platformUrl, envUser);
+                latest = userId ? loadUserTokenConfig(platformUrl, userId) : null;
+            }
+            else {
+                latest = loadTokenConfig(platformUrl);
+            }
             if (!latest) {
                 throw error;
             }
@@ -681,7 +870,17 @@ export async function withTokenRetry(fn) {
     catch (error) {
         if (error instanceof HttpError && error.status === 401) {
             const platformUrl = normalizeBaseUrl(token.baseUrl);
-            const latest = loadTokenConfig(platformUrl) ?? token;
+            const envUser = process.env.KWEAVER_USER;
+            let latest;
+            if (envUser) {
+                const userId = resolveUserId(platformUrl, envUser);
+                latest = userId ? loadUserTokenConfig(platformUrl, userId) : null;
+            }
+            else {
+                latest = loadTokenConfig(platformUrl);
+            }
+            if (!latest)
+                latest = token;
             try {
                 const refreshed = await refreshAccessToken(latest);
                 return await fn(refreshed);

package/dist/cli.js

@@ -7,24 +7,29 @@ import { runConfigCommand } from "./commands/config.js";
 import { runContextLoaderCommand } from "./commands/context-loader.js";
 import { runDsCommand } from "./commands/ds.js";
 import { runDataviewCommand } from "./commands/dataview.js";
+import { runSkillCommand } from "./commands/skill.js";
 import { runTokenCommand } from "./commands/token.js";
 import { runVegaCommand } from "./commands/vega.js";
 function printHelp() {
     console.log(`kweaver
 
 Usage:
+  kweaver [--user <userId|username>] <command> [options]
   kweaver --version | -V
   kweaver --help | -h
 
   kweaver auth <platform-url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k]
   kweaver auth login <platform-url>          (alias for auth <url>)
   kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (run on host without browser)
+  kweaver auth whoami [platform-url|alias] [--json]
   kweaver auth export [platform-url|alias] [--json]
   kweaver auth status [platform-url|alias]
   kweaver auth list
   kweaver auth use <platform-url|alias>
-  kweaver auth logout [platform-url|alias]
-  kweaver auth delete <platform-url|alias>
+  kweaver auth users [platform-url|alias]
+  kweaver auth switch [platform-url|alias] --user <userId|username>
+  kweaver auth logout [platform-url|alias] [--user <userId>]
+  kweaver auth delete <platform-url|alias> [--user <userId>]
   kweaver token
 
   kweaver call <url> [-X METHOD] [-H "Name: value"] [-d BODY] [--data-raw BODY]
@@ -53,7 +58,7 @@ Usage:
   kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value] [--pretty]
   kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value] [--pretty]
   kweaver dataview get <id> [-bd value] [--pretty]
-  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [-bd value] [--pretty]
+  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value] [--pretty]
   kweaver dataview delete <id> [-y] [-bd value]
 
   kweaver bkn list [options]
@@ -80,6 +85,12 @@ Usage:
   kweaver config list-bd
   kweaver config show
 
+  kweaver skill list|get|register|status|delete [options]
+  kweaver skill market [options]
+  kweaver skill content <skill-id> [--raw] [--output file]
+  kweaver skill read-file <skill-id> <rel-path> [--raw] [--output file]
+  kweaver skill download|install <skill-id> [path] [options]
+
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]
   kweaver vega resource list|get|query [options]
@@ -94,6 +105,9 @@ Usage:
   kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info ...
   (alias: kweaver context ...)
 
+Global options:
+  --user <id|name>  Use a specific user's credentials for this command (env: KWEAVER_USER)
+
 Commands:
   auth           Login, list, inspect, and switch saved platform auth profiles
   token          Print the current access token, refreshing it first if needed
@@ -104,13 +118,21 @@ Commands:
   bkn            Knowledge network (CRUD, build, validate, export, stats, push/pull,
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
+  skill          Skill registry and market (register, search, progressive read, download/install)
   vega           Vega observability (catalog, resource, connector-type, health/stats/inspect)
   context-loader Context-loader MCP (config, tools, resources, prompts, kn-search, query-*, etc.)
   help           Show this message`);
 }
 export async function run(argv) {
     applyTlsEnvFromSavedTokens();
-    const [command, ...rest] = argv;
+    // Global --user flag: override active user for this invocation
+    const userIdx = argv.indexOf("--user");
+    let filteredArgv = argv;
+    if (userIdx !== -1 && userIdx + 1 < argv.length) {
+        process.env.KWEAVER_USER = argv[userIdx + 1];
+        filteredArgv = [...argv.slice(0, userIdx), ...argv.slice(userIdx + 2)];
+    }
+    const [command, ...rest] = filteredArgv;
     if (command === "--version" || command === "-V" || command === "version") {
         const { createRequire } = await import("node:module");
         const require = createRequire(import.meta.url);
@@ -149,6 +171,9 @@ export async function run(argv) {
     if (command === "config") {
         return runConfigCommand(rest);
     }
+    if (command === "skill") {
+        return runSkillCommand(rest);
+    }
     if (command === "context-loader" || command === "context") {
         return runContextLoaderCommand(rest);
     }

package/dist/client.d.ts

@@ -6,6 +6,7 @@ import { DataSourcesResource } from "./resources/datasources.js";
 import { DataViewsResource } from "./resources/dataviews.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
+import { SkillsResource } from "./resources/skills.js";
 import { VegaResource } from "./resources/vega.js";
 /**
  * Shared credentials passed to every resource method.
@@ -90,6 +91,8 @@ export declare class KWeaverClient implements ClientContext {
     readonly dataviews: DataViewsResource;
     /** Vega observability platform (catalogs, resources, connector types). */
     readonly vega: VegaResource;
+    /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
+    readonly skills: SkillsResource;
     constructor(opts?: KWeaverClientOptions);
     /**
      * Async factory that auto-refreshes expired or revoked tokens.

package/dist/client.js

@@ -9,6 +9,7 @@ import { DataSourcesResource } from "./resources/datasources.js";
 import { DataViewsResource } from "./resources/dataviews.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
+import { SkillsResource } from "./resources/skills.js";
 import { VegaResource } from "./resources/vega.js";
 // ── KWeaverClient ─────────────────────────────────────────────────────────────
 /**
@@ -59,6 +60,8 @@ export class KWeaverClient {
     dataviews;
     /** Vega observability platform (catalogs, resources, connector types). */
     vega;
+    /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */
+    skills;
     constructor(opts = {}) {
         const envDomain = process.env.KWEAVER_BUSINESS_DOMAIN;
         let baseUrl;
@@ -114,6 +117,7 @@ export class KWeaverClient {
         this.datasources = new DataSourcesResource(this);
         this.dataviews = new DataViewsResource(this);
         this.vega = new VegaResource(this);
+        this.skills = new SkillsResource(this);
     }
     /**
      * Async factory that auto-refreshes expired or revoked tokens.