Document and validate development and CLI runtime prerequisites

[danielblignaut]

Outcome

Define, document, and automatically verify the prerequisites for:

1. contributing to OpenBot from a source checkout; and
2. installing and using the published OpenBot CLI at runtime.

These are different environments and must not share one vague "Requirements: Node and pnpm" paragraph. A CLI user should not accidentally need the full monorepo development toolchain, while a contributor should have a reproducible checklist that covers tests, Electron, computers, secrets, and deployments.

Current problems

• The root README lists only Node.js 24 and pnpm 10 for local development.
• The root package pins Node 24.x and pnpm 10.33.1, but the CLI package does not publish equivalent engine/runtime metadata yet.
• The CLI invokes system tools such as sops, mkfifo, Git, Docker, provider CLIs, and the selected owner-identity backend without a single capability matrix or preflight command.
• Requirements vary by command and provider. For example, openbot --help, openbot init, openbot dev, local deployment, and Vercel deployment do not need the same host capabilities.
• Local computer and desktop support depends on operating system, architecture, virtualization/display capabilities, and service manager. These constraints are currently scattered across code and ADRs.
• Missing binaries generally fail only when a command is already running, with raw spawn errors and no version or installation guidance.

Required documentation split

Contributor development prerequisites

Create one canonical contributor page and keep the root README summary short. The detailed page should cover:

• supported operating systems and architectures, including explicit Windows/WSL status;
• Node.js 24.x and the repository-pinned pnpm version through Corepack;
• Git and a clean clone/worktree;
• dependency installation and generated-contract bootstrap;
• SOPS and the POSIX FIFO requirement used for secret-safe input;
• Docker Engine/compatible OCI builder and registry authentication for computer-image builds;
• local Microsandbox hardware/virtualization prerequisites, with Vercel Sandbox as the documented remote alternative where supported;
• Linux/macOS desktop-development requirements, including display availability and Electron packaging prerequisites;
• Playwright browser/system dependencies needed only for E2E work;
• local service requirements: systemd user services on Linux or launchd on macOS;
• optional credentials and CLIs required only for selected secret backends or deployment providers;
• the exact focused and full validation commands contributors are expected to run.

Do not present every optional integration as universally required. Use a compact matrix with required, command-specific, and provider-specific columns.

Published CLI runtime prerequisites

Create a separate installation/runtime page for people consuming the npm package. It should distinguish:

• requirements for installing and launching the CLI;
• requirements for repository-oriented commands such as init, dev, check, build, and deploy;
• requirements introduced by the selected runtime, computer, secret-owner, and deployment choices;
• features bundled by the desktop application versus capabilities that must exist on the host;
• supported OS/architecture combinations and clear unsupported behavior.

At minimum document this command matrix:

Command/use	Baseline	Additional capabilities
openbot --help, --version, doctor	Published CLI runtime	None
openbot init	Writable OpenBot repository	Current SOPS, mkfifo, selected owner-identity backend
openbot secrets ...	Initialized repository	SOPS plus configured keychain/KMS identity access
openbot dev	Installed repository dependencies	pnpm, generated-contract toolchain, optional display/Electron
openbot check/build/test	Contributor/project toolchain	Command-specific build, browser, or packaging dependencies
openbot deploy	Initialized repository	Docker/OCI registry plus selected provider credentials and network access
Local runtime/computer	Supported Linux/macOS host	Service manager and supported Microsandbox virtualization
Vercel runtime/computer	Networked host	Vercel access/token and configured remote resources; no local KVM requirement

The final matrix must be generated from or tested against actual command/provider behavior so it cannot silently drift.

Proposed implementation

1. Add a CLI prerequisite model

Keep host checks in the CLI, close to command dispatch, rather than embedding another copy in documentation:

interface SystemRequirement {
  id: string;
  label: string;
  requiredFor: readonly RequirementContext[];
  platforms?: readonly NodeJS.Platform[];
  probe(context: RequirementProbeContext): Promise<RequirementResult>;
  remediation(context: RequirementProbeContext): readonly string[];
}

type RequirementResult =
  | { status: "ok"; version?: string }
  | { status: "warning"; message: string }
  | { status: "missing" | "unsupported"; message: string };

This is a CLI utility, not a new universal provider framework.

• The CLI owns universal checks: OS/architecture, Node, package manager, Git, SOPS, FIFO support, Docker, display, and service manager.
• Existing provider check() behavior remains authoritative for provider build/deployment readiness.
• Provider packages may expose small reusable probe/remediation helpers when they invoke a provider-specific binary or require a host capability; do not duplicate provider credentials or implementation details in the CLI.
• Never inspect, print, or return secret values. Credential checks should report presence/access and the owning provider only.

2. Add openbot doctor

Provide a non-mutating command:

openbot doctor
openbot doctor --mode development
openbot doctor --mode deploy
openbot doctor --json

• With no mode, inspect the current repository/configuration and report the relevant runtime requirements.
• development adds contributor, browser, and optional desktop checks.
• deploy loads the selected providers and checks Docker, registry, provider access, secret-owner access, and deployment prerequisites without creating or changing remote resources.
• --json emits a versioned, deterministic result suitable for CI and support diagnostics.
• Exit non-zero only for missing requirements that block the selected mode. Optional capabilities produce warnings.
• Include detected version, required range, affected commands, and concise remediation for every failure.

3. Run focused preflight checks at command boundaries

• init checks SOPS, secure FIFO support, platform support, and the selected owner-identity backend before writing configuration files.
• dev checks project dependencies/package manager before spawning child processes and explains how to suppress desktop startup in headless environments.
• secrets checks SOPS version and configured identity access before reading input.
• build and deploy run only the checks needed by configured participants; Docker is not a prerequisite when no computer image is being built.
• Local installation validates systemd/launchd support before writing service files.
• Desktop packaging validates the host/architecture and required signing tools separately from ordinary CLI use.

Preflight must be read-only. Mutating configuration, authenticating, installing packages, enabling virtualization, or creating cloud resources requires the existing explicit workflow.

4. Publish accurate package metadata

• Add the supported Node engine to the published CLI package.
• Decide and document whether pnpm is a CLI runtime dependency, a repository-command prerequisite, or an implementation detail that should be removed from the installed CLI path.
• Declare supported OS/CPU metadata only if npm installation should be rejected on unsupported hosts; otherwise allow installation and make individual commands report unsupported capability precisely.
• Ensure the desktop-bundled CLI in Sign, notarize, and productize the macOS Electron app #32 uses the same requirement registry while treating bundled components as satisfied.

5. Keep docs and checks in sync

• Add focused tests for every probe using injected command/platform/capability runners; tests must not depend on the developer's real host state.
• Snapshot or generate the requirements tables from the same requirement metadata used by doctor, or add a consistency test that verifies the documented command IDs and minimum versions.
• Run openbot doctor --mode development --json in an appropriate CI environment as a smoke test, without requiring optional desktop/KVM/cloud credentials.
• Link the contributor page from AGENTS.md and the root README; link CLI requirements from the installation and Mintlify work in Restructure docs and publish an OpenBot Mintlify site #35.

Suggested documentation locations

README.md                              # concise installation/contributing summaries
docs/get-started/cli-prerequisites.mdx
docs/contributing/development-prerequisites.mdx
docs/reference/doctor.mdx

Use Markdown equivalents until the Mintlify restructure in #35 lands, then preserve the same information architecture rather than maintaining parallel pages.

Acceptance criteria

• Contributor and published-CLI prerequisites are documented separately.
• Supported OS, architecture, Node, pnpm, SOPS, Docker/OCI, virtualization, desktop, browser-test, service-manager, and provider-specific requirements are explicit.
• Optional/provider-specific dependencies are not presented as universal CLI requirements.
• The published CLI declares its supported Node engine and has a documented OS/CPU policy.
• openbot doctor reports actionable, version-aware, redacted results in human and versioned JSON formats.
• init, dev, secrets, build, and deploy fail early with command-specific remediation when a required capability is missing.
• Preflight checks do not mutate local configuration or remote resources.
• Requirement probes are unit-tested with injected host behavior and the documented matrix is checked against the implementation.
• Headless development, local Linux/macOS, and Vercel-backed workflows each have a verified happy-path prerequisite profile.
• Root README, contributor guidance, CLI installation docs, and the future Mintlify navigation link to the canonical pages.

Open decisions

• Whether the published CLI should execute repository-local pnpm tooling or bundle/invoke all required build tooling itself.
• Whether unsupported npm platforms should be blocked through package metadata or handled per command by doctor.
• Minimum SOPS and Docker versions based on the exact features OpenBot uses.
• Whether doctor --fix is ever desirable. It is explicitly out of scope for this issue; the first implementation is diagnostic only.

Related work

• Establish GitHub CI/CD and a secure release process #31 — GitHub CI/CD and release process
• Sign, notarize, and productize the macOS Electron app #32 — ship the OpenBot CLI in the desktop app bundle
• Restructure docs and publish an OpenBot Mintlify site #35 — restructure docs and publish the Mintlify site