@sifurai/cli 0.1.0 → 0.1.2

package/README.md

@@ -16,19 +16,22 @@ the results and screenshots go to Sifur.
 
 ## Install
 
-Nothing to install up front:
+Install it once to get the `sifur` command:
 
 ```sh
-npx @sifurai/cli login
+npm install -g @sifurai/cli
+sifur --version
 ```
 
-Or install it globally to get a `sifur` command:
+Update it with:
 
 ```sh
-npm install -g @sifurai/cli
-sifur login
+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
@@ -50,6 +53,36 @@ To sign out (and revoke the session):
 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
@@ -66,21 +99,59 @@ sifur accept AZA-12 --url https://test.example.internal
    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 when you pass `--workdir <repository>=<dir>` (repeat it
-   for each repository); otherwise asks you for the result.
+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
 ```
 
-Every case passed: the ticket moves on to approval. Any failed or blocked: it goes back to be fixed.
+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.
 
-Screenshots and results are kept in `./.sifur/AZA-12/` (add `.sifur/` to your `.gitignore`). If the
-upload fails, send them again with `sifur accept AZA-12 --upload`.
+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
 
@@ -100,16 +171,26 @@ sifur accept AZA-12 --run --url https://test.example.internal
 sifur accept AZA-12 --upload
 ```
 
-`--download` saves the cases in `./.sifur/AZA-12/`, `--run` runs them from there and saves the
-results next to them, and `--upload` sends them. Run all three from the same directory.
+`--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 case can use a placeholder such as `{{ADMIN_PASSWORD}}` for a value it types, like a test
-account's password. The CLI takes it from the environment variable `SIFUR_SECRET_ADMIN_PASSWORD`
-or, when that isn't set, asks you for it without echoing. Secrets stay on your machine: they are
-never written to `.sifur/`, never sent to Sifur, and are replaced with `[secret]` in any error
-message.
+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
@@ -121,9 +202,23 @@ SIFUR_SECRET_ADMIN_PASSWORD='…' sifur accept AZA-12 --url https://test.example
 |---|---|
 | `--url <url>` | Your test server, where the ticket's branch is deployed |
 | `--headed` | Show the browser while the cases run |
-| `--workdir <repository>=<dir>` | Run that repository's automated cases in `<dir>`; repeatable |
+| `--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 |
-| `--api <url>` | Sifur's API, for `login` (default `https://api.sifur.ai`, or `SIFUR_API_URL`) |
+| `--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
 

package/dist/accept.js

@@ -2,20 +2,22 @@ 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 { runAutomated } from './automated.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, redact, secretNames } from './secrets.js';
-import { findTicketDir, loadCases, loadResults, saveCases, saveResults } from './store.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 };
+        return { api: api.base, organizationUuid: organization.uuid, acceptance: { ...acceptance, files: acceptance.files ?? [] } };
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 409) {
@@ -68,6 +70,9 @@ function judgeWith(io) {
         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];
@@ -81,6 +86,46 @@ function summarize(status, steps, notes) {
         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;
@@ -89,8 +134,14 @@ export async function runCases(acceptance, options, deps) {
         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(secretNames(scripted), io, deps.env);
+    const secrets = await collectSecrets(secretUses(scripted), io, deps.env);
+    const runToken = newRunToken();
     let browser = null;
     const results = [];
     try {
@@ -100,15 +151,26 @@ export async function runCases(acceptance, options, deps) {
             const notes = [];
             let steps = [];
             let output;
-            if (testCase.check === 'ui' || testCase.check === 'both') {
+            const withoutLogin = secretUses([testCase])
+                .map((use) => use.name)
+                .filter((name) => secrets[name] === undefined);
+            if ((testCase.check === 'ui' || testCase.check === 'both') && withoutLogin.length > 0) {
+                const note = `Not run: no ${withoutLogin.join(' or ')} was given.`;
+                io.out(`  skipped: ${note}`);
+                statuses.push('skipped');
+                notes.push(note);
+            }
+            else 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}` : ''}`);
@@ -127,9 +189,24 @@ export async function runCases(acceptance, options, deps) {
                 const cwd = workdirFor(testCase, workdirs);
                 let run;
                 if (testCase.automatedTestRef && cwd) {
-                    io.out(`  $ ${testCase.automatedTestRef}   (in ${cwd})`);
-                    run = await runAutomated(testCase.automatedTestRef, resolve(cwd), { echo: deps.echo });
-                    run = { ...run, note: redact(run.note, secrets), output: redact(run.output ?? '', secrets) };
+                    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
@@ -159,6 +236,12 @@ export async function runCases(acceptance, options, deps) {
     }
     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 };
 }
@@ -210,7 +293,7 @@ export function printSummary(io, results) {
     for (const result of results)
         io.out(`  ${result.status.padEnd(7)}  ${result.id}`);
     const overall = outcome(results);
-    const counts = ['passed', 'failed', 'blocked']
+    const counts = ['passed', 'failed', 'blocked', 'skipped']
         .map((status) => [status, results.filter((r) => r.status === status).length])
         .filter(([, count]) => count > 0)
         .map(([status, count]) => `${count} ${status}`);
@@ -223,11 +306,19 @@ export function ticketLink(consoleOrigin, ticketUuid) {
 /** 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.cwd, saved);
+        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;
@@ -235,22 +326,26 @@ export async function accept(api, args, deps) {
     if (args.mode === 'upload') {
         if (!api)
             throw new CliError('Run `sifur login` first.');
-        const dir = await findTicketDir(args.cwd, args.ref);
+        const dir = await findTicketDir(args.store, args.ref);
         if (!dir)
-            throw new CliError(`Nothing downloaded for ${args.ref} in ${join(args.cwd, '.sifur')}.`);
+            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, args, io);
+        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.cwd, args.ref);
+        const found = await findTicketDir(args.store, args.ref);
         if (!found)
             throw new CliError(`Nothing downloaded for ${args.ref}. Run with --download first.`);
         dir = found;
@@ -260,26 +355,34 @@ export async function accept(api, args, deps) {
         if (!api)
             throw new CliError('Run `sifur login` first.');
         saved = await download(api, args.ref);
-        dir = await saveCases(args.cwd, saved);
+        dir = await saveCases(args.store, saved);
     }
     describeDeploy(saved.acceptance, io);
-    const results = await runCases(saved.acceptance, { baseUrl, outDir: join(dir, 'screenshots'), headed: args.headed, workdirs: args.workdirs }, deps);
+    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 {
-        return await finish(api, saved, results, args, io);
+        response = await upload(api, saved, results, io);
     }
     catch (error) {
-        io.out(`The results are saved in ${resultsPath}; send them later with \`sifur accept ${saved.acceptance.ticket.key} --upload\`.`);
+        io.out(`The results are kept in ${dir}; send them later with \`sifur accept ${saved.acceptance.ticket.key} --upload\`.`);
         throw error;
     }
-}
-async function finish(api, saved, results, args, io) {
-    const response = await upload(api, saved, results, io);
+    await removeTicketFiles(args.store, dir);
     io.out();
     const overall = printSummary(io, results.results);
     if (response?.run)
@@ -289,6 +392,7 @@ async function finish(api, saved, results, args, io) {
     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) {

package/dist/api.js

@@ -3,11 +3,19 @@ export class ApiError extends Error {
     status;
     code;
     retryAfterSeconds;
-    constructor(message, status, code = null, retryAfterSeconds = null) {
+    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';
     }
 }
@@ -18,6 +26,19 @@ export class CliError extends Error {
         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(/\/+$/, '');
 }
@@ -56,23 +77,31 @@ export class Api {
             });
         }
         catch (error) {
-            const cause = error.cause?.message;
-            throw new CliError(`Couldn't reach Sifur at ${this.base}${cause ? ` (${cause})` : ''}.`);
+            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 message = json?.message?.messages?.[0] ?? `Sifur answered ${response.status} ${response.statusText}`.trim();
+            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(message, response.status, code, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : null);
+            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);
     }
 }