@kairon/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, stringFlag } from './args.js';
+import { loadCatalogue } from './catalogue.js';
+import { callTool, ToolFailed, unknownCommand } from './commands/call.js';
+import { login } from './commands/login.js';
+import { logout } from './commands/logout.js';
+import { whoami } from './commands/whoami.js';
+import { CliError } from './errors.js';
+import { commandHelp, groupHelp, rootHelp } from './help.js';
+import { findTool, groupsOf, toolsInGroup } from './naming.js';
+import { resolveServer } from './server.js';
+import { CLI_VERSION } from './version.js';
+/**
+ * The router (PRD-57 MR51/MR52).
+ *
+ * Three built-in commands — `login`, `logout`, `whoami` — and then **everything
+ * else comes from the server**. There is no list of tool commands in this file, or
+ * anywhere in `apps/cli`: `group verb` is resolved against the cached `tools/list`,
+ * so the two doors cannot drift. A tool added server-side becomes a CLI command the
+ * next time the cache refreshes, and a tool removed stops resolving. That is the
+ * whole design (ADR-0054 §7), and its evidence is the absence of a table here.
+ */
+export async function run(argv, out = process.stdout, env = process.env) {
+    const { command, positionals, flags } = parseArgs(argv);
+    if (flags.version === true) {
+        out.write(`${CLI_VERSION}\n`);
+        return;
+    }
+    const server = resolveServer(stringFlag(flags, 'server'), env);
+    const refresh = flags.refresh === true;
+    const wantsHelp = flags.help === true;
+    if (command === undefined || command === 'help') {
+        out.write(rootHelp(await catalogueFor(server, refresh, env)));
+        return;
+    }
+    if (!wantsHelp) {
+        switch (command) {
+            case 'login':
+                await login(server, out);
+                return;
+            case 'logout':
+                await logout(server, out);
+                return;
+            case 'whoami':
+                await whoami(server, out);
+                return;
+        }
+    }
+    const tools = await catalogueFor(server, refresh, env);
+    const verb = positionals[0];
+    const tool = findTool(tools, command, verb);
+    if (!tool) {
+        // A group with no verb is a request to see the group, not a mistake — `kairon
+        // list` should list, the way `git remote` does.
+        if (verb === undefined && toolsInGroup(tools, command).length > 0) {
+            out.write(groupHelp(tools, command));
+            return;
+        }
+        if (wantsHelp && ['login', 'logout', 'whoami'].includes(command)) {
+            out.write(rootHelp(tools));
+            return;
+        }
+        throw unknownCommand([command, verb].filter(Boolean).join(' '), groupsOf(tools));
+    }
+    if (wantsHelp) {
+        out.write(commandHelp(tool));
+        return;
+    }
+    await callTool(server, tool, flags, out, env);
+}
+/**
+ * The catalogue for this invocation, cache-first (MR57).
+ *
+ * A cache miss with no credentials must not turn `kairon --help` into a login
+ * prompt: help is the command you run *before* you have logged in. So a failed
+ * fetch degrades to an empty catalogue, and `rootHelp` says how to populate it.
+ * `--refresh` is the exception — it is an explicit request to go and look, so its
+ * failure is the answer.
+ */
+async function catalogueFor(server, refresh, env) {
+    try {
+        return await loadCatalogue(server, { refresh, env });
+    }
+    catch (error) {
+        if (refresh)
+            throw error;
+        return [];
+    }
+}
+/**
+ * The composition root. Three exit shapes, on purpose:
+ *
+ *  - a predicted CLI failure prints its message and a next step (MR49);
+ *  - a **tool** failure prints the server's `code` and its JSON payload on stderr
+ *    and exits non-zero (MR56) — the code first, because that is what a script
+ *    branches on;
+ *  - anything else keeps its stack, because an unforeseen crash is the one case
+ *    where the trace is the useful part.
+ *
+ * All three write to stderr, so a failed run leaves stdout empty and a pipeline
+ * sees nothing rather than half a document.
+ */
+async function main() {
+    try {
+        await run(process.argv.slice(2));
+    }
+    catch (error) {
+        if (error instanceof ToolFailed) {
+            process.stderr.write(`kairon ${error.command} failed: ${error.code}\n`);
+            if (error.payload !== undefined) {
+                process.stderr.write(`${JSON.stringify(error.payload, null, 2)}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (error instanceof CliError) {
+            process.stderr.write(`${error.message}\n`);
+            if (error.hint)
+                process.stderr.write(`\n  ${error.hint}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Are we the program, or is something importing us?
+ *
+ * The spec imports {@link run}, and importing must not parse argv or set an exit code —
+ * hence a guard. But the guard has to survive the way this file is actually invoked once
+ * installed: npm links `bin/kairon` to `dist/index.js`, and **Node reports the symlink
+ * path in `argv[1]`, not its target**. A guard that matched on the filename ending in
+ * `index.js` therefore answered `false` for every real installation, and `kairon whoami`
+ * exited 0 having done nothing at all — silence, not an error.
+ *
+ * `realpathSync` resolves the link so both sides name the same file. Wrapped because
+ * `argv[1]` can be absent (`node -e`) or point at something unstatable.
+ */
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    void main();
+}

package/dist/naming.js

@@ -0,0 +1,55 @@
+/**
+ * Tool name → command name (PRD-57 MR52).
+ *
+ * Deterministic and total, with **no mapping table** — that absence is the point.
+ * A table is a second definition of the command surface, and a second definition
+ * is a thing that drifts: add `campaign_stats` server-side, forget the table entry,
+ * and the CLI silently lacks a command nobody notices until a user asks for it.
+ * Derivation cannot forget.
+ *
+ * Split on the FIRST underscore; the remainder is kebab-cased:
+ *
+ * ```
+ * list_add                → list add
+ * campaign_run_get        → campaign run-get
+ * search_sales_navigator  → search sales-navigator
+ * signal_search           → signal search
+ * ```
+ *
+ * The first underscore, not every underscore, because the leading segment is the
+ * noun the catalogue already groups by (`list_*`, `campaign_*`, `chat_*`) and the
+ * rest is one verb phrase. Splitting on all of them would make
+ * `search_sales_navigator` into `search sales navigator` — three levels of
+ * subcommand for one operation.
+ */
+export function commandNameOf(toolName) {
+    const underscore = toolName.indexOf('_');
+    // A tool with no underscore is its own command (`kairon whoami`-shaped). None
+    // exists today; handling it here means adding one server-side is not a CLI change.
+    if (underscore === -1)
+        return { group: toolName };
+    return {
+        group: toolName.slice(0, underscore),
+        verb: toolName.slice(underscore + 1).replaceAll('_', '-'),
+    };
+}
+/** How the command reads in help and errors: `list add`. */
+export function displayName(toolName) {
+    const { group, verb } = commandNameOf(toolName);
+    return verb ? `${group} ${verb}` : group;
+}
+/** The tool a `group [verb]` pair addresses, or undefined when nothing matches. */
+export function findTool(tools, group, verb) {
+    return tools.find((tool) => {
+        const name = commandNameOf(tool.name);
+        return name.group === group && name.verb === verb;
+    });
+}
+/** Every command in a group, for `kairon list --help`. */
+export function toolsInGroup(tools, group) {
+    return tools.filter((tool) => commandNameOf(tool.name).group === group);
+}
+/** The groups a catalogue exposes, in stable order — the top level of `kairon --help`. */
+export function groupsOf(tools) {
+    return [...new Set(tools.map((tool) => commandNameOf(tool.name).group))].sort();
+}

package/dist/oauth/discovery.js

@@ -0,0 +1,62 @@
+import { CliError } from '../errors.js';
+async function getJson(url, what) {
+    let response;
+    try {
+        response = await fetch(url, { headers: { accept: 'application/json' } });
+    }
+    catch (error) {
+        throw new CliError(`Could not reach ${url} to read ${what}: ${error instanceof Error ? error.message : String(error)}`, 'Check the server URL and your network, then try again.');
+    }
+    if (!response.ok)
+        return null;
+    try {
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the authorization server for a Kairon deployment, the way an MCP client is
+ * supposed to (RFC 9728 → RFC 8414): ask the protected resource who vouches for
+ * it, then ask that issuer for its endpoints.
+ *
+ * Discovering rather than hardcoding is what makes `--server` (MR58) work against
+ * a local API, a preview deployment, and production without a build per target.
+ *
+ * Note what this deployment does **not** publish: no `jwks_uri` (access tokens are
+ * opaque and introspected server-side) and no revocation endpoint. So the CLI can
+ * neither verify a token locally nor tell the server to forget one — see
+ * `commands/logout.ts` for what that means for logout.
+ */
+export async function discoverAuthServer(server) {
+    const resource = await getJson(`${server}/.well-known/oauth-protected-resource`, 'the protected-resource metadata');
+    // Fall back to the server itself as its own issuer: a deployment that serves the
+    // authorization-server document but not the resource one is still usable, and
+    // that is exactly the shape an older Kairon has.
+    const issuer = resource?.authorization_servers?.[0] ?? server;
+    const metadata = await getJson(`${issuer.replace(/\/+$/, '')}/.well-known/oauth-authorization-server`, 'the authorization-server metadata');
+    if (!metadata?.authorization_endpoint || !metadata.token_endpoint) {
+        throw new CliError(`${server} does not look like a Kairon server: no OAuth metadata at ${issuer}.`, 'Check --server (or KAIRON_API_URL).');
+    }
+    return metadata;
+}
+/**
+ * The scopes to ask for, intersected with what the server admits it supports.
+ *
+ * `offline_access` is the load-bearing one: Better Auth only returns a refresh
+ * token when it is among the granted scopes, and without a refresh token every
+ * access token expiry (30 days) would mean another browser round trip. Asking for
+ * a scope the server doesn't list gets the whole request rejected, hence the
+ * intersection rather than a fixed string.
+ */
+export function scopesToRequest(metadata) {
+    const wanted = ['openid', 'profile', 'email', 'offline_access'];
+    const supported = metadata.scopes_supported;
+    if (!supported || supported.length === 0)
+        return wanted.join(' ');
+    const granted = wanted.filter((scope) => supported.includes(scope));
+    // `openid` alone is the floor: an authorization request with no scope at all is
+    // not one Better Auth's provider answers usefully.
+    return granted.length > 0 ? granted.join(' ') : 'openid';
+}

package/dist/oauth/loopback.js

@@ -0,0 +1,99 @@
+import { createServer } from 'node:http';
+import { CliError } from '../errors.js';
+/** What the browser tab shows once the code is in hand. */
+function resultPage(title, detail) {
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>${title}</title>
+<style>
+  body { font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+         display: grid; place-items: center; min-height: 100vh; margin: 0; color: #1a1a1a; }
+  main { max-width: 26rem; padding: 2rem; text-align: center; }
+  h1 { font-size: 1.25rem; font-weight: 600; margin: 0 0 .5rem; }
+  p { margin: 0; color: #666; }
+  @media (prefers-color-scheme: dark) { body { background: #111; color: #f5f5f5; } p { color: #999; } }
+</style></head>
+<body><main><h1>${title}</h1><p>${detail}</p></main></body></html>`;
+}
+/**
+ * A single-use HTTP listener on `127.0.0.1` to catch the OAuth redirect (MR47).
+ *
+ * Loopback (RFC 8252 §7.3) is how a native app receives an authorization code
+ * without a client secret and without a hosted callback: the browser redirects to
+ * a port only this process is listening on.
+ *
+ * Two choices worth naming:
+ *  - **`127.0.0.1`, not `localhost`.** `localhost` may resolve to `::1` on a
+ *    machine with IPv6, and then the browser knocks on a door we never opened.
+ *    RFC 8252 §8.3 says to use the literal address for exactly this reason.
+ *  - **Port 0.** The OS picks a free port, so two logins can run at once and a
+ *    fixed port can never be squatted. The cost is that registration has to wait
+ *    for the bind (see `register.ts`).
+ *
+ * `state` is verified here rather than by the caller so that a mismatched redirect
+ * can never reach the token exchange at all.
+ */
+export async function startLoopback(state) {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    // Mark the promise handled the moment it exists. It is created here but only
+    // awaited by the caller *after* dynamic client registration returns, and it can
+    // reject inside that window (a stray request to the port, a browser that
+    // pre-fetches). Node's default for an unhandled rejection is to kill the
+    // process, so without this a bad redirect crashes the CLI instead of printing
+    // the error it already knows how to print. Awaiting `code` still rejects
+    // normally — this only stops the runtime treating it as nobody's problem.
+    code.catch(() => { });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        // The browser asks for /favicon.ico on the way past; answering 404 keeps it
+        // from being mistaken for a malformed callback.
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        const send = (status, title, detail) => {
+            res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(resultPage(title, detail));
+        };
+        const error = url.searchParams.get('error');
+        if (error) {
+            const description = url.searchParams.get('error_description') ?? error;
+            send(400, 'Sign-in failed', description);
+            rejectCode(new CliError(`Authorization failed: ${description}`));
+            return;
+        }
+        if (url.searchParams.get('state') !== state) {
+            // Someone else's redirect, or a replay. Never exchange the code.
+            send(400, 'Sign-in failed', 'The response did not match this sign-in attempt.');
+            rejectCode(new CliError('Authorization state did not match. Please run kairon login again.'));
+            return;
+        }
+        const received = url.searchParams.get('code');
+        if (!received) {
+            send(400, 'Sign-in failed', 'No authorization code was returned.');
+            rejectCode(new CliError('Authorization returned no code.'));
+            return;
+        }
+        send(200, 'You are signed in', 'You can close this tab and return to your terminal.');
+        resolveCode(received);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        server.close();
+        throw new CliError('Could not open a local port to receive the sign-in redirect.');
+    }
+    const { port } = address;
+    return {
+        redirectUri: `http://127.0.0.1:${port}/callback`,
+        waitForCode: () => code,
+        close: () => server.close(),
+    };
+}

package/dist/oauth/pkce.js

@@ -0,0 +1,17 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * A PKCE verifier/challenge pair (RFC 7636), always S256.
+ *
+ * `plain` is never offered: this server rejects it, and a public client that can
+ * fall back to `plain` has no proof-of-possession at all — the interception the
+ * whole exchange exists to prevent.
+ */
+export function createPkcePair() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest().toString('base64url');
+    return { verifier, challenge, method: 'S256' };
+}
+/** A one-time value binding the browser redirect to this process (CSRF, RFC 6749 §10.12). */
+export function createState() {
+    return randomBytes(16).toString('base64url');
+}

package/dist/oauth/register.js

@@ -0,0 +1,37 @@
+import { CliError } from '../errors.js';
+/**
+ * Register this CLI as a public OAuth client (RFC 7591 Dynamic Client Registration).
+ *
+ * Registration happens on every `kairon login` rather than once at build time, and
+ * that is forced by the loopback redirect: the redirect URI carries the port we
+ * just bound, the port is ephemeral, and a registered client only accepts the
+ * exact URIs it registered. Registering after binding is the only ordering that
+ * works.
+ *
+ * `token_endpoint_auth_method: 'none'` is the honest declaration — a CLI shipped to
+ * users' machines cannot keep a client secret, so it doesn't pretend to have one.
+ * PKCE is what proves the token request came from whoever started the flow.
+ */
+export async function registerClient(metadata, redirectUri, scope) {
+    const endpoint = metadata.registration_endpoint;
+    if (!endpoint) {
+        throw new CliError('This Kairon server does not offer dynamic client registration.', 'Set KAIRON_TOKEN instead, or upgrade the server.');
+    }
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({
+            client_name: 'Kairon CLI',
+            redirect_uris: [redirectUri],
+            token_endpoint_auth_method: 'none',
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            scope,
+        }),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok || !body.client_id) {
+        throw new CliError(`Could not register with ${endpoint} (HTTP ${response.status}): ${body.error_description ?? body.error ?? 'no client_id returned'}`);
+    }
+    return body.client_id;
+}

package/dist/oauth/tokens.js

@@ -0,0 +1,100 @@
+import { CliError } from '../errors.js';
+/**
+ * Raised when the *refresh* token itself is no longer good — the one failure the
+ * CLI cannot fix on the user's behalf, so it has to become "run kairon login"
+ * rather than a retry (MR49).
+ */
+export class RefreshRejected extends Error {
+}
+/**
+ * Access-token lifetime when the server doesn't state one. Deliberately short:
+ * guessing long would mean sailing past a real expiry and failing the user's
+ * actual command, while guessing short only costs one extra refresh round trip.
+ */
+const FALLBACK_EXPIRES_IN_SECONDS = 3600;
+function toCredentials(body, clientId, previousRefreshToken) {
+    if (!body.access_token)
+        throw new CliError('The server returned no access token.');
+    const lifetime = body.expires_in ?? FALLBACK_EXPIRES_IN_SECONDS;
+    return {
+        clientId,
+        accessToken: body.access_token,
+        // Refresh-token rotation is allowed but not required; when the server declines
+        // to issue a new one, the old one stays valid and dropping it here would log
+        // the user out at the next expiry for no reason.
+        refreshToken: body.refresh_token ?? previousRefreshToken,
+        expiresAt: new Date(Date.now() + lifetime * 1000).toISOString(),
+        scope: body.scope,
+    };
+}
+async function postForm(endpoint, form) {
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json',
+        },
+        body: new URLSearchParams(form).toString(),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const detail = body.error_description ?? body.error ?? `HTTP ${response.status}`;
+        // `invalid_grant` is the spec's way of saying the grant is spent, revoked, or
+        // expired. On the refresh path that is terminal; `session.ts` turns it into
+        // the re-login message.
+        if (body.error === 'invalid_grant')
+            throw new RefreshRejected(detail);
+        throw new CliError(`Token request failed: ${detail}`);
+    }
+    return body;
+}
+/** Exchange the authorization code for tokens, proving PKCE possession (MR47). */
+export async function exchangeCode(metadata, params) {
+    const body = await postForm(metadata.token_endpoint, {
+        grant_type: 'authorization_code',
+        code: params.code,
+        redirect_uri: params.redirectUri,
+        client_id: params.clientId,
+        code_verifier: params.verifier,
+    });
+    return toCredentials(body, params.clientId);
+}
+/**
+ * Trade a refresh token for a fresh access token (MR49).
+ *
+ * Throws `RefreshRejected` when the refresh token is dead — distinct from a
+ * network blip or a 500, which are worth surfacing as themselves rather than
+ * telling the user to log in again over a transient failure.
+ */
+export async function refreshCredentials(metadata, credentials) {
+    if (!credentials.refreshToken) {
+        throw new RefreshRejected('no refresh token was stored');
+    }
+    const body = await postForm(metadata.token_endpoint, {
+        grant_type: 'refresh_token',
+        refresh_token: credentials.refreshToken,
+        client_id: credentials.clientId,
+    });
+    return toCredentials(body, credentials.clientId, credentials.refreshToken);
+}
+/**
+ * Build the URL the user's browser opens to approve the CLI.
+ *
+ * The `resource` parameter (RFC 8707) is deliberately absent: this server's
+ * authorize endpoint does not consume it, and sending an unrecognised parameter
+ * to an authorization endpoint is the sort of thing that fails in production and
+ * nowhere else.
+ */
+export function authorizeUrl(metadata, params) {
+    const url = new URL(metadata.authorization_endpoint);
+    url.search = new URLSearchParams({
+        response_type: 'code',
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        code_challenge: params.challenge,
+        code_challenge_method: 'S256',
+        scope: params.scope,
+        state: params.state,
+    }).toString();
+    return url.toString();
+}

package/dist/server.js

@@ -0,0 +1,40 @@
+import { CliError } from './errors.js';
+/**
+ * Where `kairon` points when nobody says otherwise (MR58).
+ *
+ * The API and the SPA share this origin — the MCP door is `/mcp` on it, and the
+ * OAuth authorization server is the same host (see the discovery chain in
+ * `oauth/discovery.ts`).
+ */
+export const PRODUCTION_SERVER = 'https://app.heykairon.com';
+/**
+ * Resolve the target Kairon: `--server`, else `KAIRON_API_URL`, else production
+ * (MR58). Defaulting to production is the deliberate choice — the CLI is for
+ * operators, and an operator who has to pass a flag to reach their own data will
+ * eventually point a script at the wrong place. Developers opt *out* by env var.
+ */
+export function resolveServer(flag, env = process.env) {
+    const raw = flag ?? env.KAIRON_API_URL ?? PRODUCTION_SERVER;
+    return normalizeServer(raw);
+}
+/**
+ * Canonical form of a server URL: origin + path, no trailing slash.
+ *
+ * Normalising matters beyond tidiness — the credential store is keyed by this
+ * string, so `https://app.heykairon.com` and `https://app.heykairon.com/` must
+ * not become two entries that each think the other is logged out.
+ */
+export function normalizeServer(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CliError(`"${raw}" is not a valid server URL.`, 'kairon --server https://app.heykairon.com');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new CliError(`Server URL must be http or https, got "${url.protocol}".`);
+    }
+    const path = url.pathname.replace(/\/+$/, '');
+    return `${url.origin}${path}`;
+}

package/dist/session.js

@@ -0,0 +1,54 @@
+import { readCredentials, saveCredentials } from './config.js';
+import { CliError, notLoggedIn } from './errors.js';
+import { discoverAuthServer } from './oauth/discovery.js';
+import { RefreshRejected, refreshCredentials } from './oauth/tokens.js';
+/**
+ * Refresh this far before the stated expiry.
+ *
+ * A token that is valid "for another 5 seconds" is not valid enough: the request
+ * still has to cross the network and be introspected, and the server compares
+ * against its own clock, which is not exactly ours. Sixty seconds of slack turns a
+ * rare, confusing 401 into a refresh nobody notices.
+ */
+const REFRESH_SKEW_MS = 60_000;
+export function isExpiring(expiresAt, now = Date.now()) {
+    const at = Date.parse(expiresAt);
+    // An unparseable timestamp is treated as expired: refreshing needlessly costs
+    // one round trip, whereas trusting a corrupt value costs the user's command.
+    if (Number.isNaN(at))
+        return true;
+    return at - REFRESH_SKEW_MS <= now;
+}
+/**
+ * The bearer token for the next call, refreshed if it needs to be (MR49, MR50).
+ *
+ * Order matters. `KAIRON_TOKEN` wins outright and short-circuits everything —
+ * no config file is read, none is written, and no refresh is attempted. That is
+ * what makes a headless run (CI, cron, a container) work with no `~/.kairon` at
+ * all, and it is deliberately the *only* headless story: an API-key scheme would
+ * reverse ADR-0017 §2 and is its own decision, not a convenience to slip in here.
+ */
+export async function resolveAccessToken(server, env = process.env) {
+    const override = env.KAIRON_TOKEN?.trim();
+    if (override)
+        return override;
+    const stored = await readCredentials(server, env);
+    if (!stored)
+        throw notLoggedIn(server);
+    if (!isExpiring(stored.expiresAt))
+        return stored.accessToken;
+    const metadata = await discoverAuthServer(server);
+    try {
+        const refreshed = await refreshCredentials(metadata, stored);
+        await saveCredentials(server, refreshed, env);
+        return refreshed.accessToken;
+    }
+    catch (error) {
+        if (error instanceof RefreshRejected) {
+            // The end of the road, and the one place the user has to act. Say so in a
+            // sentence and hand them the command, rather than surfacing `invalid_grant`.
+            throw new CliError(`Your session for ${server} has expired.`, `kairon login --server ${server}`);
+        }
+        throw error;
+    }
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Reported to the MCP server as the client version, and by `kairon --version`. */
+export const CLI_VERSION = '0.1.0';
+export const CLI_NAME = 'kairon-cli';