runline 0.2.2 → 0.3.0

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,46 @@
+/**
+ * Generic OAuth2 authorization-code flow.
+ *
+ * Runs the browser login dance for any plugin that declares
+ * `setOAuth(config)`: opens the provider's consent URL, catches
+ * the redirect on a local port, exchanges the code for tokens,
+ * and returns `{accessToken, refreshToken, expiresAt, scope}`.
+ *
+ * Provider-agnostic — the caller (the `auth` CLI command) supplies
+ * the plugin's `OAuthConfig` along with the client credentials.
+ */
+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;
+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;
+}
+/**
+ * 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.
+ */
+export declare function runOAuth(config: OAuthConfig, options: RunOAuthOptions): Promise<OAuthTokens>;

package/dist/core/oauth.js

@@ -0,0 +1,145 @@
+/**
+ * Generic OAuth2 authorization-code flow.
+ *
+ * Runs the browser login dance for any plugin that declares
+ * `setOAuth(config)`: opens the provider's consent URL, catches
+ * the redirect on a local port, exchanges the code for tokens,
+ * and returns `{accessToken, refreshToken, expiresAt, scope}`.
+ *
+ * Provider-agnostic — the caller (the `auth` CLI command) supplies
+ * the plugin's `OAuthConfig` along with the client credentials.
+ */
+import { spawn } from "node:child_process";
+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;
+})();
+/**
+ * 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.
+ */
+export async function runOAuth(config, options) {
+    const port = OAUTH_CALLBACK_PORT;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const state = randomState();
+    const authUrl = new URL(config.authUrl);
+    authUrl.searchParams.set("client_id", options.clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("scope", config.scopes.join(" "));
+    authUrl.searchParams.set("state", state);
+    for (const [k, v] of Object.entries(config.authParams ?? {})) {
+        authUrl.searchParams.set(k, v);
+    }
+    options.onAuthUrl?.(authUrl.toString());
+    const open = options.openBrowser ?? defaultOpenBrowser;
+    open(authUrl.toString());
+    const { code } = await captureCode(port, state);
+    const tokens = await exchangeCode(config.tokenUrl, code, options.clientId, options.clientSecret, redirectUri);
+    if (!tokens.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: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: Date.now() + tokens.expires_in * 1000,
+        scope: tokens.scope,
+        tokenType: tokens.token_type,
+    };
+}
+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");
+    });
+}
+async function exchangeCode(tokenUrl, code, clientId, clientSecret, redirectUri) {
+    const body = new URLSearchParams({
+        code,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: redirectUri,
+        grant_type: "authorization_code",
+    });
+    const res = await fetch(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()}`);
+    }
+    return (await res.json());
+}
+function randomState() {
+    return (Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2));
+}
+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 { OAuthTokens, RunOAuthOptions } from "./core/oauth.js";
+export { OAUTH_CALLBACK_PORT, 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 { OAUTH_CALLBACK_PORT, 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;
         }

package/dist/plugin/types.d.ts

@@ -23,6 +23,51 @@ export interface ActionContext {
         warn(msg: string): void;
         error(msg: string): void;
     };
+    /**
+     * Merge a partial config patch into the current connection,
+     * persisting it atomically to `.runline/config.json`.
+     *
+     * Intended for plugins that refresh credentials at runtime
+     * (OAuth access tokens, rotating API keys). The write is
+     * guarded by a file lock, so concurrent `runline exec`
+     * processes refreshing the same connection won't race.
+     *
+     * In-memory `ctx.connection.config` is also mutated so the
+     * rest of the current action sees the new values.
+     */
+    updateConnection(patch: Record<string, unknown>): Promise<void>;
+}
+/**
+ * OAuth2 authorization-code configuration declared by a plugin.
+ * Consumed by the generic `runline auth <plugin>` flow, which
+ * handles the browser redirect, code exchange, and persistence
+ * of `clientId`, `clientSecret`, `refreshToken`, `accessToken`,
+ * and `accessTokenExpiresAt` into the plugin's connection.
+ */
+export interface OAuthConfig {
+    /** Authorization endpoint, e.g. https://accounts.google.com/o/oauth2/v2/auth */
+    authUrl: string;
+    /** Token endpoint, e.g. https://oauth2.googleapis.com/token */
+    tokenUrl: string;
+    /** Scopes to request on the consent screen. */
+    scopes: string[];
+    /**
+     * Extra query parameters on the auth URL. Used for provider-
+     * specific knobs like Google's `access_type=offline` and
+     * `prompt=consent` (both required to get a refresh token back).
+     */
+    authParams?: Record<string, string>;
+    /**
+     * Printed by `runline auth <plugin>` before credentials are
+     * requested. Each array entry is a line. The token
+     * `{{redirectUri}}` is substituted with the actual callback URL
+     * the plugin will use, so users can register it verbatim with
+     * the provider (e.g. in Google Cloud Console).
+     *
+     * Omit for plugins where client credentials come from the
+     * provider's partner program and no user setup is needed.
+     */
+    setupHelp?: string[];
 }
 export interface PluginDef {
     name: string;
@@ -35,6 +80,8 @@ export interface PluginDef {
         default?: unknown;
         env?: string;
     }>;
+    /** OAuth2 config for `runline auth <plugin>`. */
+    oauth?: OAuthConfig;
     /** @internal */
     initHooks?: Array<(config: Record<string, unknown>) => void>;
 }