tracker

Overview ¶

ABOUTME: Audit subcommand — analyzes completed pipeline runs from on-disk artifacts. ABOUTME: Reads checkpoint, activity log, and node status files to produce structured reports.

ABOUTME: 2389.ai brand assets — ASCII art header, logo, taglines, and shared color palette. ABOUTME: Used by the setup wizard, pipeline startup banner, and exit screen.

ABOUTME: Run-capture spec recording — captures the exact spec the process is executing, at load time. ABOUTME: The spec is handed to the library via Config.Capture (buildCaptureConfig), which writes the artifacts once the run ID exists.

ABOUTME: Single source of truth for public CLI subcommand metadata (#612). ABOUTME: subcommandMap, flag-parser grouping, and the usage list all derive here.

ABOUTME: Command dispatch and shared utilities for the tracker CLI. ABOUTME: Routes subcommands, resolves checkpoints, and manages .env loading.

ABOUTME: Provider-status label for the openai slot under TRACKER_OPENAI_AUTH=chatgpt — used by ABOUTME: printProviderStatus (commands.go) for `tracker version`. Split out to stay under the file-size ratchet.

ABOUTME: Pre-run sandbox device-node hygiene check (#423). ABOUTME: Verifies /dev/null is a usable char device before any git/subprocess handler runs.

ABOUTME: non-Windows real implementation of the /dev/null device probe (#423). Build tag is !windows (mirrors device_probe_windows.go's windows-only stub); the _posix filename is descriptive only — Go assigns no build meaning to it.

ABOUTME: Installs the CLI's diagnostic sink so library diagnostics still reach stderr (#449). ABOUTME: The library defaults to a no-op sink; the CLI restores the pre-#449 stderr behavior.

ABOUTME: Diagnose subcommand — deep analysis of pipeline run failures. ABOUTME: Reads activity.jsonl and node status files to surface errors, tool output, and suggestions.

ABOUTME: Preflight health check — verifies API keys, dippin binary, workdir, and more. ABOUTME: Surfaces actionable guidance for common setup issues. ABOUTME: Exit 0 = all pass, Exit 1 = any failure, Exit 2 = warnings only (no errors).

ABOUTME: CLI-side aliases for the built-in workflow catalog. ABOUTME: Thin wrappers over the top-level tracker package so CLI and library share one source.

ABOUTME: Source-aware .env loading for the tracker CLI (#659): the config .env may set credentials, base ABOUTME: URLs and knobs; the project .env may set provider keys only; the shell always wins and is never overwritten.

ABOUTME: Unix open for .env files: O_NOFOLLOW so a symlink planted at <workdir>/.env is refused at the syscall. ABOUTME: The Lstat check in readEnvFileSecurely gives the friendly notice; this closes the race behind it.

ABOUTME: The `tracker estimate` command — a rough pre-run cost/scale ballpark.

ABOUTME: CLI flag parsing and usage output for the tracker command. ABOUTME: Handles subcommand detection and flag extraction for all modes.

ABOUTME: `tracker init` — copies a built-in .dip to cwd together with its sidecar tree ABOUTME: (the set pipeline.WorkflowFiles defines) and scaffolds a starter SPEC.md where needed.

ABOUTME: The CLI's native LLM client resolution: tolerate a missing client for a ABOUTME: headless global backend, or a graph whose agent nodes never need native.

ABOUTME: Pipeline file loading — reads .dip or .dot files and converts to Graph. ABOUTME: Auto-detects format from extension; resolves and loads subgraph references recursively.

ABOUTME: CLI entry point for the tracker pipeline engine. ABOUTME: Loads a pipeline file (.dip preferred, .dot deprecated) and runs it. ABOUTME: Mode 1 (default): BubbleteaInterviewer for human gates with inline TUI per gate. ABOUTME: Mode 2 (--tui): Full dashboard TUI with header, node list, agent log, and modal gates.

ABOUTME: Builds the ordered node list for TUI display from the pipeline graph. ABOUTME: Uses Kahn's topological sort algorithm with BFS tie-breaking.

ABOUTME: CLI-side pipeline name resolver — filesystem first, then built-ins. ABOUTME: Shares the built-in lookup with the top-level tracker package.

ABOUTME: Strict bundle identity verification on resume — rejects mismatches ABOUTME: between checkpoint identity and current bundle unless --force-bundle-mismatch.

ABOUTME: Builds the argument tail of the resume command printed after a failed run. ABOUTME: Repeats the run's -w and --artifact-dir, absolute and shell-quoted (#696).

ABOUTME: Pipeline execution functions for both console mode (mode 1) and TUI mode (mode 2). ABOUTME: Includes LLM client construction and interviewer selection.

ABOUTME: Helpers that populate tracker.Config from the CLI's runOptions. ABOUTME: Interviewer selection, webhook-gate mapping, and herdr pane reporting.

ABOUTME: runOptions — the explicit per-invocation config value threaded from ABOUTME: flag parsing (executeRun) into run/runTUI, replacing the active* package globals.

ABOUTME: `tracker run-json [runID]` — assembles run.json for a run directory. ABOUTME: Works after the fact, so SIGKILLed runs and runs archived before the manifest existed both get one.

ABOUTME: Starter-file scaffolding for `tracker init` — so a newcomer's first ABOUTME: `tracker build_product` succeeds instead of hard-exiting on a missing SPEC.md.

ABOUTME: Setup wizard command — interactive provider configuration UI. ABOUTME: Reads/writes API keys, base URLs and the OpenAI auth switch in the XDG config .env file.

ABOUTME: Setup wizard's OpenAI Auth row (API key or ChatGPT subscription) and device-code sign-in: ABOUTME: state, key handling and the background sign-in commands (views: setup_chatgpt_view.go).

ABOUTME: Views for the setup wizard's OpenAI page: the Auth row, the ChatGPT sign-in status ABOUTME: and key help, and the device-code sign-in page with its link, code and notice.

ABOUTME: Multi-page setup wizard TUI for configuring LLM provider credentials. ABOUTME: Checkbox provider selection, per-provider API key + base URL forms, branded exit banner.

ABOUTME: Simulate subcommand — dry-runs a pipeline (.dot or .dip) without LLM calls. ABOUTME: Shows execution plan: node order, handlers, edges, conditions, and graph attributes.

ABOUTME: `tracker status [runID]` — the agent-authored high-level timeline of a ABOUTME: run (what got done), read from the activity log without the firehose (#494).

ABOUTME: Run summary display — prints the end-of-pipeline report with stats, ABOUTME: per-node breakdown, token usage, pipeline graph, and resume hints.

ABOUTME: The end-of-run notice: a workflow's short next-steps text from <run dir>/notice.txt, ABOUTME: printed after the summary, bounded and stripped of control characters.

ABOUTME: Token/cost table helpers for the run summary — the per-provider rows ABOUTME: and trailing cost line, extracted from printTokensByProvider (complexity gate).

ABOUTME: Self-update command — downloads latest release from GitHub and replaces the binary. ABOUTME: Detects install method (Homebrew/go install/binary) and acts accordingly.

ABOUTME: Non-blocking startup version check with 24h file-based cache. ABOUTME: Prints a one-line hint if an update is available, never blocks.

ABOUTME: Two-tier CLI help output for the tracker run command (#463). ABOUTME: --help shows common flags; --help-all shows every flag grouped by concern.

ABOUTME: Validate subcommand — checks pipeline files (.dot or .dip) for structural errors and warnings. ABOUTME: Returns exit code 0 for valid pipelines, 1 for errors. Suitable for CI/pre-commit.

ABOUTME: Reads embedded VCS build info so `go install` builds show commit + date. ABOUTME: Only fills in values that are still at their default ("unknown").

ABOUTME: `tracker verify-tests <dir>` — flags duplicate/near-duplicate Go test ABOUTME: bodies so a verify gate can't bless copied "distinct" tests (#489).