@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/core/output.js

@@ -0,0 +1,68 @@
+export function shouldUseColor({ flag, env, isTTY }) {
+    if (flag !== undefined)
+        return flag;
+    if (env.NO_COLOR)
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '')
+        return env.FORCE_COLOR !== '0';
+    if (env.TERM === 'dumb')
+        return false;
+    return isTTY;
+}
+function style(enabled) {
+    const sgr = (open, close) => enabled ? (t) => `\x1b[${open}m${t}\x1b[${close}m` : (t) => t;
+    return {
+        bold: sgr(1, 22),
+        dim: sgr(2, 22),
+        red: sgr(31, 39),
+        yellow: sgr(33, 39),
+        green: sgr(32, 39)
+    };
+}
+export class Output {
+    json;
+    out;
+    err;
+    stdout;
+    stderr;
+    wrote = false;
+    constructor(opts) {
+        this.json = opts.json;
+        this.stdout = opts.stdout;
+        this.stderr = opts.stderr;
+        const color = (s) => shouldUseColor({ flag: opts.color, env: opts.env, isTTY: s.isTTY === true });
+        this.out = style(!opts.json && color(opts.stdout));
+        this.err = style(color(opts.stderr));
+    }
+    result(data, text) {
+        if (this.json) {
+            this.writeOut(JSON.stringify(data, null, 2) + '\n');
+        }
+        else if (text !== undefined) {
+            this.writeOut(text.endsWith('\n') ? text : text + '\n');
+        }
+    }
+    print(text) {
+        this.writeOut(text.endsWith('\n') ? text : text + '\n');
+    }
+    errorResult(doc) {
+        if (this.json && !this.wrote)
+            this.writeOut(JSON.stringify(doc, null, 2) + '\n');
+    }
+    writeOut(text) {
+        this.wrote = true;
+        this.stdout.write(text);
+    }
+    prompt(text) {
+        this.stderr.write(text);
+    }
+    info(message) {
+        this.stderr.write(message + '\n');
+    }
+    warn(message) {
+        this.stderr.write(`${this.err.yellow('warning:')} ${message}\n`);
+    }
+    error(message) {
+        this.stderr.write(`${this.err.red('error:')} ${message}\n`);
+    }
+}

package/dist/core/paths.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { APP_DIR_NAME, ENV } from "./domain/index.js";
+export function resolveDirs({ platform, env, home }) {
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    const override = absolute(p, env[ENV.home]);
+    if (override) {
+        return { config: override, data: override, logs: p.join(override, 'logs') };
+    }
+    if (platform === 'win32') {
+        const roaming = absolute(p, env.APPDATA) ?? p.join(home, 'AppData', 'Roaming');
+        const local = absolute(p, env.LOCALAPPDATA) ?? p.join(home, 'AppData', 'Local');
+        const data = p.join(local, APP_DIR_NAME);
+        return { config: p.join(roaming, APP_DIR_NAME), data, logs: p.join(data, 'logs') };
+    }
+    if (platform === 'darwin') {
+        const support = p.join(home, 'Library', 'Application Support', APP_DIR_NAME);
+        return { config: support, data: support, logs: p.join(home, 'Library', 'Logs', APP_DIR_NAME) };
+    }
+    const configHome = absolute(p, env.XDG_CONFIG_HOME) ?? p.join(home, '.config');
+    const stateHome = absolute(p, env.XDG_STATE_HOME) ?? p.join(home, '.local', 'state');
+    const data = p.join(stateHome, APP_DIR_NAME);
+    return { config: p.join(configHome, APP_DIR_NAME), data, logs: p.join(data, 'logs') };
+}
+function absolute(p, value) {
+    return value && p.isAbsolute(value) ? value : undefined;
+}

package/dist/core/project.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { findProjectFile } from "./config.js";
+import { BIN, DEFAULT_PROJECT_DIR, PROJECT_CONFIG_FILE, PROJECT_RECORD_FILE } from "./domain/index.js";
+import { writeSecretFile } from "./secure-fs.js";
+import { shellArg } from "./text.js";
+export function projectRecordPath(dataDir) {
+    return path.join(dataDir, PROJECT_RECORD_FILE);
+}
+export function readProjectRecord(dataDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(projectRecordPath(dataDir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const root = parsed?.root;
+    if (typeof root !== 'string' || !path.isAbsolute(root))
+        return null;
+    return { root, recordedAt: String(parsed.recordedAt ?? '') };
+}
+export function writeProjectRecord(dataDir, root, now) {
+    const body = { root, recordedAt: new Date(now).toISOString() };
+    writeSecretFile(projectRecordPath(dataDir), JSON.stringify(body, null, '\t') + '\n');
+}
+export function defaultProjectRoot(home) {
+    return path.join(home, DEFAULT_PROJECT_DIR);
+}
+export function initHint(home) {
+    const where = home === undefined ? `~/${DEFAULT_PROJECT_DIR}` : defaultProjectRoot(home);
+    return `Run '${BIN} init' (creates ${where}) or '${BIN} init <folder>'.`;
+}
+export function goneHint(root, home) {
+    return (`this host's project ${root} no longer exists. If you moved it, run any ${BIN} command inside ` +
+        `the new folder (e.g. '${BIN} status') and it is picked up. Otherwise: ${initHint(home)}`);
+}
+export function projectAlive(root) {
+    return existsSync(path.join(root, PROJECT_CONFIG_FILE));
+}
+export function samePath(a, b, platform) {
+    const norm = (p) => {
+        let real = path.resolve(p);
+        try {
+            real = realpathSync.native(real);
+        }
+        catch {
+        }
+        return platform === 'darwin' || platform === 'win32' ? real.toLowerCase() : real;
+    };
+    return norm(a) === norm(b);
+}
+export function resolveProject(input) {
+    const recorded = readProjectRecord(input.dataDir);
+    const unreadable = recorded === null && existsSync(projectRecordPath(input.dataDir))
+        ? `could not read ${projectRecordPath(input.dataDir)} (this host's project record). `
+        : '';
+    const found = findProjectFile(input.cwd);
+    if (recorded && projectAlive(recorded.root)) {
+        const notices = [];
+        if (found && !samePath(path.dirname(found), recorded.root, input.platform)) {
+            notices.push(`ignoring ${found} — this host's project is ${recorded.root}. ` +
+                `Run '${BIN} init ${shellArg(path.dirname(found))} --move' to make it the project instead.`);
+        }
+        return { projectFile: path.join(recorded.root, PROJECT_CONFIG_FILE), record: null, notices };
+    }
+    if (!found) {
+        const notices = recorded
+            ? [goneHint(recorded.root, input.home)]
+            : unreadable
+                ? [`${unreadable}${initHint(input.home)}`]
+                : [];
+        return { projectFile: null, record: null, notices };
+    }
+    const root = path.dirname(found);
+    return {
+        projectFile: found,
+        record: root,
+        notices: [
+            recorded
+                ? `this host's project ${recorded.root} no longer exists — now using ${root}.`
+                : `${unreadable}this host's project is now ${root} — commands use it from any folder.`
+        ]
+    };
+}

package/dist/core/prompt.js

@@ -0,0 +1,140 @@
+import { CliError, ExitCode } from "./domain/index.js";
+const MASK = '*';
+export async function readSecret(stdin, out, label) {
+    if (!stdin.isTTY || !stdin.setRawMode || !stdin.on || !stdin.off) {
+        throw new CliError('no terminal to prompt on. Pipe the token in with --with-token.');
+    }
+    const on = stdin.on.bind(stdin);
+    const off = stdin.off.bind(stdin);
+    out.prompt(label);
+    const listeners = [];
+    try {
+        stdin.setRawMode(true);
+        stdin.setEncoding?.('utf8');
+        stdin.resume?.();
+        return await new Promise((resolve, reject) => {
+            let value = '';
+            const skip = new EscapeSkipper();
+            const onData = (chunk) => {
+                const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+                for (const ch of text) {
+                    if (skip.consume(ch))
+                        continue;
+                    if (ch === '\r' || ch === '\n' || ch === '\u0004')
+                        return resolve(value);
+                    if (ch === '\u0003')
+                        return reject(new CliError('cancelled', ExitCode.Interrupted));
+                    if (ch === '\u007f' || ch === '\b') {
+                        if (value !== '') {
+                            value = value.slice(0, -1);
+                            out.prompt('\b \b');
+                        }
+                    }
+                    else if (ch === '\u0015') {
+                        out.prompt('\b \b'.repeat(value.length));
+                        value = '';
+                    }
+                    else if (ch >= ' ') {
+                        value += ch;
+                        out.prompt(MASK);
+                    }
+                }
+            };
+            const onEnd = () => reject(new CliError('input closed before the token was entered'));
+            const onError = (err) => reject(new CliError(`cannot read input: ${err.message}`));
+            listeners.push(['data', onData], ['end', onEnd], ['error', onError]);
+            for (const [event, listener] of listeners)
+                on(event, listener);
+        });
+    }
+    finally {
+        for (const [event, listener] of listeners)
+            off(event, listener);
+        stdin.setRawMode(false);
+        stdin.pause?.();
+        out.prompt('\n');
+    }
+}
+class EscapeSkipper {
+    state = 'none';
+    consume(ch) {
+        switch (this.state) {
+            case 'none':
+                if (ch !== '\u001b')
+                    return false;
+                this.state = 'esc';
+                return true;
+            case 'esc':
+                this.state = ch === '[' ? 'csi' : ch === 'O' ? 'ss3' : 'none';
+                return true;
+            case 'csi': {
+                const code = ch.charCodeAt(0);
+                if (code >= 0x40 && code <= 0x7e)
+                    this.state = 'none';
+                return true;
+            }
+            case 'ss3':
+                this.state = 'none';
+                return true;
+        }
+    }
+}
+export async function confirm(stdin, out, question) {
+    if (!stdin.isTTY || !stdin.setRawMode || !stdin.on || !stdin.off) {
+        throw new CliError('no terminal to ask for confirmation. Pass --yes to proceed.');
+    }
+    const on = stdin.on.bind(stdin);
+    const off = stdin.off.bind(stdin);
+    out.prompt(`${question} [y/N] `);
+    const listeners = [];
+    try {
+        stdin.setRawMode(true);
+        stdin.setEncoding?.('utf8');
+        stdin.resume?.();
+        const answer = await new Promise((resolve, reject) => {
+            let value = '';
+            const skip = new EscapeSkipper();
+            const onData = (chunk) => {
+                const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+                for (const ch of text) {
+                    if (skip.consume(ch))
+                        continue;
+                    if (ch === '\r' || ch === '\n' || ch === '\u0004')
+                        return resolve(value);
+                    if (ch === '\u0003')
+                        return reject(new CliError('cancelled', ExitCode.Interrupted));
+                    if (ch === '\u007f' || ch === '\b') {
+                        if (value !== '') {
+                            value = value.slice(0, -1);
+                            out.prompt('\b \b');
+                        }
+                    }
+                    else if (ch >= ' ') {
+                        value += ch;
+                        out.prompt(ch);
+                    }
+                }
+            };
+            const onEnd = () => reject(new CliError('input closed before an answer was given'));
+            const onError = (err) => reject(new CliError(`cannot read input: ${err.message}`));
+            listeners.push(['data', onData], ['end', onEnd], ['error', onError]);
+            for (const [event, listener] of listeners)
+                on(event, listener);
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        for (const [event, listener] of listeners)
+            off(event, listener);
+        stdin.setRawMode(false);
+        stdin.pause?.();
+        out.prompt('\n');
+    }
+}
+export async function readAllStdin(stdin) {
+    let text = '';
+    for await (const chunk of stdin) {
+        text += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+    }
+    return text;
+}

package/dist/core/redact.js

@@ -0,0 +1,45 @@
+import { truncate } from "./text.js";
+export const REDACTED = '<redacted>';
+const SECRET_KEY = /authorization|token|secret|password|passwd|api[-_]?key|signature|cookie|credential/i;
+const SECRET_VALUES = [
+    /tm_(?:host|live|test|mcp|task)_[0-9a-f]{8,}/gi,
+    /whsec_[A-Za-z0-9+/=]{8,}/g,
+    /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/g
+];
+const SECRET_ASSIGNMENTS = [
+    /(\btoken=)[^\s&#"']{8,}/gi,
+    /(\b[A-Za-z0-9_]*(?:SECRET|_KEY|TOKEN|PASSWORD)\s*=\s*)["']?[^\s"'&]{8,}["']?/gi
+];
+export function redactString(value) {
+    let out = value;
+    for (const pattern of SECRET_ASSIGNMENTS)
+        out = out.replace(pattern, `$1${REDACTED}`);
+    for (const pattern of SECRET_VALUES) {
+        out = out.replace(pattern, (match, scheme) => typeof scheme === 'string' && /^(Bearer|Basic)$/.test(scheme)
+            ? `${scheme} ${REDACTED}`
+            : REDACTED);
+    }
+    return out;
+}
+export function redact(value, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return redactString(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[circular]';
+    seen.add(value);
+    if (value instanceof Error) {
+        return { name: value.name, message: redactString(value.message) };
+    }
+    if (Array.isArray(value))
+        return value.map((v) => redact(v, seen));
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        out[key] = SECRET_KEY.test(key) && v !== null && v !== undefined ? REDACTED : redact(v, seen);
+    }
+    return out;
+}
+export function redactAndTruncate(value, maxChars) {
+    return truncate(redactString(value), maxChars);
+}

package/dist/core/secure-fs.js

@@ -0,0 +1,50 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { PRIVATE_DIR_MODE, SECRET_FILE_MODE } from "./domain/index.js";
+const isWindows = process.platform === 'win32';
+export function ensurePrivateDir(dir) {
+    const existed = existsSync(dir);
+    mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+    if (!existed && !isWindows)
+        chmodSync(dir, PRIVATE_DIR_MODE);
+}
+export function writeSecretFile(file, data) {
+    ensurePrivateDir(path.dirname(file));
+    const tmp = `${file}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        writeFileSync(tmp, data, { mode: SECRET_FILE_MODE, flag: 'wx' });
+        if (!isWindows)
+            chmodSync(tmp, SECRET_FILE_MODE);
+        renameWithRetry(tmp, file);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+export function touchSecretFile(file) {
+    ensurePrivateDir(path.dirname(file));
+    closeSync(openSync(file, 'a', SECRET_FILE_MODE));
+}
+export function looseMode(file) {
+    if (isWindows || !existsSync(file))
+        return null;
+    const mode = statSync(file).mode & 0o777;
+    return mode & 0o077 ? mode : null;
+}
+function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (!isWindows || attempt >= 4 || !['EPERM', 'EBUSY', 'EACCES'].includes(code ?? '')) {
+                throw err;
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+        }
+    }
+}

package/dist/core/text-file.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { ConfigError } from "./domain/index.js";
+export function readUserText(file) {
+    const bytes = readFileSync(file);
+    if (bytes.length >= 2 &&
+        ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff))) {
+        throw new ConfigError(`${file} is saved as UTF-16. Save it as UTF-8 — in Notepad choose "UTF-8" when saving; ` +
+            `in PowerShell write it with [IO.File]::WriteAllText(path, text).`);
+    }
+    const bom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+    return bytes.toString('utf8', bom ? 3 : 0);
+}

package/dist/core/text.js

@@ -0,0 +1,27 @@
+export function truncate(value, max) {
+    return value.length <= max ? value : value.slice(0, max - 1) + '…';
+}
+export function stripControl(text) {
+    return text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+}
+export function shellArg(value) {
+    return /^[\w+:./\\~-]+$/.test(value) ? value : `"${value}"`;
+}
+export function oneLine(value) {
+    return value.replace(/\s*\n\s*/g, ' ');
+}
+export function formatCount(n) {
+    return n.toLocaleString('en-US');
+}
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v < 10 ? v.toFixed(1) : Math.round(v)} ${units[i]}`;
+}

package/dist/core/time.js

@@ -0,0 +1,84 @@
+import { setTimeout as delay } from 'node:timers/promises';
+const DAY_MS = 86_400_000;
+export function toIsoUtc(ms) {
+    return new Date(ms).toISOString();
+}
+export function utcDate(ms) {
+    return toIsoUtc(ms).slice(0, 10);
+}
+export function formatLocal(ms) {
+    const d = new Date(ms);
+    const offset = -d.getTimezoneOffset();
+    const sign = offset < 0 ? '-' : '+';
+    const abs = Math.abs(offset);
+    return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())} ` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+}
+export function relative(ms, now) {
+    const diff = ms - now;
+    const abs = Math.abs(diff);
+    const units = [
+        [DAY_MS, 'day'],
+        [3_600_000, 'hour'],
+        [60_000, 'minute']
+    ];
+    let text = 'less than a minute';
+    for (const [size, name] of units) {
+        const n = Math.floor(abs / size);
+        if (n >= 1) {
+            text = `${n} ${name}${n === 1 ? '' : 's'}`;
+            break;
+        }
+    }
+    return diff >= 0 ? `in ${text}` : `${text} ago`;
+}
+export function describeAt(iso, now, opts = {}) {
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        return iso;
+    return opts.local ? `${formatLocal(ms)} (${relative(ms, now)})` : relative(ms, now);
+}
+export function daysToMs(days) {
+    return days * DAY_MS;
+}
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+export async function sleep(ms, signal) {
+    try {
+        await delay(ms, undefined, { signal });
+    }
+    catch (err) {
+        if (err.name !== 'AbortError')
+            throw err;
+    }
+}
+export function formatInterval(ms) {
+    return ms % 1000 === 0 ? `${ms / 1000}s` : `${ms} ms`;
+}
+export function maxTasksPerMinute(concurrency, intervalMs) {
+    return (concurrency * 60_000) / intervalMs;
+}
+export function formatThroughput(concurrency, intervalMs) {
+    const perMin = maxTasksPerMinute(concurrency, intervalMs);
+    const rate = perMin >= 1
+        ? `${Math.round(perMin).toLocaleString('en-US')} tasks/min`
+        : `${Math.round(perMin * 60).toLocaleString('en-US')} tasks/hour`;
+    return `up to ${concurrency} at a time (≈ ${rate} at most)`;
+}
+export function parseDateArg(value) {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (day) {
+        const [, y, m, d] = day.map(Number);
+        const ms = new Date(y, m - 1, d).getTime();
+        const back = new Date(ms);
+        return back.getFullYear() === y && back.getMonth() === m - 1 && back.getDate() === d
+            ? ms
+            : null;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value))
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : ms;
+}

package/dist/core/update-notice.js

@@ -0,0 +1,142 @@
+import { BIN, ENV, PACKAGE_NAME } from "./domain/index.js";
+import { parseVersion } from "./version.js";
+export const UPDATE_META = {
+    latest: 'cli_latest',
+    noticeAt: 'update_notice_at',
+    noticeVersion: 'update_notice_version'
+};
+export const UPDATE_NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export function isReleaseVersion(value) {
+    return typeof value === 'string' && /^\d{1,6}\.\d{1,6}\.\d{1,6}$/.test(value);
+}
+export function isNewerVersion(a, b) {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    }
+    return false;
+}
+export function runsFromNpx(entry = process.argv[1]) {
+    return entry !== undefined && /[\\/]_npx[\\/]/.test(entry);
+}
+export function updateCommand(entry = process.argv[1]) {
+    return runsFromNpx(entry)
+        ? `npx ${PACKAGE_NAME}@latest --version`
+        : `npm i -g ${PACKAGE_NAME}@latest`;
+}
+export function updateNote(running, entry = process.argv[1]) {
+    const npx = runsFromNpx(entry);
+    const restart = npx
+        ? `stop it with '${BIN} stop' and start it again as 'npx ${PACKAGE_NAME}@latest start'`
+        : `stop it first with '${BIN} stop' and start it again after the update`;
+    const keep = npx ? ` Keep running it as 'npx ${PACKAGE_NAME}@latest <command>'.` : '';
+    if (running === null)
+        return `If '${BIN} start' is running in the background, ${restart}.${keep}`;
+    if (running)
+        return `'${BIN} start' is running — ${restart}.${keep}`;
+    return npx ? keep.trim() : null;
+}
+export function updateInfo(current, latest, running = false) {
+    const available = latest !== null && isNewerVersion(latest, current);
+    return {
+        current,
+        latest,
+        available,
+        command: available ? updateCommand() : null,
+        note: available ? updateNote(running) : null
+    };
+}
+export function rememberLatest(db, cli, now, log) {
+    try {
+        const latest = cli?.latest;
+        if (isReleaseVersion(latest))
+            db.setMeta(UPDATE_META.latest, latest, now);
+        else
+            db.deleteMeta(UPDATE_META.latest);
+        return true;
+    }
+    catch (err) {
+        log?.('could not record the latest CLI version', { message: err.message });
+        return false;
+    }
+}
+export function recordedLatest(db) {
+    const latest = db.getMeta(UPDATE_META.latest);
+    return isReleaseVersion(latest) ? latest : null;
+}
+export function readLatest(db, log) {
+    try {
+        return recordedLatest(db);
+    }
+    catch (err) {
+        log?.('could not read the latest CLI version', { message: err.message });
+        return null;
+    }
+}
+export function updateNoticeSuppressed(env) {
+    const on = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+    return on(env[ENV.noUpdateNotice]) || env.NO_UPDATE_NOTIFIER !== undefined || on(env.CI);
+}
+export function updateNoticeLine(info) {
+    const line = `update available: ${BIN} ${info.current} → ${info.latest} — run: ${info.command}`;
+    return info.note ? `${line}\n${info.note}` : line;
+}
+export function claimUpdateNotice(db, info, now, env, log) {
+    if (!info.available || info.latest === null || updateNoticeSuppressed(env))
+        return false;
+    try {
+        const at = Number(db.getMeta(UPDATE_META.noticeAt) ?? NaN);
+        const sameVersion = db.getMeta(UPDATE_META.noticeVersion) === info.latest;
+        if (sameVersion &&
+            Number.isFinite(at) &&
+            now - at >= 0 &&
+            now - at < UPDATE_NOTICE_INTERVAL_MS) {
+            return false;
+        }
+        db.setMetas({ [UPDATE_META.noticeAt]: String(now), [UPDATE_META.noticeVersion]: info.latest }, now);
+    }
+    catch (err) {
+        log?.('could not record the update notice', { message: err.message });
+    }
+    return true;
+}
+export class LatestWatch {
+    opts;
+    seen = undefined;
+    written = undefined;
+    armed = false;
+    announcedAt = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    observe(cli) {
+        const latest = isReleaseVersion(cli?.latest) ? cli.latest : null;
+        if (latest !== this.written) {
+            const ok = rememberLatest(this.opts.db, latest === null ? undefined : { latest }, this.opts.now(), this.opts.log);
+            this.written = ok ? latest : undefined;
+        }
+        const changed = this.seen !== undefined && latest !== this.seen;
+        this.seen = latest;
+        if (!this.armed)
+            return;
+        if (changed || this.opts.now() - this.announcedAt >= UPDATE_NOTICE_INTERVAL_MS)
+            this.fire();
+    }
+    arm() {
+        this.armed = true;
+        this.fire();
+    }
+    fire() {
+        this.announcedAt = this.opts.now();
+        try {
+            this.opts.announce();
+        }
+        catch (err) {
+            this.opts.log?.('could not announce the CLI update', { message: err.message });
+        }
+    }
+}