@kosuke-ai/cli 0.0.56 → 1.0.0

package/dist/runtime/attach.js

@@ -0,0 +1,139 @@
+import { Argument, Command, InvalidArgumentError, Option } from 'commander';
+import { buildRequest, execute, readWholeBody, UsageError } from './invoke.js';
+/**
+ * One commander command per operation descriptor: positionals for path
+ * params, a flag per top-level field, `--body`/`--body-file` for a whole
+ * body and `--attach` where the operation takes files. The command's help is
+ * the contract's summary, verbatim.
+ */
+export function attachOperation(root, operation, runtime) {
+    const parent = groupFor(root, operation.command.slice(0, -1));
+    const leaf = parent.command(operation.command[operation.command.length - 1]);
+    leaf.description(operation.summary);
+    for (const name of operation.pathParams) {
+        leaf.addArgument(new Argument(`<${name}>`, humanize(name)));
+    }
+    const fields = dedupe([
+        ...operation.query,
+        ...(operation.body?.fields ?? []),
+        ...(operation.multipart ?? []),
+    ]);
+    for (const field of fields) {
+        leaf.addOption(optionFor(field));
+        // Both spellings, so a field whose meaningful value is false (members
+        // --no-include-invitations) can be said; neither given leaves it unsent.
+        if (field.kind === 'boolean') {
+            leaf.addOption(new Option(`--no-${field.flag}`, `Send ${field.name} as false.`));
+        }
+    }
+    const takesBody = operation.body !== null || operation.multipart !== null;
+    if (takesBody) {
+        leaf.option('--body <json>', 'The whole request body as JSON; overrides field flags.');
+        leaf.option('--body-file <path>', 'Read the whole request body from a file, or - for stdin.');
+    }
+    if (operation.attachments) {
+        leaf.option('--attach <path>', 'Attach a file; repeat for several. Sends the request as multipart.', collect, []);
+    }
+    leaf.action(async (...args) => {
+        const options = args[args.length - 2];
+        const positionals = args.slice(0, operation.pathParams.length);
+        const input = {
+            pathParams: Object.fromEntries(operation.pathParams.map((name, i) => [name, positionals[i]])),
+            fields: Object.fromEntries(fields.map((field) => [field.name, options[optionKey(field.flag)]])),
+            wholeBody: readWholeBody({
+                body: options.body,
+                bodyFile: options.bodyFile,
+            }),
+            attachments: options.attach ?? [],
+        };
+        let request;
+        try {
+            request = buildRequest(operation, input);
+        }
+        catch (error) {
+            if (error instanceof UsageError)
+                leaf.error(error.message);
+            throw error;
+        }
+        const client = runtime.client({ anonymous: operation.anonymous });
+        const outcome = await execute(client, request);
+        runtime.output(outcome);
+    });
+    return leaf;
+}
+function groupFor(root, path) {
+    let current = root;
+    for (const segment of path) {
+        const existing = current.commands.find((command) => command.name() === segment);
+        current = existing ?? current.command(segment).description(`${humanize(segment)} commands`);
+    }
+    return current;
+}
+function optionFor(field) {
+    const description = field.description ?? '';
+    if (field.kind === 'boolean')
+        return new Option(`--${field.flag}`, description);
+    const option = new Option(`--${field.flag} <value>`, description);
+    if (field.choices)
+        option.choices([...field.choices]);
+    if (field.kind === 'number' || field.kind === 'integer')
+        option.argParser(numberParser(field));
+    if (field.kind === 'json')
+        option.argParser(jsonParser);
+    return option;
+}
+/**
+ * Decimal digits only. `Number()` reads '' as 0, '0x10' as 16 and '1e999' as
+ * Infinity (which JSON writes as null), none of which a customer meant.
+ */
+const DECIMAL = /^-?\d+(\.\d+)?$/;
+const INTEGER = /^-?\d+$/;
+function numberParser(field) {
+    return (raw) => {
+        const pattern = field.kind === 'integer' ? INTEGER : DECIMAL;
+        if (!pattern.test(raw)) {
+            throw new InvalidArgumentError(field.kind === 'integer' ? 'Expected an integer.' : 'Expected a number.');
+        }
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new InvalidArgumentError('Expected a finite number.');
+        return value;
+    };
+}
+function jsonParser(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new InvalidArgumentError('Expected JSON.');
+    }
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+/**
+ * One option per flag. The generator gives the same wire name on the JSON and
+ * the form branch one flag, and two wire names never one flag; this keys on
+ * the flag because that is what commander refuses to register twice.
+ */
+function dedupe(fields) {
+    const seen = new Set();
+    return fields.filter((field) => {
+        if (seen.has(field.flag))
+            return false;
+        seen.add(field.flag);
+        return true;
+    });
+}
+/** commander stores `--exclude-archived` as `excludeArchived`. */
+export function optionKey(flag) {
+    return flag.replace(/-([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+/** `projectId` reads as `Project id`; `env-vars` as `Env vars`. */
+export function humanize(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/-/g, ' ')
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}

package/dist/runtime/attachments.js

@@ -0,0 +1,58 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+/**
+ * Files on a multipart request, the way the platform reads them.
+ *
+ * Hand-written on purpose. The API takes `attachmentCount` and one file per
+ * `attachment_<i>` field, and a field whose name carries an index is not
+ * something an OpenAPI document can describe: the spec marks the operation
+ * with `x-kosuke-attachments` and stops there, so the convention lives here,
+ * outside the generated tree, in the one place that has to know it.
+ *
+ * Limits mirror the server's (10 files, 10 MiB each) so a bad batch fails
+ * before any byte is uploaded rather than after.
+ */
+const MAX_ATTACHMENT_FILES = 10;
+const MAX_ATTACHMENT_FILE_SIZE = 10 * 1024 * 1024;
+/**
+ * The server trusts an explicit media type and only infers one, from the
+ * extension, for documents sent as octet-stream. Images are never inferred,
+ * so a screenshot has to arrive typed or it is refused.
+ */
+const MEDIA_TYPES = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.tsv': 'text/tab-separated-values',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.yaml': 'application/x-yaml',
+    '.yml': 'application/x-yaml',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xls': 'application/vnd.ms-excel',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+};
+function mediaTypeFor(path) {
+    return MEDIA_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+export function appendAttachments(form, paths) {
+    if (paths.length > MAX_ATTACHMENT_FILES) {
+        throw new Error(`At most ${MAX_ATTACHMENT_FILES} attachments per request; ${paths.length} given.`);
+    }
+    // Size from the inode before the read: a file past the cap must fail with
+    // this message, not with the runtime's own error once it has been loaded.
+    for (const path of paths) {
+        if (statSync(path).size > MAX_ATTACHMENT_FILE_SIZE) {
+            throw new Error(`${path} is larger than the 10 MiB attachment limit.`);
+        }
+    }
+    const files = paths.map((path) => new File([readFileSync(path)], basename(path), { type: mediaTypeFor(path) }));
+    form.set('attachmentCount', String(files.length));
+    files.forEach((file, index) => form.set(`attachment_${index}`, file));
+}

package/dist/runtime/client.js

@@ -0,0 +1,12 @@
+import createClient, {} from 'openapi-fetch';
+import { version } from './version.js';
+export function createApiClient({ apiUrl, apiKey, fetch }) {
+    return createClient({
+        baseUrl: apiUrl,
+        headers: {
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            'User-Agent': `@kosuke-ai/cli/${version}`,
+        },
+        ...(fetch ? { fetch } : {}),
+    });
+}

package/dist/runtime/config.js

@@ -0,0 +1,49 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_API_URL = 'https://app.kosuke.ai';
+function configDir(env = process.env) {
+    if (env.KOSUKE_CONFIG_DIR)
+        return env.KOSUKE_CONFIG_DIR;
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, 'kosuke');
+    if (process.platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, 'kosuke');
+    return join(homedir(), '.config', 'kosuke');
+}
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), 'credentials.json');
+}
+export function readCredentials(env = process.env) {
+    try {
+        const parsed = JSON.parse(readFileSync(credentialsPath(env), 'utf8'));
+        if (parsed && typeof parsed === 'object' && 'apiKey' in parsed) {
+            const { apiKey, apiUrl } = parsed;
+            if (typeof apiKey === 'string' && apiKey.length > 0) {
+                return { apiKey, ...(typeof apiUrl === 'string' ? { apiUrl } : {}) };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(credentials, null, 2) + '\n', { mode: 0o600 });
+    // `mode` on write only applies to a file being created; an existing one keeps
+    // whatever it had, and a token file must not.
+    chmodSync(path, 0o600);
+    return path;
+}
+export function deleteCredentials(env = process.env) {
+    try {
+        rmSync(credentialsPath(env));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime/credentials.js

@@ -0,0 +1,24 @@
+import { DEFAULT_API_URL, readCredentials } from './config.js';
+export function resolveCredentials(flags, env = process.env) {
+    const stored = readCredentials(env);
+    const apiKey = flags.apiKey
+        ? { value: flags.apiKey, source: 'flag' }
+        : env.KOSUKE_API_KEY
+            ? { value: env.KOSUKE_API_KEY, source: 'env' }
+            : stored
+                ? { value: stored.apiKey, source: 'file' }
+                : null;
+    const apiUrl = flags.apiUrl
+        ? { value: flags.apiUrl, source: 'flag' }
+        : env.KOSUKE_API_URL
+            ? { value: env.KOSUKE_API_URL, source: 'env' }
+            : stored?.apiUrl
+                ? { value: stored.apiUrl, source: 'file' }
+                : { value: DEFAULT_API_URL, source: 'default' };
+    return {
+        apiKey: apiKey?.value ?? null,
+        apiKeySource: apiKey?.source ?? null,
+        apiUrl: apiUrl.value.replace(/\/+$/, ''),
+        apiUrlSource: apiUrl.source,
+    };
+}

package/dist/runtime/descriptor.js

@@ -0,0 +1,7 @@
+/**
+ * What the generator writes per operation, and what the runtime builds a
+ * command from. Data only: the generated tree holds no logic, so it stays
+ * small, byte-stable and reviewable, and every behaviour lives in one
+ * hand-written place.
+ */
+export {};

package/dist/runtime/invoke.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { appendAttachments } from './attachments.js';
+export class UsageError extends Error {
+}
+export function buildRequest(operation, input) {
+    const queryNames = new Set(operation.query.map((field) => field.name));
+    const query = {};
+    for (const field of operation.query) {
+        const value = input.fields[field.name];
+        if (value !== undefined)
+            query[field.name] = value;
+    }
+    for (const field of operation.query) {
+        if (field.required && query[field.name] === undefined) {
+            throw new UsageError(`--${field.flag} is required.`);
+        }
+    }
+    const bodyFields = Object.fromEntries(Object.entries(input.fields).filter(([name, value]) => !queryNames.has(name) && value !== undefined));
+    return {
+        method: operation.method,
+        path: operation.path,
+        pathParams: input.pathParams,
+        query,
+        body: buildBody(operation, bodyFields, input),
+    };
+}
+/**
+ * Which media type to send. Multipart when the operation only takes that, when
+ * files are attached, or when a field given exists only on the form branch;
+ * JSON otherwise, including an empty `{}` for a body-taking operation given
+ * nothing, which is how the deploy route reads "start a deploy".
+ */
+function buildBody(operation, fields, input) {
+    const takesJson = operation.body !== null;
+    const takesMultipart = operation.multipart !== null;
+    if (!takesJson && !takesMultipart) {
+        if (input.wholeBody !== undefined || Object.keys(fields).length || input.attachments.length) {
+            throw new UsageError(`kosuke ${operation.command.join(' ')} takes no body.`);
+        }
+        return null;
+    }
+    if (input.attachments.length && !operation.attachments) {
+        throw new UsageError(`kosuke ${operation.command.join(' ')} takes no attachments.`);
+    }
+    // The keys that decide the media type come from --body as much as from the
+    // flags: `--body '{"content":"hi"}'` on the deploy route names a form-only
+    // field, and sending it as JSON would have zod strip it and the handler read
+    // an empty body, which there means "start a fresh deploy".
+    const jsonFields = operation.body?.fields ?? null;
+    const jsonNames = new Set(jsonFields?.map((field) => field.name) ?? []);
+    // A field flag always names a field of one branch, so it decides on its
+    // own. The keys of --body decide only against a flat JSON body: a non-flat
+    // one (an array, a union) has no field names to hold them against, and
+    // sending such a --body as the form would be a guess. No operation has that
+    // shape beside a form branch today; if one does, --body stays JSON there.
+    const given = [
+        ...Object.keys(fields),
+        ...(jsonFields ? Object.keys(asRecordOrEmpty(input.wholeBody)) : []),
+    ];
+    const multipartOnly = given.some((name) => !jsonNames.has(name));
+    const useMultipart = takesMultipart && (!takesJson || input.attachments.length > 0 || multipartOnly);
+    if (useMultipart) {
+        const form = new FormData();
+        const source = input.wholeBody !== undefined ? asRecord(input.wholeBody, 'The body') : fields;
+        const known = new Map((operation.multipart ?? []).map((field) => [field.name, field]));
+        for (const [name, value] of Object.entries(source)) {
+            if (!known.has(name))
+                throw new UsageError(`Unknown form field "${name}".`);
+            if (value === undefined || value === null)
+                continue;
+            form.set(name, formValue(value));
+        }
+        for (const field of operation.multipart ?? []) {
+            if (field.required && !form.has(field.name)) {
+                throw new UsageError(`--${field.flag} is required.`);
+            }
+        }
+        if (input.attachments.length)
+            appendAttachments(form, input.attachments);
+        return { kind: 'multipart', value: form };
+    }
+    if (input.wholeBody !== undefined)
+        return { kind: 'json', value: input.wholeBody };
+    if (operation.body?.fields === null) {
+        if (Object.keys(fields).length) {
+            throw new UsageError(`This body is not a flat object; pass it whole with --body, --body-file or on stdin.`);
+        }
+        if (operation.body.required) {
+            throw new UsageError(`A body is required: pass --body, or --body-file with a path or - for stdin.`);
+        }
+        return null;
+    }
+    for (const field of operation.body?.fields ?? []) {
+        if (field.required && fields[field.name] === undefined) {
+            throw new UsageError(`--${field.flag} is required.`);
+        }
+    }
+    return { kind: 'json', value: fields };
+}
+/**
+ * A form field is a string. A value already parsed as JSON (an object from a
+ * `json` flag, or from --body) goes back to its text, which is what the
+ * handler JSON-parses on the form branch; scalars go as they print.
+ */
+function formValue(value) {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function asRecordOrEmpty(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asRecord(value, what) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    throw new UsageError(`${what} must be a JSON object for a multipart request.`);
+}
+/**
+ * `--body '<json>'`, or `--body-file <path>` with `-` for stdin. Stdin is read
+ * only when asked for: a CLI that reads an inherited pipe on its own hangs
+ * whenever the parent never closes it, which is a bug that only shows up in
+ * someone else's script.
+ */
+export function readWholeBody(options, readStdin = () => readFileSync(0, 'utf8')) {
+    let text = null;
+    if (options.body !== undefined)
+        text = options.body;
+    else if (options.bodyFile === '-')
+        text = readStdin();
+    else if (options.bodyFile !== undefined)
+        text = readFileSync(options.bodyFile, 'utf8');
+    if (text === null || text.trim() === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('The body is not valid JSON.');
+    }
+}
+export async function execute(client, request) {
+    const init = {
+        params: { path: request.pathParams, query: request.query },
+    };
+    if (request.body)
+        init.body = request.body.value;
+    // `request()` rather than the typed verbs: the descriptor decides the path at
+    // run time, and openapi-fetch's per-path types cannot follow a variable.
+    const { data, error, response } = await client.request(request.method, request.path, init);
+    return { ok: response.ok, status: response.status, body: response.ok ? data : error };
+}

package/dist/runtime/runtime.js

@@ -0,0 +1,41 @@
+import { createApiClient } from './client.js';
+import { resolveCredentials, } from './credentials.js';
+export function createRuntime({ flags, env = process.env, fetch, stdout = (line) => process.stdout.write(line + '\n'), stderr = (line) => process.stderr.write(line + '\n'), exit = (code) => {
+    process.exitCode = code;
+}, }) {
+    let resolved = null;
+    const credentials = () => (resolved ??= resolveCredentials(flags, env));
+    return {
+        credentials,
+        client({ anonymous = false } = {}) {
+            const { apiKey, apiUrl } = credentials();
+            if (!apiKey && !anonymous) {
+                stderr('No auth token. Run `kosuke auth login`, set KOSUKE_API_KEY, or pass --api-key. ' +
+                    'Create one in Settings on the platform.');
+                exit(1);
+                throw new ExitSignal();
+            }
+            return createApiClient({ apiUrl, apiKey: anonymous ? null : apiKey, fetch });
+        },
+        output(outcome) {
+            if (outcome.ok) {
+                // 204 has nothing to print; anything else is passed through as JSON so
+                // `| jq` works without the platform CLI knowing the shape.
+                if (outcome.body !== undefined)
+                    stdout(render(outcome.body));
+                return;
+            }
+            stderr(render(outcome.body ?? { error: `HTTP ${outcome.status}` }));
+            exit(1);
+        },
+    };
+}
+function render(body) {
+    return typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+}
+/** Thrown after `exit` so the action stops without printing a second error. */
+export class ExitSignal extends Error {
+    constructor() {
+        super('exit');
+    }
+}

package/dist/runtime/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+// Read at run time rather than imported with an attribute: the package's own
+// manifest ships with it, and this works the same from src/ and from dist/.
+const manifest = createRequire(import.meta.url)('../../package.json');
+export const version = manifest.version;