@voxli/cli 0.3.2 → 0.5.0

package/README.md

@@ -12,13 +12,21 @@ Requires Node.js 18+.
 
 ## Setup
 
-Authenticate with your Voxli API key:
+Authenticate with your Voxli account:
 
 ```sh
 voxli auth
 ```
 
-This saves your key to `~/.voxli/config.json`. You can also set the `VOXLI_API_KEY` environment variable instead.
+This opens your browser to `app.voxli.io` where you log in and approve access. An API key is created automatically and saved to `~/.voxli/config.json`.
+
+To enter an API key manually instead:
+
+```sh
+voxli auth --manual
+```
+
+You can also set the `VOXLI_API_TOKEN` environment variable instead.
 
 ## Usage
 
@@ -32,7 +40,7 @@ The CLI polls the Voxli API for pending test batches. When work arrives, it spaw
 
 | Variable | Description |
 |---|---|
-| `VOXLI_API_KEY` | Your API key |
+| `VOXLI_API_TOKEN` | Your API key |
 | `TEST_RESULT_IDS` | JSON array of test result IDs to run |
 | `RUN_ID` | The run ID (if part of a run) |
 
@@ -40,5 +48,7 @@ The CLI polls the Voxli API for pending test batches. When work arrives, it spaw
 
 | Command | Description |
 |---|---|
-| `voxli auth` | Authenticate with your API key |
+| `voxli auth` | Authenticate via browser |
+| `voxli auth --manual` | Authenticate by entering an API key manually |
 | `voxli listen --command <cmd>` | Poll for pending test work and run it locally |
+

package/dist/cli.js

@@ -14,6 +14,7 @@ program
     .command("auth")
     .description("Authenticate with your Voxli API key")
     .option("--manual", "Enter API key manually instead of browser auth")
+    .option("--local", "Save credentials in the current directory")
     .action(authCommand);
 program
     .command("listen")

package/dist/commands/auth.d.ts

@@ -1,3 +1,4 @@
 export declare function authCommand(opts: {
     manual?: boolean;
+    local?: boolean;
 }): Promise<void>;

package/dist/commands/auth.js

@@ -4,54 +4,63 @@ import { writeConfig } from "../lib/config.js";
 import { register, ApiError } from "../lib/api.js";
 import { getStableHostname } from "../lib/hostname.js";
 import { browserAuth } from "../lib/browser-auth.js";
-async function promptForKey() {
+async function promptForToken() {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
-        const apiKey = await rl.question("Enter your Voxli API key: ");
-        if (!apiKey.trim()) {
+        const token = await rl.question("Enter your Voxli API key: ");
+        if (!token.trim()) {
             console.error("API key cannot be empty.");
             process.exit(1);
         }
-        return apiKey.trim();
+        return token.trim();
     }
     finally {
         rl.close();
     }
 }
-async function validateAndSave(key, userId) {
+async function validateAndSave(token, extra, opts) {
+    const label = extra ? "Access token" : "API key";
     console.log("Validating...");
     try {
         const hostname = getStableHostname();
-        await register(key, {
+        await register(token, {
             name: hostname,
             unique_identifier: hostname,
         });
-        console.log("API key is valid.");
+        console.log(`${label} is valid.`);
     }
     catch (err) {
         if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
-            console.error(`Authentication failed (${err.status}). Check your API key.`);
+            console.error(`Authentication failed (${err.status}). Check your ${label.toLowerCase()}.`);
             process.exit(1);
         }
         // Network error or other — warn but still save
-        console.warn("Warning: could not validate key (network error). Saving anyway.");
+        console.warn("Warning: could not validate token (network error). Saving anyway.");
     }
-    await writeConfig({ apiKey: key, userId });
-    console.log("API key saved to ~/.voxli/config.json");
+    const target = opts?.local ? "local" : "global";
+    const savedPath = await writeConfig({
+        accessToken: token,
+        refreshToken: extra?.refreshToken,
+        clientId: extra?.clientId,
+    }, { target });
+    console.log(`${label} saved to ${savedPath}`);
 }
 export async function authCommand(opts) {
     if (!opts.manual) {
         try {
             const result = await browserAuth();
-            await validateAndSave(result.apiKey, result.userId);
+            await validateAndSave(result.accessToken, {
+                refreshToken: result.refreshToken,
+                clientId: result.clientId,
+            }, { local: opts.local });
             return;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.log(`\nBrowser auth failed: ${msg}`);
-            console.log("Falling back to manual key entry.\n");
+            console.log("Falling back to manual token entry.\n");
         }
     }
-    const key = await promptForKey();
-    await validateAndSave(key);
+    const token = await promptForToken();
+    await validateAndSave(token, undefined, { local: opts.local });
 }

package/dist/commands/listen.js

@@ -1,12 +1,27 @@
+import { join } from "node:path";
 import { spawn } from "node:child_process";
-import { resolveApiKeyAsync } from "../lib/config.js";
+import { resolveApiKey, resolveConfig, attemptTokenRefresh, } from "../lib/config.js";
 import { getStableHostname } from "../lib/hostname.js";
 import { register, ApiError } from "../lib/api.js";
 const POLL_INTERVAL = 5_000;
 export async function listenCommand(options) {
-    const apiKey = await resolveApiKeyAsync();
+    const isEnvToken = !!resolveApiKey();
+    let apiKey = null;
+    let credentialSource = null;
+    if (isEnvToken) {
+        apiKey = resolveApiKey();
+        credentialSource = "VOXLI_API_TOKEN";
+    }
+    else {
+        const resolved = await resolveConfig();
+        if (resolved) {
+            const { config, configDir } = resolved;
+            apiKey = config.accessToken ?? config.apiKey ?? null;
+            credentialSource = join(configDir, "config.json");
+        }
+    }
     if (!apiKey) {
-        console.error("Error: No API key found. Set VOXLI_API_KEY or run `voxli auth`.");
+        console.error("Error: No API key found. Set VOXLI_API_TOKEN or run `voxli auth`.");
         process.exit(1);
     }
     const hostname = getStableHostname();
@@ -21,7 +36,7 @@ export async function listenCommand(options) {
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
-    console.log(`Listening as ${hostname}...`);
+    console.log(`Listening as ${hostname} using credentials from ${credentialSource}`);
     while (true) {
         try {
             const data = await register(apiKey, {
@@ -35,7 +50,7 @@ export async function listenCommand(options) {
                 console.log(`Spawning subprocess for ${testResultIds.length} test(s) (${label})`);
                 const env = {
                     ...process.env,
-                    VOXLI_API_KEY: apiKey,
+                    VOXLI_API_TOKEN: apiKey,
                     VOXLI_API_URL: process.env.VOXLI_API_URL,
                     VOXLI_APP_URL: process.env.VOXLI_APP_URL,
                     TEST_RESULT_IDS: JSON.stringify(testResultIds),
@@ -64,7 +79,23 @@ export async function listenCommand(options) {
             }
         }
         catch (err) {
-            if (err instanceof ApiError) {
+            if (err instanceof ApiError &&
+                (err.status === 401 || err.status === 403)) {
+                if (isEnvToken) {
+                    console.error(`Error: Authentication failed (${err.status}). Your VOXLI_API_TOKEN environment variable may be expired or invalid.`);
+                    process.exit(1);
+                }
+                console.log("Access token expired, attempting refresh...");
+                const newToken = await attemptTokenRefresh();
+                if (newToken) {
+                    apiKey = newToken;
+                    console.log("Token refreshed successfully.");
+                    continue;
+                }
+                console.error("Error: Could not refresh access token. Please re-authenticate with `voxli auth`.");
+                process.exit(1);
+            }
+            else if (err instanceof ApiError) {
                 console.error(`Poll error: API ${err.status}`);
             }
             else {

package/dist/lib/api.d.ts

@@ -1,4 +1,5 @@
 import type { RegisterPayload, RegisterResponse } from "../types.js";
+export declare function getApiBaseUrl(): string;
 export declare function register(apiKey: string, payload: RegisterPayload): Promise<RegisterResponse>;
 export declare class ApiError extends Error {
     status: number;

package/dist/lib/api.js

@@ -1,7 +1,10 @@
 const DEFAULT_BASE_URL = "https://api.voxli.io";
-function getBaseUrl() {
+export function getApiBaseUrl() {
     return process.env.VOXLI_API_URL || DEFAULT_BASE_URL;
 }
+function getBaseUrl() {
+    return getApiBaseUrl();
+}
 export async function register(apiKey, payload) {
     const url = `${getBaseUrl()}/agents/register`;
     const res = await fetch(url, {

package/dist/lib/browser-auth.d.ts

@@ -1,5 +1,6 @@
 export interface BrowserAuthResult {
-    apiKey: string;
-    userId?: string;
+    accessToken: string;
+    refreshToken?: string;
+    clientId: string;
 }
 export declare function browserAuth(): Promise<BrowserAuthResult>;

package/dist/lib/browser-auth.js

@@ -1,14 +1,11 @@
-import { createServer } from "node:http";
+import { createServer, } from "node:http";
 import { randomBytes } from "node:crypto";
 import { execFile } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
-import { getStableHostname } from "./hostname.js";
+import { getApiBaseUrl } from "./api.js";
+import { generatePkceChallenge, registerOAuthClient, exchangeCodeForToken, buildAuthorizeUrl, } from "./oauth.js";
 const AUTH_TIMEOUT_MS = 120_000;
-const DEFAULT_APP_URL = "https://app.voxli.io";
-function getAppUrl() {
-    return process.env.VOXLI_APP_URL || DEFAULT_APP_URL;
-}
 const SUCCESS_HTML = `<!DOCTYPE html>
 <html>
 <head><meta charset="utf-8"><title>Voxli CLI</title>
@@ -46,6 +43,7 @@ export async function browserAuth() {
     finally {
         rl.close();
     }
+    const baseUrl = getApiBaseUrl();
     return new Promise((resolve, reject) => {
         const state = randomBytes(32).toString("hex");
         const server = createServer((req, res) => {
@@ -55,15 +53,14 @@ export async function browserAuth() {
                 res.end("Not found");
                 return;
             }
-            const returnedKey = url.searchParams.get("key");
+            const returnedCode = url.searchParams.get("code");
             const returnedState = url.searchParams.get("state");
-            const returnedUserId = url.searchParams.get("user_id");
             if (returnedState !== state) {
                 res.writeHead(403, { "Content-Type": "text/html" });
                 res.end(ERROR_HTML);
                 return;
             }
-            if (!returnedKey) {
+            if (!returnedCode) {
                 res.writeHead(400, { "Content-Type": "text/html" });
                 res.end(ERROR_HTML);
                 return;
@@ -71,30 +68,51 @@ export async function browserAuth() {
             res.writeHead(200, { "Content-Type": "text/html" });
             res.end(SUCCESS_HTML);
             cleanup();
-            resolve({ apiKey: returnedKey, userId: returnedUserId || undefined });
+            exchangeCodeForToken(baseUrl, returnedCode, codeVerifier, clientId, redirectUri)
+                .then(({ accessToken, refreshToken }) => resolve({ accessToken, refreshToken, clientId }))
+                .catch(reject);
         });
+        let codeVerifier;
+        let clientId;
+        let redirectUri;
         const timeout = setTimeout(() => {
             cleanup();
             reject(new Error("Browser authentication timed out after 2 minutes."));
         }, AUTH_TIMEOUT_MS);
         function cleanup() {
             clearTimeout(timeout);
+            server.closeAllConnections();
             server.close();
         }
-        server.listen(0, "127.0.0.1", () => {
-            const addr = server.address();
-            if (!addr || typeof addr === "string") {
+        server.listen(0, "127.0.0.1", async () => {
+            try {
+                const addr = server.address();
+                if (!addr || typeof addr === "string") {
+                    cleanup();
+                    reject(new Error("Failed to start local server."));
+                    return;
+                }
+                const port = addr.port;
+                redirectUri = `http://127.0.0.1:${port}/callback`;
+                const registration = await registerOAuthClient(baseUrl, redirectUri);
+                clientId = registration.clientId;
+                const pkce = generatePkceChallenge();
+                codeVerifier = pkce.codeVerifier;
+                const authUrl = buildAuthorizeUrl(baseUrl, {
+                    clientId,
+                    redirectUri,
+                    codeChallenge: pkce.codeChallenge,
+                    state,
+                });
+                console.log("Opening browser to authenticate...");
+                openBrowser(authUrl);
+                console.log("Waiting for authentication (timeout: 2 min)...");
+                console.log(`\nIf the browser didn't open, visit:\n  ${authUrl}\n`);
+            }
+            catch (err) {
                 cleanup();
-                reject(new Error("Failed to start local server."));
-                return;
+                reject(err);
             }
-            const port = addr.port;
-            const hostname = encodeURIComponent(getStableHostname());
-            const authUrl = `${getAppUrl()}/cli-auth?port=${port}&state=${state}&hostname=${hostname}`;
-            console.log("Opening browser to authenticate...");
-            openBrowser(authUrl);
-            console.log(`Waiting for authentication (timeout: 2 min)...`);
-            console.log(`\nIf the browser didn't open, visit:\n  ${authUrl}\n`);
         });
     });
 }

package/dist/lib/config.d.ts

@@ -1,5 +1,26 @@
 import type { VoxliConfig } from "../types.js";
+/**
+ * Walk up from CWD looking for a `.voxli/config.json` file.
+ * Returns the `.voxli` directory path if found, or null.
+ */
+export declare function findLocalConfigDir(): Promise<string | null>;
 export declare function readConfig(): Promise<VoxliConfig | null>;
-export declare function writeConfig(config: VoxliConfig): Promise<void>;
+/**
+ * Resolve config checking local first, then global.
+ * Returns the config and the directory it was found in.
+ */
+export declare function resolveConfig(): Promise<{
+    config: VoxliConfig;
+    configDir: string;
+} | null>;
+export declare function writeConfig(config: {
+    accessToken: string;
+    refreshToken?: string;
+    clientId?: string;
+}, opts?: {
+    target?: "global" | "local";
+    configDir?: string;
+}): Promise<string>;
 export declare function resolveApiKey(): string | null;
 export declare function resolveApiKeyAsync(): Promise<string | null>;
+export declare function attemptTokenRefresh(): Promise<string | null>;

package/dist/lib/config.js

@@ -1,35 +1,121 @@
-import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, writeFile, mkdir, chmod, access } from "node:fs/promises";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-const CONFIG_DIR = join(homedir(), ".voxli");
-const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-export async function readConfig() {
+import { refreshAccessToken } from "./oauth.js";
+import { getApiBaseUrl } from "./api.js";
+const GLOBAL_CONFIG_DIR = join(homedir(), ".voxli");
+const GLOBAL_CONFIG_PATH = join(GLOBAL_CONFIG_DIR, "config.json");
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk up from CWD looking for a `.voxli/config.json` file.
+ * Returns the `.voxli` directory path if found, or null.
+ */
+export async function findLocalConfigDir() {
+    let dir = process.cwd();
+    while (true) {
+        const candidate = join(dir, ".voxli", "config.json");
+        if (await fileExists(candidate)) {
+            return join(dir, ".voxli");
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+async function readConfigFrom(configPath) {
     try {
-        const raw = await readFile(CONFIG_PATH, "utf-8");
+        const raw = await readFile(configPath, "utf-8");
         return JSON.parse(raw);
     }
     catch {
         return null;
     }
 }
-export async function writeConfig(config) {
-    await mkdir(CONFIG_DIR, { recursive: true });
-    await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {
+export async function readConfig() {
+    return readConfigFrom(GLOBAL_CONFIG_PATH);
+}
+/**
+ * Resolve config checking local first, then global.
+ * Returns the config and the directory it was found in.
+ */
+export async function resolveConfig() {
+    const localDir = await findLocalConfigDir();
+    if (localDir) {
+        const config = await readConfigFrom(join(localDir, "config.json"));
+        if (config)
+            return { config, configDir: localDir };
+    }
+    const config = await readConfigFrom(GLOBAL_CONFIG_PATH);
+    if (config)
+        return { config, configDir: GLOBAL_CONFIG_DIR };
+    return null;
+}
+export async function writeConfig(config, opts) {
+    let targetDir;
+    if (opts?.configDir) {
+        targetDir = opts.configDir;
+    }
+    else if (opts?.target === "local") {
+        targetDir = join(process.cwd(), ".voxli");
+    }
+    else {
+        targetDir = GLOBAL_CONFIG_DIR;
+    }
+    const targetPath = join(targetDir, "config.json");
+    const data = { accessToken: config.accessToken };
+    if (config.refreshToken)
+        data.refreshToken = config.refreshToken;
+    if (config.clientId)
+        data.clientId = config.clientId;
+    await mkdir(targetDir, { recursive: true });
+    await writeFile(targetPath, JSON.stringify(data, null, 2) + "\n", {
         mode: 0o600,
     });
-    await chmod(CONFIG_PATH, 0o600);
+    await chmod(targetPath, 0o600);
+    return targetPath;
 }
 export function resolveApiKey() {
-    const envKey = process.env.VOXLI_API_KEY;
+    const envKey = process.env.VOXLI_API_TOKEN;
     if (envKey)
         return envKey;
-    // Caller should await readConfig() for the file-based key
     return null;
 }
 export async function resolveApiKeyAsync() {
     const envKey = resolveApiKey();
     if (envKey)
         return envKey;
-    const config = await readConfig();
-    return config?.apiKey ?? null;
+    const resolved = await resolveConfig();
+    const config = resolved?.config;
+    return config?.accessToken ?? config?.apiKey ?? null;
+}
+export async function attemptTokenRefresh() {
+    try {
+        const resolved = await resolveConfig();
+        if (!resolved)
+            return null;
+        const { config, configDir } = resolved;
+        if (!config.refreshToken || !config.clientId)
+            return null;
+        const baseUrl = getApiBaseUrl();
+        const result = await refreshAccessToken(baseUrl, config.refreshToken, config.clientId);
+        await writeConfig({
+            accessToken: result.accessToken,
+            refreshToken: result.refreshToken ?? config.refreshToken,
+            clientId: config.clientId,
+        }, { configDir });
+        return result.accessToken;
+    }
+    catch {
+        return null;
+    }
 }

package/dist/lib/oauth.d.ts

@@ -0,0 +1,21 @@
+export declare function generatePkceChallenge(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};
+export declare function registerOAuthClient(baseUrl: string, redirectUri: string): Promise<{
+    clientId: string;
+}>;
+export declare function exchangeCodeForToken(baseUrl: string, code: string, codeVerifier: string, clientId: string, redirectUri: string): Promise<{
+    accessToken: string;
+    refreshToken?: string;
+}>;
+export declare function refreshAccessToken(baseUrl: string, refreshToken: string, clientId: string): Promise<{
+    accessToken: string;
+    refreshToken?: string;
+}>;
+export declare function buildAuthorizeUrl(baseUrl: string, params: {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    state: string;
+}): string;

package/dist/lib/oauth.js

@@ -0,0 +1,78 @@
+import { randomBytes, createHash } from "node:crypto";
+export function generatePkceChallenge() {
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256")
+        .update(codeVerifier)
+        .digest("base64url");
+    return { codeVerifier, codeChallenge };
+}
+export async function registerOAuthClient(baseUrl, redirectUri) {
+    const res = await fetch(`${baseUrl}/oauth/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: "Voxli CLI",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`OAuth client registration failed (${res.status})`);
+    }
+    const data = (await res.json());
+    return { clientId: data.client_id };
+}
+export async function exchangeCodeForToken(baseUrl, code, codeVerifier, clientId, redirectUri) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: codeVerifier,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+    });
+    const res = await fetch(`${baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`Token exchange failed (${res.status})`);
+    }
+    const data = (await res.json());
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+    };
+}
+export async function refreshAccessToken(baseUrl, refreshToken, clientId) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId,
+    });
+    const res = await fetch(`${baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`Token refresh failed (${res.status})`);
+    }
+    const data = (await res.json());
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+    };
+}
+export function buildAuthorizeUrl(baseUrl, params) {
+    const url = new URL("/oauth/authorize", baseUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", params.state);
+    return url.toString();
+}

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 export interface VoxliConfig {
-    apiKey: string;
-    userId?: string;
+    accessToken: string;
+    apiKey?: string;
+    refreshToken?: string;
+    clientId?: string;
 }
 export interface RegisterPayload {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxli/cli",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "CLI agent for running Voxli test scenarios locally",
   "type": "module",
   "bin": {