verify

livewiki verify command

This page documents the livewiki verify CLI subcommand, which checks a generated wiki for the kinds of corruption that would break readers or CI pipelines.

When to use this page

• Wire livewiki verify into a CI pipeline so build steps fail when the wiki no longer matches its index.
• Inspect what counts as a "verification failure": broken anchors, altered manual blocks, and broken internal links.
• Choose between the default human-readable report and a machine-readable JSON report using the --json flag.
• Debug non-zero exits from the verifier by understanding the option parsing, error handling, and exit-code flow inside registerVerify.

How it fits

The file lives at packages/cli/src/commands/verify.ts, inside the @livewiki/cli package's commands directory. It sits in the command-registration layer of the CLI: each file here exports one registerXxx(program) function that a higher-level CLI bootstrap attaches to a commander Command instance. registerVerify delegates all heavy lifting to the @livewiki/core/verify module — specifically runVerify (the actual checker) and formatVerifyHuman (the text reporter) — and adds only the CLI-shaped concerns: parsing VerifyOptions, resolving the repository root, switching between JSON and human output, and translating outcomes into a process exit code. The verifier itself is what walks the wiki pages and the index; this file is the thin adapter that exposes it as a subcommand.

Diagram

%% livewiki/diagrams/commands-verify.mmd

Command registration

The single responsibility of this file is to teach the top-level commander program how to invoke the verify subcommand and how to render the result.

export function registerVerify(program: Command): void

registerVerify takes the parent commander Command instance and returns nothing; attaching a subcommand to it mutates the program in place.

// packages/cli/src/commands/verify.ts
export function registerVerify(program: Command): void {
  program
    .command("verify")
    .description(
      "validate wiki: anchors + manual blocks + internal links. Exit ≠ 0 on failure (Phase 2, CI-friendly)",
    )
    .action(async (_options: VerifyOptions, command: Command) => {
      const opts = command.optsWithGlobals<VerifyOptions>();
      const json = Boolean(opts.json);
      const repoRoot = path.resolve(process.cwd(), opts.repo ?? ".");
      let result: VerifyResult;
      try {
        result = await runVerify(repoRoot);
      } catch (err) {
        process.stderr.write(`livewiki verify: error — ${(err as Error).message}\n`);
        // An abrupt exit after writing stderr can crash libuv on Windows
        // while I/O is pending. Let Node drain the event loop naturally.
        process.exitCode = 1;
        return;
      }
      if (json) {
        process.stdout.write(JSON.stringify(result) + "\n");
      } else {
        process.stdout.write(formatVerifyHuman(result) + "\n");
      }
      // CI-friendly: exit code != 0 if there are errors
      if (!result.ok) process.exitCode = 1;
    });
}