@kairon/cli 0.1.0

package/dist/commands/whoami.js

@@ -0,0 +1,51 @@
+import { connectMcp } from '../client.js';
+import { CliError } from '../errors.js';
+import { resolveAccessToken } from '../session.js';
+/**
+ * `kairon whoami` — who this machine is authenticated as, and whether the MCP door
+ * actually opens (MR48).
+ *
+ * It answers with two independent facts on purpose. `GET /mcp/me` names the
+ * principal; the MCP handshake proves the *transport* works and reports how many
+ * tools this server offers. A token can pass the first and fail the second (an
+ * expired seat, a locked subscription, a proxy eating the JSON-RPC POST), and
+ * "logged in but nothing works" is precisely the state a whoami command exists to
+ * make legible.
+ */
+export async function whoami(server, out = process.stdout) {
+    const token = await resolveAccessToken(server);
+    const identity = await fetchIdentity(server, token);
+    const client = await connectMcp(server, token);
+    let toolCount;
+    try {
+        const { tools } = await client.listTools();
+        toolCount = tools.length;
+    }
+    finally {
+        await client.close();
+    }
+    out.write(`${identity.user.name} <${identity.user.email}>\n`);
+    out.write(`Organization: ${identity.organization.name} (${identity.organization.id})\n`);
+    out.write(`Server:       ${server}\n`);
+    out.write(`Tools:        ${toolCount}\n`);
+    return { identity, toolCount };
+}
+async function fetchIdentity(server, token) {
+    let response;
+    try {
+        response = await fetch(`${server}/mcp/me`, {
+            headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
+        });
+    }
+    catch (error) {
+        throw new CliError(`Could not reach ${server}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (response.status === 401) {
+        throw new CliError(`${server} rejected your credentials.`, `kairon login --server ${server}`);
+    }
+    if (!response.ok) {
+        const body = (await response.json().catch(() => ({})));
+        throw new CliError(body.message ?? body.error ?? `${server} answered HTTP ${response.status}.`, response.status === 403 ? 'Connect a LinkedIn account in the Kairon web app.' : undefined);
+    }
+    return (await response.json());
+}

package/dist/config.js

@@ -0,0 +1,87 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const EMPTY = { version: 1, servers: {} };
+/** `~/.kairon`, or `KAIRON_CONFIG_DIR` when a test (or a sandbox) redirects it. */
+export function configDir(env = process.env) {
+    return env.KAIRON_CONFIG_DIR ?? join(homedir(), '.kairon');
+}
+export function configPath(env = process.env) {
+    return join(configDir(env), 'config.json');
+}
+/**
+ * Read the credential file, treating "absent" and "unreadable" alike.
+ *
+ * A corrupt config must not brick the CLI: the file holds nothing that cannot be
+ * rebuilt by logging in again, so a parse failure degrades to "logged out" and
+ * the user gets the ordinary `kairon login` prompt instead of a JSON syntax error.
+ */
+export async function readConfig(env = process.env) {
+    let raw;
+    try {
+        raw = await readFile(configPath(env), 'utf8');
+    }
+    catch {
+        return { ...EMPTY, servers: {} };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.servers !== 'object') {
+            return { ...EMPTY, servers: {} };
+        }
+        return { version: 1, servers: parsed.servers ?? {} };
+    }
+    catch {
+        return { ...EMPTY, servers: {} };
+    }
+}
+/**
+ * Persist the credential file at mode `0600` (MR47).
+ *
+ * Two details that are easy to get wrong and silent when you do:
+ *
+ *  - `writeFile`'s `mode` option applies **only when the file is created**. On
+ *    every later write an already-loose file keeps its old mode, so the `chmod`
+ *    below is not belt-and-braces — it is the only thing that repairs a file that
+ *    was created before this code, or by a umask that widened it.
+ *  - The write goes to a temp file and is renamed into place. `rename` within a
+ *    directory is atomic, so an interrupted write (Ctrl-C mid-login) leaves the
+ *    previous credentials intact rather than a truncated file.
+ */
+export async function writeConfig(config, env = process.env) {
+    const path = configPath(env);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await chmod(tmp, 0o600);
+    await rename(tmp, path);
+}
+export async function readCredentials(server, env = process.env) {
+    const config = await readConfig(env);
+    return config.servers[server];
+}
+export async function saveCredentials(server, credentials, env = process.env) {
+    const config = await readConfig(env);
+    config.servers[server] = credentials;
+    await writeConfig(config, env);
+}
+/**
+ * Forget one server's credentials. Returns whether there was anything to forget,
+ * so `kairon logout` can tell the truth instead of always claiming success.
+ *
+ * When the last server goes, the file goes with it: leaving an empty `servers: {}`
+ * behind would mean `kairon logout` never actually removes stored credentials,
+ * which is the thing it promises to do (MR48).
+ */
+export async function clearCredentials(server, env = process.env) {
+    const config = await readConfig(env);
+    if (!(server in config.servers))
+        return false;
+    delete config.servers[server];
+    if (Object.keys(config.servers).length === 0) {
+        await rm(configPath(env), { force: true });
+        return true;
+    }
+    await writeConfig(config, env);
+    return true;
+}

package/dist/errors.js

@@ -0,0 +1,23 @@
+/**
+ * The one error a user is *meant* to see.
+ *
+ * Everything the CLI can predict — no credentials, a dead refresh token, an
+ * unreachable server, a bad flag — is a `CliError`, and `index.ts` prints its
+ * message and exits 1 with no stack trace (MR49). A stack trace escaping to the
+ * terminal therefore means something genuinely unforeseen happened, which is the
+ * only time it is useful information.
+ */
+export class CliError extends Error {
+    hint;
+    constructor(message, 
+    /** What to do next, printed under the message. Keep it to one runnable line. */
+    hint) {
+        super(message);
+        this.hint = hint;
+        this.name = 'CliError';
+    }
+}
+/** The message every "your session is over" path ends at, so they read alike. */
+export function notLoggedIn(server) {
+    return new CliError(`Not logged in to ${server}.`, `kairon login --server ${server}`);
+}

package/dist/flags.js

@@ -0,0 +1,254 @@
+import { CliError } from './errors.js';
+/** Flags the CLI owns; a tool input of the same name is reachable through `--json`. */
+export const RESERVED_FLAGS = new Set(['server', 'json', 'refresh', 'help', 'h', 'version', 'v']);
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+/**
+ * Derive the flag list from a tool's input schema (MR53).
+ *
+ * Three shapes, three treatments:
+ *
+ * - **scalars** become `--flag` and take their value literally;
+ * - **nested objects** recurse into dot paths (`--config.keyword`), because an
+ *   agent-facing schema nests freely and flattening the names would collide;
+ * - **arrays and unions** become one flag that takes **JSON text**
+ *   (`--items '[{"url":"…"}]'`). There is no honest flat spelling for
+ *   "an array of either a memberId or a url or a snapshot", and inventing one
+ *   (repeated flags? comma splitting?) would be a second, worse schema language.
+ *   `--json` remains available for the whole object either way.
+ *
+ * Order is schema order, not alphabetical: the schema lists the identifying fields
+ * first, and help that mirrors it reads like the call you are about to make.
+ */
+export function flagsOf(schema, prefix = '', reachable = true) {
+    const properties = schema?.properties;
+    if (!properties)
+        return [];
+    const required = new Set(schema.required ?? []);
+    return Object.entries(properties).flatMap(([key, property]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        // A leaf is only required if EVERY ancestor is too. `search_sales_navigator`
+        // has an optional `annualRevenue` whose own `currency`/`min`/`max` are required
+        // *within it*; without this, help demanded three flags for a filter nobody has
+        // to use — found by rendering the real catalogue, not by reading the code.
+        const isRequired = reachable && required.has(key);
+        if (isPlainObject(property)) {
+            const nested = flagsOf(property, path, isRequired);
+            // An object with no declared properties (a free-form record) has nothing to
+            // recurse into — offer it as one JSON flag rather than dropping it silently.
+            if (nested.length > 0)
+                return nested;
+            return [{ path, type: 'json', required: isRequired, json: true, ...describe(property) }];
+        }
+        return [
+            {
+                path,
+                type: typeOf(property),
+                required: isRequired,
+                json: !isScalar(property),
+                ...describe(property),
+            },
+        ];
+    });
+}
+function describe(schema) {
+    return schema.description ? { description: schema.description } : {};
+}
+function isPlainObject(schema) {
+    return schema.type === 'object' && !schema.anyOf && !schema.oneOf;
+}
+function isScalar(schema) {
+    return schema.type !== undefined && SCALAR_TYPES.has(schema.type);
+}
+function typeOf(schema) {
+    if (Array.isArray(schema.enum) && schema.enum.length > 0)
+        return schema.enum.join('|');
+    if (schema.type === 'array')
+        return 'json array';
+    if (!isScalar(schema))
+        return 'json';
+    return schema.type;
+}
+/**
+ * Assemble the tool input from parsed flags (MR53).
+ *
+ * `--json` wins outright when present: it is the escape hatch for anything the flat
+ * flags express badly, and merging the two would make the resulting input depend on
+ * a precedence rule nobody wants to learn. Passing both is an error, not a merge.
+ *
+ * A flag the schema doesn't know is a hard error rather than a passthrough — the
+ * server would reject it anyway, and rejecting it here is what turns `--limmit 5`
+ * into a named typo instead of a round trip and a 422.
+ */
+export function buildInput(flags, schema, command) {
+    const specs = flagsOf(schema);
+    const byPath = new Map(specs.map((spec) => [spec.path, spec]));
+    const supplied = Object.entries(flags).filter(([name]) => !RESERVED_FLAGS.has(name));
+    const raw = flags.json;
+    if (typeof raw === 'string') {
+        if (supplied.length > 0) {
+            throw new CliError(`--json carries the whole input, so it cannot be combined with --${supplied[0]?.[0]}.`, `kairon ${command} --json '{…}'`);
+        }
+        // A tool's input is an object. Valid JSON that is an array, a string or `null`
+        // parses fine and then is NOT one — and for a tool with no required fields
+        // nothing downstream notices, so it goes to the server as the argument object.
+        // (`null` used to reach `Object.entries` and throw a raw TypeError, which
+        // `index.ts` prints as a stack trace — the one thing MR49 says never happens.)
+        const parsed = parseJsonFlag(raw, 'json', command);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new CliError(`--json must be a JSON object, got ${describeJson(parsed)}.`, `kairon ${command} --json '{"…":"…"}'`);
+        }
+        return parsed;
+    }
+    const input = {};
+    for (const [name, value] of supplied) {
+        const spec = byPath.get(name);
+        if (!spec)
+            throw unknownFlag(name, specs, command);
+        assign(input, name, spec.json ? parseJsonFlag(value, name, command) : coerce(value, spec, command));
+    }
+    return input;
+}
+/** `config.target.url` → `input.config.target.url`, creating the objects on the way. */
+function assign(input, path, value) {
+    const segments = path.split('.');
+    const leaf = segments.pop();
+    let cursor = input;
+    for (const segment of segments) {
+        const existing = cursor[segment];
+        if (existing === undefined)
+            cursor[segment] = {};
+        cursor = cursor[segment];
+    }
+    cursor[leaf] = value;
+}
+/**
+ * Parse a flag's JSON value. Returns `unknown`, because that is what it is — the
+ * previous signature was `never`, which is assignable to everything and therefore
+ * type-checked nothing; the caller's `Record<string, unknown>` was simply believed.
+ */
+function parseJsonFlag(value, name, command) {
+    if (typeof value !== 'string') {
+        throw new CliError(`--${name} needs a JSON value.`, `kairon ${command} --${name} '{…}'`);
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new CliError(`--${name} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, `kairon ${command} --${name} '{…}'`);
+    }
+}
+/** "an array" / "a string" / "null" — enough for the user to see what they passed. */
+function describeJson(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return `a ${typeof value}`;
+}
+function coerce(value, spec, command) {
+    if (spec.type === 'boolean') {
+        if (typeof value === 'boolean')
+            return value;
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        throw new CliError(`--${spec.path} is a flag; pass --${spec.path} or --no-${spec.path}.`, `kairon ${command} --${spec.path}`);
+    }
+    // `--flag` with no value on a non-boolean is the "I forgot the value" case, and
+    // silently sending `true` would fail server-side with a type error about a value
+    // the user never typed.
+    if (typeof value === 'boolean') {
+        throw new CliError(`--${spec.path} needs a value.`, `kairon ${command} --${spec.path} <value>`);
+    }
+    if (spec.type === 'number' || spec.type === 'integer') {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) {
+            throw new CliError(`--${spec.path} must be a number (got "${value}").`);
+        }
+        return parsed;
+    }
+    return value;
+}
+/**
+ * Name the offending flag, and — when it is close to a real one — the flag they meant.
+ * A typo is the single most common way a generated CLI is wrong, and "unknown option"
+ * with no candidate makes the user go read `--help` for a name they nearly typed.
+ */
+function unknownFlag(name, specs, command) {
+    const closest = specs
+        .map((spec) => ({ path: spec.path, distance: distance(name, spec.path) }))
+        .filter((candidate) => candidate.distance <= Math.max(2, Math.floor(name.length / 3)))
+        .sort((a, b) => a.distance - b.distance)[0];
+    return new CliError(`Unknown option "--${name}" for "kairon ${command}".`, closest ? `Did you mean --${closest.path}?` : `kairon ${command} --help`);
+}
+/** Levenshtein, small and local — the alternative is a dependency for one hint. */
+function distance(a, b) {
+    // One rolling row instead of the full matrix: the hint only needs the number.
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+/**
+ * Validate the assembled input against the cached schema BEFORE connecting (MR54).
+ *
+ * Checks only what it can be sure of — required fields, scalar types, enum members —
+ * and says nothing about anything else. The asymmetry is deliberate: a false
+ * rejection here blocks a call the server would have accepted and there is no way
+ * for the user to override it, whereas a missed check just means the server answers
+ * instead. So this errs toward letting things through.
+ */
+export function validateInput(input, schema, command, prefix = '') {
+    if (!schema?.properties)
+        return;
+    for (const name of schema.required ?? []) {
+        if (input[name] === undefined) {
+            const path = prefix ? `${prefix}.${name}` : name;
+            throw new CliError(`"kairon ${command}" needs --${path}.`, `kairon ${command} --${path} <value>`);
+        }
+    }
+    for (const [key, value] of Object.entries(input)) {
+        const property = schema.properties[key];
+        if (!property)
+            continue;
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (Array.isArray(property.enum) &&
+            property.enum.length > 0 &&
+            !property.enum.includes(value)) {
+            throw new CliError(`--${path} must be one of: ${property.enum.join(', ')} (got "${String(value)}").`);
+        }
+        if (isScalar(property) && !matchesType(value, property.type)) {
+            throw new CliError(`--${path} must be ${article(property.type)} (got ${typeName(value)}).`);
+        }
+        if (isPlainObject(property) && value !== null && typeof value === 'object') {
+            validateInput(value, property, command, path);
+        }
+    }
+}
+function matchesType(value, type) {
+    if (type === 'integer')
+        return typeof value === 'number' && Number.isInteger(value);
+    if (type === 'number')
+        return typeof value === 'number';
+    if (type === 'boolean')
+        return typeof value === 'boolean';
+    return typeof value === 'string';
+}
+/** "an integer" / "a string" — the message is read by people, not parsed. */
+function article(noun) {
+    return `${/^[aeiou]/.test(noun) ? 'an' : 'a'} ${noun}`;
+}
+function typeName(value) {
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    return article(typeof value);
+}

package/dist/help.js

@@ -0,0 +1,126 @@
+import { flagsOf } from './flags.js';
+import { commandNameOf, displayName, groupsOf, toolsInGroup } from './naming.js';
+/**
+ * Help, rendered from the catalogue (MR51/MR53).
+ *
+ * Every line below comes from `tools/list`. Nothing here knows the name of a single
+ * tool, which is what makes the CLI incapable of drifting from the server — and also
+ * what makes this file's job narrow: lay out text, decide nothing.
+ *
+ * ADR-0054 §7 accepted a consequence that shows up here: a tool `description` is now
+ * *user-facing help* as well as model-facing guidance. `search_sales_navigator`'s
+ * playbook runs to thousands of tokens and reads oddly in a terminal. The answer is
+ * not two descriptions that drift apart — it is that the summary line is the first
+ * sentence, with the full text kept for the command's own `--help`.
+ */
+/** Abbreviations whose period does NOT end a sentence. */
+const ABBREVIATIONS = /(?:^|[\s([])(?:e\.g|i\.e|etc|vs|approx|no|max|min)\.$/i;
+/**
+ * The first sentence of a description — the one-line summary in a command list.
+ *
+ * The abbreviation guard is not fussiness: without it, "Profile languages as
+ * 2-letter ISO codes (e.g. en, es)" summarised to "…codes (e.g." — a line that
+ * reads as truncated text rather than a summary, and there were two of them on one
+ * screen of `search sales-navigator --help`.
+ */
+export function summarize(description, width = 68) {
+    if (!description)
+        return '';
+    const firstLine = (description.split('\n')[0] ?? '').replace(/\*\*/g, '').replace(/`/g, '');
+    let sentence = firstLine;
+    for (const match of firstLine.matchAll(/[.!?](\s|$)/g)) {
+        const candidate = firstLine.slice(0, (match.index ?? 0) + 1);
+        if (ABBREVIATIONS.test(candidate))
+            continue;
+        sentence = candidate;
+        break;
+    }
+    const clean = sentence.trim();
+    return clean.length > width ? `${clean.slice(0, width - 1).trimEnd()}…` : clean;
+}
+function pad(entries, indent = '  ') {
+    const width = Math.max(0, ...entries.map(([left]) => left.length));
+    return entries
+        .map(([left, right]) => `${indent}${left.padEnd(width)}  ${right}`.trimEnd())
+        .join('\n');
+}
+const GLOBAL_OPTIONS = [
+    ['--server <url>', 'Target a specific Kairon (default: KAIRON_API_URL, else production)'],
+    ['--json <json>', 'Pass the entire tool input as one JSON object'],
+    ['--refresh', 'Re-fetch the tool catalogue before running'],
+    ['-h, --help', 'Show help'],
+    ['-v, --version', 'Show the CLI version'],
+];
+/** `kairon --help` — the built-in commands, then one line per tool group. */
+export function rootHelp(tools) {
+    const groups = groupsOf(tools).map((group) => [
+        group,
+        `${toolsInGroup(tools, group).length} command${toolsInGroup(tools, group).length === 1 ? '' : 's'}`,
+    ]);
+    const sections = [
+        'kairon — drive Kairon from your terminal',
+        '',
+        'Usage',
+        '  kairon <command> [options]',
+        '',
+        'Account',
+        pad([
+            ['login', 'Sign in through your browser and store credentials'],
+            ['logout', 'Remove stored credentials for a server'],
+            ['whoami', 'Show the authenticated user, organization, and tool count'],
+        ]),
+    ];
+    if (groups.length > 0) {
+        sections.push('', 'Tools', pad(groups), '', `Run "kairon <group> --help" to list its commands.`);
+    }
+    else {
+        sections.push('', 'Tools', '  (none cached yet — run "kairon login", then "kairon --refresh --help")');
+    }
+    sections.push('', 'Options', pad(GLOBAL_OPTIONS), '', 'Environment', pad([
+        ['KAIRON_API_URL', 'Default server, overridden by --server'],
+        ['KAIRON_TOKEN', 'Use this access token and ignore stored credentials'],
+        ['KAIRON_CONFIG_DIR', 'Where credentials and the tool cache live (default: ~/.kairon)'],
+    ]));
+    return `${sections.join('\n')}\n`;
+}
+/** `kairon list --help` — every command in one group. */
+export function groupHelp(tools, group) {
+    const entries = toolsInGroup(tools, group).map((tool) => [
+        commandNameOf(tool.name).verb ?? tool.name,
+        summarize(tool.description),
+    ]);
+    return `Usage\n  kairon ${group} <command> [options]\n\nCommands\n${pad(entries)}\n\nRun "kairon ${group} <command> --help" for a command's flags.\n`;
+}
+/** `kairon list add --help` — the tool's own description and its derived flags. */
+export function commandHelp(tool) {
+    const name = displayName(tool.name);
+    const flags = flagsOf(tool.inputSchema);
+    const required = flags.filter((flag) => flag.required);
+    const optional = flags.filter((flag) => !flag.required);
+    const usage = [
+        `  kairon ${name}`,
+        ...required.map((flag) => `--${flag.path} <${flag.type}>`),
+    ].join(' ');
+    const sections = [`${tool.title ?? name} (${tool.name})`, '', 'Usage', usage];
+    if (tool.description)
+        sections.push('', 'Description', indent(tool.description));
+    if (required.length > 0)
+        sections.push('', 'Required', pad(required.map(row)));
+    if (optional.length > 0)
+        sections.push('', 'Optional', pad(optional.map(row)));
+    sections.push('', 'Options', pad([
+        ['--json <json>', 'Pass the entire input as one JSON object instead of flags'],
+        ['--server <url>', 'Target a specific Kairon'],
+        ['--refresh', 'Re-fetch the tool catalogue first'],
+    ]));
+    return `${sections.join('\n')}\n`;
+}
+function row(flag) {
+    return [`--${flag.path} <${flag.type}>`, summarize(flag.description, 60)];
+}
+function indent(text) {
+    return text
+        .split('\n')
+        .map((line) => (line.length > 0 ? `  ${line}` : line))
+        .join('\n');
+}