@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/commands/logs.js

@@ -0,0 +1,154 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { BIN, DEFAULT_LOG_LINES, ExitCode, LOG_FOLLOW_INTERVAL_MS, UsageError } from "../core/domain/index.js";
+import { stripControl as clean, tailLines as tail } from "../core/log-read.js";
+import { channelDir, listChannelFiles, pruneLogs } from "../core/logger.js";
+import { assertWorkerName } from "../core/names.js";
+import { formatLocal, sleep } from "../core/time.js";
+const LOG_OPTIONS = {
+    follow: { type: 'boolean', short: 'f', description: 'Keep printing new log lines' },
+    lines: {
+        type: 'string',
+        short: 'n',
+        valueName: 'lines',
+        description: `Number of recent lines to show (default ${DEFAULT_LOG_LINES})`
+    }
+};
+const RETENTION_NOTE = 'Times are shown in your local time zone; --json prints the raw JSON Lines (UTC).\n' +
+    'Logs are kept for 30 days by default (logRetentionDays) and limited to 300 MB in total\n' +
+    '(logMaxBytes): the oldest files are deleted first.';
+export const logs = {
+    name: 'logs',
+    summary: 'Show the CLI log (fetches, live connection, stops, errors)',
+    usage: '[-f] [-n <lines>]',
+    description: `For one worker's log use '${BIN} worker logs <name>'.\n${RETENTION_NOTE}`,
+    options: LOG_OPTIONS,
+    args: { min: 0, max: 0 },
+    run: (ctx) => show(ctx, null)
+};
+export const workerLogs = {
+    name: 'worker logs',
+    summary: "Show one worker's log (ctx.log, console output, errors with stack traces)",
+    usage: '<name> [-f] [-n <lines>]',
+    description: RETENTION_NOTE,
+    options: LOG_OPTIONS,
+    args: { min: 1, max: 1 },
+    run(ctx) {
+        const worker = ctx.positionals[0];
+        assertWorkerName(worker);
+        return show(ctx, worker);
+    }
+};
+async function show(ctx, worker) {
+    const { values, out } = ctx;
+    const count = parseLines(values.lines);
+    const { logRetentionDays, logMaxBytes } = ctx.loadConfig().values;
+    try {
+        pruneLogs({
+            dir: ctx.dirs.logs,
+            now: ctx.now(),
+            retentionDays: logRetentionDays,
+            maxBytes: logMaxBytes
+        });
+    }
+    catch (err) {
+        out.warn(`log cleanup failed: ${err.message}`);
+    }
+    const dir = channelDir(ctx.dirs.logs, worker);
+    const lines = tail(dir, count);
+    if (lines.length === 0 && !values.follow) {
+        out.info(worker === null ? 'No logs yet.' : `No logs for worker "${worker}" yet.`);
+        return ExitCode.Ok;
+    }
+    for (const line of lines)
+        print(out, line);
+    if (values.follow)
+        await follow(dir, out, ctx.signal);
+    return ExitCode.Ok;
+}
+function parseLines(raw) {
+    if (raw === undefined)
+        return DEFAULT_LOG_LINES;
+    const n = Number(raw);
+    if (typeof raw !== 'string' || !Number.isInteger(n) || n < 1) {
+        throw new UsageError('--lines must be a positive integer');
+    }
+    return n;
+}
+async function follow(dir, out, signal) {
+    let current = listChannelFiles(dir).at(-1)?.file ?? null;
+    let offset = current ? (statSync(current, { throwIfNoEntry: false })?.size ?? 0) : 0;
+    let partial = '';
+    const drain = (file) => {
+        const size = statSync(file, { throwIfNoEntry: false })?.size;
+        if (size === undefined)
+            return;
+        if (size < offset) {
+            offset = 0;
+            partial = '';
+        }
+        if (size === offset)
+            return;
+        let fd;
+        try {
+            fd = openSync(file, 'r');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        try {
+            const buf = Buffer.alloc(size - offset);
+            readSync(fd, buf, 0, buf.length, offset);
+            offset = size;
+            const text = partial + buf.toString('utf8');
+            const parts = text.split('\n');
+            partial = parts.pop() ?? '';
+            for (const line of parts)
+                if (line !== '')
+                    print(out, line);
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    while (!signal.aborted) {
+        const latest = listChannelFiles(dir).at(-1)?.file ?? null;
+        if (current)
+            drain(current);
+        if (latest && latest !== current) {
+            current = latest;
+            offset = 0;
+            partial = '';
+            drain(current);
+        }
+        await sleep(LOG_FOLLOW_INTERVAL_MS, signal);
+    }
+}
+function print(out, line) {
+    if (out.json) {
+        out.print(line);
+        return;
+    }
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        out.print(clean(line));
+        return;
+    }
+    const ts = Date.parse(record.timestamp);
+    const level = String(record.severity_text ?? '').padEnd(5);
+    const paint = record.severity_text === 'error'
+        ? out.out.red
+        : record.severity_text === 'warn'
+            ? out.out.yellow
+            : out.out.dim;
+    const attrs = Object.entries(record.attributes ?? {})
+        .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join(' ');
+    const time = Number.isNaN(ts) ? clean(String(record.timestamp)) : formatLocal(ts);
+    out.print(`${out.out.dim(time)}  ${paint(clean(level))}  ${clean(String(record.body))}` +
+        (attrs ? `  ${out.out.dim(clean(attrs))}` : ''));
+}

package/dist/commands/new.js

@@ -0,0 +1,109 @@
+import { existsSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { BIN, CliError, ExitCode, StopError, TEMPLATE_EXTENSION, WORKER_EXTENSIONS } from "../core/domain/index.js";
+import { assertWorkerName } from "../core/names.js";
+import { failReload, reloadRunner } from "../core/host/reload.js";
+import { readRunner } from "../core/host/runner-lock.js";
+import { reloadLines } from "../modules/workers/reload-result.js";
+import { DOTENV_FILE } from "../modules/workers/runtime/env.js";
+import { jsTemplate, tsTemplate } from "../modules/workers/template.js";
+import { requireWorkersDir } from "./common.js";
+export const workerNew = {
+    name: 'worker new',
+    summary: 'Create a worker file from a template',
+    usage: '<name> [--ts] [--no-reload]',
+    description: 'The name becomes the file name (workers/<name>.mjs) and the task route (/task/<name>).\n' +
+        'Allowed: 1-50 lowercase letters, digits, "_" and "-", not starting with "_" (reserved for\n' +
+        'built-in workers).\n' +
+        'Prints absolute paths of the new file, the workers folder and the project .env.\n' +
+        "If 'start' is running on this folder, the worker is registered right away (3minapi reload).",
+    options: {
+        ts: { type: 'boolean', description: 'Write a TypeScript worker (runs without a build step)' },
+        reload: {
+            type: 'boolean',
+            negated: true,
+            description: "Do not register it with the running 'start' now (run '3minapi reload' later)"
+        }
+    },
+    args: { min: 1, max: 1 },
+    async run(ctx) {
+        const { positionals, values, out, loadConfig } = ctx;
+        const name = positionals[0];
+        assertWorkerName(name);
+        const { root, dir } = requireWorkersDir(loadConfig());
+        const existing = WORKER_EXTENSIONS.map((ext) => path.join(dir, name + ext)).find((f) => existsSync(f));
+        if (existing)
+            throw new CliError(`worker "${name}" already exists: ${existing}`);
+        const file = path.join(dir, name + (values.ts ? TEMPLATE_EXTENSION.ts : TEMPLATE_EXTENSION.js));
+        writeFileSync(file, values.ts ? tsTemplate(name) : jsTemplate(name), { flag: 'wx' });
+        const env = path.join(root, DOTENV_FILE);
+        const envExists = existsSync(env);
+        const lines = [
+            `${out.out.green('created')}  ${file}`,
+            `workers  ${dir}`,
+            `env      ${env}${envExists ? '' : out.out.dim(' (not created yet)')}`,
+            ''
+        ];
+        const reload = await registerNow(ctx, dir, values.reload === false);
+        lines.push(...reload.lines, '', `Next: edit the handler, then test it with '${BIN} worker run ${name}'`);
+        out.result({ name, file, workersDir: dir, env, envExists, reload: reload.json }, lines.join('\n'));
+        return ExitCode.Ok;
+    }
+};
+async function registerNow(ctx, dir, disabled) {
+    const runner = readRunner(ctx.dirs.data);
+    if (runner.state !== 'running') {
+        return {
+            lines: [`The next '${BIN} start' registers it with 3Min API.`],
+            json: { status: 'skipped', reason: 'not_running' }
+        };
+    }
+    const { info } = runner;
+    if (disabled) {
+        return {
+            lines: [`'${BIN} start' is running — run '${BIN} reload' to register it.`],
+            json: { status: 'skipped', reason: 'disabled' }
+        };
+    }
+    if (!info.reload || !info.workersDir) {
+        return {
+            lines: [
+                `'${BIN} start' (pid ${info.pid}) is from an older 3minapi and cannot reload — restart it to register this worker.`
+            ],
+            json: { status: 'skipped', reason: 'unsupported' }
+        };
+    }
+    if (!sameDir(info.workersDir, dir)) {
+        return {
+            lines: [
+                `'${BIN} start' is running on ${info.workersDir}, not this folder — this worker is not registered.`
+            ],
+            json: { status: 'skipped', reason: 'other_folder' }
+        };
+    }
+    ctx.out.info(`'${BIN} start' is running — registering it now (${BIN} reload)...`);
+    try {
+        const result = await reloadRunner(ctx, info);
+        if (!result.ok)
+            failReload(result);
+        return { lines: reloadLines(result), json: { status: 'done', result } };
+    }
+    catch (err) {
+        if (err instanceof StopError || !(err instanceof CliError))
+            throw err;
+        ctx.out.warn(`${err.message}\nThe file was created; run '${BIN} reload' to register it.`);
+        return { lines: [], json: { status: 'failed', error: err.message } };
+    }
+}
+export function sameDir(a, b, platform = process.platform) {
+    const real = (p) => {
+        try {
+            return realpathSync.native(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}

package/dist/commands/paths.js

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { APP_LOG_DIR, CONTROL_DB_FILE, CREDENTIALS_FILE, ConfigError, ExitCode, LOCAL_SERVER_TOKEN_FILE, RUNNER_OUT_FILE, USER_CONFIG_FILE, USER_DB_FILE } from "../core/domain/index.js";
+import { initHint, projectRecordPath } from "../core/project.js";
+import { DOTENV_FILE } from "../modules/workers/runtime/env.js";
+import { workersPath } from "./common.js";
+export const paths = {
+    name: 'paths',
+    summary: 'Show absolute paths of project files and CLI folders',
+    usage: '',
+    description: 'No API calls. Edit the project files (workers, .env, 3minapi.json); use commands for the\n' +
+        'rest — the CLI folders hold the host token and internal state.',
+    options: {},
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const { out, dirs } = ctx;
+        let projectRoot = null;
+        let workersDir = null;
+        let projectConfig = null;
+        try {
+            const config = ctx.loadConfig();
+            projectRoot = config.projectRoot;
+            projectConfig = config.projectFile;
+            if (projectRoot)
+                workersDir = workersPath(projectRoot, config);
+        }
+        catch (err) {
+            if (!(err instanceof ConfigError))
+                throw err;
+            out.warn(err.message);
+        }
+        const entry = (p, note) => ({
+            path: p,
+            exists: p !== null && existsSync(p),
+            note
+        });
+        const data = {
+            projectRoot: entry(projectRoot, projectRoot
+                ? "this host's project — commands use it from any folder. To move it, see '3minapi help init'"
+                : `this host has no project. ${initHint(ctx.home)}`),
+            projectConfig: entry(projectConfig, 'project settings — edit'),
+            workersDir: entry(workersDir, 'worker files — edit'),
+            env: entry(projectRoot && path.join(projectRoot, DOTENV_FILE), 'secrets for workers — edit, do not print values'),
+            db: entry(projectRoot && path.join(projectRoot, USER_DB_FILE), "SQLite file — saved task results (_3minapi_ tables, '3minapi worker results') and workers' own data"),
+            userConfig: entry(path.join(dirs.config, USER_CONFIG_FILE), 'user settings (project settings win)'),
+            logs: entry(dirs.logs, "read with '3minapi logs' / '3minapi worker logs <name>'"),
+            runnerOut: entry(path.join(dirs.logs, APP_LOG_DIR, RUNNER_OUT_FILE), "output of 'start --detach'"),
+            localServerToken: entry(path.join(dirs.config, LOCAL_SERVER_TOKEN_FILE), "read only to call 'start --serve' from a local script"),
+            controlDb: entry(path.join(dirs.data, CONTROL_DB_FILE), "task run history and internal state — do not edit ('3minapi tasks prune')"),
+            projectRecord: entry(projectRecordPath(dirs.data), "which folder is this host's project — change with '3minapi init <folder> --move'"),
+            credentials: entry(path.join(dirs.config, CREDENTIALS_FILE), 'host token — do not read or share')
+        };
+        const width = Math.max(...Object.keys(data).map((k) => k.length)) + 2;
+        const text = Object.entries(data)
+            .map(([key, e]) => {
+            const value = e.path ?? '-';
+            const missing = e.path !== null && !e.exists ? out.out.dim(' (not created yet)') : '';
+            return `${key.padEnd(width)}${value}${missing}\n${' '.repeat(width)}${out.out.dim(e.note)}`;
+        })
+            .join('\n');
+        out.result(data, text);
+        return ExitCode.Ok;
+    }
+};

package/dist/commands/reload.js

@@ -0,0 +1,32 @@
+import { BIN, ExitCode } from "../core/domain/index.js";
+import { failReload, reloadRunner } from "../core/host/reload.js";
+import { readRunnerSettled } from "../core/host/runner-lock.js";
+import { reloadLines } from "../modules/workers/reload-result.js";
+export const reload = {
+    name: 'reload',
+    summary: "Apply added, renamed or re-described worker files to the running 'start'",
+    usage: '',
+    description: 'Asks the running start (the host process) to read the worker files again and register\n' +
+        'them with 3Min API (one API call), without stopping it: running tasks keep going.\n' +
+        'Use it after adding or renaming a worker file or changing its description —\n' +
+        "'worker new' does it by itself.\n" +
+        'Handler code and .env changes need no reload; they apply to the next task.\n' +
+        'Like start, it imports every worker file, so top-level code in them runs again.\n' +
+        'Without a running start there is nothing to reload: the next start registers the files.',
+    options: {},
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const { out } = ctx;
+        const current = await readRunnerSettled(ctx.dirs.data);
+        if (current.state !== 'running') {
+            out.result({ reloaded: false, running: false }, `No '${BIN} start' is running — the next '${BIN} start' registers the worker files.`);
+            return ExitCode.Ok;
+        }
+        out.info(`reloading pid ${current.info.pid}...`);
+        const result = await reloadRunner(ctx, current.info);
+        if (!result.ok)
+            failReload(result);
+        out.result({ reloaded: true, ...result }, reloadLines(result).join('\n'));
+        return ExitCode.Ok;
+    }
+};