runline 0.2.2 → 0.3.1

package/dist/commands/auth.d.ts

@@ -0,0 +1,7 @@
+export declare function auth(plugin: string, options: {
+    name?: string;
+    clientId?: string;
+    clientSecret?: string;
+    json?: boolean;
+    quiet?: boolean;
+}): Promise<void>;

package/dist/commands/auth.js

@@ -0,0 +1,96 @@
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import chalk from "chalk";
+import { addConnection } from "../config/loader.js";
+import { OAUTH_CALLBACK_PORT, runOAuth } from "../core/oauth.js";
+import { loadAllPlugins } from "../plugin/loader.js";
+import { registry } from "../plugin/registry.js";
+import { printError, printJson, printSuccess } from "../utils/output.js";
+export async function auth(plugin, options) {
+    await loadAllPlugins();
+    const def = registry.getPlugin(plugin);
+    if (!def) {
+        printError(`Plugin "${plugin}" not found. Run \`runline plugin list\`.`);
+        process.exit(1);
+    }
+    if (!def.oauth) {
+        printError(`Plugin "${plugin}" does not declare OAuth config.`);
+        process.exit(1);
+    }
+    // Client credentials: CLI flag > env > interactive prompt.
+    // Env var names follow the plugin's own convention when declared
+    // on its connection schema; fall back to generic names otherwise.
+    const envIdVar = def.connectionConfigSchema?.clientId?.env;
+    const envSecretVar = def.connectionConfigSchema?.clientSecret?.env;
+    const resolvedClientId = options.clientId ?? (envIdVar ? process.env[envIdVar] : undefined);
+    const resolvedClientSecret = options.clientSecret ??
+        (envSecretVar ? process.env[envSecretVar] : undefined);
+    // If we're about to prompt and the plugin published setup help,
+    // print it once so the user knows what to paste. Suppressed
+    // under --json and --quiet.
+    const willPrompt = !resolvedClientId || !resolvedClientSecret;
+    if (willPrompt &&
+        def.oauth.setupHelp &&
+        def.oauth.setupHelp.length > 0 &&
+        !options.json &&
+        !options.quiet) {
+        const redirectUri = `http://127.0.0.1:${OAUTH_CALLBACK_PORT}/callback`;
+        console.log();
+        console.log(chalk.bold(`Setting up ${plugin} OAuth`));
+        console.log();
+        for (const line of def.oauth.setupHelp) {
+            console.log(chalk.dim("  ") +
+                line.replace(/\{\{redirectUri\}\}/g, chalk.cyan(redirectUri)));
+        }
+        console.log();
+    }
+    const clientId = resolvedClientId ?? (await prompt(`${plugin} OAuth client ID: `));
+    const clientSecret = resolvedClientSecret ?? (await prompt(`${plugin} OAuth client secret: `));
+    if (!clientId || !clientSecret) {
+        printError("Both client ID and client secret are required.");
+        process.exit(1);
+    }
+    const connectionName = options.name ?? plugin;
+    if (!options.quiet && !options.json) {
+        console.log(`\nOpening browser to authorize ${chalk.bold(plugin)}\u2026`);
+    }
+    try {
+        const tokens = await runOAuth(def.oauth, {
+            clientId,
+            clientSecret,
+            onAuthUrl: (url) => {
+                if (!options.quiet && !options.json) {
+                    console.log(chalk.dim(`If it doesn't open automatically, visit:\n  ${url}\n`));
+                }
+            },
+        });
+        addConnection(connectionName, plugin, {
+            clientId,
+            clientSecret,
+            refreshToken: tokens.refreshToken,
+            accessToken: tokens.accessToken,
+            accessTokenExpiresAt: tokens.expiresAt,
+        });
+        if (options.json) {
+            printJson({ ok: true, name: connectionName, plugin });
+        }
+        else {
+            printSuccess(`Connection ${chalk.bold(connectionName)} saved (plugin: ${plugin})`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        printError(msg);
+        process.exit(1);
+    }
+}
+async function prompt(q) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await rl.question(q);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/config/loader.d.ts

@@ -5,6 +5,17 @@ export declare function loadConfig(): RunlineConfig;
 export declare function saveConfig(config: RunlineConfig): void;
 export declare function addConnection(name: string, plugin: string, configValues: Record<string, unknown>): void;
 export declare function removeConnection(name: string): boolean;
+/**
+ * Merge a partial config patch into an existing connection, atomically.
+ *
+ * Used by plugins that need to persist refreshed OAuth tokens (or any
+ * other runtime-mutated credential) back to disk. The whole read-
+ * modify-write is guarded by a file lock so two concurrent `runline
+ * exec` processes refreshing the same token don't stomp each other.
+ *
+ * If the connection doesn't exist the call is a no-op.
+ */
+export declare function updateConnectionConfig(name: string, patch: Record<string, unknown>): Promise<void>;
 export declare function getConnection(plugin: string, name?: string): ConnectionConfig | undefined;
 export declare function applyEnvOverrides(conn: ConnectionConfig, schema?: Record<string, {
     env?: string;

package/dist/config/loader.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import lockfile from "proper-lockfile";
 import { DEFAULT_CONFIG } from "./types.js";
 const CONFIG_DIR_NAME = ".runline";
 const CONFIG_FILE = "config.json";
@@ -61,6 +62,51 @@ export function removeConnection(name) {
     saveConfig(config);
     return true;
 }
+/**
+ * Merge a partial config patch into an existing connection, atomically.
+ *
+ * Used by plugins that need to persist refreshed OAuth tokens (or any
+ * other runtime-mutated credential) back to disk. The whole read-
+ * modify-write is guarded by a file lock so two concurrent `runline
+ * exec` processes refreshing the same token don't stomp each other.
+ *
+ * If the connection doesn't exist the call is a no-op.
+ */
+export async function updateConnectionConfig(name, patch) {
+    const configDir = findConfigDir() ?? join(process.cwd(), CONFIG_DIR_NAME);
+    mkdirSync(configDir, { recursive: true });
+    const configPath = join(configDir, CONFIG_FILE);
+    if (!existsSync(configPath))
+        writeFileSync(configPath, "{}\n");
+    const release = await lockfile.lock(configPath, {
+        retries: { retries: 10, factor: 2, minTimeout: 50, maxTimeout: 2_000 },
+        stale: 30_000,
+        realpath: false,
+    });
+    try {
+        let raw;
+        try {
+            raw = {
+                ...DEFAULT_CONFIG,
+                ...JSON.parse(readFileSync(configPath, "utf-8")),
+            };
+        }
+        catch {
+            raw = { ...DEFAULT_CONFIG };
+        }
+        const idx = raw.connections.findIndex((c) => c.name === name);
+        if (idx < 0)
+            return;
+        raw.connections[idx] = {
+            ...raw.connections[idx],
+            config: { ...raw.connections[idx].config, ...patch },
+        };
+        writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+    }
+    finally {
+        await release();
+    }
+}
 export function getConnection(plugin, name) {
     const config = loadConfig();
     if (name)

package/dist/core/engine.js

@@ -1,5 +1,5 @@
 import { getQuickJS, shouldInterruptAfterDeadline, } from "quickjs-emscripten";
-import { applyEnvOverrides } from "../config/loader.js";
+import { applyEnvOverrides, updateConnectionConfig } from "../config/loader.js";
 export class ExecutionEngine {
     registry;
     config;
@@ -138,6 +138,12 @@ export class ExecutionEngine {
                 warn: (msg) => console.warn(`[${plugin.name}] ${msg}`),
                 error: (msg) => console.error(`[${plugin.name}] ${msg}`),
             },
+            updateConnection: async (patch) => {
+                // Mutate the in-memory copy so the rest of this action
+                // sees the new values without re-reading disk.
+                Object.assign(connection.config, patch);
+                await updateConnectionConfig(connection.name, patch);
+            },
         };
         return action.execute(args, ctx);
     }

package/dist/core/oauth.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Generic OAuth2 authorization-code flow.
+ *
+ * Two surfaces:
+ *
+ * 1. `runOAuth(config, {clientId, clientSecret})` — end-to-end CLI
+ *    flow. Opens the browser, captures the redirect on a pinned
+ *    localhost port, exchanges the code, returns tokens. Used by
+ *    `runline auth <plugin>`.
+ *
+ * 2. Primitives for callers that can't run a local callback server
+ *    (hosted apps, GUIs, anywhere the user's browser doesn't talk
+ *    back to the process driving the flow):
+ *
+ *      - `generatePKCE()` — S256 verifier + challenge
+ *      - `buildAuthUrl(config, opts)` — assemble the consent URL
+ *      - `exchangeAuthCode(config, opts)` — POST to the token
+ *        endpoint, get back tokens
+ *
+ *    The caller orchestrates: generates state + PKCE, builds the
+ *    URL, shows it to the user, receives the code back however it
+ *    wants (redirect-URI paste, browser popup with postMessage,
+ *    public HTTPS callback, …), calls exchangeAuthCode.
+ */
+import type { OAuthConfig } from "../plugin/types.js";
+/**
+ * Fixed callback port for OAuth redirects. Pinned so users can
+ * register `http://127.0.0.1:<PORT>/callback` once with the
+ * provider and have it keep working across every `runline auth`
+ * invocation. Override via `RUNLINE_OAUTH_CALLBACK_PORT` if you
+ * need a different port (you'll have to re-register the redirect
+ * URI with the provider after changing it).
+ */
+export declare const OAUTH_CALLBACK_PORT: number;
+/** Canonical localhost redirect URI for CLI-based flows. */
+export declare const OAUTH_CALLBACK_URI: string;
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Milliseconds since epoch. */
+    expiresAt: number;
+    scope?: string;
+    tokenType?: string;
+}
+export interface RunOAuthOptions {
+    clientId: string;
+    clientSecret: string;
+    /**
+     * Called with the consent URL before the browser is opened.
+     * Lets the CLI print a clickable link in case auto-open fails.
+     */
+    onAuthUrl?: (url: string) => void;
+    /** Override the browser launcher. Defaults to OS-appropriate command. */
+    openBrowser?: (url: string) => void;
+}
+export interface BuildAuthUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    /** S256 code challenge. Pass alongside a verifier kept by the driver. */
+    pkceChallenge?: string;
+}
+export interface ExchangeCodeOptions {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+    /** PKCE verifier matching the challenge sent on the auth URL. */
+    codeVerifier?: string;
+}
+export interface PKCEPair {
+    verifier: string;
+    /** Base64url SHA-256 of the verifier, for `code_challenge_method=S256`. */
+    challenge: string;
+}
+/**
+ * Generate a PKCE verifier and its SHA-256 challenge. The verifier
+ * stays with the driver until the token exchange; the challenge
+ * goes on the auth URL.
+ */
+export declare function generatePKCE(): PKCEPair;
+/**
+ * Assemble the authorization URL for a plugin's OAuth config.
+ * Pass `pkceChallenge` to include PKCE; omit for plain auth-code.
+ */
+export declare function buildAuthUrl(config: OAuthConfig, opts: BuildAuthUrlOptions): string;
+/**
+ * Exchange an authorization code for tokens. Throws if the
+ * provider doesn't return a refresh_token — that's almost always a
+ * misconfiguration (e.g. missing `access_type=offline` for Google).
+ */
+export declare function exchangeAuthCode(config: OAuthConfig, opts: ExchangeCodeOptions): Promise<OAuthTokens>;
+/**
+ * Run the full OAuth2 authorization-code flow end-to-end.
+ * Resolves with the exchanged tokens once the user completes the
+ * browser consent and the token endpoint returns a refresh token.
+ *
+ * Uses the pinned localhost callback port. If you can't run a
+ * local callback server, drive the flow yourself with
+ * `buildAuthUrl` + `exchangeAuthCode`.
+ */
+export declare function runOAuth(config: OAuthConfig, options: RunOAuthOptions): Promise<OAuthTokens>;

package/dist/core/oauth.js

@@ -0,0 +1,225 @@
+/**
+ * Generic OAuth2 authorization-code flow.
+ *
+ * Two surfaces:
+ *
+ * 1. `runOAuth(config, {clientId, clientSecret})` — end-to-end CLI
+ *    flow. Opens the browser, captures the redirect on a pinned
+ *    localhost port, exchanges the code, returns tokens. Used by
+ *    `runline auth <plugin>`.
+ *
+ * 2. Primitives for callers that can't run a local callback server
+ *    (hosted apps, GUIs, anywhere the user's browser doesn't talk
+ *    back to the process driving the flow):
+ *
+ *      - `generatePKCE()` — S256 verifier + challenge
+ *      - `buildAuthUrl(config, opts)` — assemble the consent URL
+ *      - `exchangeAuthCode(config, opts)` — POST to the token
+ *        endpoint, get back tokens
+ *
+ *    The caller orchestrates: generates state + PKCE, builds the
+ *    URL, shows it to the user, receives the code back however it
+ *    wants (redirect-URI paste, browser popup with postMessage,
+ *    public HTTPS callback, …), calls exchangeAuthCode.
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, } from "node:http";
+/**
+ * Fixed callback port for OAuth redirects. Pinned so users can
+ * register `http://127.0.0.1:<PORT>/callback` once with the
+ * provider and have it keep working across every `runline auth`
+ * invocation. Override via `RUNLINE_OAUTH_CALLBACK_PORT` if you
+ * need a different port (you'll have to re-register the redirect
+ * URI with the provider after changing it).
+ */
+export const OAUTH_CALLBACK_PORT = (() => {
+    const raw = process.env.RUNLINE_OAUTH_CALLBACK_PORT;
+    if (raw) {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n > 0 && n < 65536)
+            return n;
+    }
+    return 47823;
+})();
+/** Canonical localhost redirect URI for CLI-based flows. */
+export const OAUTH_CALLBACK_URI = `http://127.0.0.1:${OAUTH_CALLBACK_PORT}/callback`;
+// ─── Primitives ──────────────────────────────────────────────────
+/**
+ * Generate a PKCE verifier and its SHA-256 challenge. The verifier
+ * stays with the driver until the token exchange; the challenge
+ * goes on the auth URL.
+ */
+export function generatePKCE() {
+    const verifier = base64urlEncode(randomBytes(32));
+    const challenge = base64urlEncode(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+/**
+ * Assemble the authorization URL for a plugin's OAuth config.
+ * Pass `pkceChallenge` to include PKCE; omit for plain auth-code.
+ */
+export function buildAuthUrl(config, opts) {
+    const url = new URL(config.authUrl);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", config.scopes.join(" "));
+    url.searchParams.set("state", opts.state);
+    if (opts.pkceChallenge) {
+        url.searchParams.set("code_challenge", opts.pkceChallenge);
+        url.searchParams.set("code_challenge_method", "S256");
+    }
+    for (const [k, v] of Object.entries(config.authParams ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/**
+ * Exchange an authorization code for tokens. Throws if the
+ * provider doesn't return a refresh_token — that's almost always a
+ * misconfiguration (e.g. missing `access_type=offline` for Google).
+ */
+export async function exchangeAuthCode(config, opts) {
+    const body = new URLSearchParams({
+        code: opts.code,
+        client_id: opts.clientId,
+        client_secret: opts.clientSecret,
+        redirect_uri: opts.redirectUri,
+        grant_type: "authorization_code",
+    });
+    if (opts.codeVerifier)
+        body.set("code_verifier", opts.codeVerifier);
+    const res = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`OAuth: token exchange failed (${res.status}): ${await res.text()}`);
+    }
+    const data = (await res.json());
+    if (!data.refresh_token) {
+        throw new Error("OAuth: provider did not return a refresh token. This usually means a prior consent is cached — revoke access with the provider and retry. For Google, set authParams: { access_type: 'offline', prompt: 'consent' }.");
+    }
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+        scope: data.scope,
+        tokenType: data.token_type,
+    };
+}
+// ─── End-to-end CLI flow ─────────────────────────────────────────
+/**
+ * Run the full OAuth2 authorization-code flow end-to-end.
+ * Resolves with the exchanged tokens once the user completes the
+ * browser consent and the token endpoint returns a refresh token.
+ *
+ * Uses the pinned localhost callback port. If you can't run a
+ * local callback server, drive the flow yourself with
+ * `buildAuthUrl` + `exchangeAuthCode`.
+ */
+export async function runOAuth(config, options) {
+    const redirectUri = OAUTH_CALLBACK_URI;
+    const state = randomState();
+    const { verifier, challenge } = generatePKCE();
+    const authUrl = buildAuthUrl(config, {
+        clientId: options.clientId,
+        redirectUri,
+        state,
+        pkceChallenge: challenge,
+    });
+    // Always make the URL visible. `onAuthUrl` is the preferred
+    // channel (CLI formats it inline); if absent, fall back to
+    // stderr so headless invocations (SSH, CI) aren't left waiting
+    // on a browser that never opens.
+    if (options.onAuthUrl) {
+        options.onAuthUrl(authUrl);
+    }
+    else {
+        console.error(`Open this URL to authorize:\n  ${authUrl}`);
+    }
+    const open = options.openBrowser ?? defaultOpenBrowser;
+    open(authUrl);
+    const { code } = await captureCode(OAUTH_CALLBACK_PORT, state);
+    return exchangeAuthCode(config, {
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        code,
+        redirectUri,
+        codeVerifier: verifier,
+    });
+}
+// ─── Local callback server ───────────────────────────────────────
+function captureCode(port, expectedState) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                res.statusCode = 404;
+                res.end("Not found");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.statusCode = 400;
+                res.end(`Authorization failed: ${error}. You can close this tab.`);
+                server.close();
+                reject(new Error(`OAuth: ${error}`));
+                return;
+            }
+            if (!code) {
+                res.statusCode = 400;
+                res.end("Missing code");
+                return;
+            }
+            if (state !== expectedState) {
+                res.statusCode = 400;
+                res.end("State mismatch — possible CSRF. Aborting.");
+                server.close();
+                reject(new Error("OAuth: state mismatch"));
+                return;
+            }
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(`<!doctype html><meta charset="utf-8"><title>Connected</title>` +
+                `<body style="font-family:system-ui;padding:2rem">` +
+                `<h1 style="margin:0 0 0.5rem">Connected \u2713</h1>` +
+                `<p style="color:#666">You can close this tab and return to your terminal.</p>`);
+            server.close();
+            resolve({ code });
+        });
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1");
+    });
+}
+// ─── Helpers ─────────────────────────────────────────────────────
+function randomState() {
+    return base64urlEncode(randomBytes(16));
+}
+function base64urlEncode(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function defaultOpenBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    const proc = spawn(cmd, [url], {
+        stdio: "ignore",
+        detached: true,
+    });
+    proc.on("error", () => {
+        // Browser failed to open — caller's onAuthUrl prints the URL
+        // so the user can paste it manually.
+    });
+    proc.unref();
+}

package/dist/index.d.ts

@@ -1,15 +1,17 @@
-export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, } from "./config/loader.js";
+export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export type { RunlineConfig } from "./config/types.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
 export type { EngineOptions, ExecuteResult } from "./core/engine.js";
 export { ExecutionEngine } from "./core/engine.js";
+export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
+export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
 export type { ActionDefinition, PluginFunction, RunlinePluginAPI, SchemaField, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";
 export { PluginRegistry, registry } from "./plugin/registry.js";
-export type { ActionContext, ActionDef, ConnectionConfig, InputField, InputSchema, PluginDef, } from "./plugin/types.js";
+export type { ActionContext, ActionDef, ConnectionConfig, InputField, InputSchema, OAuthConfig, PluginDef, } from "./plugin/types.js";
 export type { RunlineOptions } from "./sdk.js";
 export { Runline } from "./sdk.js";
 export type { ExecOptions, ExecResult, OutputParser } from "./utils/cli.js";

package/dist/index.js

@@ -1,6 +1,7 @@
-export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, } from "./config/loader.js";
+export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
 export { ExecutionEngine } from "./core/engine.js";
+export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";

package/dist/main.js

@@ -2,6 +2,7 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { actions } from "./commands/actions.js";
+import { auth } from "./commands/auth.js";
 import { connectionAdd, connectionList, connectionRemove, } from "./commands/connection.js";
 import { exec } from "./commands/exec.js";
 import { init } from "./commands/init.js";
@@ -27,6 +28,7 @@ Examples:
   $ runline exec -f ./scripts/deploy.js
   $ runline actions
   $ runline connection add gh --plugin github --set token=ghp_xxx
+  $ runline auth gmail
 
 https://github.com/Michaelliv/runline`);
 program
@@ -114,6 +116,32 @@ pluginCmd
     await pluginList({ json: globals.json });
 });
 // ── init ────────────────────────────────────────────────
+program
+    .command("auth <plugin>")
+    .description("Run the OAuth login flow for a plugin and save the connection")
+    .option("-n, --name <name>", "Connection name (default: plugin name)")
+    .option("--client-id <id>", "OAuth client ID (falls back to env or prompt)")
+    .option("--client-secret <secret>", "OAuth client secret (falls back to env or prompt)")
+    .addHelpText("after", `
+The plugin must declare OAuth config via setOAuth(). The flow
+opens your browser to the provider's consent screen, catches the
+redirect on a localhost port, exchanges the code for tokens, and
+writes a connection into .runline/config.json.
+
+Examples:
+  $ runline auth gmail
+  $ runline auth gmail --name gmail-work
+  $ runline auth gmail --client-id $CLIENT --client-secret $SECRET`)
+    .action(async (plugin, opts, cmd) => {
+    const globals = cmd.optsWithGlobals();
+    await auth(plugin, {
+        name: opts.name,
+        clientId: opts.clientId,
+        clientSecret: opts.clientSecret,
+        json: globals.json,
+        quiet: globals.quiet,
+    });
+});
 program
     .command("init")
     .description("Create .runline/ in current directory")

package/dist/plugin/api.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDef, InputSchema, PluginDef } from "./types.js";
+import type { ActionDef, InputSchema, OAuthConfig, PluginDef } from "./types.js";
 export interface SchemaField {
     type: "string" | "number" | "boolean";
     required?: boolean;
@@ -16,6 +16,12 @@ export interface RunlinePluginAPI {
     setConnectionSchema(schema: Record<string, SchemaField>): void;
     setName(name: string): void;
     setVersion(version: string): void;
+    /**
+     * Declare OAuth2 configuration so `runline auth <plugin>` can
+     * run the browser login flow and seed this plugin's connection
+     * with refreshable tokens.
+     */
+    setOAuth(oauth: OAuthConfig): void;
     onInit(fn: (config: Record<string, unknown>) => void): void;
     log: {
         info(msg: string): void;

package/dist/plugin/api.js

@@ -3,6 +3,7 @@ export function createPluginAPI(pluginId) {
     let version = "0.0.0";
     const actions = [];
     let connectionConfigSchema;
+    let oauth;
     const initHooks = [];
     const api = {
         setName(n) {
@@ -23,6 +24,9 @@ export function createPluginAPI(pluginId) {
                 connectionConfigSchema[key] = { ...field };
             }
         },
+        setOAuth(cfg) {
+            oauth = { ...cfg };
+        },
         onInit(fn) {
             initHooks.push(fn);
         },
@@ -45,6 +49,9 @@ export function createPluginAPI(pluginId) {
             actions,
             connectionConfigSchema,
         };
+        if (oauth) {
+            plugin.oauth = oauth;
+        }
         if (initHooks.length > 0) {
             plugin.initHooks = initHooks;
         }