verifika 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/). The CLI flags, exit codes, configuration format (`version: 1`) and JSON output (`schemaVersion: 1`) are the public API.
 
+## [0.0.3] - 2026-10-13
+
+### Added
+
+- Live status block in `human` mode on an interactive terminal: progress and elapsed time, each running check with a spinner, its elapsed time and latest output line, and what queued checks wait on. Finished checks print above it as in line mode. Line output remains the fallback in CI, when piped, with `TERM=dumb`, and with the new `--no-live` flag or `VERIFIKA_LIVE=0`.
+- `human` output: a `verifika · <selection> · <n> checks · <j> parallel` header, aligned durations, the command and a rerun hint (`vfk -c <check>`) on failure lines, a `○ not run: build failed` marker for checks blocked by a failed dependency, and an estimate of the time saved by skipped checks from their last recorded durations.
+- In `human` mode, the first interrupt prints `stopping… (Ctrl-C again to force)`.
+- `vfk logs` on a terminal: local and relative start time (`today 01:12, 3m ago`), clickable OSC 8 log paths (opt out with `VERIFIKA_HYPERLINKS=0`), and paging through `$PAGER` or `less -R -F -X` (`--no-pager` to opt out; never with `--tail`, when piped, or in `agent` mode).
+- `vfk plan` in `human` mode colours `run` and dims skipped checks.
+- `vfk init` adds `"verify": "vfk"` and `"verify:ci": "vfk --all"` to `package.json` when they are absent, keeping its indentation, line endings, key order and trailing newline; existing scripts are never overwritten.
+- JSON (additive, `schemaVersion: 1`): `checks[].blockedBy` on blocked checks in run results, naming the dependency that did not pass; `checks[].requiredBy` in plan output on checks selected only as dependencies.
+
+### Changed
+
+- **`npm run verify` is now selective.** The recommended scripts are `"verify": "vfk"` for local work and `"verify:ci": "vfk --all"` for the full gate; use `npm run verify:ci` (or `vfk --all`) in CI and before delivery. The README setup prompt, docs and agent skill say so, and the prompt only replaces an existing `verify` script when the configured checks cover what it ran. If you followed the 0.0.2 setup, your `"verify": "vfk --all"` script still runs the full gate; to adopt the split, rename it to `verify:ci` and add `"verify": "vfk"` by hand (`vfk init` only adds scripts when it creates the config).
+- A check pulled in by several dependents now names all of them (`required by test, pack`), in plan output and reasons.
+- Failure previews leave out package-manager script banners (`> app@1.0.0 lint`, `> eslint .`, yarn's `$ …`).
+
+### Fixed
+
+- ESLint failure previews showed only the `✖ N problems` summary; they now keep each `line:col  error` line under its file heading, plus the summary.
+- A failed check whose preview was hidden by the three-preview limit looked as if nothing was found; its line now says `(preview omitted: vfk logs <check>)`, in `human` and `agent` output.
+
 ## [0.0.2] - 2026-10-12
 
 ### Changed
@@ -37,5 +60,6 @@ First public release.
 - A process that deliberately detaches from the check (on Linux and macOS: leaves the process group, for example via `setsid`; on Windows: breaks away from the job with an exited intermediate parent) is not tracked unless it keeps the check's output open, in which case the check is reported as `error`.
 - On Windows, confirming cleanup queries the process table with PowerShell after each check, which costs roughly 0.5–3 s per check.
 
+[0.0.3]: https://github.com/alexportelli12/verifika/compare/v0.0.2...v0.0.3
 [0.0.2]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.2
 [0.0.1]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.1

package/README.md

@@ -62,7 +62,14 @@ Set up Verifika (https://github.com/alexportelli12/verifika) in this repository.
      runs on every change.
    - Add `dependsOn` where one check needs another's output (for example e2e after build).
    - Keep concurrency at 1 unless the checks clearly share no build outputs.
-   - If package.json has no "verify" script, add "verify": "vfk --all".
+   - Make sure package.json has two scripts: "verify": "vfk" (selective, for local
+     work) and "verify:ci": "vfk --all" (the full gate). `vfk init` adds them when
+     they are missing. If a "verify" or "verify:ci" script already exists, replace
+     it only when the configured checks cover everything it ran; otherwise leave it
+     and report the conflict. This is the one exception to the rule below about
+     existing scripts.
+   - If the CI workflow runs the gate some other way, report that switching it to
+     `npm run verify:ci` is recommended. Do not edit the workflow.
    Reference: https://github.com/alexportelli12/verifika/blob/main/docs/configuration.md
 3. Validate the config:
    - Run `npx vfk --all`. If a check fails, decide whether the config is wrong (fix it)
@@ -74,9 +81,11 @@ Set up Verifika (https://github.com/alexportelli12/verifika) in this repository.
    agent's skills directory (see
    https://github.com/alexportelli12/verifika/blob/main/docs/agents.md).
 
-Do not change source code or existing scripts to make checks pass, and do not commit.
+Do not change source code or existing scripts to make checks pass (except "verify"
+and "verify:ci", as step 2 describes), and do not commit.
 Finish with: the checks you configured and why, the --all result, the expected
-selection for those two edits, and any existing failures you found.
+selection for those two edits, the scripts you added, replaced or left (with any
+conflicts), any CI recommendation, and any existing failures you found.
 ```
 
 Review the config it writes before committing it: the commands in it run on every verification.
@@ -85,7 +94,8 @@ Review the config it writes before committing it: the commands in it run on ever
 
 ```sh
 npm install --save-dev verifika
-npx vfk init     # creates verifika.config.json from your package.json scripts
+npx vfk init     # creates verifika.config.json from your package.json scripts,
+                 # and adds "verify" / "verify:ci" scripts if they are missing
 ```
 
 `init` only maps conventional script names (`lint`, `test`, `build`, ...) and leaves every check unfiltered, so open the file and give each check `paths`:
@@ -115,12 +125,14 @@ npx vfk          # run them
 npx vfk --all    # run everything (do this before you push)
 ```
 
-Add a script so everyone runs the same full gate:
+`init` adds two scripts unless package.json already has scripts with those names (it never overwrites them):
 
 ```json
-{ "scripts": { "verify": "vfk --all" } }
+{ "scripts": { "verify": "vfk", "verify:ci": "vfk --all" } }
 ```
 
+`npm run verify` runs the checks your changes affect, for quick feedback while you work. `npm run verify:ci` runs every check: it is the full gate, so use it in CI and before you push or open a pull request.
+
 Run logs go to `.verifika/`, which ignores itself in git, so you do not need to edit `.gitignore`. To install globally instead, run `npm install --global verifika`.
 
 ## How checks are selected
@@ -141,12 +153,14 @@ A check without `paths` runs whenever any file changed; `"always": true` runs it
 
 The default is `human` on an interactive terminal and `agent` otherwise. Override with `--mode` or `VERIFIKA_MODE`.
 
-| Mode    | Success                       | Failure                                             |
-| ------- | ----------------------------- | --------------------------------------------------- |
-| `human` | Live progress, summary        | Failing checks, previews, logs hint                 |
-| `agent` | One line: `PASS 4/4 (4.3s) …` | One line per problem, bounded preview, logs command |
-| `json`  | Versioned result document     | Same document, `"status": "failed"`                 |
-| `quiet` | Nothing                       | One line on stderr                                  |
+| Mode    | Success                       | Failure                                                         |
+| ------- | ----------------------------- | --------------------------------------------------------------- |
+| `human` | Live status block, summary    | Failing checks with command and rerun hint, previews, logs hint |
+| `agent` | One line: `PASS 4/4 (4.3s) …` | One line per problem, bounded preview, logs command             |
+| `json`  | Versioned result document     | Same document, `"status": "failed"`                             |
+| `quiet` | Nothing                       | One line on stderr                                              |
+
+In `human` mode on an interactive terminal, a live status block shows progress, each running check with its latest output line, and what the queued checks wait on; finished checks print above it. In CI, when piped, with `TERM=dumb`, or with `--no-live` / `VERIFIKA_LIVE=0`, `human` mode prints plain lines instead (one per check start and end, plus a note every 30 seconds for long checks), which read well in logs. `NO_COLOR` turns colour off in both.
 
 Exit codes: `0` passed (or nothing to verify), `1` verification failed, `2` usage or configuration error, `128+n` interrupted by a signal (`130` SIGINT, `143` SIGTERM).
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { ExitCode } from "./errors.js";
 import { main } from "./main.js";
+import { systemTerminal } from "./reporters/live.js";
 const write = (stream) => (text) => {
     stream.write(text);
 };
@@ -17,6 +18,9 @@ main(process.argv.slice(2), {
     isTTY: Boolean(process.stdout.isTTY),
     out: write(process.stdout),
     err: write(process.stderr),
+    ...(process.stdout.isTTY
+        ? { terminal: systemTerminal(write(process.stdout), write(process.stderr), process.stdout) }
+        : {}),
 }).then((code) => {
     process.exitCode = code;
 }, (error) => {

package/dist/init.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { CONFIG_FILE } from "./config.js";
 import { VerifikaError } from "./errors.js";
@@ -14,6 +14,44 @@ const CANDIDATES = [
     ["build", ["build"]],
 ];
 const NPM_PLACEHOLDER_TEST = /no test specified/;
+/** npm scripts `vfk init` adds: selective verification while working, the full gate for CI. */
+export const VERIFY_SCRIPTS = {
+    verify: "vfk",
+    "verify:ci": "vfk --all",
+};
+/**
+ * Adds the `verify` and `verify:ci` scripts to package.json where they are
+ * absent; existing scripts are never overwritten. Keeps the file's indentation,
+ * line endings, key order and trailing newline.
+ */
+export async function addVerifyScripts(root) {
+    const file = path.join(root, "package.json");
+    const raw = await readFile(file, "utf8");
+    const bom = raw.startsWith("\uFEFF") ? "\uFEFF" : "";
+    const text = raw.slice(bom.length);
+    const manifest = JSON.parse(text);
+    const scripts = (manifest.scripts ??= {});
+    const result = { added: [], kept: [] };
+    for (const [name, command] of Object.entries(VERIFY_SCRIPTS)) {
+        const existing = scripts[name];
+        if (existing === undefined) {
+            scripts[name] = command;
+            result.added.push(name);
+        }
+        else {
+            result.kept.push({ name, command: existing });
+        }
+    }
+    if (result.added.length === 0)
+        return result;
+    // A one-line manifest stays on one line.
+    const indent = text.trim().includes("\n") ? (/^[ \t]+(?=")/m.exec(text)?.[0] ?? "  ") : "";
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const trailing = /\r?\n$/.test(text) ? newline : "";
+    const json = JSON.stringify(manifest, null, indent).replace(/\n/g, newline);
+    await writeFile(file, `${bom}${json}${trailing}`);
+    return result;
+}
 /**
  * Writes a starter verifika.config.json from the package.json scripts in `root`.
  * Checks are created without path filters (they run on any change); narrowing

package/dist/logs.js

@@ -2,7 +2,9 @@ import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
 import { open } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { VerifikaError } from "./errors.js";
+import { withPager } from "./pager.js";
 import { duration, isFailureStatus, selectionLabel } from "./reporters/reporter.js";
 import { plain, symbol } from "./reporters/human.js";
 import { stripAnsi } from "./preview.js";
@@ -15,7 +17,7 @@ import { readRun } from "./runs.js";
 export async function showLogs(request, output) {
     const run = await readRun(request.root, request.runId);
     if (request.checks.length === 0 && !request.failed) {
-        output.out(renderRunSummary(run));
+        output.out(renderRunSummary(run, request.display));
         return 0;
     }
     let targets;
@@ -35,20 +37,29 @@ export async function showLogs(request, output) {
         targets = request.checks.map((name) => byName.get(name));
     }
     const headers = request.failed || targets.length > 1;
-    for (const check of targets) {
-        if (headers)
-            output.out(`── ${check.name}: ${check.status} (${check.reason}) ──\n`);
-        if (!check.log) {
-            output.out(`${check.name} has no log: ${check.status} (${check.reason})\n`);
-            continue;
+    const print = async (write) => {
+        for (const check of targets) {
+            if (headers)
+                await write(`── ${check.name}: ${check.status} (${check.reason}) ──\n`);
+            if (!check.log) {
+                await write(`${check.name} has no log: ${check.status} (${check.reason})\n`);
+                continue;
+            }
+            await printLog(path.join(request.root, check.log), request, write);
         }
-        await printLog(path.join(request.root, check.log), request, output);
+    };
+    if (request.pager !== undefined && request.tail === undefined) {
+        await withPager(request.pager, request.env ?? process.env, print);
+    }
+    else {
+        await print((text) => output.out(text));
     }
     return 0;
 }
-export function renderRunSummary(run) {
+export function renderRunSummary(run, display) {
+    const started = display ? describeTime(new Date(run.startedAt), display.now) : run.startedAt;
     const lines = [
-        `Run ${run.runId} · ${run.status} · ${duration(run.durationMs)} · ${run.startedAt}`,
+        `Run ${run.runId} · ${run.status} · ${duration(run.durationMs)} · ${started}`,
         selectionLabel(run.selection, run.summary.skipped),
     ];
     if (run.status === "running")
@@ -60,8 +71,9 @@ export function renderRunSummary(run) {
         parts.push(duration(check.durationMs).padStart(6));
         if (check.status !== "passed")
             parts.push(check.reason);
-        if (check.log)
-            parts.push(check.log);
+        if (check.log) {
+            parts.push(display?.hyperlinks ? hyperlink(check.log, path.join(run.root, check.log)) : check.log);
+        }
         lines.push(parts.join("  "));
     }
     // One line for everything not selected; large configs would otherwise list dozens.
@@ -72,12 +84,41 @@ export function renderRunSummary(run) {
     }
     return `${lines.join("\n")}\n`;
 }
-async function printLog(file, { tail, stripAnsi: strip = false }, output) {
+/**
+ * `today 01:12, 3m ago`; `yesterday 23:40, 2h ago`; otherwise the local date.
+ * Local time, because that is what the user's clock shows.
+ */
+export function describeTime(time, now) {
+    const pad = (value) => String(value).padStart(2, "0");
+    const clock = `${pad(time.getHours())}:${pad(time.getMinutes())}`;
+    const day = (date) => new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+    const days = Math.round((day(now) - day(time)) / 86_400_000);
+    const date = days === 0
+        ? "today"
+        : days === 1
+            ? "yesterday"
+            : `${time.getFullYear()}-${pad(time.getMonth() + 1)}-${pad(time.getDate())}`;
+    return `${date} ${clock}, ${ago(now.getTime() - time.getTime())}`;
+}
+function ago(ms) {
+    if (ms < 60_000)
+        return ms < 1_000 ? "just now" : `${Math.floor(ms / 1000)}s ago`;
+    if (ms < 3_600_000)
+        return `${Math.floor(ms / 60_000)}m ago`;
+    if (ms < 86_400_000)
+        return `${Math.floor(ms / 3_600_000)}h ago`;
+    return `${Math.floor(ms / 86_400_000)}d ago`;
+}
+/** An OSC 8 terminal hyperlink to a local file; terminals without support show just the text. */
+export function hyperlink(text, file) {
+    return `\u001b]8;;${pathToFileURL(file).href}\u001b\\${text}\u001b]8;;\u001b\\`;
+}
+async function printLog(file, { tail, stripAnsi: strip = false }, write) {
     try {
         if (tail !== undefined) {
             const text = await readTail(file, tail);
             const shown = strip ? stripAnsi(text) : text;
-            output.out(shown.endsWith("\n") || shown === "" ? shown : `${shown}\n`);
+            await write(shown.endsWith("\n") || shown === "" ? shown : `${shown}\n`);
             return;
         }
         if (strip) {
@@ -87,16 +128,16 @@ async function printLog(file, { tail, stripAnsi: strip = false }, output) {
                 crlfDelay: Infinity,
             });
             for await (const line of lines)
-                output.out(`${stripAnsi(line)}\n`);
+                await write(`${stripAnsi(line)}\n`);
             return;
         }
         let last = "";
         for await (const chunk of createReadStream(file, { encoding: "utf8" })) {
-            output.out(chunk);
+            await write(chunk);
             last = chunk;
         }
         if (last !== "" && !last.endsWith("\n"))
-            output.out("\n");
+            await write("\n");
     }
     catch (error) {
         throw new VerifikaError(`cannot read log ${file}: ${error.message}`);

package/dist/main.js

@@ -3,17 +3,21 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { findConfigFile, loadConfig } from "./config.js";
 import { ExitCode, VerifikaError } from "./errors.js";
-import { initConfig } from "./init.js";
+import { addVerifyScripts, initConfig, VERIFY_SCRIPTS } from "./init.js";
 import { showLogs } from "./logs.js";
+import { pagerAvailable, pagerCommand } from "./pager.js";
 import { plan } from "./planner.js";
 import { killAllNow } from "./process.js";
 import { agentReporter } from "./reporters/agent.js";
+import { detectCi } from "./ci.js";
 import { colors, humanReporter, plain } from "./reporters/human.js";
 import { jsonReporter } from "./reporters/json.js";
+import { liveReporter } from "./reporters/live.js";
 import { planJson, renderPlan } from "./reporters/plan.js";
 import { quietReporter } from "./reporters/quiet.js";
 import { OUTPUT_MODES } from "./reporters/reporter.js";
 import { runVerification } from "./runner.js";
+import { estimateSkipped } from "./runs.js";
 const COMMANDS = ["run", "plan", "logs", "init", "help"];
 const DEFAULT_PREVIEW_LINES = 10;
 export const HELP = `vfk - run the checks your changes need, with minimal output
@@ -24,6 +28,7 @@ Usage:
   vfk plan [options]              Show which checks would run and why
   vfk logs [check...]             Show logs from the latest run
   vfk init [--force]              Create verifika.config.json from package.json scripts
+                                  and add "verify"/"verify:ci" scripts if absent
 
 Selection (run, plan):
       --all                       Run every check
@@ -38,11 +43,15 @@ Execution (run):
       --fail-fast                 Stop everything after the first failure
       --no-fail-fast              Run every selected check even after a failure
       --preview <lines>           Failure preview lines per check (default ${DEFAULT_PREVIEW_LINES}, 0 = off)
+      --no-live                   Print progress line by line instead of a live
+                                  status block (or set VERIFIKA_LIVE=0)
 
 Logs:
       --failed                    Print logs of every failed check
       --tail <lines>              Print only the last lines of each log
       --run <id>                  Read a specific run instead of the latest
+      --no-pager                  Print logs directly instead of through $PAGER
+                                  (paging only happens on a terminal)
 
 Output:
       --mode <mode>               human | agent | json | quiet
@@ -77,6 +86,7 @@ const OPTIONS = {
         "fail-fast": { type: "boolean" },
         "no-fail-fast": { type: "boolean" },
         preview: { type: "string" },
+        "no-live": { type: "boolean" },
     },
     plan: { ...SHARED, ...SELECTION },
     logs: {
@@ -84,6 +94,7 @@ const OPTIONS = {
         failed: { type: "boolean" },
         tail: { type: "string" },
         run: { type: "string" },
+        "no-pager": { type: "boolean" },
     },
     init: { ...SHARED, force: { type: "boolean" } },
     help: SHARED,
@@ -123,6 +134,9 @@ export async function main(argv, io) {
                 ...(values.run !== undefined ? { runId: values.run } : {}),
                 ...(values.tail !== undefined ? { tail: integerOption(values.tail, "--tail", 1) } : {}),
                 stripAnsi: !io.isTTY,
+                env: io.env,
+                // Agents in a pseudo-terminal must never get a pager waiting for a keypress.
+                ...(mode === "human" ? logsDisplay(io, values["no-pager"] === true) : {}),
             }, io);
         }
         const request = {
@@ -146,8 +160,10 @@ export async function main(argv, io) {
         if (command === "plan") {
             if (mode === "json")
                 io.out(planJson(selection, config));
-            else if (mode !== "quiet")
-                io.out(renderPlan(selection, mode === "human" ? 50 : 20));
+            else if (mode === "human")
+                io.out(renderPlan(selection, 50, humanStyle(io)));
+            else if (mode === "agent")
+                io.out(renderPlan(selection, 20));
             return ExitCode.Passed;
         }
         if (values["fail-fast"] && values["no-fail-fast"]) {
@@ -160,18 +176,31 @@ export async function main(argv, io) {
         const previewLines = values.preview !== undefined
             ? integerOption(values.preview, "--preview", 0)
             : DEFAULT_PREVIEW_LINES;
-        const result = await withInterruptHandling((signal) => runVerification({
-            config,
-            selection,
-            concurrency,
-            failFast,
-            previewLines,
-            signal,
-            reporter: reporterFor(mode, io),
-            version: version(),
-            env: io.env,
-        }));
-        return result.exitCode;
+        const skipped = selection.checks.filter((check) => !check.selected).map((check) => check.name);
+        const reporter = reporterFor(mode, io, {
+            live: values["no-live"] !== true,
+            // Only people see the estimate; other modes skip reading earlier runs.
+            ...(mode === "human" && skipped.length > 0
+                ? { skipEstimate: await estimateSkipped(config.root, skipped) }
+                : {}),
+        });
+        try {
+            const result = await withInterruptHandling(() => reporter.onInterrupt?.(), (signal) => runVerification({
+                config,
+                selection,
+                concurrency,
+                failFast,
+                previewLines,
+                signal,
+                reporter,
+                version: version(),
+                env: io.env,
+            }));
+            return result.exitCode;
+        }
+        finally {
+            reporter.dispose?.();
+        }
     }
     catch (error) {
         if (error instanceof VerifikaError) {
@@ -191,6 +220,18 @@ async function runInit(io, values) {
     const root = values.config ? path.dirname(path.resolve(io.cwd, values.config)) : io.cwd;
     const { file, checks } = await initConfig(root, Boolean(values.force));
     io.out(`Created ${path.relative(io.cwd, file) || file} with checks: ${checks.join(", ")}\n`);
+    const scripts = await addVerifyScripts(root);
+    if (scripts.added.length > 0) {
+        const added = scripts.added.map((name) => `"${name}": "${VERIFY_SCRIPTS[name]}"`);
+        io.out(`Added package.json scripts: ${added.join(", ")}\n`);
+    }
+    for (const { name, command } of scripts.kept) {
+        if (command === VERIFY_SCRIPTS[name]) {
+            io.out(`package.json already has "${name}": "${command}"\n`);
+            continue;
+        }
+        io.out(`Kept the existing "${name}" script (${command}); to use Verifika, change it to "${VERIFY_SCRIPTS[name]}" once the checks cover everything it runs\n`);
+    }
     io.out('Review the commands, add "paths" to checks that only some files affect, format the file if your repository checks formatting, then run: vfk plan\n');
     return ExitCode.Passed;
 }
@@ -240,13 +281,22 @@ function guessMode(argv, io) {
             ? "human"
             : "agent";
 }
-function reporterFor(mode, io) {
+function reporterFor(mode, io, options) {
     switch (mode) {
         case "human": {
-            const color = io.isTTY && !io.env.NO_COLOR
-                ? true
-                : Boolean(io.env.FORCE_COLOR && io.env.FORCE_COLOR !== "0");
-            return humanReporter(io, color ? colors : plain, { heartbeat: io.isTTY });
+            const style = humanStyle(io);
+            // The live block redraws in place, so it needs a real, capable terminal that
+            // nobody is logging; everywhere else the line reporter is the fallback.
+            const live = options.live &&
+                io.terminal !== undefined &&
+                io.isTTY &&
+                !detectCi(io.env).ci &&
+                io.env.TERM !== "dumb" &&
+                !isOff(io.env.VERIFIKA_LIVE);
+            const estimate = options.skipEstimate ? { skipEstimate: options.skipEstimate } : {};
+            if (live && io.terminal)
+                return liveReporter(io.terminal, style, estimate);
+            return humanReporter(io, style, { heartbeat: io.isTTY, ...estimate });
         }
         case "agent":
             return agentReporter(io);
@@ -256,6 +306,28 @@ function reporterFor(mode, io) {
             return quietReporter(io);
     }
 }
+/**
+ * On a terminal, `vfk logs` speaks to a person: local relative times, clickable
+ * log paths (not in CI, whose log viewers show escape codes), and a pager.
+ */
+function logsDisplay(io, noPager) {
+    if (!io.isTTY)
+        return {};
+    const capable = !detectCi(io.env).ci && io.env.TERM !== "dumb";
+    const pager = pagerCommand(io.env);
+    return {
+        display: { now: new Date(), hyperlinks: capable && !isOff(io.env.VERIFIKA_HYPERLINKS) },
+        ...(noPager || !pagerAvailable(pager, io.env) ? {} : { pager }),
+    };
+}
+/** Colour on a terminal unless NO_COLOR is set; FORCE_COLOR enables it elsewhere. */
+function humanStyle(io) {
+    const color = io.isTTY && !io.env.NO_COLOR ? true : Boolean(io.env.FORCE_COLOR && io.env.FORCE_COLOR !== "0");
+    return color ? colors : plain;
+}
+function isOff(value) {
+    return value !== undefined && ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
 function reportError(error, mode, io) {
     if (mode === "json") {
         const document = {
@@ -273,14 +345,16 @@ function reportError(error, mode, io) {
  * First SIGINT/SIGTERM/SIGHUP stops scheduling and terminates running checks
  * gracefully; a second one kills them immediately.
  */
-async function withInterruptHandling(operation) {
+async function withInterruptHandling(onFirstSignal, operation) {
     const controller = new AbortController();
     const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
     const onSignal = (signal) => {
         if (controller.signal.aborted)
             killAllNow();
-        else
+        else {
+            onFirstSignal();
             controller.abort(signal);
+        }
     };
     for (const signal of signals)
         process.on(signal, onSignal);

package/dist/pager.js

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+/** Used when `PAGER` is unset: quit if one screen, keep colours, leave output on screen. */
+export const DEFAULT_PAGER = "less -R -F -X";
+/** The pager command line from `PAGER`, or the default. */
+export function pagerCommand(env) {
+    const configured = env.PAGER?.trim();
+    return configured ? configured : DEFAULT_PAGER;
+}
+/**
+ * Whether the pager's program exists, so a missing one (e.g. `less` on Windows)
+ * falls back to plain output instead of a shell error. Checks the first word of
+ * the command (which may be quoted): a path, or a name looked up on PATH (with
+ * PATHEXT on Windows).
+ */
+export function pagerAvailable(command, env) {
+    const match = /^\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(command);
+    const program = match?.[1] ?? match?.[2] ?? match?.[3] ?? "";
+    if (program === "")
+        return false;
+    const isWindows = process.platform === "win32";
+    const extensions = isWindows
+        ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)]
+        : [""];
+    const candidates = program.includes("/") || program.includes("\\")
+        ? [program]
+        : (env.PATH ?? env.Path ?? "")
+            .split(path.delimiter)
+            .filter(Boolean)
+            .map((directory) => path.join(directory, program));
+    return candidates.some((candidate) => extensions.some((extension) => {
+        try {
+            accessSync(candidate + extension, isWindows ? constants.F_OK : constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/**
+ * Pipes everything `produce` writes into the pager, which takes over the
+ * terminal until the user quits it. Quitting early is not an error: further
+ * output is dropped. Ctrl-C belongs to the pager meanwhile, so Verifika ignores
+ * SIGINT until the pager exits (as git does).
+ */
+export async function withPager(command, env, produce) {
+    // Like git: colours and quit-if-one-screen for a plain `less`, unless the user configured LESS.
+    const child = spawn(command, {
+        shell: true,
+        stdio: ["pipe", "inherit", "inherit"],
+        env: { LESS: "FRX", ...env },
+    });
+    const ignoreInterrupt = () => undefined;
+    process.on("SIGINT", ignoreInterrupt);
+    const exited = new Promise((resolve) => {
+        child.once("close", () => resolve());
+        child.once("error", () => resolve());
+    });
+    let closed = false;
+    const stdin = child.stdin;
+    stdin.on("error", () => {
+        // EPIPE: the user quit the pager before reading everything.
+        closed = true;
+    });
+    child.once("close", () => {
+        closed = true;
+    });
+    try {
+        await produce((text) => {
+            if (closed)
+                return;
+            if (!stdin.write(text)) {
+                return new Promise((resolve) => {
+                    const done = () => {
+                        stdin.off("drain", done);
+                        child.off("close", done);
+                        resolve();
+                    };
+                    stdin.once("drain", done);
+                    child.once("close", done);
+                });
+            }
+        });
+    }
+    finally {
+        stdin.end();
+        await exited;
+        process.off("SIGINT", ignoreInterrupt);
+    }
+}