@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/commands/worker.js

@@ -0,0 +1,178 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { BIN, CliError, ExitCode, REPORT_ENVELOPE_RESERVE, REPORT_MAX_BYTES, RESULT_RESERVED_KEY, UsageError, WORKER_DESCRIPTION_MAX_CHARS } from "../core/domain/index.js";
+import { assertWorkerName } from "../core/names.js";
+import { formatCount } from "../core/text.js";
+import { workerEnv } from "../modules/workers/runtime/env.js";
+import { Executor } from "../modules/workers/runtime/executor.js";
+import { collectWorkers, descriptionTooLong } from "../modules/workers/workers.js";
+import { requireProject, requireWorkersDir, workersPath } from "./common.js";
+import { workerDelete } from "./delete.js";
+import { workerLogs } from "./logs.js";
+import { workerNew } from "./new.js";
+import { workerResults } from "./results.js";
+export const workerList = {
+    name: 'worker list',
+    summary: 'List the workers in this project and check that each one can load',
+    usage: '',
+    description: 'Loads every worker file (without running the handler) and reports its description,\n' +
+        'timeout and whether it has an inputSchema. Makes no API calls.\n' +
+        "Loading runs the file's top-level code, as a real run would.",
+    options: {},
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const { out } = ctx;
+        const { root, dir } = requireWorkersDir(ctx.loadConfig());
+        const workers = (await collectWorkers(dir, workerEnv(root, ctx.env))).map((w) => {
+            const warnings = [];
+            const description = w.meta?.description ?? null;
+            if (w.meta && description === null) {
+                warnings.push('no description — the AI will not know what it does');
+            }
+            else if (description !== null && descriptionTooLong(description)) {
+                warnings.push(`description is over ${WORKER_DESCRIPTION_MAX_CHARS} characters — the server will not register this worker`);
+            }
+            return {
+                name: w.name,
+                files: w.files,
+                ok: w.meta !== null,
+                problem: w.message,
+                description,
+                timeoutMs: w.meta?.timeoutMs ?? null,
+                hasInputSchema: w.meta?.hasInputSchema ?? false,
+                warnings
+            };
+        });
+        const text = workers.length === 0
+            ? `No workers in ${dir}. Create one with '${BIN} worker new <name>'.`
+            : [
+                `workers  ${dir}`,
+                '',
+                ...workers.flatMap((w) => [
+                    `${w.ok ? out.out.green('ok   ') : out.out.red('error')}  ${w.name}  ${out.out.dim(w.files.join(', '))}`,
+                    ...(w.ok
+                        ? [
+                            `       ${w.description ?? out.out.dim('(no description)')}`,
+                            `       ${out.out.dim(`timeout ${(w.timeoutMs ?? 60_000) / 1000}s · ${w.hasInputSchema ? 'inputSchema' : 'no inputSchema (any input)'}`)}`
+                        ]
+                        : [`       ${w.problem}`]),
+                    ...w.warnings.map((m) => `       ${out.out.yellow('warn')} ${m}`)
+                ])
+            ].join('\n');
+        out.result({ workersDir: dir, workers }, text);
+        return ExitCode.Ok;
+    }
+};
+export const workerRun = {
+    name: 'worker run',
+    summary: 'Run one worker once with the given input — no task, no API calls',
+    usage: '<worker> [--input <json> | --input-file <file>]',
+    description: 'Runs the worker file once on this machine, without a task: same thread, timeout and\n' +
+        'inputSchema check as start, so if it works here it works as a real task.\n' +
+        'Makes no API calls (no quota, no login needed). Input defaults to {}.\n' +
+        'ctx.log lines go to stderr; the result goes to stdout (--json).',
+    options: {
+        input: { type: 'string', valueName: 'json', description: 'Input as a JSON string' },
+        'input-file': { type: 'string', valueName: 'file', description: 'Read input JSON from a file' }
+    },
+    args: { min: 1, max: 1 },
+    async run(ctx) {
+        const { out, values } = ctx;
+        const name = ctx.positionals[0];
+        assertWorkerName(name);
+        if (values.input !== undefined && values['input-file'] !== undefined) {
+            throw new UsageError('use either --input or --input-file, not both');
+        }
+        const input = parseInput(ctx);
+        const config = ctx.loadConfig();
+        const root = requireProject(config);
+        ctx.chdir(root);
+        const executor = new Executor({
+            workersDir: workersPath(root, config),
+            concurrency: 1,
+            env: workerEnv(root, ctx.env)
+        });
+        ctx.claimInterrupt();
+        const id = 'local-run';
+        const onAbort = () => executor.cancel(id, 'interrupted');
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            const outcome = await executor.run({ id, worker: name, input }, {
+                onLog: (message) => out.info(`${out.err.dim('log')}     ${message}`),
+                onReport: async (message) => out.info(`${out.err.dim('report')}  ${message}`)
+            });
+            await executor.idle();
+            if (outcome.status === 'completed') {
+                const result = JSON.parse(outcome.resultJson);
+                warnReplyLimits(ctx, result, Buffer.byteLength(outcome.resultJson));
+                out.result({ status: 'completed', result }, JSON.stringify(result, null, 2));
+                return ExitCode.Ok;
+            }
+            if (outcome.status === 'cancelled') {
+                out.result({ status: 'cancelled' }, 'Cancelled.');
+                return ExitCode.Interrupted;
+            }
+            if (out.json)
+                out.result({ status: 'failed', reason: outcome.reason, message: outcome.message });
+            throw new CliError(`${name} failed (${outcome.reason}): ${outcome.message}`);
+        }
+        finally {
+            ctx.signal.removeEventListener('abort', onAbort);
+        }
+    }
+};
+export const worker = {
+    name: 'worker',
+    summary: 'Create, test and inspect local workers',
+    usage: '<command>',
+    description: 'A worker is one file in the workers folder; its file name is the worker name. ' +
+        "'start' registers it as a local worker; with 'start --serve --public' a name registered as a " +
+        'public worker on the dashboard is served as that public worker instead. ' +
+        "Removing the file does not remove the local worker from 3Min API — use 'worker delete'.",
+    options: {},
+    args: { min: 0, max: 0 },
+    subcommands: [workerNew, workerRun, workerList, workerLogs, workerDelete, workerResults],
+    async run() {
+        return ExitCode.Usage;
+    }
+};
+function warnReplyLimits(ctx, result, bytes) {
+    if (result !== null &&
+        typeof result === 'object' &&
+        !Array.isArray(result) &&
+        Object.hasOwn(result, RESULT_RESERVED_KEY)) {
+        ctx.out.warn(`the result has a top-level "${RESULT_RESERVED_KEY}" key, which 3minapi reserves — as a task it fails ` +
+            '(reserved_result_key). Rename the key.');
+    }
+    if (bytes > REPORT_MAX_BYTES - REPORT_ENVELOPE_RESERVE) {
+        ctx.out.warn(`the result is ${formatCount(bytes)} bytes, over the 100 KiB reply limit. As a task, a local worker ` +
+            "saves it in data.db and sends the AI a summary instead; a public worker's task fails.");
+    }
+}
+function parseInput(ctx) {
+    const { values } = ctx;
+    let text;
+    let from;
+    if (typeof values['input-file'] === 'string') {
+        from = values['input-file'];
+        try {
+            text = readFileSync(path.resolve(ctx.cwd, from), 'utf8');
+        }
+        catch (err) {
+            throw new UsageError(`cannot read ${from}: ${err.message}`);
+        }
+    }
+    else if (typeof values.input === 'string') {
+        from = '--input';
+        text = values.input;
+    }
+    else {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new UsageError(`${from} is not valid JSON: ${err.message}`);
+    }
+}

package/dist/core/api.js

@@ -0,0 +1,132 @@
+import { API_TIMEOUT_MS, BIN, CliError, ENV, StopError, isStopCode } from "./domain/index.js";
+import { stripControl } from "./text.js";
+export class ApiError extends CliError {
+    status;
+    code;
+    retryAfterMs;
+    constructor(message, status, code, retryAfterMs = null) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export function userAgent(version, platform) {
+    return `${BIN}/${version} node/${process.versions.node} ${platform}`;
+}
+export class ApiClient {
+    opts;
+    stop = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get halted() {
+        return this.stop;
+    }
+    notifyCli(cli) {
+        try {
+            this.opts.onServerCli?.(cli);
+        }
+        catch {
+        }
+    }
+    halt(err) {
+        this.stop ??= err;
+    }
+    async getHost() {
+        const res = await this.request('GET', this.opts.apiUrl + '/api/v1/host');
+        this.notifyCli(res.cli);
+        return res;
+    }
+    async pullTasks(max) {
+        const res = await this.request('GET', `${this.opts.apiUrl}/api/v1/host/tasks?max=${max}`);
+        this.notifyCli(res.cli);
+        return res;
+    }
+    async syncWorkers(body) {
+        const res = await this.request('PUT', this.opts.apiUrl + '/api/v1/host/workers', body);
+        this.notifyCli(res.cli);
+        return res;
+    }
+    deleteWorker(name) {
+        return this.request('DELETE', `${this.opts.apiUrl}/api/v1/host/workers/${encodeURIComponent(name)}`);
+    }
+    report(callbackUrl, body) {
+        let target;
+        try {
+            target = new URL(callbackUrl);
+        }
+        catch {
+            throw new ApiError(`invalid callback_url: ${callbackUrl}`, null, null);
+        }
+        if (target.origin !== new URL(this.opts.apiUrl).origin) {
+            throw new ApiError(`refusing to send the token to ${target.origin}: callback_url must be on ${this.opts.apiUrl}`, null, null);
+        }
+        return this.request('POST', target.href, body);
+    }
+    async request(method, url, payload) {
+        if (this.stop)
+            throw this.stop;
+        const signals = [AbortSignal.timeout(API_TIMEOUT_MS)];
+        if (this.opts.signal)
+            signals.push(this.opts.signal);
+        const headers = {
+            authorization: `Bearer ${this.opts.token}`,
+            accept: 'application/json',
+            'user-agent': this.opts.userAgent
+        };
+        if (payload !== undefined)
+            headers['content-type'] = 'application/json';
+        let res;
+        let text;
+        try {
+            res = await (this.opts.fetch ?? fetch)(url, {
+                method,
+                headers,
+                body: payload === undefined ? undefined : JSON.stringify(payload),
+                signal: AbortSignal.any(signals)
+            });
+            text = await res.text();
+        }
+        catch (err) {
+            throw new ApiError(`cannot reach ${this.opts.apiUrl}: ${networkReason(err)}`, null, null);
+        }
+        const body = parseJson(text);
+        if (res.ok && body !== null && body.success === true) {
+            return body;
+        }
+        const code = body?.code;
+        const message = body?.error;
+        const sentence = typeof message === 'string' && message !== '' ? stripControl(message) : `HTTP ${res.status}`;
+        if (isStopCode(code)) {
+            this.stop ??= new StopError(code, sentence);
+            throw this.stop;
+        }
+        const hint = res.status === 404 && typeof code !== 'string'
+            ? `\nThis server has no host API. Check the API URL (--api-url or ${ENV.apiUrl}).`
+            : '';
+        throw new ApiError(`${method} ${url} failed: ${sentence}${hint}`, res.status, typeof code === 'string' ? code : null, retryAfterMs(res.headers.get('retry-after')));
+    }
+}
+function retryAfterMs(value) {
+    if (value === null || !/^\d+$/.test(value.trim()))
+        return null;
+    return Number(value.trim()) * 1000;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function networkReason(err) {
+    const e = err;
+    if (e?.name === 'TimeoutError')
+        return `no response within ${API_TIMEOUT_MS / 1000}s`;
+    if (e?.name === 'AbortError')
+        return 'aborted';
+    return e?.cause?.code ?? e?.cause?.message ?? e?.message ?? String(err);
+}

package/dist/core/config.js

@@ -0,0 +1,188 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { BIN, CONCURRENCY_MAX, CONCURRENCY_MIN, ConfigError, DEFAULT_API_URL, DEFAULT_CONCURRENCY, DEFAULT_LOCAL_SERVER_PORT, DEFAULT_LOG_MAX_BYTES, DEFAULT_LOG_RETENTION_DAYS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_WORKERS_DIR, ENV, LOG_MAX_BYTES_MAX, LOG_MAX_BYTES_MIN, LOG_RETENTION_MAX_DAYS, LOG_RETENTION_MIN_DAYS, LOCAL_SERVER_PORT_MAX, LOCAL_SERVER_PORT_MIN, POLL_INTERVAL_MAX_MS, POLL_INTERVAL_MIN_MS, PROJECT_CONFIG_FILE, RECEIVE_MODES, USER_CONFIG_FILE } from "./domain/index.js";
+import { readUserText } from "./text-file.js";
+export const DEFAULTS = {
+    apiUrl: DEFAULT_API_URL,
+    workersDir: DEFAULT_WORKERS_DIR,
+    pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    logRetentionDays: DEFAULT_LOG_RETENTION_DAYS,
+    logMaxBytes: DEFAULT_LOG_MAX_BYTES,
+    concurrency: DEFAULT_CONCURRENCY,
+    localServerPort: DEFAULT_LOCAL_SERVER_PORT,
+    receiveMode: 'live'
+};
+const ENV_KEYS = {
+    apiUrl: ENV.apiUrl,
+    pollIntervalMs: ENV.pollIntervalMs,
+    logRetentionDays: ENV.logRetentionDays,
+    logMaxBytes: ENV.logMaxBytes,
+    concurrency: ENV.concurrency,
+    localServerPort: ENV.localServerPort,
+    receiveMode: ENV.receiveMode
+};
+const FLAG_NAMES = {
+    localServerPort: '--port',
+    receiveMode: '--mode'
+};
+const INTEGER_RANGES = {
+    pollIntervalMs: [POLL_INTERVAL_MIN_MS, POLL_INTERVAL_MAX_MS],
+    logRetentionDays: [LOG_RETENTION_MIN_DAYS, LOG_RETENTION_MAX_DAYS],
+    logMaxBytes: [LOG_MAX_BYTES_MIN, LOG_MAX_BYTES_MAX],
+    concurrency: [CONCURRENCY_MIN, CONCURRENCY_MAX],
+    localServerPort: [LOCAL_SERVER_PORT_MIN, LOCAL_SERVER_PORT_MAX]
+};
+export function loadConfig(input) {
+    const warnings = [];
+    const userFile = path.join(input.configDir, USER_CONFIG_FILE);
+    let projectFile;
+    if (input.configFile !== undefined) {
+        projectFile = path.resolve(input.cwd, input.configFile);
+        if (!existsSync(projectFile))
+            throw new ConfigError(`config file not found: ${projectFile}`);
+    }
+    else if (input.projectFile !== undefined) {
+        projectFile = input.projectFile;
+    }
+    else {
+        projectFile = findProjectFile(input.cwd);
+    }
+    const layers = [
+        ['flag', input.flags ?? {}],
+        ['env', fromEnv(input.env)],
+        ['project', projectFile ? projectLayer(projectFile, warnings) : {}],
+        ['user', existsSync(userFile) ? readJsonObject(userFile, warnings) : {}]
+    ];
+    const values = { ...DEFAULTS };
+    const sources = Object.fromEntries(Object.keys(DEFAULTS).map((k) => [k, 'default']));
+    for (const key of Object.keys(DEFAULTS)) {
+        for (const [source, layer] of layers) {
+            const raw = layer[key];
+            if (raw === undefined)
+                continue;
+            setValue(values, key, raw, source);
+            sources[key] = source;
+            break;
+        }
+    }
+    return {
+        values,
+        sources,
+        projectRoot: projectFile ? path.dirname(projectFile) : null,
+        projectFile,
+        userFile,
+        warnings
+    };
+}
+function projectLayer(file, warnings) {
+    const layer = readJsonObject(file, warnings);
+    if (layer.apiUrl !== undefined) {
+        delete layer.apiUrl;
+        warnings.push(`apiUrl in ${file} is ignored — a project file must not decide where your host token is sent. ` +
+            `Set it with --api-url, ${ENV.apiUrl} or ${USER_CONFIG_FILE} in the CLI config folder ('${BIN} paths'), and remove it from ${file}.`);
+    }
+    return layer;
+}
+export function findProjectFile(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(dir, PROJECT_CONFIG_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function fromEnv(env) {
+    const out = {};
+    for (const [key, name] of Object.entries(ENV_KEYS)) {
+        const v = env[name];
+        if (v !== undefined && v !== '')
+            out[key] = v;
+    }
+    return out;
+}
+function readJsonObject(file, warnings) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readUserText(file));
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        throw new ConfigError(`cannot read ${file}: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigError(`${file} must contain a JSON object`);
+    }
+    for (const key of Object.keys(parsed)) {
+        if (!(key in DEFAULTS))
+            warnings.push(`unknown key "${key}" in ${file} (ignored)`);
+    }
+    return parsed;
+}
+function setValue(values, key, raw, source) {
+    const where = source === 'env'
+        ? ENV_KEYS[key]
+        : source === 'flag'
+            ? (FLAG_NAMES[key] ?? `--${kebab(key)}`)
+            : key;
+    switch (key) {
+        case 'apiUrl': {
+            if (typeof raw !== 'string' || !isApiUrl(raw)) {
+                throw new ConfigError(`${where} must be an https URL (http only for 127.0.0.1, localhost or [::1])`);
+            }
+            values.apiUrl = raw.replace(/\/+$/, '');
+            return;
+        }
+        case 'workersDir': {
+            if (typeof raw !== 'string' || raw.trim() === '' || path.isAbsolute(raw)) {
+                throw new ConfigError(`${where} must be a relative directory path`);
+            }
+            const normalized = path.normalize(raw);
+            if (normalized === '..' ||
+                normalized.startsWith(`..${path.sep}`) ||
+                normalized.startsWith('../')) {
+                throw new ConfigError(`${where} must be inside the project folder`);
+            }
+            values.workersDir = raw;
+            return;
+        }
+        case 'pollIntervalMs':
+        case 'logRetentionDays':
+        case 'logMaxBytes':
+        case 'concurrency':
+        case 'localServerPort': {
+            const [min, max] = INTEGER_RANGES[key];
+            const n = typeof raw === 'string' ? Number(raw) : raw;
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < min || n > max) {
+                throw new ConfigError(`${where} must be an integer between ${min} and ${max}`);
+            }
+            values[key] = n;
+            return;
+        }
+        case 'receiveMode': {
+            if (typeof raw !== 'string' || !RECEIVE_MODES.includes(raw)) {
+                throw new ConfigError(`${where} must be one of: ${RECEIVE_MODES.join(', ')}`);
+            }
+            values.receiveMode = raw;
+            return;
+        }
+    }
+}
+function isApiUrl(value) {
+    try {
+        const u = new URL(value);
+        if (u.protocol === 'https:')
+            return true;
+        return u.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(u.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function kebab(key) {
+    return key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}