@3minapi/cli 0.0.0-stage → 0.22.1

package/dist/commands/dashboard.js

@@ -0,0 +1,298 @@
+import path from 'node:path';
+import { APP_LOG_DIR, BIN, CliError, DASHBOARD_OUT_FILE, DETACH_READY_MS, ENV, ExitCode, STOP_CHECK_INTERVAL_MS, UsageError } from "../core/domain/index.js";
+import { outputTail, spawnDetached } from "../core/host/detach.js";
+import { Logger, pruneLogs } from "../core/logger.js";
+import { openBrowser } from "../core/open-browser.js";
+import { confirm } from "../core/prompt.js";
+import { sleep } from "../core/time.js";
+import { acquireDashboardLock, dashboardLockPath, readDashboard, readDashboardLinks, readDashboardSettled, requestDashboardStop } from "../modules/dashboard/lock.js";
+import { startDashboard } from "../modules/dashboard/server.js";
+import { workersPath } from "./common.js";
+import { stopLocked } from "./stop.js";
+import { initHint } from "../core/project.js";
+const LAN_WARNING = [
+    '--lan opens the dashboard to other devices on this network over plain HTTP (not encrypted).',
+    '  Saved results (they may contain personal data), logs and the access link travel in clear text.',
+    '  Use it only on a network you trust, such as your home or office — not on public or shared Wi-Fi.',
+    '  Anyone with the link can see the dashboard: do not share it. If it may have leaked, run',
+    `  '${BIN} dashboard stop' and start again — every run makes a new link.`,
+    '  macOS and Windows may ask whether to allow incoming connections: allow them, or other devices',
+    '  cannot connect. On Linux, a firewall (ufw, firewalld) may need the port opened.'
+].join('\n');
+export const dashboard = {
+    name: 'dashboard',
+    summary: 'Open a local, read-only web view of runs, results, workers and logs',
+    usage: '[stop | url] [--port <port>] [--no-open] [--lan [--yes]] [--detach]',
+    description: 'Serves a page on 127.0.0.1 and opens it in your browser with a link that works for this run only.\n' +
+        'It reads the task history, the results saved in data.db and the logs on this PC — nothing is sent anywhere,\n' +
+        `and nothing is changed: use the CLI for that (the page shows the commands). Works while '${BIN} start' is running or not.\n` +
+        'Press Ctrl+C to stop it. Only one can run per host.\n' +
+        '\n' +
+        '--lan also opens it to other devices on the same network (another PC or a phone on your Wi-Fi) over\n' +
+        'plain HTTP, which is not encrypted. It shows a warning and asks first; pass --yes to skip the question\n' +
+        '(scripts and AI agents — without a terminal, --lan needs --yes). Use it only on a network you trust.\n' +
+        '\n' +
+        '--detach keeps it running in the background after the terminal is closed.\n' +
+        `'${BIN} dashboard url' prints the link again, '${BIN} dashboard stop' ends it, and '${BIN} status' shows it.`,
+    options: {
+        port: {
+            type: 'string',
+            valueName: 'port',
+            description: 'Port to listen on (default: any free port)'
+        },
+        open: {
+            type: 'boolean',
+            negated: true,
+            description: 'Print the link without opening a browser'
+        },
+        lan: {
+            type: 'boolean',
+            description: 'Also serve other devices on this network (plain HTTP — asks first)'
+        },
+        yes: {
+            type: 'boolean',
+            short: 'y',
+            description: 'Agree to the --lan warning without asking (scripts, AI agents)'
+        },
+        detach: {
+            type: 'boolean',
+            short: 'd',
+            description: `Run in the background (stop with '${BIN} dashboard stop')`
+        }
+    },
+    args: { min: 0, max: 1 },
+    async run(ctx) {
+        const action = ctx.positionals[0];
+        if (action !== undefined) {
+            if (action !== 'stop' && action !== 'url') {
+                throw new UsageError(`unknown dashboard action "${action}" — use '${BIN} dashboard stop' or '${BIN} dashboard url'`);
+            }
+            const { values } = ctx;
+            if (values.port !== undefined || values.lan || values.detach || values.yes) {
+                throw new UsageError(`'${BIN} dashboard ${action}' takes no options`);
+            }
+            return action === 'stop' ? stopDashboard(ctx) : printUrl(ctx);
+        }
+        const port = parsePort(ctx.values.port);
+        const lan = Boolean(ctx.values.lan);
+        const child = ctx.env[ENV.detached] === '1';
+        if (lan && !child)
+            await agreeToLan(ctx);
+        if (ctx.values.detach && !child)
+            return startDetached(ctx, port, lan);
+        return runDashboard(ctx, port, lan, child);
+    }
+};
+async function runDashboard(ctx, port, lan, child) {
+    const { out, values } = ctx;
+    const config = ctx.loadConfig();
+    const root = config.projectRoot;
+    const lock = acquireDashboardLock(ctx.dirs.data, { detached: child, lan, outFile: child ? outFilePath(ctx) : null }, ctx.now());
+    try {
+        ctx.claimInterrupt();
+        const logger = lan ? accessLogger(ctx, config.values) : null;
+        const dashboard = await startDashboard({
+            port,
+            version: ctx.version,
+            dataDir: ctx.dirs.data,
+            logsDir: ctx.dirs.logs,
+            projectRoot: root,
+            workersDir: root ? workersPath(root, config) : null,
+            now: ctx.now,
+            lan,
+            onError: (err, url) => out.warn(`${url}: ${err instanceof CliError ? err.message : (err?.stack ?? String(err))}`),
+            ...(logger ? { onAccess: (e) => logAccess(logger, e) } : {})
+        });
+        const shutdown = new AbortController();
+        const onAbort = () => shutdown.abort();
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+        const stopWatch = setInterval(() => {
+            lock.heartbeat();
+            if (lock.stopRequested())
+                shutdown.abort();
+        }, STOP_CHECK_INTERVAL_MS);
+        try {
+            lock.listening({
+                url: dashboard.url,
+                lanUrls: dashboard.lanUrls,
+                port: dashboard.port,
+                origins: [dashboard.origin, ...dashboard.lanOrigins]
+            });
+            logger?.info('dashboard started', { lan: true, port: dashboard.port, pid: process.pid });
+            if (child) {
+                out.info(`dashboard started · pid ${process.pid} · ${lock.info.origins.join(' · ')}` +
+                    (lan ? ' · LAN (plain HTTP)' : ''));
+            }
+            else {
+                out.result(linksJson(lock.info, dashboard), linksText(ctx, dashboard, lan) +
+                    '\n' +
+                    out.out.dim('Read-only. The links work for this run only. Press Ctrl+C to stop.'));
+            }
+            if (!root) {
+                out.warn(`this host has no project — saved results and workers are not shown. ${initHint(ctx.home)}`);
+            }
+            if (!child && values.open !== false && !(await openBrowser(dashboard.url, ctx.platform))) {
+                out.info('Could not open a browser — open the link above yourself.');
+            }
+            if (!shutdown.signal.aborted) {
+                await new Promise((resolve) => shutdown.signal.addEventListener('abort', () => resolve(), { once: true }));
+            }
+            logger?.info('dashboard stopped', { pid: process.pid });
+        }
+        finally {
+            clearInterval(stopWatch);
+            ctx.signal.removeEventListener('abort', onAbort);
+            await dashboard.close();
+        }
+    }
+    finally {
+        lock.release();
+    }
+    return ExitCode.Ok;
+}
+async function agreeToLan(ctx) {
+    const { out } = ctx;
+    out.warn(LAN_WARNING);
+    if (ctx.values.yes)
+        return;
+    if (out.json || !ctx.stdin.isTTY) {
+        throw new UsageError(`--lan serves the dashboard to your network over plain HTTP and needs agreement. Nothing was opened. Once the user has agreed, run it again with --yes.`);
+    }
+    if (!(await confirm(ctx.stdin, out, 'Open the dashboard to this network over plain HTTP?'))) {
+        throw new CliError('cancelled — the dashboard was not opened.');
+    }
+}
+function accessLogger(ctx, values) {
+    return new Logger({
+        dir: ctx.dirs.logs,
+        now: ctx.now,
+        onMaintenance(now) {
+            pruneLogs({
+                dir: ctx.dirs.logs,
+                now,
+                retentionDays: values.logRetentionDays,
+                maxBytes: values.logMaxBytes
+            });
+        },
+        onError: (message) => ctx.out.warn(message)
+    });
+}
+function logAccess(logger, e) {
+    const attrs = { remote: e.remote ?? null, host: e.host ?? null, path: e.path, status: e.status };
+    if (e.kind === 'granted')
+        logger.info('dashboard access granted', attrs);
+    else
+        logger.warn('dashboard access denied', attrs);
+}
+async function startDetached(ctx, port, lan) {
+    const { out, values } = ctx;
+    const current = readDashboard(ctx.dirs.data);
+    if (current.state === 'running') {
+        throw new CliError(`the dashboard is already running (pid ${current.info.pid}). Only one can run per host.\n` +
+            `Open it with '${BIN} dashboard url', or stop it with '${BIN} dashboard stop' first.`);
+    }
+    const args = ['dashboard', '--no-open'];
+    if (port !== 0)
+        args.push('--port', String(port));
+    if (lan)
+        args.push('--lan', '--yes');
+    if (typeof values['api-url'] === 'string')
+        args.push('--api-url', values['api-url']);
+    if (typeof values.config === 'string')
+        args.push('--config', path.resolve(ctx.cwd, values.config));
+    const outFile = outFilePath(ctx);
+    const startedAt = Date.now();
+    const child = spawnDetached({ args, cwd: ctx.cwd, env: ctx.env, outFile });
+    let exited = null;
+    child.once('exit', (code) => (exited = code ?? 1));
+    let ready = null;
+    while (Date.now() - startedAt < DETACH_READY_MS && exited === null) {
+        const state = readDashboard(ctx.dirs.data);
+        if (state.state === 'running' && state.info.pid === child.pid && state.info.port !== null) {
+            const links = readDashboardLinks(ctx.dirs.data, state.info);
+            if (links) {
+                ready = { info: state.info, links };
+                break;
+            }
+        }
+        await sleep(100);
+    }
+    child.unref();
+    if (!ready) {
+        if (exited === null) {
+            try {
+                child.kill();
+            }
+            catch {
+            }
+        }
+        throw new CliError(`the background dashboard did not start${exited !== null ? ` (exit code ${exited})` : ''}.\n` +
+            outputTail(outFile));
+    }
+    const { info, links } = ready;
+    out.result({ ...linksJson(info, links), outFile }, [
+        `${out.out.green('dashboard started in the background')}  pid ${info.pid}`,
+        linksText(ctx, links, info.lan),
+        `output: ${outFile}`,
+        `link again with '${BIN} dashboard url' · stop with '${BIN} dashboard stop'`
+    ].join('\n'));
+    if (values.open !== false && !(await openBrowser(links.url, ctx.platform))) {
+        out.info('Could not open a browser — open the link above yourself.');
+    }
+    return ExitCode.Ok;
+}
+function stopDashboard(ctx) {
+    return stopLocked(ctx, {
+        read: () => readDashboard(ctx.dirs.data),
+        readSettled: () => readDashboardSettled(ctx.dirs.data),
+        requestStop: (info) => requestDashboardStop(ctx.dirs.data, info),
+        lockFile: dashboardLockPath(ctx.dirs.data)
+    });
+}
+async function printUrl(ctx) {
+    const { out } = ctx;
+    const current = await readDashboardSettled(ctx.dirs.data);
+    const links = current.state === 'running' ? readDashboardLinks(ctx.dirs.data, current.info) : null;
+    if (current.state !== 'running' || !links) {
+        out.result({ running: false }, `Not running. Start it with '${BIN} dashboard'.`);
+        return ExitCode.Failure;
+    }
+    out.result(linksJson(current.info, links), linksText(ctx, links, current.info.lan));
+    return ExitCode.Ok;
+}
+function linksJson(info, links) {
+    return {
+        url: links.url,
+        port: links.port ?? info.port,
+        lan: info.lan,
+        lanUrls: links.lanUrls,
+        pid: info.pid,
+        detached: info.detached
+    };
+}
+function linksText(ctx, links, lan) {
+    const lines = [`Dashboard: ${links.url}`];
+    if (lan) {
+        if (links.lanUrls.length === 0) {
+            lines.push(ctx.out.out.yellow('No network address found on this PC — only this PC can open it.'));
+        }
+        else {
+            lines.push('From other devices on this network (plain HTTP):');
+            for (const url of links.lanUrls)
+                lines.push(`  ${url}`);
+        }
+    }
+    return lines.join('\n');
+}
+function outFilePath(ctx) {
+    return path.join(ctx.dirs.logs, APP_LOG_DIR, DASHBOARD_OUT_FILE);
+}
+function parsePort(raw) {
+    if (raw === undefined)
+        return 0;
+    const n = Number(raw);
+    if (typeof raw !== 'string' || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new UsageError('--port must be a number from 1 to 65535');
+    }
+    return n;
+}

package/dist/commands/delete.js

@@ -0,0 +1,167 @@
+import { rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { ApiError } from "../core/api.js";
+import { BIN, CliError, ExitCode, StopError, UsageError, WORKER_EXTENSIONS } from "../core/domain/index.js";
+import { assertWorkerName } from "../core/names.js";
+import { confirm } from "../core/prompt.js";
+import { notifyDeleted, readRunner } from "../core/host/runner-lock.js";
+import { clearStop, openSession, recordStop, rememberQuota, stopHint } from "../core/host/session.js";
+import { formatCount } from "../core/text.js";
+import { ResultStore } from "../modules/workers/results/store.js";
+import { client, requireToken, workersPath } from "./common.js";
+const DELETE_MAX_ROUNDS = 500;
+export const workerDelete = {
+    name: 'worker delete',
+    summary: 'Delete a local worker and its task history from 3Min API, and remove its file',
+    usage: '<worker> [--yes]',
+    description: 'Deletes the local worker of this host from 3Min API together with its task history (this\n' +
+        'cannot be undone), then removes its file from the workers folder. Removing the file alone\n' +
+        "leaves the worker on 3Min API, where AIs keep sending it tasks. A running 'start' on this PC\n" +
+        'turns the worker off right away (no API call). Works when the quota is used up; one API call when\n' +
+        'there is quota left. Asks for confirmation in a terminal; pass --yes otherwise.',
+    options: {
+        yes: { type: 'boolean', description: 'Delete without asking for confirmation' }
+    },
+    args: { min: 1, max: 1 },
+    async run(ctx) {
+        const { out } = ctx;
+        const name = ctx.positionals[0];
+        assertWorkerName(name);
+        const token = requireToken(ctx);
+        const { files, runner } = localFiles(ctx, name);
+        if (!ctx.values.yes) {
+            if (out.json || !ctx.stdin.isTTY) {
+                throw new UsageError(`deleting a worker removes its task history and cannot be undone. Nothing was deleted. Once the user has agreed, run: ${BIN} worker delete ${name} --yes`);
+            }
+            const also = files.length > 0 ? `, and remove ${files.map((f) => shown(ctx, f)).join(', ')}` : '';
+            const yes = await confirm(ctx.stdin, out, `Delete local worker "${name}" and its task history from 3Min API${also}? This cannot be undone.`);
+            if (!yes)
+                throw new CliError('cancelled — nothing was deleted.');
+        }
+        const result = await deleteOnServer(ctx, token.token, name);
+        if (result.server === 'not_found' && files.length === 0) {
+            throw new CliError(`no local worker "${name}" on this host, and no file for it here. '${BIN} status' lists the workers 3Min API has for this host.`);
+        }
+        const failed = [];
+        for (const file of files) {
+            try {
+                rmSync(file);
+            }
+            catch (err) {
+                failed.push(`${file}: ${err.message}`);
+            }
+        }
+        const removed = files.filter((f) => !failed.some((line) => line.startsWith(`${f}:`)));
+        const quota = result.server === 'deleted' ? result.quota : null;
+        const lines = [];
+        if (result.server === 'deleted') {
+            lines.push(`Deleted local worker "${name}" and its task history from 3Min API.`);
+        }
+        else {
+            lines.push(`"${name}" was not a local worker on this host — nothing to delete on 3Min API.`);
+        }
+        if (removed.length > 0)
+            lines.push(`Removed ${removed.map((f) => shown(ctx, f)).join(', ')}.`);
+        else if (files.length === 0)
+            lines.push('No local file for it was found here.');
+        if (result.server === 'deleted' && runner && files.length > 0) {
+            lines.push(tellRunner(ctx, runner, name)
+                ? `'${BIN} start' is running: it turns "${name}" off now, and stops if no other worker is left. No restart needed.`
+                : `'${BIN} start' is running: it turns "${name}" off on its next fetch, and stops if no other worker is left. No restart needed.`);
+        }
+        if (quota)
+            lines.push(`quota    ${formatCount(quota.remaining)} of ${formatCount(quota.limit)} calls left`);
+        const kept = savedResultCount(ctx, name);
+        if (kept > 0) {
+            lines.push(`${formatCount(kept)} saved result(s) of "${name}" stay in data.db — ` +
+                `'${BIN} worker results prune --worker ${name} --before <date>' deletes them.`);
+        }
+        out.result({ name, server: result.server, files: removed, quota }, lines.join('\n'));
+        if (failed.length > 0) {
+            throw new CliError(`could not remove the worker file — delete it yourself, or the next '${BIN} start' registers it again:\n` +
+                failed.map((line) => `  ${line}`).join('\n'));
+        }
+        return ExitCode.Ok;
+    }
+};
+function savedResultCount(ctx, name) {
+    try {
+        const root = ctx.loadConfig().projectRoot;
+        const store = root ? ResultStore.openReadOnly(root) : null;
+        if (!store)
+            return 0;
+        try {
+            return store.usage({ worker: name }).count;
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch {
+        return 0;
+    }
+}
+async function deleteOnServer(ctx, token, name) {
+    const session = openSession(ctx);
+    try {
+        const api = client(ctx, session, token);
+        for (let round = 0; round < DELETE_MAX_ROUNDS; round += 1) {
+            let res;
+            try {
+                res = await api.deleteWorker(name);
+            }
+            catch (err) {
+                if (err instanceof StopError) {
+                    recordStop(session, err, ctx.now());
+                    throw new StopError(err.reason, `${err.message}\n${stopHint(err.reason)}`, err.resetAt);
+                }
+                if (err instanceof ApiError && err.code === 'worker_not_found') {
+                    clearStop(session);
+                    return round === 0 ? { server: 'not_found' } : { server: 'deleted', quota: null };
+                }
+                throw err;
+            }
+            clearStop(session);
+            rememberQuota(session, res.quota, ctx.now());
+            if (res.complete)
+                return { server: 'deleted', quota: res.quota };
+            if (round === 0)
+                ctx.out.info(`deleting the task history of "${name}" — this can take a while…`);
+        }
+    }
+    finally {
+        session.close();
+    }
+    throw new CliError(`the task history of "${name}" is still being deleted. Run '${BIN} worker delete ${name} --yes' again to continue.`);
+}
+function localFiles(ctx, name) {
+    const state = readRunner(ctx.dirs.data);
+    const runner = state.state === 'running' && state.info.workersDir ? state.info : null;
+    let dir;
+    if (runner) {
+        dir = runner.workersDir;
+    }
+    else {
+        const config = ctx.loadConfig();
+        if (!config.projectRoot)
+            return { files: [], runner };
+        dir = workersPath(config.projectRoot, config);
+    }
+    const files = WORKER_EXTENSIONS.map((ext) => path.join(dir, name + ext)).filter((f) => statSync(f, { throwIfNoEntry: false })?.isFile());
+    return { files, runner };
+}
+function tellRunner(ctx, runner, name) {
+    if (!runner.localDelete)
+        return false;
+    try {
+        notifyDeleted(ctx.dirs.data, runner, [name]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shown(ctx, file) {
+    const rel = path.relative(ctx.cwd, file);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : file;
+}