@sifurai/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# Sifur CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run a Sifur ticket's acceptance cases against your own test server, from your own machine, and
+send the results back to Sifur.
+
+Use it when your app only runs on your team's servers, behind a firewall or VPN that Sifur can't
+reach. Sifur never deploys to your server, never holds VPN or server credentials, and never connects
+into your network: you deploy the ticket's branch, this tool runs the cases on your machine, and only
+the results and screenshots go to Sifur.
+
+## Requirements
+
+- Node.js 20 or newer
+- Google Chrome or Microsoft Edge (the tool drives the browser you already have; it downloads none)
+- A machine that can reach your test server (usually: on your company VPN)
+
+## Install
+
+Install it once to get the `sifur` command:
+
+```sh
+npm install -g @sifurai/cli
+sifur --version
+```
+
+Update it with:
+
+```sh
+npm install -g @sifurai/cli@latest
+```
+
+(`npx @sifurai/cli …` works too, but npx can keep running an older version it has cached, so an
+installed `sifur` is the reliable way.)
+
+## Sign in
+
+```sh
+sifur login
+```
+
+This prints a code and opens Sifur in your browser. Check that the code matches, approve it, and
+the CLI is signed in. The sign-in is listed with your other sessions in Sifur, where you can revoke it.
+It follows your organization's single sign-on and MFA rules, like the console.
+
+The token is saved with owner-only permissions (0600) in:
+
+- macOS and Linux: `~/.config/sifur/credentials.json` (or `$XDG_CONFIG_HOME/sifur`)
+- Windows: `%APPDATA%\sifur\credentials.json`
+
+To sign out (and revoke the session):
+
+```sh
+sifur logout
+```
+
+## Apply Sifur's work before you deploy
+
+Sifur pushes the ticket's branch only when you approve it after acceptance testing, so your CI
+isn't set off by every change along the way. Until then, `sifur apply` puts Sifur's changes in your
+checkout, for you to deploy to your test server and test:
+
+```sh
+cd ~/src/azalea
+sifur apply AZA-12
+```
+
+It works on the checkout you're in when it's the ticket's repository (as for automated cases,
+below), or on `--workdir <repository>=<dir>` for each repository. The checkout needs no uncommitted
+changes (commit or stash them first) and must have the commit Sifur's work starts from; if it
+doesn't, the CLI tells you to `git fetch` and check out the ticket's branch. The changes are
+applied with `git apply --3way` and left uncommitted (staged); the CLI prints how many files each
+repository's changes touch.
+
+To take them back out:
+
+```sh
+sifur apply AZA-12 --revert
+```
+
+`apply` keeps a copy of the patch in the cache folder (`<cache>/AZA-12/applied/`) for `--revert`,
+which deletes it once the changes are out.
+
+`sifur accept AZA-12 --apply --url …` applies the changes first, then runs the cases. It doesn't
+take them out afterwards.
+
+## Run a ticket's acceptance cases
+
+When a ticket is in **Acceptance testing**, its Overview shows the branch and the commit of each
+repository to deploy. Deploy them to your test server, then run:
+
+```sh
+sifur accept AZA-12 --url https://test.example.internal
+```
+
+`AZA-12` is the ticket's key; its uuid works too. The CLI:
+
+1. Finds the ticket in your organizations and downloads its cases.
+2. Runs each UI case in a headless browser against `--url` (paths in the cases are relative to
+   it), taking a screenshot after every step. Add `--headed` to watch.
+3. For a step that needs a person's eye, shows you the screenshot's path and asks whether it looks
+   right.
+4. Runs automated cases in your checkout of their repository (see below); without one, asks you
+   for the result.
+5. For a case with no script, shows its steps and expected result and asks you for the result:
+   passed, failed or blocked, with a note.
+6. Uploads the screenshots and results, prints a summary, and links to the ticket.
+
+Every case passed: the ticket moves on to approval. Any failed or blocked: it goes back to be fixed.
+
+`--url` is the root of your test server: the cases' paths are opened under it. The CLI warns when
+it has a path or a query string, since that's rarely what's wanted.
+
+Until they're uploaded, the cases, screenshots and results are kept outside your checkout, in a
+cache folder per user:
+
+- macOS and Linux: `~/.cache/sifur/AZA-12/` (or `$XDG_CACHE_HOME/sifur/AZA-12/`)
+- Windows: `%LOCALAPPDATA%\sifur\AZA-12\`
+
+The CLI prints where. Once Sifur has the results, it deletes that folder, leaving nothing behind
+(except a patch from `sifur apply` that's still applied, which `--revert` needs). If the upload
+fails, everything is kept: send it again with `sifur accept AZA-12 --upload`, from any directory.
+
+The CLI never reads or writes a `.sifur` folder in your checkout. Version 0.1.0 kept its files
+there; if one is left over, the CLI says so, and you can delete it.
+
+## Automated cases
+
+An automated case runs its test command in your checkout of the case's repository. Run `accept`
+from inside that checkout and the CLI uses it: the top of the git checkout you're in is used for a
+repository when the cases name only that one repository, or when the checkout's folder has the
+repository's name. It prints which folder it uses for which repository. For anything else, name
+the folder with `--workdir <repository>=<dir>`, repeated for each repository; `--workdir` always
+wins:
+
+```sh
+sifur accept AZA-12 --url https://test.example.internal \
+    --workdir api=~/src/azalea-api --workdir web=~/src/azalea-web
+```
+
+A case's command is written for Sifur's sandbox, where the repository is checked out at
+`/workspace/<repository>`. On your machine, a leading `cd /workspace/<repository> &&` is dropped,
+any other `/workspace/<repository>` path becomes your checkout's, and the command runs in your
+checkout.
+
+If the command can't run in your checkout at all (the shell says the program isn't there or isn't
+executable, exit 127 or 126, say because `vendor/` or `node_modules/` isn't installed), that isn't
+recorded as a failure. The CLI says what's missing (with a hint like "run `composer install`?"),
+and asks you for the result as it does for a case with no checkout. This is the same with `--run`.
+
+Some test files Sifur writes for a ticket are kept out of the repository, so they never show up in
+your branch. Before a repository's automated cases run, the CLI puts them in your checkout, and
+afterwards it removes them again (also on Ctrl-C), along with any folder it made for them, so
+`git status` is just as it was. A file of yours at the same path is set aside and put back; one
+that's already identical is left alone. A path outside the checkout is refused.
+
+## VPN: split tunnel or full tunnel
+
+With a **split-tunnel** VPN (only company traffic goes through it), one command does everything:
+your machine reaches the test server and Sifur at the same time.
+
+With a **full-tunnel** VPN that blocks the internet while it's up, work in three steps:
+
+```sh
+# VPN down
+sifur accept AZA-12 --download
+
+# VPN up: runs the cases, talks only to your test server
+sifur accept AZA-12 --run --url https://test.example.internal
+
+# VPN down
+sifur accept AZA-12 --upload
+```
+
+`--download` saves the cases (and the test files Sifur keeps out of the repository) in the cache
+folder, `--run` runs them from there and saves the results next to them, and `--upload` sends them
+and then deletes them.
+They don't need to run from the same directory; run `--run` from your checkout to have automated
+cases run in it.
+
+## Secrets
+
+A UI case can use a placeholder such as `{{APP_USERNAME}}` or `{{APP_PASSWORD}}` for a test
+account's sign-in, in what it types, the page it opens, and the text or URL it checks for. The CLI
+takes each from the environment variable `SIFUR_SECRET_<NAME>` (for example
+`SIFUR_SECRET_APP_PASSWORD`) or, when that isn't set, asks you for it once per run, after saying
+which case and step needs it. A name with `USER`, `EMAIL` or `LOGIN` in it shows what you type;
+any other, and always one with `PASSWORD`, `TOKEN` or `SECRET`, doesn't. Secrets stay on your
+machine: they are never written to disk, never sent to Sifur, and are replaced with `[secret]` in
+any error message.
+
+`{{RUN}}` isn't a secret and is never asked for: it's replaced with a short token, new for each
+run and the same in every case and step of it, so a case can create data that's unique each time
+(`qa-{{RUN}}@example.com`) and check for it afterwards.
+
+```sh
+SIFUR_SECRET_ADMIN_PASSWORD='…' sifur accept AZA-12 --url https://test.example.internal
+```
+
+## Options
+
+| Option | |
+|---|---|
+| `--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, page loads included (default 60). Raise it when the test server is slow, for example over a VPN |
+| `--workdir <repository>=<dir>` | Run that repository's automated cases in `<dir>`; repeatable. Default: the checkout you're in, when it's that repository's |
+| `--download` / `--run` / `--upload` | The three steps for a full-tunnel VPN |
+| `--apply` | With `accept`: put Sifur's changes in your checkouts first, as `sifur apply` does |
+| `--revert` | With `apply`: take the changes back out |
+| `--api <url>` | Sifur's API, for `login` (default `https://api.sifur.ai`, or `SIFUR_API_URL`). Not your test server: that's `--url` |
+
+## Troubleshooting
+
+**`<url> isn't Sifur's API`** from `sifur login --api <url>`: `--api` is Sifur's own address (for
+example `https://api.sifur.ai`), and is only needed for a Sifur other than the default. Your test
+server goes in `sifur accept --url`.
+
+**`unable to get local issuer certificate`** or **`self-signed certificate`**: Node doesn't trust the
+certificate of the Sifur it's talking to. If this is a local or company Sifur with its own
+certificate, run with `NODE_OPTIONS=--use-system-ca` (Node 22.15+), or point Node at the root
+certificate with `NODE_EXTRA_CA_CERTS=<root cert>`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Every case passed (or `--download` finished) |
+| 1 | At least one case failed or was blocked |
+| 2 | An error: not signed in, the ticket isn't in acceptance testing, Sifur unreachable, no Chrome or Edge, … |

package/dist/accept.js

@@ -0,0 +1,399 @@
+import { existsSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { ApiError, CliError } from './api.js';
+import { applyChanges } from './apply.js';
+import { COULD_NOT_RUN, missingProgram, runAutomated } from './automated.js';
+import { launchBrowser } from './browser.js';
+import { askStatus, confirm } from './io.js';
+import { resolveTicket } from './resolve.js';
+import { buildResultsPayload, combine, outcome } from './results.js';
+import { runUiCase } from './runner.js';
+import { collectSecrets, newRunToken, redact, secretUses } from './secrets.js';
+import { findTicketDir, loadCases, loadResults, removeTicketFiles, saveCases, saveResults } from './store.js';
+import { checkFilePaths, defaultWorkdirs, gitTopLevel, localizeCommand, placeTestFiles, removeOnExit } from './workspace.js';
+export const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+export async function download(api, ref) {
+    const { ticketUuid, organization } = await resolveTicket(api, ref);
+    try {
+        const acceptance = await api.request(`tickets/${ticketUuid}/acceptance`, { organization: organization.uuid });
+        return { api: api.base, organizationUuid: organization.uuid, acceptance: { ...acceptance, files: acceptance.files ?? [] } };
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 409) {
+            throw new CliError(`${ref} isn't waiting for acceptance testing: ${error.message}`);
+        }
+        throw error;
+    }
+}
+export function describeDeploy(acceptance, io) {
+    const { ticket, heads } = acceptance;
+    io.out(`${ticket.key}: ${ticket.title}`);
+    if (ticket.branch)
+        io.out(`Branch: ${ticket.branch}`);
+    const repositories = Object.entries(heads ?? {});
+    if (repositories.length > 0) {
+        io.out('The test server should be running:');
+        for (const [repository, sha] of repositories)
+            io.out(`  ${repository}  ${sha}`);
+    }
+    io.out(`${acceptance.cases.length} case${acceptance.cases.length === 1 ? '' : 's'}`);
+    io.out();
+}
+function printCase(io, testCase) {
+    for (const [index, step] of (testCase.steps ?? []).entries())
+        io.out(`    ${index + 1}. ${step}`);
+    if (testCase.expected)
+        io.out(`    Expected: ${testCase.expected}`);
+}
+async function askNote(io, prompt) {
+    return (await io.ask(prompt)).trim();
+}
+async function askEngineer(io, testCase, why) {
+    io.out(`  ${why}. Check it by hand:`);
+    printCase(io, testCase);
+    if (testCase.automatedTestRef)
+        io.out(`    Test: ${testCase.automatedTestRef}`);
+    const status = await askStatus(io, '  Result');
+    const note = await askNote(io, status === 'passed' ? '  Note (optional): ' : '  What happened? ');
+    return { status, note };
+}
+function judgeWith(io) {
+    return async (step, screenshot, testCase) => {
+        io.out(`  Judge: ${step.caption ?? 'Does the page look right?'}`);
+        if (testCase.expected)
+            io.out(`    Expected: ${testCase.expected}`);
+        io.out(screenshot ? `    Screenshot: ${screenshot}` : '    (No screenshot could be taken.)');
+        if (await confirm(io, '  Does it look right?'))
+            return { ok: true };
+        const note = await askNote(io, "  What's wrong? ");
+        return { ok: false, note: note || undefined };
+    };
+}
+function filesFor(testCase, files, workdirs) {
+    return files.filter((f) => f.repository === testCase.repository || (!testCase.repository && !workdirs[f.repository]));
+}
+function workdirFor(testCase, workdirs) {
+    if (testCase.repository && workdirs[testCase.repository])
+        return workdirs[testCase.repository];
+    const all = Object.values(workdirs);
+    return !testCase.repository && all.length === 1 ? all[0] : null;
+}
+function summarize(status, steps, notes) {
+    if (notes.length > 0)
+        return notes.join('\n');
+    if (status === 'passed' && steps.length > 0)
+        return `All ${steps.length} step${steps.length === 1 ? '' : 's'} passed.`;
+    return status === 'passed' ? 'Passed.' : `The case ${status}.`;
+}
+/**
+ * Before anything runs: the checkouts whose cases need dependencies that aren't installed, said once
+ * rather than as a prompt for every case. Quitting is the default; continuing asks for those cases.
+ */
+async function checkDependencies(cases, workdirs, io) {
+    const missing = new Map();
+    for (const testCase of cases) {
+        if (testCase.check === 'ui' || !testCase.automatedTestRef)
+            continue;
+        const cwd = workdirFor(testCase, workdirs);
+        if (!cwd)
+            continue;
+        const workdir = resolve(cwd);
+        const command = localizeCommand(testCase.automatedTestRef, workdir);
+        const needs = [
+            /(^|[\s;&|])(npm|npx|yarn|pnpm)\s|node_modules\/\.bin\//.test(command) &&
+                !existsSync(join(workdir, 'node_modules'))
+                ? { folder: 'node_modules', setup: 'npm install' }
+                : null,
+            /(^|[\s/])vendor\/bin\//.test(command) && !existsSync(join(workdir, 'vendor'))
+                ? { folder: 'vendor', setup: 'composer install' }
+                : null,
+        ].filter((need) => need !== null);
+        for (const need of needs) {
+            const key = `${workdir}\0${need.folder}`;
+            const entry = missing.get(key) ?? { setup: `${need.setup} in ${workdir} (there's no ${need.folder})`, ids: [] };
+            entry.ids.push(testCase.id);
+            missing.set(key, entry);
+        }
+    }
+    if (missing.size === 0)
+        return;
+    io.out('Some cases need dependencies this checkout doesn\'t have yet:');
+    for (const entry of missing.values())
+        io.out(`  ${entry.setup}: ${entry.ids.join(', ')}`);
+    const answer = (await io.ask('[q]uit to install them first, or [c]ontinue and answer those cases yourself: ')).trim().toLowerCase();
+    if (!answer.startsWith('c')) {
+        throw new CliError(`Install them, then run this again: ${[...missing.values()].map((entry) => entry.setup.split(' (')[0]).join('; ')}.`);
+    }
+}
+/** Runs every case on this machine against the engineer's test server. Nothing here talks to Sifur. */
+export async function runCases(acceptance, options, deps) {
+    const { io } = deps;
+    const workdirs = options.workdirs ?? {};
+    for (const [repository, dir] of Object.entries(workdirs)) {
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            throw new CliError(`--workdir ${repository}=${dir}: no such directory.`);
+    }
+    const files = acceptance.files ?? [];
+    checkFilePaths(files);
+    const placed = new Map();
+    let stopRemovingOnExit = null;
+    await checkDependencies(acceptance.cases, workdirs, io);
+    const scripted = acceptance.cases.filter((c) => c.check !== 'automated' && (c.uiScript?.length ?? 0) > 0);
+    const secrets = await collectSecrets(secretUses(scripted), io, deps.env);
+    const runToken = newRunToken();
+    let browser = null;
+    const results = [];
+    try {
+        for (const testCase of acceptance.cases) {
+            io.out(`${testCase.id}  ${testCase.title}`);
+            const statuses = [];
+            const notes = [];
+            let steps = [];
+            let output;
+            if (testCase.check === 'ui' || testCase.check === 'both') {
+                if (scripted.includes(testCase)) {
+                    browser ??= await (deps.launch ?? launchBrowser)({ headed: options.headed });
+                    const ui = await runUiCase(browser, testCase, {
+                        baseUrl: options.baseUrl,
+                        outDir: options.outDir,
+                        secrets,
+                        runToken,
+                        judge: judgeWith(io),
+                        timeoutMs: deps.timeoutMs,
+                        onStep: (n, caption) => io.out(`  … ${n}. ${caption}`),
+                    });
+                    for (const step of ui.steps)
+                        io.out(`  ${step.ok ? 'ok  ' : 'FAIL'} ${step.n}. ${step.caption}${step.error ? `: ${step.error}` : ''}`);
+                    statuses.push(ui.status);
+                    notes.push(...ui.notes);
+                    steps = ui.steps;
+                }
+                else {
+                    const answer = await askEngineer(io, testCase, 'No UI script');
+                    statuses.push(answer.status);
+                    if (answer.note)
+                        notes.push(answer.note);
+                }
+            }
+            if (testCase.check === 'automated' || testCase.check === 'both') {
+                const cwd = workdirFor(testCase, workdirs);
+                let run;
+                if (testCase.automatedTestRef && cwd) {
+                    const workdir = resolve(cwd);
+                    const key = `${testCase.repository ?? ''}\0${workdir}`;
+                    const needed = filesFor(testCase, files, workdirs);
+                    if (!placed.has(key) && needed.length > 0) {
+                        stopRemovingOnExit ??= removeOnExit(() => [...placed.values()]);
+                        placed.set(key, placeTestFiles(workdir, needed));
+                    }
+                    const command = localizeCommand(testCase.automatedTestRef, workdir);
+                    io.out(`  $ ${command}   (in ${cwd})`);
+                    run = await runAutomated(command, workdir, { echo: deps.echo });
+                    if (run.exitCode !== undefined && run.exitCode !== null && COULD_NOT_RUN.has(run.exitCode)) {
+                        io.out(`  ${missingProgram(command, run.exitCode, workdir, run.output ?? '')}`);
+                        const answer = await askEngineer(io, testCase, "The test couldn't run here, so it isn't recorded as failed");
+                        run = { status: answer.status, note: answer.note };
+                    }
+                    else {
+                        run = { ...run, note: redact(run.note, secrets), output: redact(run.output ?? '', secrets) };
+                    }
+                }
+                else {
+                    const why = !testCase.automatedTestRef
+                        ? 'No test command'
+                        : `No --workdir ${testCase.repository ?? '<repository>'}=<dir> to run \`${testCase.automatedTestRef}\` in`;
+                    const answer = await askEngineer(io, testCase, why);
+                    run = { status: answer.status, note: answer.note };
+                }
+                statuses.push(run.status);
+                if (run.note)
+                    notes.push(run.note);
+                if (run.output !== undefined)
+                    output = run.output;
+            }
+            const status = combine(statuses);
+            io.out(`  → ${status}`);
+            io.out();
+            results.push({
+                caseUuid: testCase.uuid,
+                id: testCase.id,
+                status,
+                notes: summarize(status, steps, notes),
+                steps,
+                ...(output !== undefined ? { output } : {}),
+            });
+        }
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        for (const files of placed.values()) {
+            files.remove();
+            const count = `${files.count} test file${files.count === 1 ? '' : 's'}`;
+            io.out(`Put ${count} that Sifur keeps out of the repository in ${files.workdir} for the run, and removed ${files.count === 1 ? 'it' : 'them'} again.`);
+        }
+        stopRemovingOnExit?.();
+    }
+    return { baseUrl: options.baseUrl, ranAt: new Date().toISOString(), results };
+}
+async function uploadScreenshot(api, saved, path) {
+    const bytes = await readFile(path);
+    const type = extname(path).toLowerCase() === '.png' ? 'image/png' : 'image/jpeg';
+    const form = new FormData();
+    form.append('file', new Blob([bytes], { type }), basename(path));
+    const uploaded = await api.request(`tickets/${saved.acceptance.ticket.uuid}/acceptance/screenshots`, {
+        method: 'POST',
+        form,
+        organization: saved.organizationUuid,
+    });
+    return uploaded.uuid;
+}
+export async function upload(api, saved, results, io) {
+    const screenshots = new Map();
+    const paths = [...new Set(results.results.flatMap((r) => r.steps.map((s) => s.screenshot)).filter((p) => Boolean(p)))];
+    if (paths.length > 0)
+        io.out(`Uploading ${paths.length} screenshot${paths.length === 1 ? '' : 's'}…`);
+    for (const path of paths) {
+        if (!existsSync(path)) {
+            io.out(`  Skipped ${path}: the file is gone.`);
+            continue;
+        }
+        if (statSync(path).size > MAX_SCREENSHOT_BYTES) {
+            io.out(`  Skipped ${path}: larger than 5 MB.`);
+            continue;
+        }
+        screenshots.set(path, await uploadScreenshot(api, saved, path));
+    }
+    const payload = buildResultsPayload(saved.acceptance.ticket.stateVersion, results.baseUrl, results.results, screenshots);
+    try {
+        return await api.request(`tickets/${saved.acceptance.ticket.uuid}/acceptance/results`, {
+            method: 'POST',
+            body: payload,
+            organization: saved.organizationUuid,
+        });
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 409) {
+            throw new CliError(`Sifur refused the results: ${error.message} The ticket has moved on since the cases were downloaded; run accept again.`);
+        }
+        throw error;
+    }
+}
+export function printSummary(io, results) {
+    io.out('Summary');
+    for (const result of results)
+        io.out(`  ${result.status.padEnd(7)}  ${result.id}`);
+    const overall = outcome(results);
+    const counts = ['passed', 'failed', 'blocked']
+        .map((status) => [status, results.filter((r) => r.status === status).length])
+        .filter(([, count]) => count > 0)
+        .map(([status, count]) => `${count} ${status}`);
+    io.out(`${overall === 'passed' ? 'Passed' : 'Not passed'}: ${counts.join(', ') || 'no cases'}`);
+    return overall;
+}
+export function ticketLink(consoleOrigin, ticketUuid) {
+    return consoleOrigin ? `${consoleOrigin.replace(/\/+$/, '')}/tickets/${ticketUuid}` : null;
+}
+/** The whole `accept` command; returns the exit code (0 all passed, 1 any not passed). Errors throw, for exit 2. */
+export async function accept(api, args, deps) {
+    const { io } = deps;
+    if (args.apply) {
+        if (args.mode === 'run' || args.mode === 'upload')
+            throw new CliError(`--apply needs Sifur, so it can't go with --${args.mode}.`);
+        if (!api)
+            throw new CliError('Run `sifur login` first.');
+        await applyChanges(api, args.ref, { workdirs: args.workdirs, cwd: args.cwd, store: args.store }, io);
+        io.out();
+    }
+    if (args.mode === 'download') {
+        if (!api)
+            throw new CliError('Run `sifur login` first.');
+        const saved = await download(api, args.ref);
+        const dir = await saveCases(args.store, saved);
+        describeDeploy(saved.acceptance, io);
+        io.out(`Saved to ${dir}. Run \`sifur accept ${saved.acceptance.ticket.key} --run --url <test url>\` next.`);
+        return 0;
+    }
+    if (args.mode === 'upload') {
+        if (!api)
+            throw new CliError('Run `sifur login` first.');
+        const dir = await findTicketDir(args.store, args.ref);
+        if (!dir)
+            throw new CliError(`Nothing downloaded for ${args.ref} in ${args.store}.`);
+        const saved = await loadCases(dir);
+        if (saved.api !== api.base)
+            throw new CliError(`${args.ref} was downloaded from ${saved.api}, but you're signed in to ${api.base}.`);
+        const results = await loadResults(dir);
+        return finish(api, saved, results, dir, args, io);
+    }
+    if (!args.url)
+        throw new CliError('--url <test url> is required: the test server the branch is deployed to.');
+    const baseUrl = parseBaseUrl(args.url);
+    const parsedUrl = new URL(baseUrl);
+    if (parsedUrl.pathname !== '/' || parsedUrl.search || parsedUrl.hash) {
+        io.out(`Note: the cases' paths are opened under ${baseUrl}, so the root of the site (${parsedUrl.origin}/) is usually what's wanted.`);
+    }
+    let saved;
+    let dir;
+    if (args.mode === 'run') {
+        const found = await findTicketDir(args.store, args.ref);
+        if (!found)
+            throw new CliError(`Nothing downloaded for ${args.ref}. Run with --download first.`);
+        dir = found;
+        saved = await loadCases(dir);
+    }
+    else {
+        if (!api)
+            throw new CliError('Run `sifur login` first.');
+        saved = await download(api, args.ref);
+        dir = await saveCases(args.store, saved);
+    }
+    describeDeploy(saved.acceptance, io);
+    const { workdirs, chosen } = defaultWorkdirs(saved.acceptance.cases, args.workdirs ?? {}, gitTopLevel(args.cwd));
+    if (chosen)
+        io.out(`Running ${chosen.repository}'s automated cases in ${chosen.dir} (the checkout you're in). Use --workdir ${chosen.repository}=<dir> for another.`);
+    io.out(`Results and screenshots are kept in ${dir} until they're uploaded.`);
+    io.out();
+    const results = await runCases(saved.acceptance, { baseUrl, outDir: join(dir, 'screenshots'), headed: args.headed, workdirs }, deps);
+    const resultsPath = await saveResults(dir, results);
+    if (args.mode === 'run') {
+        const overall = printSummary(io, results.results);
+        io.out(`Saved to ${resultsPath}. Run \`sifur accept ${saved.acceptance.ticket.key} --upload\` to send them.`);
+        return overall === 'passed' ? 0 : 1;
+    }
+    return finish(api, saved, results, dir, args, io);
+}
+/** Uploads the results; once Sifur has them, nothing kept for the ticket is needed any more. */
+async function finish(api, saved, results, dir, args, io) {
+    let response;
+    try {
+        response = await upload(api, saved, results, io);
+    }
+    catch (error) {
+        io.out(`The results are kept in ${dir}; send them later with \`sifur accept ${saved.acceptance.ticket.key} --upload\`.`);
+        throw error;
+    }
+    await removeTicketFiles(args.store, dir);
+    io.out();
+    const overall = printSummary(io, results.results);
+    if (response?.run)
+        io.out(`Recorded as run ${response.run.runNumber}: ${response.run.result}.`);
+    if (response?.state)
+        io.out(`The ticket is now in ${response.state.replaceAll('_', ' ')}.`);
+    const link = ticketLink(args.consoleOrigin, saved.acceptance.ticket.uuid);
+    if (link)
+        io.out(link);
+    io.out(`Cleaned up: removed the cases, results and screenshots kept in ${dir}.`);
+    return overall === 'passed' ? 0 : 1;
+}
+export function parseBaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!['http:', 'https:'].includes(parsed.protocol))
+            throw new Error();
+        return parsed.toString();
+    }
+    catch {
+        throw new CliError(`--url ${url} isn't an http(s) URL.`);
+    }
+}