@resolflow/cli 0.0.0-stage → 0.1.0-beta.0

package/dist/log.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Logging for the CLI. Rules (CA-08): never log a prompt, an answer or a secret. Call sites only pass short
+ * operational messages (ids, counts, durations); `redact` is a second line of defence for tokens and keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+exports.createLogger = createLogger;
+const TOKEN_PATTERNS = [
+    /cli_[0-9a-f]{32}_[0-9a-f]{64}/gi, // device tokens
+    /cli_[0-9a-f]{64}/gi, // legacy tokens
+    /\b(sk|rk|pk)-[A-Za-z0-9_-]{12,}/g, // provider keys (OpenAI sk-…, Anthropic sk-ant-…)
+    /\bAIza[0-9A-Za-z_-]{20,}/g, // Google API keys
+    /(authorization:\s*bearer\s+)\S+/gi,
+    /([?&#](token|t|key|secret)=)[^&\s]+/gi,
+];
+function redact(text) {
+    let out = String(text);
+    for (const re of TOKEN_PATTERNS)
+        out = out.replace(re, (m, p1) => (typeof p1 === 'string' && m.startsWith(p1) ? `${p1}[redacted]` : '[redacted]'));
+    return out;
+}
+function createLogger(opts = {}) {
+    const sink = opts.sink ?? ((line) => process.stderr.write(line + '\n'));
+    const at = () => new Date().toISOString().slice(11, 19);
+    return {
+        info: (m) => sink(`[${at()}] ${redact(m)}`),
+        warn: (m) => sink(`[${at()}] warn: ${redact(m)}`),
+        error: (m) => sink(`[${at()}] error: ${redact(m)}`),
+        debug: (m) => {
+            if (opts.verbose)
+                sink(`[${at()}] debug: ${redact(m)}`);
+        },
+    };
+}

package/dist/protocol.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = void 0;
+exports.isJob = isJob;
+/**
+ * Device protocol v2 (mirror of backend/src/cli-bridge/device-protocol.ts — keep the two in step).
+ *
+ *   server → device  job         { jobId, kind, adapter?, payload }
+ *   server → device  job_cancel  { jobId }
+ *   server → device  job_input   { jobId, questionId, answer }   (answer to ask_user; P4 Mode B)
+ *   device → server  job_event   { jobId, seq, event: JobEvent }
+ */
+exports.PROTOCOL_VERSION = 2;
+function isJob(v) {
+    return (!!v &&
+        typeof v.jobId === 'string' &&
+        v.jobId.length > 0 &&
+        v.jobId.length <= 100 &&
+        (v.kind === 'llm_request' || v.kind === 'agent_job') &&
+        (v.adapter === undefined || typeof v.adapter === 'string') &&
+        !!v.payload &&
+        typeof v.payload === 'object');
+}

package/dist/run-log.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunLog = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const MAX_ENTRIES = 1000;
+const ALLOWED_KEYS = ['at', 'requestId', 'model', 'status', 'errorKind', 'ms', 'promptTokens', 'completionTokens'];
+class RunLog {
+    file;
+    constructor(dir) {
+        this.file = path.join(dir, 'runs.log');
+    }
+    append(entry) {
+        try {
+            // Whitelist the fields: nothing else (e.g. a payload) can ever end up in the file
+            const clean = {};
+            for (const k of ALLOWED_KEYS)
+                if (entry[k] !== undefined)
+                    clean[k] = entry[k];
+            (0, config_1.ensurePrivateDir)(path.dirname(this.file));
+            fs.appendFileSync(this.file, JSON.stringify(clean) + '\n', { mode: 0o600 });
+            const lines = fs.readFileSync(this.file, 'utf8').split('\n').filter(Boolean);
+            if (lines.length > MAX_ENTRIES * 1.2)
+                (0, config_1.writePrivateFile)(this.file, lines.slice(-MAX_ENTRIES).join('\n') + '\n');
+        }
+        catch {
+            /* the log never breaks serving */
+        }
+    }
+    recent(n = 10) {
+        try {
+            return fs
+                .readFileSync(this.file, 'utf8')
+                .split('\n')
+                .filter(Boolean)
+                .slice(-n)
+                .map((l) => JSON.parse(l));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.RunLog = RunLog;

package/dist/runtime.js

@@ -0,0 +1,38 @@
+"use strict";
+/** How this process was started and how it talks to the terminal (RF-94502d0b). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NPX_PREFIX = void 0;
+exports.skipUpdateCheck = skipUpdateCheck;
+exports.invokedViaNpx = invokedViaNpx;
+exports.cliCommand = cliCommand;
+exports.guardPipes = guardPipes;
+exports.NPX_PREFIX = 'npx @resolflow/cli';
+/** `--version` / `--help` / no command: answered and exited by commander at once, so no update check (it could not finish). */
+function skipUpdateCheck(argv = process.argv) {
+    const args = argv.slice(2);
+    return args.length === 0 || args[0] === 'help' || args.some((a) => a === '--version' || a === '-V' || a === '--help' || a === '-h');
+}
+/** Started through `npx @resolflow/cli …` (npm exec sets npm_command=exec; npx installs into the npm cache's _npx). */
+function invokedViaNpx(env = process.env, argv = process.argv) {
+    return env.npm_command === 'exec' || /[\\/]_npx[\\/]/.test(argv[1] ?? '');
+}
+/** How the user runs a command of this CLI: `resolflow start` or `npx @resolflow/cli start`. */
+function cliCommand(sub, env = process.env, argv = process.argv) {
+    return `${invokedViaNpx(env, argv) ? exports.NPX_PREFIX : 'resolflow'} ${sub}`;
+}
+/**
+ * `resolflow status | head -1`: the reader closes the pipe and the next write fails with EPIPE. That is not an
+ * error of ours — exit quietly instead of printing a stack trace. Other stream errors still surface.
+ */
+function guardPipes(streams = [process.stdout, process.stderr], exit = (c) => process.exit(c)) {
+    for (const s of streams) {
+        s.on('error', (err) => {
+            if (err?.code === 'EPIPE')
+                exit(0);
+            else
+                setImmediate(() => {
+                    throw err;
+                });
+        });
+    }
+}

package/dist/secrets.js

@@ -0,0 +1,207 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAFE_SECRET = exports.FileSecretStore = void 0;
+exports.keychainAccount = keychainAccount;
+exports.agentKeyEntry = agentKeyEntry;
+exports.chooseSecretStore = chooseSecretStore;
+const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const SERVICE = 'resolflow-cli';
+/**
+ * The keychain account of a config directory: one entry per config dir (RESOLFLOW_CONFIG_DIR), so two CLIs on one
+ * machine (another user profile, staging next to production) never share or overwrite each other's token.
+ */
+function keychainAccount(dir) {
+    return `device-token:${crypto.createHash('sha256').update(path.resolve(dir)).digest('hex').slice(0, 16)}`;
+}
+function run(cmd, args, stdin) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: ['pipe', 'pipe', 'ignore'], shell: false });
+        let stdout = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.on('error', () => resolve({ code: -1, stdout: '' }));
+        child.on('close', (code) => resolve({ code: code ?? -1, stdout }));
+        if (stdin !== undefined)
+            child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}
+class FileSecretStore {
+    kind = 'file';
+    file;
+    constructor(dir, fileName = 'device-token') {
+        this.file = path.join(dir, fileName);
+    }
+    async get() {
+        try {
+            if (process.platform !== 'win32') {
+                const mode = fs.statSync(this.file).mode & 0o777;
+                if (mode & 0o077)
+                    fs.chmodSync(this.file, 0o600); // tighten a loosened file
+            }
+            return fs.readFileSync(this.file, 'utf8').trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(secret) {
+        (0, config_1.writePrivateFile)(this.file, secret + '\n');
+    }
+    async delete() {
+        try {
+            fs.unlinkSync(this.file);
+        }
+        catch {
+            /* not there */
+        }
+    }
+}
+exports.FileSecretStore = FileSecretStore;
+/** Characters a secret may use (device tokens, vendor API keys): nothing the `security -i` command parser treats specially. */
+exports.SAFE_SECRET = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,511}$/;
+class MacKeychainStore {
+    account;
+    label;
+    kind = 'macos-keychain';
+    static BIN = '/usr/bin/security';
+    constructor(account, label = 'Resolflow CLI device') {
+        this.account = account;
+        this.label = label;
+    }
+    async get() {
+        return new Promise((resolve) => {
+            (0, child_process_1.execFile)(MacKeychainStore.BIN, ['find-generic-password', '-a', this.account, '-s', SERVICE, '-w'], (err, stdout) => resolve(err ? null : stdout.trim() || null));
+        });
+    }
+    async set(secret) {
+        if (!exports.SAFE_SECRET.test(secret))
+            throw new Error('Unexpected secret format');
+        // `security -i` reads commands from stdin: the secret never appears in a process list
+        const r = await run(MacKeychainStore.BIN, ['-i'], `add-generic-password -U -a ${this.account} -s ${SERVICE} -l "${this.label}" -w ${secret}\n`);
+        if (r.code !== 0)
+            throw new Error('Could not write to the macOS keychain');
+    }
+    async delete() {
+        await run(MacKeychainStore.BIN, ['delete-generic-password', '-a', this.account, '-s', SERVICE]);
+    }
+}
+class LibsecretStore {
+    bin;
+    account;
+    label;
+    kind = 'libsecret';
+    constructor(bin, account, label = 'Resolflow CLI device') {
+        this.bin = bin;
+        this.account = account;
+        this.label = label;
+    }
+    async get() {
+        const r = await run(this.bin, ['lookup', 'service', SERVICE, 'account', this.account]);
+        return r.code === 0 ? r.stdout.trim() || null : null;
+    }
+    async set(secret) {
+        const r = await run(this.bin, ['store', `--label=${this.label}`, 'service', SERVICE, 'account', this.account], secret);
+        if (r.code !== 0)
+            throw new Error('Could not write to the Secret Service (libsecret)');
+    }
+    async delete() {
+        await run(this.bin, ['clear', 'service', SERVICE, 'account', this.account]);
+    }
+}
+class KeytarStore {
+    keytar;
+    account;
+    kind = 'keytar';
+    constructor(keytar, account) {
+        this.keytar = keytar;
+        this.account = account;
+    }
+    async get() {
+        return (await this.keytar.getPassword(SERVICE, this.account)) ?? null;
+    }
+    async set(secret) {
+        await this.keytar.setPassword(SERVICE, this.account, secret);
+    }
+    async delete() {
+        await this.keytar.deletePassword(SERVICE, this.account);
+    }
+}
+function loadKeytar() {
+    try {
+        // Optional dependency: only when the user installed it
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require('keytar');
+    }
+    catch {
+        return null;
+    }
+}
+const LIBSECRET_BINS = ['/usr/bin/secret-tool', '/usr/local/bin/secret-tool'];
+function agentKeyEntry(dir, tool) {
+    if (!/^[a-z0-9-]{1,40}$/.test(tool))
+        throw new Error('Unknown tool');
+    const hash = crypto.createHash('sha256').update(path.resolve(dir)).digest('hex').slice(0, 16);
+    return { account: `agent-key:${tool}:${hash}`, fileName: `agent-key-${tool}`, label: `Resolflow CLI ${tool} API key`, what: `the ${tool} API key` };
+}
+/** The best store available here (see the header). `warning` is set when only the file store is left. */
+function chooseSecretStore(dir, env = process.env, entry) {
+    const forced = env.RESOLFLOW_SECRET_STORE;
+    const account = entry?.account ?? keychainAccount(dir);
+    const label = entry?.label ?? 'Resolflow CLI device';
+    const file = new FileSecretStore(dir, entry?.fileName);
+    const fileWarning = `No OS keychain available: ${entry?.what ?? 'the device token'} is stored in ${file.file} (readable by your user only). Install "keytar" or libsecret's secret-tool for keychain storage.`;
+    if (forced === 'file')
+        return { store: file, warning: fileWarning };
+    if (forced !== 'keychain') {
+        const keytar = loadKeytar();
+        if (keytar)
+            return { store: new KeytarStore(keytar, account) };
+        if (forced === 'keytar')
+            return { store: file, warning: fileWarning };
+    }
+    if (process.platform === 'darwin' && fs.existsSync(MacKeychainStore.BIN))
+        return { store: new MacKeychainStore(account, label) };
+    if (process.platform === 'linux') {
+        const bin = LIBSECRET_BINS.find((b) => fs.existsSync(b));
+        if (bin && (env.DBUS_SESSION_BUS_ADDRESS || env.DISPLAY || env.WAYLAND_DISPLAY))
+            return { store: new LibsecretStore(bin, account, label) };
+    }
+    return { store: file, warning: fileWarning };
+}

package/dist/update-check.js

@@ -0,0 +1,180 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECK_INTERVAL_MS = exports.DEFAULT_REGISTRY = exports.PACKAGE_NAME = void 0;
+exports.updateCheckDisabled = updateCheckDisabled;
+exports.compareVersions = compareVersions;
+exports.readUpdateCache = readUpdateCache;
+exports.writeUpdateCache = writeUpdateCache;
+exports.fetchLatestVersion = fetchLatestVersion;
+exports.isStandaloneBinary = isStandaloneBinary;
+exports.updateHint = updateHint;
+exports.startUpdateCheck = startUpdateCheck;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Non-blocking "a newer version is available" hint (RF-94502d0b). Asks the npm registry for the `latest` dist-tag of
+ * @resolflow/cli at most once a day (result cached in the config directory) and prints one line on stderr after the
+ * command. Never installs anything. Off with RESOLFLOW_NO_UPDATE_CHECK=1 (also NO_UPDATE_NOTIFIER, CI, or when stderr
+ * is not a terminal). Only the package name goes to the registry — no device, token or usage data.
+ */
+exports.PACKAGE_NAME = '@resolflow/cli';
+exports.DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+exports.CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const CACHE_FILE = 'update-check.json';
+function updateCheckDisabled(env = process.env, isTTY = !!process.stderr.isTTY) {
+    const on = (v) => !!v && v !== '0' && v.toLowerCase() !== 'false';
+    return on(env.RESOLFLOW_NO_UPDATE_CHECK) || on(env.NO_UPDATE_NOTIFIER) || on(env.CI) || !isTTY;
+}
+function parse(v) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(v.trim());
+    if (!m)
+        return null;
+    return { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split('.') : [] };
+}
+/** Semver precedence: <0 when a < b, 0 when equal, >0 when a > b; NaN when either is not a version. */
+function compareVersions(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        return NaN;
+    for (let i = 0; i < 3; i++)
+        if (pa.core[i] !== pb.core[i])
+            return pa.core[i] - pb.core[i];
+    if (!pa.pre.length || !pb.pre.length)
+        return pb.pre.length - pa.pre.length; // a release beats its pre-releases
+    for (let i = 0; i < Math.max(pa.pre.length, pb.pre.length); i++) {
+        const x = pa.pre[i];
+        const y = pb.pre[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const nx = /^\d+$/.test(x);
+        const ny = /^\d+$/.test(y);
+        if (nx && ny)
+            return Number(x) - Number(y);
+        if (nx !== ny)
+            return nx ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+function readUpdateCache(dir) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(dir, CACHE_FILE), 'utf8'));
+        return typeof data?.checkedAt === 'number' ? { checkedAt: data.checkedAt, latest: typeof data.latest === 'string' ? data.latest : undefined } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateCache(dir, cache) {
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(path.join(dir, CACHE_FILE), JSON.stringify(cache) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** The registry's `latest` dist-tag, or null on any problem. */
+async function fetchLatestVersion(registry, signal) {
+    try {
+        const res = await fetch(`${registry.replace(/\/+$/, '')}/-/package/${exports.PACKAGE_NAME.replace('/', '%2F')}/dist-tags`, {
+            headers: { accept: 'application/json' },
+            redirect: 'error',
+            signal,
+        });
+        if (!res.ok)
+            return null;
+        const tags = (await res.json());
+        return typeof tags.latest === 'string' && parse(tags.latest) ? tags.latest : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when this process is a standalone binary (Node single executable application). */
+function isStandaloneBinary() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return !!require('node:sea').isSea();
+    }
+    catch {
+        return false;
+    }
+}
+function updateHint(current, latest, binary = isStandaloneBinary()) {
+    if (!latest || !(compareVersions(latest, current) > 0))
+        return null;
+    const how = binary ? 'download it from the Resolflow CLI releases page' : `run: npm i -g ${exports.PACKAGE_NAME}@latest`;
+    return `resolflow ${latest} is available (you have ${current}) — ${how}. Hide this with RESOLFLOW_NO_UPDATE_CHECK=1.`;
+}
+function startUpdateCheck(opts) {
+    const env = opts.env ?? process.env;
+    if (updateCheckDisabled(env, opts.isTTY ?? !!process.stderr.isTTY))
+        return { finish: async () => null };
+    const now = opts.now ?? Date.now();
+    const cache = readUpdateCache(opts.dir);
+    const hintFrom = (latest) => updateHint(opts.current, latest, opts.binary);
+    if (cache && now - cache.checkedAt < exports.CHECK_INTERVAL_MS && now >= cache.checkedAt) {
+        return { finish: async () => hintFrom(cache.latest) };
+    }
+    const ctrl = new AbortController();
+    const registry = env.RESOLFLOW_UPDATE_REGISTRY || exports.DEFAULT_REGISTRY;
+    const fetchLatest = opts.fetchLatest ?? ((signal) => fetchLatestVersion(registry, signal));
+    const pending = fetchLatest(ctrl.signal).then((latest) => {
+        // Remember the attempt even when it failed, so an offline machine asks at most once a day
+        writeUpdateCache(opts.dir, { checkedAt: now, latest: latest ?? cache?.latest });
+        return latest ?? cache?.latest;
+    });
+    return {
+        async finish(maxMs = 800) {
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    ctrl.abort();
+                    resolve(undefined);
+                }, maxMs);
+            });
+            const latest = await Promise.race([pending, timeout]);
+            clearTimeout(timer);
+            return hintFrom(latest ?? cache?.latest);
+        },
+    };
+}

package/dist/urls.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * URL policy of the CLI (CA-08):
+ * - the Resolflow API: https only (so the socket is wss://); plain http only to a loopback host (local development);
+ * - the local model server: loopback only (127.0.0.1, ::1, localhost) — the device never forwards prompts to
+ *   another machine, and nothing else on the network can be reached through it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlPolicyError = exports.DEFAULT_LOCAL_ENDPOINT = exports.DEFAULT_API_URL = void 0;
+exports.isLoopbackHost = isLoopbackHost;
+exports.normaliseApiUrl = normaliseApiUrl;
+exports.normaliseLocalEndpoint = normaliseLocalEndpoint;
+exports.DEFAULT_API_URL = 'https://api.resolflow.ai';
+exports.DEFAULT_LOCAL_ENDPOINT = 'http://127.0.0.1:11434/v1';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+function isLoopbackHost(hostname) {
+    const h = hostname.toLowerCase();
+    return LOOPBACK_HOSTS.has(h) || /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(h);
+}
+class UrlPolicyError extends Error {
+}
+exports.UrlPolicyError = UrlPolicyError;
+/**
+ * Normalise the Resolflow API base (no trailing slash, no `/api` suffix). The REST API is `<base>/api/...`, the
+ * device socket is socket.io namespace `/cli` on `<base>`.
+ */
+function normaliseApiUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw.trim());
+    }
+    catch {
+        throw new UrlPolicyError(`Not a URL: ${raw}`);
+    }
+    if (u.username || u.password)
+        throw new UrlPolicyError('The API URL must not contain credentials');
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && isLoopbackHost(u.hostname))) {
+        throw new UrlPolicyError('The Resolflow API must use https:// (http:// is allowed only for localhost development)');
+    }
+    u.search = '';
+    u.hash = '';
+    let path = u.pathname.replace(/\/+$/, '');
+    if (path.endsWith('/api'))
+        path = path.slice(0, -4);
+    return `${u.protocol}//${u.host}${path}`;
+}
+/** The OpenAI-compatible base of the local model server, e.g. http://127.0.0.1:11434/v1. Loopback only. */
+function normaliseLocalEndpoint(raw) {
+    let u;
+    try {
+        u = new URL(raw.trim());
+    }
+    catch {
+        throw new UrlPolicyError(`Not a URL: ${raw}`);
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:')
+        throw new UrlPolicyError('The local endpoint must be http(s)://');
+    if (!isLoopbackHost(u.hostname)) {
+        throw new UrlPolicyError('The local model endpoint must be on this machine (127.0.0.1, ::1 or localhost)');
+    }
+    if (u.username || u.password)
+        throw new UrlPolicyError('The local endpoint must not contain credentials');
+    u.search = '';
+    u.hash = '';
+    let path = u.pathname.replace(/\/+$/, '');
+    if (!/\/v\d+$/.test(path))
+        path = `${path}/v1`;
+    return `${u.protocol}//${u.host}${path}`;
+}