@kweaver-ai/kweaver-sdk 0.6.0 → 0.6.1

package/README.md

@@ -142,7 +142,7 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## CLI Reference
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--insecure|-k]
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (headless login)
 kweaver auth export [url|alias] [--json]   (export command to run on a headless host)
 kweaver auth status/list/use/delete/logout

package/README.zh.md

@@ -131,7 +131,7 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## 命令速查
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--insecure|-k]
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (无浏览器登录)
 kweaver auth export [url|alias] [--json]   (导出在无浏览器机器上运行的命令)
 kweaver auth status/list/use/delete/logout

package/dist/auth/oauth.d.ts

@@ -14,20 +14,23 @@ export declare function normalizeBaseUrl(value: string): string;
 /**
  * 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 (or manual paste for non-localhost)
+ * 2. Open browser to /oauth2/auth (unless `noBrowser` or browser launch fails)
+ * 3. Receive authorization code via local HTTP callback, or stdin paste (`noBrowser` / fallback)
  * 4. Exchange code for access_token + refresh_token
  * 5. Save token.json + client.json to ~/.kweaver/
  */
 export declare function oauth2Login(baseUrl: string, options?: {
     port?: number;
-    /** Full redirect URI override (e.g. "http://127.0.0.1:9010/callback" or a remote URL). */
-    redirectUri?: string;
     scope?: string;
     clientId?: string;
     clientSecret?: string;
     /** Skip TLS certificate verification (self-signed / dev servers only). */
     tlsInsecure?: boolean;
+    /**
+     * Do not open a browser; print the auth URL and prompt for the callback URL or code (stdin).
+     * For headless servers or when automatic browser launch is unavailable.
+     */
+    noBrowser?: boolean;
 }): Promise<TokenConfig>;
 /**
  * Playwright-automated OAuth2 login.
@@ -44,8 +47,6 @@ export declare function playwrightLogin(baseUrl: string, options?: {
     username?: string;
     password?: string;
     port?: number;
-    /** Full redirect URI override. */
-    redirectUri?: string;
     scope?: string;
     tlsInsecure?: boolean;
 }): Promise<TokenConfig>;

package/dist/auth/oauth.js

@@ -160,8 +160,7 @@ async function isClientStillValid(baseUrl, clientId, redirectUri) {
         });
         if (resp.status === 302) {
             const location = resp.headers.get("location") ?? "";
-            if (location.includes("error=invalid_client") ||
-                location.includes("error=error")) {
+            if (location.includes("error=")) {
                 return false;
             }
             return true;
@@ -199,73 +198,99 @@ async function resolveOrRegisterClient(baseUrl, redirectUri, scope, options) {
     }
     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 storedUri = client.redirectUri ?? redirectUri;
+        const valid = await isClientStillValid(baseUrl, client.clientId, storedUri);
+        if (valid) {
+            if (storedUri !== redirectUri) {
+                process.stderr.write("Redirect URI changed. Re-registering OAuth2 client…\n");
+                deleteClientConfig(baseUrl);
+                client = null;
+            }
+            else {
+                return client;
+            }
+        }
+        else {
+            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.
+ * Emphasize text on stderr (bold + bright yellow) when stderr is a TTY and `NO_COLOR` is unset.
+ * See https://no-color.org/
  */
-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 };
+function stderrEmphasis(text) {
+    const noColor = process.env.NO_COLOR;
+    if (noColor != null && noColor !== "") {
+        return text;
     }
-    catch {
-        return null;
+    if (!process.stderr.isTTY) {
+        return text;
     }
+    return `\x1b[1;33m${text}\x1b[0m`;
 }
 /**
- * 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.
+ * Headless login: read authorization code from stdin (full callback URL or raw code).
+ * Used with `--no-browser` or when automatic browser launch fails.
  */
-async function waitForManualCode(authUrl, state) {
+async function promptForCode(authUrl, state, port, pasteMode = "explicit") {
     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 intro = pasteMode === "explicit"
+        ? "Open this URL on any device (use a private/incognito window if you need the full sign-in form):\n\n"
+        : "Could not open a browser automatically. Open this URL on any device:\n\n";
+    const pasteInstructions = "After login, the browser may show an error page (this is expected if nothing listens on localhost).\n" +
+        "Copy the FULL URL from the address bar and paste it here, or paste only the authorization code.\n" +
+        `The URL looks like: http://127.0.0.1:${port}/callback?code=THIS_PART&state=...\n\n`;
+    process.stderr.write("\n" +
+        intro +
+        `  ${authUrl}\n\n` +
+        stderrEmphasis(pasteInstructions));
     const rl = createInterface({ input: process.stdin, output: process.stderr });
-    const callbackUrl = await new Promise((resolve) => {
-        rl.question("Callback URL> ", (answer) => {
+    const input = await new Promise((resolve, reject) => {
+        rl.on("close", () => reject(new Error("Login cancelled.")));
+        rl.question("Paste URL or code> ", (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}`);
+    if (input.includes("code=")) {
+        let url;
+        try {
+            url = new URL(input.startsWith("http") ? input : `http://x/?${input}`);
+        }
+        catch {
+            throw new Error("Could not parse the pasted URL. Paste the full callback URL or the code value.");
+        }
+        const receivedState = url.searchParams.get("state");
+        if (receivedState && receivedState !== state) {
+            throw new Error("OAuth2 state mismatch — possible CSRF attack.");
+        }
+        const err = url.searchParams.get("error");
+        if (err) {
+            const desc = url.searchParams.get("error_description") ?? "";
+            throw new Error(desc ? `Authorization failed: ${err} — ${desc}` : `Authorization failed: ${err}`);
+        }
+        const code = url.searchParams.get("code");
+        if (!code) {
+            throw new Error("No authorization code found in the pasted URL.");
+        }
+        return code;
     }
-    const code = parsed.searchParams.get("code");
-    if (!code) {
-        throw new Error("No authorization code found in the callback URL.");
+    if (!input) {
+        throw new Error("No authorization code entered.");
     }
-    return code;
+    return input;
 }
 /**
  * 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 (or manual paste for non-localhost)
+ * 2. Open browser to /oauth2/auth (unless `noBrowser` or browser launch fails)
+ * 3. Receive authorization code via local HTTP callback, or stdin paste (`noBrowser` / fallback)
  * 4. Exchange code for access_token + refresh_token
  * 5. Save token.json + client.json to ~/.kweaver/
  */
@@ -276,12 +301,7 @@ export async function oauth2Login(baseUrl, options) {
         const base = normalizeBaseUrl(baseUrl);
         const port = options?.port ?? DEFAULT_REDIRECT_PORT;
         const scope = options?.scope ?? DEFAULT_SCOPE;
-        // 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";
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
         // Step 1: Determine client — use provided client ID or fall back to dynamic registration
         let client;
         try {
@@ -315,9 +335,19 @@ export async function oauth2Login(baseUrl, options) {
             authParams.set("code_challenge_method", "S256");
         }
         const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
+        const runPasteCodeFlow = async (pasteMode) => {
+            const code = await promptForCode(authUrl, state, port, pasteMode);
+            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);
+            process.stderr.write("\nOn a machine without a browser, run:\n\n  " + copyCommand + "\n\n");
+            return exchanged;
+        };
         let token;
-        if (isLocalRedirect) {
-            // Step 4a: Local callback — start HTTP server to receive the authorization code
+        if (options?.noBrowser) {
+            token = await runPasteCodeFlow("explicit");
+        }
+        else {
+            // Step 4: Local HTTP callback, or paste-code if browser cannot be opened
             token = await new Promise((resolve, reject) => {
                 let server;
                 const timeoutId = setTimeout(() => {
@@ -327,8 +357,8 @@ export async function oauth2Login(baseUrl, options) {
                 server = createServer((req, res) => {
                     void (async () => {
                         try {
-                            const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
-                            if (url.pathname !== callbackPathname) {
+                            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                            if (url.pathname !== "/callback") {
                                 res.writeHead(404);
                                 res.end();
                                 return;
@@ -387,19 +417,25 @@ export async function oauth2Login(baseUrl, options) {
                         }
                     })();
                 });
-                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`);
+                server.listen(port, "127.0.0.1", () => {
+                    void (async () => {
+                        const { openBrowser } = await import("../utils/browser.js");
+                        const opened = await openBrowser(authUrl);
+                        process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
+                        if (!opened) {
+                            clearTimeout(timeoutId);
+                            server.close();
+                            try {
+                                resolve(await runPasteCodeFlow("fallback"));
+                            }
+                            catch (err) {
+                                reject(err instanceof Error ? err : new Error(String(err)));
+                            }
+                        }
+                    })();
                 });
             });
         }
-        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;
     });
@@ -520,10 +556,7 @@ 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 = options?.redirectUri ?? `http://127.0.0.1:${port}/callback`;
-        const parsedRedirect = parseRedirectUri(redirectUri);
-        const listenPort = parsedRedirect?.port ?? port;
-        const callbackPathname = parsedRedirect?.pathname ?? "/callback";
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
         const hasCredentials = !!(options?.username && options?.password);
         // Step 1: Ensure registered OAuth2 client (with stale-client auto-recovery)
         let client;
@@ -564,8 +597,8 @@ export async function playwrightLogin(baseUrl, options) {
             server = createServer((req, res) => {
                 void (async () => {
                     try {
-                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${listenPort}`);
-                        if (url.pathname !== callbackPathname) {
+                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                        if (url.pathname !== "/callback") {
                             res.writeHead(404);
                             res.end();
                             return;
@@ -629,7 +662,7 @@ export async function playwrightLogin(baseUrl, options) {
                     }
                 })();
             });
-            server.listen(listenPort, "127.0.0.1", async () => {
+            server.listen(port, "127.0.0.1", async () => {
                 try {
                     browser = await chromium.launch({ headless: hasCredentials });
                     const context = await browser.newContext({ ignoreHTTPSErrors: !!options?.tlsInsecure });
@@ -670,7 +703,7 @@ export async function playwrightLogin(baseUrl, options) {
  */
 export async function refreshTokenLogin(baseUrl, options) {
     const base = normalizeBaseUrl(baseUrl);
-    const redirectUri = `http://127.0.0.1:${DEFAULT_REDIRECT_PORT}/callback`;
+    const redirectUri = `http://localhost:${DEFAULT_REDIRECT_PORT}/callback`;
     const client = {
         baseUrl: base,
         clientId: options.clientId,

package/dist/cli.js

@@ -21,7 +21,7 @@ Usage:
   kweaver --version | -V
   kweaver --help | -h
 
-  kweaver auth <platform-url> [--alias name] [--no-auth] [-u user] [-p pass] [--playwright] [--insecure|-k]
+  kweaver auth <platform-url> [--alias name] [--no-auth] [--no-browser] [-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]

package/dist/commands/auth.js

@@ -28,9 +28,8 @@ Login options:
                          Requires --client-id and --client-secret.
                          Get these from the callback page after browser login or \`auth export\`.
   --port <n>             Local callback port (default: 9010). Use when 9010 is occupied.
-  --redirect-uri <uri>   Full OAuth2 redirect URI override. Localhost URIs start a local server;
-                         non-localhost URIs use a manual paste-the-callback-URL flow.
-                         When set, --port is ignored. Example: --redirect-uri http://127.0.0.1:9010/callback
+  --no-browser           Do not open a browser; print the auth URL and prompt for the callback URL or code (stdin).
+                         Use on headless servers or when automatic browser launch fails.
   -u, --username         Username (with -p triggers Playwright headless login)
   -p, --password         Password
   --playwright           Force Playwright browser login even without -u/-p
@@ -40,7 +39,7 @@ Login options:
     }
     if (target === "login") {
         if (rest[0] === "--help" || rest[0] === "-h") {
-            console.log(`kweaver auth login <platform-url> [--alias <name>] [--no-auth] [-u user] [-p pass] [--playwright] [--refresh-token T --client-id ID --client-secret S]`);
+            console.log(`kweaver auth login <platform-url> [--alias <name>] [--no-auth] [--no-browser] [-u user] [-p pass] [--playwright] [--refresh-token T --client-id ID --client-secret S]`);
             return 0;
         }
         const url = rest[0];
@@ -73,19 +72,22 @@ Login options:
             const clientId = readOption(args, "--client-id");
             const clientSecret = readOption(args, "--client-secret");
             const refreshToken = readOption(args, "--refresh-token");
-            const customRedirectUri = readOption(args, "--redirect-uri");
             const customPortStr = readOption(args, "--port");
             const customPort = customPortStr ? parseInt(customPortStr, 10) : undefined;
             const tlsInsecure = args.includes("--insecure") || args.includes("-k");
             const noAuth = args.includes("--no-auth");
+            const noBrowser = args.includes("--no-browser");
+            if (args.includes("--redirect-uri")) {
+                console.error("Warning: --redirect-uri is deprecated and ignored. The redirect URI is always http://127.0.0.1:<port>/callback.");
+            }
             const KNOWN_LOGIN_FLAGS = new Set([
                 "--alias", "--client-id", "--client-secret", "--refresh-token",
-                "--port", "--redirect-uri", "--username", "-u", "--password", "-p",
-                "--playwright", "--insecure", "-k", "--no-auth",
+                "--port", "--no-browser", "--username", "-u", "--password", "-p",
+                "--playwright", "--insecure", "-k", "--no-auth", "--redirect-uri",
             ]);
             const KNOWN_VALUE_FLAGS = new Set([
                 "--alias", "--client-id", "--client-secret", "--refresh-token",
-                "--port", "--redirect-uri", "--username", "-u", "--password", "-p",
+                "--port", "--username", "-u", "--password", "-p", "--redirect-uri",
             ]);
             for (let i = 0; i < args.length; i++) {
                 const a = args[i];
@@ -105,10 +107,21 @@ Login options:
                 console.error("--no-auth cannot be used with --refresh-token.");
                 return 1;
             }
+            if (noAuth && noBrowser) {
+                console.error("--no-auth does not require a browser; --no-browser is ignored.");
+            }
             if (noAuth && (username || password || usePlaywright)) {
                 console.error("--no-auth cannot be used with Playwright login or -u/-p.");
                 return 1;
             }
+            if (noBrowser && (username || password || usePlaywright)) {
+                console.error("--no-browser cannot be used with Playwright login or -u/-p.");
+                return 1;
+            }
+            if (noBrowser && refreshToken) {
+                console.error("--no-browser cannot be used with --refresh-token.");
+                return 1;
+            }
             let token;
             if (noAuth) {
                 token = saveNoAuthPlatform(normalizedTarget, { tlsInsecure });
@@ -127,19 +140,20 @@ Login options:
             else if (username && password) {
                 console.log("Logging in (headless)...");
                 token = await playwrightLogin(normalizedTarget, {
-                    username, password, tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    username, password, tlsInsecure, port: customPort,
                 });
             }
             else if (usePlaywright) {
                 console.log("Opening browser for login (Playwright)...");
                 token = await playwrightLogin(normalizedTarget, {
-                    tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    tlsInsecure, port: customPort,
                 });
             }
             else {
-                if (clientId) {
+                if (noBrowser) {
+                    console.log("OAuth2 login (no browser — open the URL on any device, then paste the callback URL or code)...");
+                }
+                else if (clientId) {
                     console.log(`Opening browser for OAuth2 login (client: ${clientId})...`);
                 }
                 else {
@@ -148,8 +162,7 @@ Login options:
                 token = await oauth2Login(normalizedTarget, {
                     clientId: clientId ?? undefined,
                     clientSecret: clientSecret ?? undefined,
-                    tlsInsecure,
-                    port: customPort, redirectUri: customRedirectUri ?? undefined,
+                    tlsInsecure, port: customPort, noBrowser,
                 });
             }
             if (alias) {

package/dist/utils/browser.js

@@ -1,22 +1,45 @@
+import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { release } from "node:os";
+let _isWSL;
+function isWSL() {
+    if (_isWSL !== undefined)
+        return _isWSL;
+    if (process.platform !== "linux")
+        return (_isWSL = false);
+    if (/microsoft/i.test(release()))
+        return (_isWSL = true);
+    try {
+        const procVersion = readFileSync("/proc/version", "utf8");
+        return (_isWSL = /microsoft/i.test(procVersion));
+    }
+    catch {
+        return (_isWSL = false);
+    }
+}
+function resolveCommand(url) {
+    if (process.platform === "darwin") {
+        return { command: "open", args: [url], detached: true };
+    }
+    if (process.platform === "win32") {
+        return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url], detached: false };
+    }
+    if (isWSL()) {
+        return { command: "cmd.exe", args: ["/c", "start", "", url.replace(/&/g, "^&")], detached: true };
+    }
+    return { command: "xdg-open", args: [url], detached: true };
+}
 export function openBrowser(url) {
-    const isWindows = process.platform === "win32";
-    const command = process.platform === "darwin" ? "open" : isWindows ? "rundll32.exe" : "xdg-open";
-    const args = isWindows
-        ? [
-            "url.dll,FileProtocolHandler",
-            url,
-        ]
-        : [url];
+    const { command, args, detached } = resolveCommand(url);
     return new Promise((resolve) => {
         const child = spawn(command, args, {
             stdio: "ignore",
-            detached: !isWindows,
+            detached,
             windowsHide: true,
         });
         child.once("error", () => resolve(false));
         child.once("spawn", () => resolve(true));
-        if (!isWindows) {
+        if (detached) {
             child.unref();
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",