verifika 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+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.1] - 2026-10-12
+
+First public release.
+
+### Added
+
+- `vfk`: a shorthand executable for `verifika`, installed by the same package.
+- `verifika` / `verifika run`: runs configured checks concurrently with dependency ordering, per-check timeouts, optional fail-fast, process-tree cleanup and signal handling.
+- Safety defaults: checks run sequentially unless `defaults.concurrency` or `-j` opts into parallelism; CI always runs the full suite unless `--changed`/`--changed-since` is passed explicitly (environment variables cannot switch CI mode off); a check passes only if its process tree was confirmed cleaned up; concurrent Verifika invocations in one directory keep their run records and logs apart.
+- Hybrid selection: selective runs from git changes locally (`changes.base`, `--changed`, `--changed-since <ref>` with merge-base semantics), full runs in CI and with `--all`, explicit `--check`. Global invalidation (`invalidateAll`), `paths`/`exclude` globs, `always` checks and `dependsOn`.
+- Conservative fallbacks: full runs when git cannot determine changes implicitly; exit 2 when an explicit comparison is impossible.
+- Output modes: `human` (live progress), `agent` (one line on success, bounded failure preview), `json` (versioned result, `schemaVersion: 1`) and `quiet`.
+- `verifika plan` to show selection decisions and reasons without running checks.
+- `verifika logs` with `--failed`, `--tail` and `--run`; logs stored in a self-ignoring `.verifika/` directory with retention (`defaults.keepRuns`).
+- `verifika init` to create a starter config from `package.json` scripts.
+- JSON schema for `verifika.config.json` with editor autocomplete.
+- Agent skill (`skills/verifika/SKILL.md`) for Claude Code, Codex, OpenCode and other agents.
+- Published to npm as `verifika`; the package tarball is also attached to the GitHub release.
+
+### Known limitations
+
+- No per-check lock: checks that write shared outputs need `dependsOn` or `concurrency: 1` (see the configuration reference).
+- 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.1]: https://github.com/alexportelli12/verifika/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Portelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# Verifika
 
-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.
+[![CI](https://github.com/alexportelli12/verifika/actions/workflows/ci.yml/badge.svg)](https://github.com/alexportelli12/verifika/actions/workflows/ci.yml)
+[![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.
+
+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).
+
+```text
+$ verifika
+PASS 3/3 (4.1s) selective: 2 files changed since HEAD (a1b2c3d); 2 skipped
+
+$ verifika --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
+```
+
+_Verifika_ is Maltese for "verification".
+
+## Why
+
+- **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.
+
+## Install
+
+Requires Node.js 22.13 or newer.
+
+```sh
+npm install --save-dev verifika
+```
+
+The package installs two commands: `verifika` and its shorthand `vfk`. They are the same program, so use whichever you prefer:
+
+```sh
+npx verifika plan    # same as: npx vfk plan
+npx vfk --all        # same as: npx verifika --all
+```
+
+The docs use `verifika` throughout. To install it globally instead, run `npm install --global verifika`; to try it without installing, run `npx verifika --help`.
+
+## Quick start
+
+Generate a starter config from your `package.json` scripts:
+
+```sh
+npx verifika init
+```
+
+Or write `verifika.config.json` yourself:
+
+```json
+{
+  "$schema": "./node_modules/verifika/schemas/verifika.schema.json",
+  "version": 1,
+  "changes": {
+    "invalidateAll": ["package.json", "package-lock.json", "tsconfig*.json"]
+  },
+  "checks": {
+    "format": { "command": "npm run format:check" },
+    "lint": { "command": "npm run lint", "paths": ["src/**/*.{ts,html}"] },
+    "typecheck": { "command": "npm run typecheck", "paths": ["src/**/*.ts"] },
+    "test": { "command": "npm test", "paths": ["src/**", "test/**"] },
+    "build": { "command": "npm run build", "paths": ["src/**"], "dependsOn": ["typecheck"] }
+  }
+}
+```
+
+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)
+```
+
+Add a script so everyone runs the same full gate:
+
+```json
+{ "scripts": { "verify": "verifika --all" } }
+```
+
+## 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)      |
+
+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.
+
+## 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                                  |
+
+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).
+
+## Logs
+
+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
+```
+
+Logs contain whatever your commands print, which can include secrets. They never leave your machine; keep `.verifika/` out of anything you publish.
+
+## Agent integration
+
+Verifika ships an [agent skill](skills/verifika/SKILL.md) that teaches coding agents when to run selective versus full verification, how to read results, and how not to claim success too early. See [docs/agents.md](docs/agents.md) to install it for Claude Code, Codex or OpenCode.
+
+## Documentation
+
+- [Configuration reference](docs/configuration.md)
+- [CLI reference](docs/cli.md)
+- [Agent integration](docs/agents.md)
+- [Architecture](docs/architecture.md)
+- [Validation and benchmarks](docs/benchmarks.md)
+- [Example configs](examples/)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
+
+## Trust model
+
+`verifika.config.json` is trusted code: its commands run through your shell with your permissions, exactly like `package.json` scripts. Verifika never puts file names, git refs or other external input into those commands. Review config changes as carefully as script changes.
+
+## License
+
+[MIT](LICENSE)

package/dist/ci.js

@@ -0,0 +1,34 @@
+/** Variables set by common CI providers. */
+export const CI_VARIABLES = [
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "TRAVIS",
+    "JENKINS_URL",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER",
+    "CODEBUILD_BUILD_ID",
+    "DRONE",
+    "APPVEYOR",
+    "SEMAPHORE",
+];
+/**
+ * Decides whether this is a CI run, where verification defaults to the full
+ * suite. Environment variables can only turn CI mode on: a truthy `CI` or any
+ * provider variable means CI, and nothing (including `CI=false`, which some
+ * build setups export for unrelated reasons) can switch a detected provider
+ * off. Selective runs in CI require an explicit `--changed` or `--changed-since`.
+ */
+export function detectCi(env) {
+    if (isEnabled(env.CI))
+        return { ci: true, source: "CI" };
+    const provider = CI_VARIABLES.find((name) => isEnabled(env[name]));
+    return provider ? { ci: true, source: provider } : { ci: false, source: "none" };
+}
+function isEnabled(value) {
+    if (value === undefined)
+        return false;
+    return !["", "0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { ExitCode } from "./errors.js";
+import { main } from "./main.js";
+const write = (stream) => (text) => {
+    stream.write(text);
+};
+// A closed pipe (e.g. `verifika logs lint | head`) is not an error worth a stack trace.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (error) => {
+        if (error.code !== "EPIPE")
+            throw error;
+    });
+}
+main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    env: process.env,
+    isTTY: Boolean(process.stdout.isTTY),
+    out: write(process.stdout),
+    err: write(process.stderr),
+}).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`verifika: internal error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exitCode = ExitCode.Internal;
+});

package/dist/config.js

@@ -0,0 +1,294 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { VerifikaError } from "./errors.js";
+export const CONFIG_FILE = "verifika.config.json";
+export const CHECK_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const DEFAULT_TIMEOUT_MS = 600_000;
+/** Largest delay setTimeout accepts (about 24.8 days); larger values would fire immediately. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/** Device names Windows reserves in every directory; they cannot be log file names. */
+const RESERVED_NAMES = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+const DEFAULT_KEEP_RUNS = 10;
+/**
+ * Checks run one at a time unless the config (or `-j`) opts into parallelism:
+ * only the project knows which of its scripts share build outputs, and running
+ * those concurrently produces real but misleading failures.
+ */
+export const DEFAULT_CONCURRENCY = 1;
+/** Walks up from `cwd` to find verifika.config.json, or uses the explicit path. */
+export function findConfigFile(cwd, explicit) {
+    if (explicit) {
+        const file = path.resolve(cwd, explicit);
+        if (!isFile(file))
+            throw new VerifikaError(`config file not found: ${explicit}`);
+        return file;
+    }
+    let directory = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(directory, CONFIG_FILE);
+        if (isFile(candidate))
+            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");
+        }
+        directory = parent;
+    }
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function loadConfig(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new VerifikaError(`cannot read ${file}: ${error.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch (error) {
+        throw new VerifikaError(`${path.basename(file)} is not valid JSON: ${error.message}`);
+    }
+    return parseConfig(raw, file);
+}
+/** Validates raw JSON and applies defaults. Reports every problem at once. */
+export function parseConfig(raw, file) {
+    const errors = [];
+    const v = new Validator(errors);
+    if (!v.object(raw, "config"))
+        throw configError(file, errors);
+    v.keys(raw, "config", ["$schema", "version", "defaults", "changes", "checks"]);
+    v.string(raw.$schema, "$schema");
+    if (raw.version !== 1) {
+        errors.push(raw.version === undefined
+            ? "version: required; set it to 1"
+            : `version: unsupported value ${JSON.stringify(raw.version)}; this release supports 1`);
+    }
+    const defaults = raw.defaults ?? {};
+    let concurrency = DEFAULT_CONCURRENCY;
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    let failFast = false;
+    let keepRuns = DEFAULT_KEEP_RUNS;
+    if (v.object(defaults, "defaults")) {
+        v.keys(defaults, "defaults", ["concurrency", "timeoutMs", "failFast", "keepRuns"]);
+        concurrency = v.integer(defaults.concurrency, "defaults.concurrency", 1, 64) ?? concurrency;
+        timeoutMs = v.integer(defaults.timeoutMs, "defaults.timeoutMs", 1, MAX_TIMEOUT_MS) ?? timeoutMs;
+        failFast = v.boolean(defaults.failFast, "defaults.failFast") ?? failFast;
+        keepRuns = v.integer(defaults.keepRuns, "defaults.keepRuns", 1, 1000) ?? keepRuns;
+    }
+    const changes = raw.changes ?? {};
+    let base = "HEAD";
+    let invalidateAll = [];
+    if (v.object(changes, "changes")) {
+        v.keys(changes, "changes", ["base", "invalidateAll"]);
+        base = v.string(changes.base, "changes.base") ?? base;
+        invalidateAll = v.globs(changes.invalidateAll, "changes.invalidateAll", true) ?? [];
+    }
+    // A config edit can change what every check means, so it always invalidates everything.
+    if (!invalidateAll.includes(CONFIG_FILE))
+        invalidateAll = [...invalidateAll, CONFIG_FILE];
+    const checks = [];
+    if (raw.checks === undefined) {
+        errors.push("checks: required; declare at least one check");
+    }
+    else if (v.object(raw.checks, "checks")) {
+        const entries = Object.entries(raw.checks);
+        if (entries.length === 0)
+            errors.push("checks: declare at least one check");
+        for (const [name, value] of entries) {
+            const at = `checks.${name}`;
+            if (!CHECK_NAME_PATTERN.test(name)) {
+                errors.push(`${at}: invalid name; use letters, digits, ".", "_" or "-", starting with a letter or digit`);
+            }
+            if (RESERVED_NAMES.test(name)) {
+                errors.push(`${at}: "${name}" is a reserved device name on Windows; choose another name`);
+            }
+            const clash = entries.find(([other]) => other !== name && other.toLowerCase() === name.toLowerCase());
+            if (clash && clash[0] < name) {
+                errors.push(`${at}: differs from "${clash[0]}" only by case; log files would collide`);
+            }
+            if (!v.object(value, at))
+                continue;
+            v.keys(value, at, ["command", "paths", "exclude", "always", "dependsOn", "timeoutMs"]);
+            const command = v.string(value.command, `${at}.command`, true);
+            const paths = v.globs(value.paths, `${at}.paths`, false);
+            const exclude = v.globs(value.exclude, `${at}.exclude`, true) ?? [];
+            const always = v.boolean(value.always, `${at}.always`) ?? false;
+            const dependsOn = v.stringArray(value.dependsOn, `${at}.dependsOn`) ?? [];
+            const checkTimeout = v.integer(value.timeoutMs, `${at}.timeoutMs`, 1, MAX_TIMEOUT_MS);
+            if (always && paths) {
+                errors.push(`${at}: "always" and "paths" cannot be combined; an always-run check ignores paths`);
+            }
+            if (always && exclude.length > 0) {
+                errors.push(`${at}: "always" and "exclude" cannot be combined`);
+            }
+            checks.push({
+                name,
+                command: command ?? "",
+                paths,
+                exclude,
+                always,
+                dependsOn,
+                timeoutMs: checkTimeout ?? timeoutMs,
+            });
+        }
+        validateDependencies(checks, errors);
+    }
+    if (errors.length > 0)
+        throw configError(file, errors);
+    return {
+        file,
+        root: path.dirname(file),
+        concurrency,
+        timeoutMs,
+        failFast,
+        keepRuns,
+        base,
+        invalidateAll,
+        checks,
+    };
+}
+function validateDependencies(checks, errors) {
+    const byName = new Map(checks.map((check) => [check.name, check]));
+    for (const check of checks) {
+        const seen = new Set();
+        for (const dependency of check.dependsOn) {
+            if (dependency === check.name) {
+                errors.push(`checks.${check.name}.dependsOn: a check cannot depend on itself`);
+            }
+            else if (!byName.has(dependency)) {
+                errors.push(`checks.${check.name}.dependsOn: unknown check "${dependency}"`);
+            }
+            else if (seen.has(dependency)) {
+                errors.push(`checks.${check.name}.dependsOn: "${dependency}" is listed twice`);
+            }
+            seen.add(dependency);
+        }
+    }
+    const cycle = findCycle(checks, byName);
+    if (cycle)
+        errors.push(`checks: dependency cycle ${cycle.join(" -> ")}`);
+}
+function findCycle(checks, byName) {
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        if (state.get(name) === "done")
+            return null;
+        if (state.get(name) === "visiting")
+            return [...stack.slice(stack.indexOf(name)), name];
+        state.set(name, "visiting");
+        stack.push(name);
+        for (const dependency of byName.get(name)?.dependsOn ?? []) {
+            if (dependency === name || !byName.has(dependency))
+                continue;
+            const cycle = visit(dependency);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(name, "done");
+        return null;
+    };
+    for (const check of checks) {
+        const cycle = visit(check.name);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+function configError(file, errors) {
+    return new VerifikaError(`invalid ${path.basename(file)}:\n${errors.map((error) => `  - ${error}`).join("\n")}`);
+}
+/** Small collecting validator; each method returns `undefined` for absent or invalid values. */
+class Validator {
+    errors;
+    constructor(errors) {
+        this.errors = errors;
+    }
+    object(value, at) {
+        if (typeof value === "object" && value !== null && !Array.isArray(value))
+            return true;
+        this.errors.push(`${at}: expected an object`);
+        return false;
+    }
+    keys(value, at, allowed) {
+        for (const key of Object.keys(value)) {
+            if (!allowed.includes(key)) {
+                this.errors.push(`${at}: unknown property "${key}" (allowed: ${allowed.join(", ")})`);
+            }
+        }
+    }
+    string(value, at, required = false) {
+        if (value === undefined) {
+            if (required)
+                this.errors.push(`${at}: required`);
+            return undefined;
+        }
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+        this.errors.push(`${at}: expected a non-empty string`);
+        return undefined;
+    }
+    boolean(value, at) {
+        if (value === undefined || typeof value === "boolean")
+            return value;
+        this.errors.push(`${at}: expected true or false`);
+        return undefined;
+    }
+    integer(value, at, min, max) {
+        if (value === undefined)
+            return undefined;
+        if (typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= min &&
+            (max === undefined || value <= max)) {
+            return value;
+        }
+        const range = max === undefined ? `>= ${min}` : `between ${min} and ${max}`;
+        this.errors.push(`${at}: expected an integer ${range}`);
+        return undefined;
+    }
+    stringArray(value, at) {
+        if (value === undefined)
+            return undefined;
+        if (Array.isArray(value) &&
+            value.every((item) => typeof item === "string" && item.trim() !== "")) {
+            return value;
+        }
+        this.errors.push(`${at}: expected an array of non-empty strings`);
+        return undefined;
+    }
+    /** Glob lists must be portable: forward slashes, relative to the config directory. */
+    globs(value, at, allowEmpty) {
+        const list = this.stringArray(value, at);
+        if (list === undefined)
+            return undefined;
+        if (list.length === 0 && !allowEmpty) {
+            this.errors.push(`${at}: must not be empty; omit it to match every file, or use "always": true`);
+            return undefined;
+        }
+        const normalized = [];
+        for (const pattern of list) {
+            if (pattern.includes("\\")) {
+                this.errors.push(`${at}: "${pattern}" contains a backslash; use forward slashes on every platform`);
+            }
+            else if (pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern)) {
+                this.errors.push(`${at}: "${pattern}" is absolute; patterns are relative to the config directory`);
+            }
+            else {
+                normalized.push(pattern.replace(/^(\.\/)+/, ""));
+            }
+        }
+        return normalized;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+/** Exit codes are part of the public CLI contract; see docs/cli.md. */
+export const ExitCode = {
+    Passed: 0,
+    Failed: 1,
+    Usage: 2,
+    Internal: 70,
+};
+/**
+ * A problem with how Verifika was invoked or configured. These never represent
+ * check results, so they always exit with the usage code rather than a pass.
+ */
+export class VerifikaError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "VerifikaError";
+        this.hint = hint;
+    }
+}

package/dist/format.js

@@ -0,0 +1,10 @@
+/** Compact duration: `0.4s`, `12s`, `3m05s`. */
+export function formatSeconds(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 10)
+        return `${seconds.toFixed(1)}s`;
+    if (seconds < 120)
+        return `${Math.round(seconds)}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${String(Math.floor(seconds % 60)).padStart(2, "0")}s`;
+}