Add man page generator for tagoio CLI

[bgelatti]

Closes tago-io/project-sdk-and-tools#3

Problem

The tagoio CLI ships no man(1) page. Users have no offline reference (man tagoio returns "No manual entry"), and fish-shell users can't enable tab-completion since fish_update_completions works by scraping installed man pages.

Investigation

• Commander already exposes the full command surface as structured metadata (program.commands, each with options, registeredArguments, description, and addHelpText blocks). That's exactly the data a man page needs — there's no missing source of truth, only a missing emitter.
• A small audit against clig.dev man-page guidelines confirmed the conventional sections (NAME, SYNOPSIS, DESCRIPTION, GLOBAL OPTIONS, COMMANDS, EXIT STATUS, ENVIRONMENT, FILES, SEE ALSO, AUTHOR), the synopsis convention (<required> / [optional] / [args...]), and the practice of bolding flags / italicizing metavariables.
• Existing libraries (marked-man, ronn, help2man, pandoc) all expect either hand-written Markdown or run-time parsing of --help text — both of which reintroduce the drift problem we're trying to solve. Closest commander-specific alternatives are unmaintained.

Solution

Three tightly-scoped commits on top of feat/cli-refactoring-deps:

1. refactor(index): extract buildProgram for build-time tool reuse — pulls command registration out of initiateCMD into buildProgram(defaultEnv), returning a configured Command without parsing argv. Guarded the auto-run with an import.meta.url check so build tools can import this module without triggering program.parse(). Single source of truth for the command tree.

2. feat(man): generate tagoio.1 from commander definitions — new src/lib/generate-man.ts walks buildProgram() and emits a roff page. Wired into the build chain (npm run man runs first), into prepublishOnly, and into package.json (man field + files array) so npm i -g symlinks it into <prefix>/share/man/man1/tagoio.1. A Vitest snapshot test acts as the CI drift gate; a companion mandoc/groff integration test catches roff syntax errors. The interactive prompt-driven flows (start-config, backup restore, export-setup) are excluded from the coverage threshold since they're covered by manual smokes.

3. fix(man): correct FILES paths and add EXIT STATUS per clig.dev audit — verified the actual filesystem contracts in code (src/lib/token.ts, src/lib/dotenv-config.ts) and corrected the FILES section to list ./tagoconfig.json, ./.tago-lock.<env>.lock, and ./.tagoio/personal.env accurately. Added the EXIT STATUS section.

Why a hand-rolled walker (≈250 LoC) is the right choice for this CLI

• The command tree IS the source of truth; the walker is a thin reflection of what commander already knows. Zero drift by construction.
• All ready-made alternatives reintroduce a problem we don't have:
  • marked-man / ronn / pandoc require Markdown source — either hand-authored (drift) or auto-generated from commander first (which is just our walker with extra steps).
  • help2man parses --help heuristically and depends on GNU conventions; it's a system dependency and brittle on CI.
  • No maintained commander-to-man npm package exists in the modern ecosystem.
• Snapshot testing pins the output byte-for-byte, so any commander-API surprise surfaces in CI immediately rather than at publish time.
• Industry pattern matches: Go's gh and kubectl do exactly this with cobra; npm is the only big CLI using Markdown + marked-man, and they do so because their docs team writes prose by hand — not our use case.

If we ever need per-command man pages (tagoio-deploy.1, etc.) it'd be worth re-evaluating Markdown sources, but for a single umbrella page the walker wins on simplicity.

Test plan

• npm run man produces a byte-stable man/tagoio.1 (verified by snapshot test)
• npm test fails locally and in CI when a flag/command is added without regenerating the snapshot — drift gate
• mandoc -Tutf8 man/tagoio.1 exits 0 (integration test)
• npm run build regenerates the page automatically as a pre-step
• npm pack --dry-run shows man/tagoio.1 (13.7kB) in the tarball
• After npm i -g ./tago-io-cli-3.2.0.tgz, man tagoio renders the page on macOS
• Fish users can run fish_update_completions and get tab-completion (zsh / bash do not — explicitly out of scope; documented in README)

[vitorfdl]

Header and Footer must be readable