verifika 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 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
+
+- `vfk` is now the advertised command: `--help`, run hints (`Run: vfk logs <check>`), error hints, the README, the docs and the agent skill use it. `verifika` keeps working and is identical.
+
+### Added
+
+- README: a copy-paste prompt that has a coding agent install Verifika, write and validate a config, and install the skill.
+
 ## [0.0.1] - 2026-10-12
 
 First public release.
@@ -27,4 +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

@@ -4,56 +4,101 @@
 [![Release](https://img.shields.io/github/v/release/alexportelli12/verifika)](https://github.com/alexportelli12/verifika/releases/latest)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Run the checks your changes need, concurrently, with minimal output.
+**Run only the checks your change needs. Get one line back when they pass.**
 
-Verifika is a small CLI for repository verification. You declare your checks (lint, typecheck, tests, build, ...) in `verifika.config.json`. Locally, Verifika runs only the checks affected by your changes; in CI it runs everything. Successful runs print one line, failures print exactly what failed and how to see the full logs. It works the same for developers, CI pipelines and AI coding agents (Claude Code, Codex, OpenCode, and others).
+Every repository has a verification gate: format, lint, typecheck, tests, build. Using it well is harder than it looks:
+
+- **Running everything is slow.** A one-line fix waits minutes for checks it cannot affect, so people (and agents) skip the gate or batch changes until the end.
+- **Picking checks by hand is unreliable.** It is easy to forget the one that breaks, and "it passed" stops meaning much.
+- **Failures are buried in noise.** A test runner can print tens of thousands of lines to report one failed assertion. A coding agent pays for every line in tokens and context, and often never reaches the line that matters.
+
+Verifika fixes this with one config file and one command. You list your checks in `verifika.config.json`, with the files each one covers. Then `vfk` runs only the checks your changes affect, CI runs all of them, and the output says exactly what failed:
 
 ```text
-$ verifika
+$ vfk
 PASS 3/3 (4.1s) selective: 2 files changed since HEAD (a1b2c3d); 2 skipped
 
-$ verifika --all
+$ vfk --all
 FAIL 4/5 (12s) full run (--all)
 typecheck: exit 2
   src/cart.ts(14,7): error TS2322: Type 'string' is not assignable to type 'number'.
-Run: verifika logs typecheck
+Run: vfk logs typecheck
 ```
 
-_Verifika_ is Maltese for "verification".
+## Why Verifika
 
-## Why
+- **Small output, especially for agents.** On a real Angular project, one failing test produced 94,900 bytes of output with the project's previous verify script (~23,700 tokens). Verifika reported the same failure in 369 bytes (~90 tokens): the test name, the assertion and the totals. Full logs stay on disk until you ask for them.
+- **Less waiting.** Locally, only affected checks run: in a 25-check monorepo, a typical edit ran 1–13 of them. Checks that share no build outputs can also run in parallel; on that Angular project, four at a time cut the full gate from 95.5 s to 61.7 s. [Measurements](docs/benchmarks.md).
+- **Deterministic and conservative.** Selection comes from your config, file globs, dependencies and git; no heuristics, no LLM. When the scope of a change is unclear, Verifika runs everything or fails loudly. It never quietly skips a check, and in CI it runs the full suite unless you explicitly ask for a selective run.
+- **Trustworthy results.** Timeouts, fail-fast, correct exit codes and signal handling. A check only passes once its whole process tree has exited. Tested on Linux, macOS and Windows.
+- **Built for humans and coding agents alike.** Live progress on a terminal, one line in agent sessions, JSON for scripts. It ships an [agent skill](skills/verifika/SKILL.md) for Claude Code, Codex, OpenCode and others.
+- **Small.** One JSON file, one runtime dependency, no daemon, no cache to invalidate.
 
-- **Deterministic.** Check selection comes from your config, file globs, dependencies and git. No heuristics, no LLM. When the change scope is unclear, Verifika runs everything or fails loudly; it never quietly skips a check.
-- **Token-efficient.** Agents get one line on success and a bounded failure preview on failure. Full logs stay on disk until asked for.
-- **Fast.** Selective runs skip unaffected checks, and independent checks can run in parallel once you opt in (`defaults.concurrency`). One small runtime dependency.
-- **Reliable.** Timeouts, fail-fast, process cleanup, correct exit codes and signal handling, tested on Linux, macOS and Windows.
+_Verifika_ is Maltese for "verification". The command is `vfk`, short for `verifika`; both are installed and identical.
 
-## Install
+## Get started
 
 Requires Node.js 22.13 or newer.
 
-```sh
-npm install --save-dev verifika
-```
+### With a coding agent
 
-The package installs two commands: `verifika` and its shorthand `vfk`. They are the same program, so use whichever you prefer:
+Paste this prompt into Claude Code, Codex, OpenCode or another coding agent, from your repository root. It installs Verifika, writes and validates a config for your project, and reports what it found.
 
-```sh
-npx verifika plan    # same as: npx vfk plan
-npx vfk --all        # same as: npx verifika --all
+```text
+Set up Verifika (https://github.com/alexportelli12/verifika) in this repository.
+
+1. Check that Node.js is 22.13 or newer, and install the project's dependencies if
+   they are missing. Install Verifika as a dev dependency with this repository's
+   package manager (npm install --save-dev verifika, or the pnpm/yarn equivalent).
+   It provides the `vfk` command.
+2. Run `npx vfk init` to create verifika.config.json, then refine it by reading
+   package.json, the CI workflows and the tool configs:
+   - One check per quality gate the project actually has (such as format, lint,
+     typecheck, unit tests, build). Do not invent checks for tools it does not use,
+     or add a check that another one already fully covers. Every command must be
+     non-interactive and exit on its own: no watch mode, no prompts, no dev servers.
+   - Give each check `paths` globs for the files that can affect it, so local runs
+     select only what a change needs. If unsure, leave `paths` out: the check then
+     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.
+   - 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)
+     or the project already fails that check (report it; do not fix it).
+   - Run `npx vfk plan`. Until this setup is committed, the changed package.json and
+     lockfile select every check; that is expected. Explain which checks a typical
+     source edit and a documentation-only edit would select once it is committed.
+4. Install the agent skill: copy node_modules/verifika/skills/verifika into this
+   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 (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, the scripts you added, replaced or left (with any
+conflicts), any CI recommendation, and any existing failures you found.
 ```
 
-The docs use `verifika` throughout. To install it globally instead, run `npm install --global verifika`; to try it without installing, run `npx verifika --help`.
+Review the config it writes before committing it: the commands in it run on every verification.
 
-## Quick start
-
-Generate a starter config from your `package.json` scripts:
+### By hand
 
 ```sh
-npx verifika init
+npm install --save-dev verifika
+npx vfk init     # creates verifika.config.json from your package.json scripts,
+                 # and adds "verify" / "verify:ci" scripts if they are missing
 ```
 
-Or write `verifika.config.json` yourself:
+`init` only maps conventional script names (`lint`, `test`, `build`, ...) and leaves every check unfiltered, so open the file and give each check `paths`:
 
 ```json
 {
@@ -72,46 +117,50 @@ Or write `verifika.config.json` yourself:
 }
 ```
 
-If your repository checks the formatting of every file (for example `prettier --check .`), format the new `verifika.config.json` too.
-
-Then:
+If your repository checks the formatting of every file (for example `prettier --check .`), format the new `verifika.config.json` too. Then:
 
 ```sh
-npx verifika plan     # which checks would run for your changes, and why
-npx verifika          # run them
-npx verifika --all    # run everything (do this before you push)
+npx vfk plan     # which checks would run for your changes, and why
+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": "verifika --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
 
-| Situation                                      | What runs                                                                                                           |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `verifika` locally                             | Checks whose `paths` match files changed since `changes.base` (default `HEAD`: your uncommitted and untracked work) |
-| `verifika` in CI (`CI` or a known CI variable) | Everything; only `--changed`/`--changed-since` on the command line can narrow it                                    |
-| `verifika --all`                               | Everything                                                                                                          |
-| `verifika --check lint`                        | `lint` and its dependencies                                                                                         |
-| `verifika --changed-since origin/main`         | Checks matching files changed since `merge-base(origin/main, HEAD)`, plus uncommitted and untracked files           |
-| A changed file matches `invalidateAll`         | Everything                                                                                                          |
-| Git unavailable, no commits, unknown base      | Everything, with the reason printed (or an error, when you asked for `--changed`/`--changed-since` explicitly)      |
+| Situation                                 | What runs                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `vfk` locally                             | Checks whose `paths` match files changed since `changes.base` (default `HEAD`: your uncommitted and untracked work) |
+| `vfk` in CI (`CI` or a known CI variable) | Everything; only `--changed`/`--changed-since` on the command line can narrow it                                    |
+| `vfk --all`                               | Everything                                                                                                          |
+| `vfk --check lint`                        | `lint` and its dependencies                                                                                         |
+| `vfk --changed-since origin/main`         | Checks matching files changed since `merge-base(origin/main, HEAD)`, plus uncommitted and untracked files           |
+| A changed file matches `invalidateAll`    | Everything                                                                                                          |
+| Git unavailable, no commits, unknown base | Everything, with the reason printed (or an error, when you asked for `--changed`/`--changed-since` explicitly)      |
 
-A check without `paths` runs whenever any file changed; `"always": true` runs it even when nothing changed. Selecting a check also selects its `dependsOn` checks. `verifika plan` shows every decision.
+A check without `paths` runs whenever any file changed; `"always": true` runs it even when nothing changed. Selecting a check also selects its `dependsOn` checks. `vfk plan` shows every decision.
 
 ## Output modes
 
 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).
 
@@ -120,10 +169,10 @@ Exit codes: `0` passed (or nothing to verify), `1` verification failed, `2` usag
 Every run stores each check's combined stdout/stderr under `.verifika/runs/<run-id>/`. The directory ignores itself in git, and only the last 10 runs are kept (`defaults.keepRuns`).
 
 ```sh
-verifika logs                    # latest run: statuses and log paths
-verifika logs typecheck          # full log of one check
-verifika logs --failed           # logs of every failed check
-verifika logs test --tail 50     # last 50 lines
+vfk logs                  # latest run: statuses and log paths
+vfk logs typecheck        # full log of one check
+vfk logs --failed         # logs of every failed check
+vfk logs test --tail 50   # last 50 lines
 ```
 
 Logs contain whatever your commands print, which can include secrets. They never leave your machine; keep `.verifika/` out of anything you publish.

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/config.js

@@ -30,7 +30,7 @@ export function findConfigFile(cwd, explicit) {
             return candidate;
         const parent = path.dirname(directory);
         if (parent === directory) {
-            throw new VerifikaError(`no ${CONFIG_FILE} found in ${cwd} or any parent directory`, "Create one with: verifika init");
+            throw new VerifikaError(`no ${CONFIG_FILE} found in ${cwd} or any parent directory`, "Create one with: vfk init");
         }
         directory = parent;
     }

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}`);