@sifurai/cli 0.0.0-stage → 0.1.1

package/dist/api.js

@@ -0,0 +1,107 @@
+export const DEFAULT_API = 'https://api.sifur.ai';
+export class ApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    json;
+    fromSifur;
+    constructor(message, status, code = null, retryAfterSeconds = null, 
+    /** False when the body wasn't JSON at all: an HTML error page, say, from something that isn't Sifur. */
+    json = true, 
+    /** False when `message` is ours, made up from the status, rather than Sifur's own words. */
+    fromSifur = true) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.json = json;
+        this.fromSifur = fromSifur;
+        this.name = 'ApiError';
+    }
+}
+/** Something the engineer has to act on, printed without a stack trace. */
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliError';
+    }
+}
+const TLS_CODES = new Set([
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'UNABLE_TO_GET_ISSUER_CERT',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+]);
+export const TLS_HINT = 'If this is a local or company Sifur with its own certificate, run with NODE_OPTIONS=--use-system-ca (Node 22.15+) or NODE_EXTRA_CA_CERTS=<root cert>.';
+export function isTlsError(cause) {
+    if (!cause)
+        return false;
+    return TLS_CODES.has(cause.code ?? '') || /local issuer certificate|self[- ]signed certificate/i.test(cause.message ?? '');
+}
+export function normalizeApi(api) {
+    return api.replace(/\/+$/, '');
+}
+export class Api {
+    token;
+    userAgent;
+    base;
+    constructor(base, token = null, userAgent = 'sifur-cli') {
+        this.token = token;
+        this.userAgent = userAgent;
+        this.base = normalizeApi(base);
+    }
+    withToken(token) {
+        return new Api(this.base, token, this.userAgent);
+    }
+    async request(path, options = {}) {
+        const headers = { Accept: 'application/json', 'User-Agent': this.userAgent };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        if (options.organization)
+            headers['X-Organization'] = options.organization;
+        let body;
+        if (options.form) {
+            body = options.form;
+        }
+        else if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(options.body);
+        }
+        let response;
+        try {
+            response = await fetch(`${this.base}/api/v1/${path.replace(/^\//, '')}`, {
+                method: options.method ?? (body === undefined ? 'GET' : 'POST'),
+                headers,
+                body,
+            });
+        }
+        catch (error) {
+            const cause = error.cause;
+            const reason = cause?.message ? ` (${cause.message})` : '';
+            throw new CliError(`Couldn't reach Sifur at ${this.base}${reason}.${isTlsError(cause) ? `\n${TLS_HINT}` : ''}`);
+        }
+        const text = await response.text();
+        let json = null;
+        let isJson = true;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = null;
+            isJson = false;
+        }
+        const status = response.status;
+        // undici calls a status it has no name for, like Laravel's 419, "unknown status".
+        const statusText = response.statusText && response.statusText !== 'unknown status' ? ` ${response.statusText}` : '';
+        if (!response.ok) {
+            const said = json?.message?.messages?.[0];
+            const code = json?.code ?? json?.data?.code ?? null;
+            const retryAfter = Number(response.headers.get('retry-after'));
+            throw new ApiError(said ?? `Sifur answered ${status}${statusText}.`, status, code, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null, isJson, said !== undefined);
+        }
+        if (!isJson)
+            throw new ApiError(`Sifur answered ${status}${statusText}, but not with JSON.`, status, null, null, false, false);
+        return (json?.data ?? null);
+    }
+}

package/dist/apply.js

@@ -0,0 +1,143 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { ApiError, CliError } from './api.js';
+import { parseTicketRef, resolveTicket } from './resolve.js';
+import { APPLIED, pruneTicketDir, ticketDir } from './store.js';
+import { defaultWorkdirFor, gitTopLevel } from './workspace.js';
+const INDEX = 'checkouts.json';
+function git(dir, args, input) {
+    const result = spawnSync('git', args, { cwd: dir, input, encoding: 'utf8', maxBuffer: 1024 * 1024 * 1024 });
+    if (result.error)
+        throw new CliError(`Couldn't run git in ${dir}: ${result.error.message}`);
+    return { ok: result.status === 0, stdout: result.stdout ?? '', stderr: (result.stderr ?? '').trim() };
+}
+const patchFile = (repository) => `${repository.replace(/[^A-Za-z0-9_.-]/g, '_')}.patch`;
+function filesIn(dir, patch) {
+    const numstat = git(dir, ['apply', '--numstat'], patch);
+    return numstat.ok ? numstat.stdout.split('\n').filter(Boolean).length : 0;
+}
+async function readIndex(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, INDEX), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** A key names its folder; a uuid is looked for among the tickets with applied changes. */
+async function findAppliedDir(store, ref) {
+    const direct = join(ticketDir(store, ref.toUpperCase()), APPLIED);
+    if (await readIndex(direct))
+        return direct;
+    let entries;
+    try {
+        entries = await readdir(store);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const dir = join(store, entry, APPLIED);
+        if ((await readIndex(dir))?.ticketUuid === ref.toLowerCase())
+            return dir;
+    }
+    return null;
+}
+/**
+ * Puts Sifur's unpushed work for a ticket in the engineer's checkouts, uncommitted, so they can deploy it.
+ * Every checkout is checked before any patch is applied.
+ */
+export async function applyChanges(api, ref, options, io) {
+    const { ticketUuid, key, organization } = await resolveTicket(api, ref);
+    let patches;
+    try {
+        patches = (await api.request(`tickets/${ticketUuid}/changes/patch`, { organization: organization.uuid })) ?? [];
+    }
+    catch (error) {
+        if (error instanceof ApiError && [404, 409].includes(error.status))
+            throw new CliError(`Sifur has no changes for ${ref} to apply: ${error.message}`);
+        throw error;
+    }
+    if (patches.length === 0)
+        io.out(`${ref}: nothing to apply.`);
+    const withChanges = patches.filter((p) => p.patch.trim() !== '');
+    for (const p of patches)
+        if (!withChanges.includes(p))
+            io.out(`${p.repository}: nothing to apply.`);
+    if (withChanges.length === 0)
+        return;
+    const appliedDir = join(ticketDir(options.store, key ?? ('uuid' in parseTicketRef(ref) ? ref : ref.toUpperCase())), APPLIED);
+    const index = (await readIndex(appliedDir)) ?? { ticketUuid, checkouts: {} };
+    let workdirs = options.workdirs ?? {};
+    const named = new Set(patches.map((p) => p.repository));
+    const top = gitTopLevel(options.cwd);
+    for (const p of withChanges) {
+        const picked = defaultWorkdirFor(named, [p.repository], workdirs, top);
+        if (picked.chosen)
+            io.out(`Applying ${picked.chosen.repository}'s changes in ${picked.chosen.dir} (the checkout you're in).`);
+        workdirs = picked.workdirs;
+    }
+    const plan = [];
+    for (const p of withChanges) {
+        const given = workdirs[p.repository];
+        if (!given)
+            throw new CliError(`No checkout of ${p.repository}: run this from inside it, or pass --workdir ${p.repository}=<dir>.`);
+        const dir = resolve(given);
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            throw new CliError(`--workdir ${p.repository}=${given}: no such directory.`);
+        const saved = join(appliedDir, patchFile(p.repository));
+        if (existsSync(saved)) {
+            throw new CliError(`Sifur's changes to ${p.repository} are already applied. Run \`sifur apply ${key ?? ref} --revert\` first, or delete ${saved} if you've taken them out yourself.`);
+        }
+        const status = git(dir, ['status', '--porcelain', '--untracked-files=no']);
+        if (!status.ok)
+            throw new CliError(`${dir} isn't a git checkout: ${status.stderr}`);
+        if (status.stdout.trim())
+            throw new CliError(`${dir} has uncommitted changes. Commit or stash them, then run this again.`);
+        if (!git(dir, ['cat-file', '-e', `${p.base}^{commit}`]).ok) {
+            throw new CliError(`${dir} doesn't have ${p.base.slice(0, 12)}, the commit Sifur's changes to ${p.repository} start from. Run \`git fetch\` and check out ${p.branch} first.`);
+        }
+        plan.push({ patch: p, dir });
+    }
+    await mkdir(appliedDir, { recursive: true });
+    for (const { patch, dir } of plan) {
+        const applied = git(dir, ['apply', '--3way', '--whitespace=nowarn'], patch.patch);
+        if (!applied.ok) {
+            throw new CliError(`Couldn't apply Sifur's changes to ${patch.repository} in ${dir} cleanly:\n${applied.stderr}\nSee \`git status\` there: resolve the conflicts, or put the checkout back as it was with \`git reset --hard\`.`);
+        }
+        await writeFile(join(appliedDir, patchFile(patch.repository)), patch.patch);
+        index.checkouts[patch.repository] = dir;
+        await writeFile(join(appliedDir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+        const count = filesIn(dir, patch.patch);
+        io.out(`${patch.repository}: applied Sifur's changes to ${count} file${count === 1 ? '' : 's'} in ${dir} (${patch.head.slice(0, 7)} on ${patch.branch}). Nothing was committed.`);
+    }
+}
+/** Takes back out what `applyChanges` put in, from the patches it saved. Needs no connection to Sifur. */
+export async function revertChanges(ref, options, io) {
+    const appliedDir = await findAppliedDir(options.store, ref);
+    const index = appliedDir ? await readIndex(appliedDir) : null;
+    const repositories = Object.keys(index?.checkouts ?? {}).filter((r) => existsSync(join(appliedDir, patchFile(r))));
+    if (!appliedDir || !index || repositories.length === 0) {
+        io.out(`Nothing from ${ref} is applied.`);
+        return;
+    }
+    for (const repository of repositories) {
+        const dir = resolve(options.workdirs?.[repository] ?? index.checkouts[repository]);
+        const saved = join(appliedDir, patchFile(repository));
+        const patch = await readFile(saved, 'utf8');
+        const reverted = git(dir, ['apply', '-R', '--3way', '--whitespace=nowarn'], patch);
+        if (!reverted.ok) {
+            throw new CliError(`Couldn't take Sifur's changes to ${repository} back out of ${dir}:\n${reverted.stderr}\nThe patch is kept in ${saved}.`);
+        }
+        await rm(saved);
+        delete index.checkouts[repository];
+        await writeFile(join(appliedDir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+        io.out(`${repository}: took Sifur's changes back out of ${dir}.`);
+    }
+    if (Object.keys(index.checkouts).length === 0) {
+        await rm(appliedDir, { recursive: true, force: true });
+        await pruneTicketDir(options.store, dirname(appliedDir));
+    }
+}

package/dist/automated.js

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+const TAIL_LINES = 5;
+export const MAX_OUTPUT_CHARS = 200_000;
+/** The case's test command in the engineer's checkout; its output streams to the terminal, its tail goes in the note. */
+export function runAutomated(command, cwd, options = {}) {
+    const echo = options.echo ?? ((chunk) => process.stdout.write(chunk));
+    return new Promise((resolve) => {
+        let output = '';
+        const child = spawn(command, { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        const collect = (chunk) => {
+            const text = chunk.toString();
+            echo(text);
+            output = (output + text).slice(-MAX_OUTPUT_CHARS);
+        };
+        child.stdout.on('data', collect);
+        child.stderr.on('data', collect);
+        child.on('error', (error) => resolve({ status: 'blocked', note: `\`${command}\` couldn't start in ${cwd}: ${error.message}` }));
+        child.on('close', (code, signal) => {
+            const tail = output.trimEnd().split('\n').slice(-TAIL_LINES).join('\n');
+            const ended = signal ? `was stopped by ${signal}` : `exited with ${code}`;
+            resolve({
+                status: code === 0 ? 'passed' : 'failed',
+                note: `\`${command}\` ${ended}.${tail ? `\n${tail}` : ''}`,
+                output,
+                exitCode: code,
+            });
+        });
+    });
+}
+/** The shell's "command not found" and "not executable": the checkout can't run the test, which says nothing about the ticket. */
+export const COULD_NOT_RUN = new Set([126, 127]);
+/** The program a command runs: its first word, past any `cd … &&` and VAR=value prefixes. */
+export function programOf(command) {
+    const segment = command.split(/&&|\|\||;/).map((s) => s.trim()).find((s) => s && !/^cd(\s|$)/.test(s)) ?? command.trim();
+    const words = segment.split(/\s+/).filter((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+    return words[0] ?? segment;
+}
+/** The program the shell said it couldn't find, as in `sh: mocha: command not found`. */
+export function notFoundIn(output) {
+    const match = /(?:^|\n)[^\n:]*?:\s*(?:line \d+:\s*)?([^\s:]+):\s*(?:command )?not found/.exec(output);
+    return match?.[1] ?? null;
+}
+const SCRIPT_RUNNERS = new Set(['npm', 'yarn', 'pnpm']);
+export function missingProgram(command, exitCode, workdir, output = '') {
+    const program = programOf(command);
+    const words = command.trim().split(/\s+/);
+    // `npm run x` ran: what's missing is the tool its script calls, installed by `npm install`.
+    const reported = notFoundIn(output);
+    if (reported && reported !== program && SCRIPT_RUNNERS.has(program)) {
+        return `\`${reported}\` isn't installed in ${workdir}: run \`${program} install\`?`;
+    }
+    if (program === 'npx') {
+        const runs = words.slice(words.indexOf('npx') + 1).find((w) => !w.startsWith('-')) ?? 'its package';
+        return `\`npx\` couldn't run ${runs} in ${workdir}: run \`npm install\`?`;
+    }
+    const where = program.includes('/') ? `in ${workdir}` : 'on your PATH';
+    let message = exitCode === 126 ? `\`${program}\` isn't executable ${where}` : `\`${program}\` isn't ${where}`;
+    if (/(^|\/)vendor\/bin\//.test(program))
+        message += ': run `composer install`?';
+    else if (/(^|\/)node_modules\/\.bin\//.test(program))
+        message += ': run `npm install`?';
+    return message;
+}

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { describeError, main } from './cli.js';
+import { terminalIo } from './io.js';
+const io = terminalIo();
+let code;
+try {
+    code = await main(process.argv.slice(2), io);
+}
+catch (error) {
+    process.stderr.write(`${describeError(error)}\n`);
+    code = 2;
+}
+finally {
+    io.close();
+}
+process.exit(code);

package/dist/browser.js

@@ -0,0 +1,16 @@
+import { chromium } from 'playwright-core';
+import { CliError } from './api.js';
+const CHANNELS = ['chrome', 'msedge'];
+/** The engineer's own Chrome, else Edge: playwright-core downloads no browser of its own. */
+export async function launchBrowser(options = {}) {
+    const failures = [];
+    for (const channel of CHANNELS) {
+        try {
+            return await chromium.launch({ channel, headless: !options.headed });
+        }
+        catch (error) {
+            failures.push(`${channel}: ${String(error.message ?? error).split('\n')[0]}`);
+        }
+    }
+    throw new CliError(`Couldn't start Google Chrome or Microsoft Edge. Install one of them (https://www.google.com/chrome/) and run this again.\n  ${failures.join('\n  ')}`);
+}

package/dist/cli.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { accept } from './accept.js';
+import { Api, ApiError, CliError, DEFAULT_API, normalizeApi } from './api.js';
+import { applyChanges, revertChanges } from './apply.js';
+import { cacheDir, loadCredentials } from './config.js';
+import { login, logout } from './login.js';
+import { LEGACY_STORE } from './store.js';
+const USAGE = `Usage:
+  sifur login [--api <url>]
+  sifur logout
+  sifur apply <KEY|uuid> [--workdir <repo>=<dir> …]
+  sifur apply <KEY|uuid> --revert
+  sifur accept <KEY|uuid> --url <test url> [--apply] [--headed] [--workdir <repo>=<dir> …]
+  sifur accept <KEY|uuid> --download [--apply]
+  sifur accept <KEY|uuid> --run --url <test url> [--headed] [--workdir <repo>=<dir> …]
+  sifur accept <KEY|uuid> --upload
+
+Options:
+  --api <url>              Sifur's API (default ${DEFAULT_API}, or SIFUR_API_URL)
+  --url <url>              Your test server, where the ticket's branch is deployed
+  --headed                 Show the browser while the cases run
+  --timeout <seconds>      How long each browser step may take (default 60; raise it for a slow VPN)
+  --apply                  Put Sifur's changes in your checkouts first, uncommitted, as \`sifur apply\` does
+  --revert                 Take the changes \`sifur apply\` put in back out
+  --workdir <repo>=<dir>   Run that repository's automated cases in <dir>; repeatable. Without it,
+                           the git checkout you're in, when it's that repository's
+  --download               Save the cases to ${cacheDir()}/<KEY>/ (before a full-tunnel VPN is up)
+  --run                    Run the saved cases and save the results (no connection to Sifur)
+  --upload                 Send the saved results (after the VPN is down)
+
+Secrets: {{NAME}} in a case comes from SIFUR_SECRET_NAME, or is asked for. It never leaves this machine.
+Exit codes: 0 every case passed, 1 any case failed or was blocked, 2 an error.`;
+function version() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function parseWorkdirs(values) {
+    const workdirs = {};
+    for (const value of values) {
+        const at = value.indexOf('=');
+        if (at <= 0 || at === value.length - 1)
+            throw new CliError(`--workdir ${value}: expected <repository>=<dir>.`);
+        workdirs[value.slice(0, at)] = value.slice(at + 1);
+    }
+    return workdirs;
+}
+const DEFAULT_TIMEOUT_SECONDS = 60;
+export function timeoutSeconds(value) {
+    if (value === undefined)
+        return DEFAULT_TIMEOUT_SECONDS;
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        throw new CliError(`--timeout ${value}: expected a number of seconds.`);
+    return seconds;
+}
+export async function main(argv, io, env = process.env, cwd = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            api: { type: 'string' },
+            url: { type: 'string' },
+            headed: { type: 'boolean', default: false },
+            timeout: { type: 'string' },
+            workdir: { type: 'string', multiple: true, default: [] },
+            download: { type: 'boolean', default: false },
+            run: { type: 'boolean', default: false },
+            upload: { type: 'boolean', default: false },
+            apply: { type: 'boolean', default: false },
+            revert: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    const [command, ...rest] = positionals;
+    if (values.version) {
+        io.out(version());
+        return 0;
+    }
+    if (values.help || !command || command === 'help') {
+        io.out(USAGE);
+        return command || values.help ? 0 : 2;
+    }
+    const explicitApi = values.api ?? env.SIFUR_API_URL;
+    const userAgent = `sifur-cli/${version()} node/${process.versions.node}`;
+    if ((command === 'accept' || command === 'apply') && existsSync(join(cwd, LEGACY_STORE))) {
+        io.out(`${join(cwd, LEGACY_STORE)} is left over from sifur 0.1.0, which kept its files there; nothing uses it now, so it can be deleted.`);
+    }
+    switch (command) {
+        case 'login': {
+            const api = new Api(explicitApi ?? DEFAULT_API, null, userAgent);
+            await login(api, { io, env });
+            return 0;
+        }
+        case 'logout':
+            await logout(io, env);
+            return 0;
+        case 'apply': {
+            const ref = rest[0];
+            if (!ref || rest.length > 1)
+                throw new CliError('Usage: sifur apply <KEY|uuid> [--workdir <repo>=<dir> …]');
+            const options = { workdirs: parseWorkdirs(values.workdir ?? []), cwd, store: cacheDir(env) };
+            if (values.revert) {
+                await revertChanges(ref, options, io);
+                return 0;
+            }
+            await applyChanges(signedIn(await loadCredentials(env), explicitApi, userAgent), ref, options, io);
+            return 0;
+        }
+        case 'accept': {
+            const ref = rest[0];
+            if (!ref || rest.length > 1)
+                throw new CliError('Usage: sifur accept <KEY|uuid> --url <test url>');
+            const modes = ['download', 'run', 'upload'].filter((mode) => values[mode]);
+            if (modes.length > 1)
+                throw new CliError('Use one of --download, --run and --upload at a time.');
+            const mode = modes[0] ?? 'full';
+            const credentials = await loadCredentials(env);
+            const api = mode !== 'run' || values.apply ? signedIn(credentials, explicitApi, userAgent) : null;
+            return accept(api, {
+                ref,
+                mode,
+                url: values.url,
+                headed: values.headed,
+                workdirs: parseWorkdirs(values.workdir ?? []),
+                cwd,
+                store: cacheDir(env),
+                apply: values.apply,
+                consoleOrigin: env.SIFUR_CONSOLE_URL ?? credentials?.console ?? null,
+            }, { io, env, timeoutMs: timeoutSeconds(values.timeout) * 1000 });
+        }
+        default:
+            throw new CliError(`Unknown command "${command}".\n\n${USAGE}`);
+    }
+}
+function signedIn(credentials, explicitApi, userAgent) {
+    if (!credentials)
+        throw new CliError('Not signed in. Run `sifur login` first.');
+    if (explicitApi && normalizeApi(explicitApi) !== normalizeApi(credentials.api)) {
+        throw new CliError(`You're signed in to ${credentials.api}, not ${explicitApi}. Run \`sifur login --api ${explicitApi}\`.`);
+    }
+    return new Api(credentials.api, credentials.token, userAgent);
+}
+export function describeError(error) {
+    if (error instanceof ApiError && error.status === 401)
+        return 'Your sign-in has expired or was revoked. Run `sifur login` again.';
+    if (error instanceof ApiError)
+        return error.fromSifur ? `Sifur answered ${error.status}: ${error.message}` : error.message;
+    if (error instanceof CliError)
+        return error.message;
+    if (error instanceof TypeError && error.code?.startsWith('ERR_PARSE_ARGS'))
+        return `${error.message}\n\n${USAGE}`;
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}

package/dist/config.js

@@ -0,0 +1,39 @@
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function configDir(env = process.env, platform = process.platform) {
+    if (env.SIFUR_CONFIG_DIR)
+        return env.SIFUR_CONFIG_DIR;
+    if (platform === 'win32')
+        return join(env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'sifur');
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'sifur');
+}
+/** Where downloaded cases, results and screenshots are kept: outside the engineer's checkout. */
+export function cacheDir(env = process.env, platform = process.platform) {
+    if (platform === 'win32')
+        return join(env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'sifur');
+    return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'sifur');
+}
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), 'credentials.json');
+}
+export async function loadCredentials(env = process.env) {
+    try {
+        const parsed = JSON.parse(await readFile(credentialsPath(env), 'utf8'));
+        return parsed.api && parsed.token ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    // writeFile's mode only applies when it creates the file; an older one keeps its own.
+    await chmod(path, 0o600);
+    return path;
+}
+export async function deleteCredentials(env = process.env) {
+    await rm(credentialsPath(env), { force: true });
+}

package/dist/io.js

@@ -0,0 +1,96 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { CliError } from './api.js';
+/**
+ * The terminal: one readline over stdin for every question, muted while a secret is typed. Lines are
+ * queued as they arrive, because piped input arrives all at once, before most questions are asked.
+ */
+export function terminalIo() {
+    let muted = false;
+    let rl = null;
+    let ended = false;
+    const lines = [];
+    const waiting = [];
+    const output = new Writable({
+        write(chunk, encoding, callback) {
+            if (!muted)
+                process.stdout.write(chunk, encoding);
+            callback();
+        },
+    });
+    const inputEnded = () => new CliError('Input ended before every question was answered.');
+    function readline() {
+        if (!rl) {
+            rl = createInterface({ input: process.stdin, output, terminal: Boolean(process.stdin.isTTY) });
+            rl.on('line', (line) => {
+                const next = waiting.shift();
+                if (next)
+                    next.resolve(line);
+                else
+                    lines.push(line);
+            });
+            // In terminal mode readline swallows Ctrl-C; without this it would pause instead of quitting.
+            rl.on('SIGINT', () => {
+                rl?.close();
+                process.stdout.write('\n');
+                process.exit(130);
+            });
+            rl.on('close', () => {
+                ended = true;
+                for (const next of waiting.splice(0))
+                    next.reject(inputEnded());
+            });
+        }
+        return rl;
+    }
+    function nextLine() {
+        readline();
+        const queued = lines.shift();
+        if (queued !== undefined)
+            return Promise.resolve(queued);
+        if (ended)
+            return Promise.reject(inputEnded());
+        return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+    }
+    function question(prompt) {
+        const reader = readline();
+        reader.setPrompt(prompt);
+        reader.prompt();
+        return nextLine();
+    }
+    return {
+        out: (line = '') => void process.stdout.write(`${line}\n`),
+        ask: (prompt) => question(prompt),
+        async askHidden(prompt) {
+            const reader = readline();
+            process.stdout.write(prompt);
+            reader.setPrompt('');
+            muted = true;
+            try {
+                return await nextLine();
+            }
+            finally {
+                muted = false;
+                process.stdout.write('\n');
+            }
+        },
+        close: () => rl?.close(),
+    };
+}
+export async function confirm(io, prompt) {
+    for (;;) {
+        const answer = (await io.ask(`${prompt} [y/n] `)).trim().toLowerCase();
+        if (['y', 'yes'].includes(answer))
+            return true;
+        if (['n', 'no'].includes(answer))
+            return false;
+    }
+}
+export async function askStatus(io, prompt) {
+    const choices = { p: 'passed', passed: 'passed', f: 'failed', failed: 'failed', b: 'blocked', blocked: 'blocked' };
+    for (;;) {
+        const answer = choices[(await io.ask(`${prompt} [p]assed / [f]ailed / [b]locked: `)).trim().toLowerCase()];
+        if (answer)
+            return answer;
+    }
+}