Terminal UI

Picket includes an interactive scanner console for report triage.

Commands

picket tui <report> opens a full-screen scanner console when the picket-tui companion executable is installed beside picket or is available on PATH.

picket-tui <report> runs the companion directly.

picket tui --scan and picket-tui --scan open the native scan workspace without loading an existing report.

picket tui <report> --flow and picket-tui <report> --flow render interactive steps inline in the normal terminal buffer. picket-tui --flow can prompt for the report path before loading the report.

Supported Inputs

The TUI reads the same summary inputs as picket view:

• Picket JSON and JSON Lines,
• Gitleaks JSON,
• TruffleHog JSON and JSON Lines,
• GitLab code-quality JSON,
• SARIF,
• Picket HTML summary metadata.

The initial console uses only non-secret fields: rule IDs, detector names, paths, line numbers, fingerprints, severity, confidence, validation state, commit and author attribution when present, counts, and format names. It does not load raw secret, match, or source-line evidence into TUI state.

Full-Screen Console

The full-screen console is designed as a scanner console:

• a top command strip with view switching and Run scan,
• a Dashboard summary with severity and validation counts plus top-rule and top-file tables,
• a sectioned Scan page for target selection, output settings, validation filters, limits, command preview, status, scan timing, report path, and result counts,
• a responsive findings triage list with stable row focus, severity, and validation state,
• focused-finding details that can be selected and yanked,
• rule and file frequency views with labelled finding counts,
• searchable scanner output on the Logs view,
• a compact status footer with non-wrapping command hints.

Dashboard is the first tab and the default initial view, whether the console starts empty, restores a previous scan, or opens an explicit report. Use -t, --tab <1-6> to start on Dashboard, Scan, Findings, Rules, Files, or Logs by one-based tab number. Run scan remains available in the header and through Ctrl+R, while Dashboard presents the current state before the operator moves into Scan or Findings. The interface favors readable scanner-console density, predictable keyboard navigation, and text status over decorative layout.

The Findings page keeps the table visible at narrow terminal sizes. At wider sizes, a draggable details pane appears beside the table with constrained minimum, initial, and maximum widths; at narrower sizes, a compact details strip appears below it. Details lead with rule, severity, validation, confidence, and location, include commit and author when present, and place randomness diagnostics last. The full fingerprint remains in finding details and yank text rather than consuming a table column.

Keyboard Reference

Press F1 or ? to open the in-app keyboard reference. The reference is generated from the active Hex1b input bindings, so it reflects the commands available in the current view.

Press 1 through 6 to open Dashboard, Scan, Findings, Rules, Files, or Logs. These shortcuts remain inactive while entering text so numeric paths, filters, and limits can be typed normally. Global chord navigation uses g d for Dashboard, g s for Scan, g f for Findings, g r for Rules, g b for Files, and g l for Logs.

Tab advances through the active page in visual reading order and wraps after its last control. Shift+Tab follows the same order in reverse. Both keys leave text fields and read-only panes instead of inserting a tab or trapping focus. Ctrl+R runs a scan, F5 opens the Scan page, y yanks the current row or text selection, and Ctrl+Q quits. View-specific actions and their keys appear in the footer and keyboard reference.

Set NO_COLOR to any non-empty value to use the monochrome palette. Picket retains visible grayscale focus, selection, progress, and yank states, and all semantic states remain labelled in text.

Native AOT Packaging

The companion is a separate executable for packaging and surface-area isolation. It is published as Native AOT with the same release profiles as picket and is staged beside picket in RID-specific release archives.

Keeping the TUI in picket-tui prevents Hex1b terminal UI code and terminal-native assets from increasing the default scanner binary while preserving a first-class installed experience through picket tui.

Scan Workspace

The TUI includes a scan workspace for running native scans interactively. It builds and displays the command-equivalent picket scan request, then runs the scanner executable.

The default report path is under the operating system temporary directory rather than the scanned checkout. The path is stable across TUI launches so the previous report can be restored when it still exists. The Output settings accept an explicit report path when a durable artifact is required.

The workspace keeps the normal path short: choose a target, check the command preview, press Run scan, then jump to Findings when row triage is needed. It exposes commonly changed options directly:

• local path, local container archive, remote registry image, source-host target, or object-store target,
• profile and config,
• ignore behavior,
• verification mode,
• result filters,
• archive and target-size limits,
• redaction,
• report formats and output paths,
• optional encrypted source-scan checkpoint and explicit reset controls.

The Scan page groups controls into Source, Output, Validation, and Limits sections so the default view stays readable while every scan option remains reachable. Source-host providers use a compact picker so every provider name stays visible without widening the settings pane.

For source-host, object-store, container archive, and registry targets, the Output page can pass a checkpoint path to the CLI. The reset toggle is available beside it and requires a non-empty checkpoint path. Local filesystem scans do not show these controls because checkpointing is a native source-provider workflow. The report and checkpoint paths must differ.

Container targets include Docker archives, OCI image-layout archives, and remote registry images. The registry mode exposes the image reference, endpoint overrides, environment-variable credential names, platform filter, aggregate image cap, and source endpoint policy controls. All container modes use the shared archive and target-size limits from the Limits section.

For GitHub targets, a Scope picker selects exactly one target: one owner/name repository, repositories in an organization, repositories owned by a user, one gist, the authenticated user’s gists, or one user’s public gists. Only the fields and options relevant to the selected scope are shown. A personal repository uses its account login as the owner portion of owner/name; it is not also an organization target. The workspace also includes repository type and issue state filters where applicable; issue, release, and Actions artifact toggles; token environment variable; ref and pull request selectors; source API endpoint override; and explicit source endpoint policy toggles.

For Azure DevOps targets, the workspace includes endpoint, organization, project, repository, branch, pull request, token environment variable, token kind, build ID, release ID, wiki/artifact/log/release-artifact toggles, artifact and log size caps, and explicit source endpoint policy toggles.

For GitLab targets, the workspace includes project and group selectors, ref, merge request, pipeline ID, token environment variable, API endpoint override, subgroup/snippet/job artifact/job log/package toggles, and explicit source endpoint policy toggles.

For Gitea targets, the workspace includes repository, organization, user, ref, pull request, issue state, release, Actions artifact, Actions run, generic package, token environment variable, API endpoint, and explicit source endpoint policy controls.

Bitbucket Cloud and Bitbucket Data Center are separate targets. Cloud exposes repository and workspace scopes, project filtering, refs, pull requests, downloads, pipeline logs, snippets, Cloud credential modes, and an optional Cloud API endpoint. Data Center exposes its required REST API base path, project key, optional repository slug, ref or pull request, bearer or Basic credential environment variables, and source endpoint policy controls.

For object-store targets, the workspace includes S3, Google Cloud Storage, and Azure Blob Storage selectors, prefixes, token environment variable names, endpoint overrides where the CLI supports them, and explicit source endpoint policy controls.

During a scan it shows an animated activity indicator with text status, exit code state, started/completed/elapsed-time diagnostics, output availability, and cancellation status. The Logs view owns captured stdout/stderr, distinguishes errors and warnings with semantic colors and text, and highlights active search matches without changing the finding filter. While the scanner is running, the Run scan button becomes Cancel and Ctrl+C requests cancellation without closing the console.

Before launch, the workspace prepares the report output directory and moves any previous output aside. A readable report from the current scan replaces the previous report and is loaded even when one or more inputs could not be scanned. The status identifies it as a partial report and operational success remains false. Clean completion requires exit 0 with zero findings or exit 1 with one or more findings. An exit/report mismatch is reported as a failure while preserving the readable artifact. A missing or malformed report restores the previous report and loaded results.

The Scan page shows the loaded finding count and report path. The dedicated Findings view uses the same non-secret report readers as picket view and owns filtering, selected-row focus, finding details, and finding-specific yank text.

The Dashboard summary, finding details, and logs are selectable read-only panes so terminal users can select and yank exact text with the mouse or keyboard. Plain y and selection-based yank operations visibly flash the copied text; table views flash the copied row. Rule and file rows can filter the Findings view to the selected rule or file. Findings and file rows can open local files when the path exists on disk; Picket uses PICKET_EDITOR, then VISUAL, then EDITOR, with line-aware arguments for common editors, and falls back to the operating system default file opener. For terminal editors such as nvim, Picket leaves the full-screen console, runs the editor in the restored terminal, then returns to the console when the editor exits.

Inline Flow Mode

Flow mode renders interactive steps in the normal terminal buffer. Steps reserve terminal rows, complete to frozen scrollback output, and can open the same full-screen scanner console when a larger workspace is needed.

Use Flow mode when the user should keep terminal history visible, such as guided report selection or a short triage summary before returning to a scriptable shell session.

Testing

TUI changes require first-class Hex1b tests. Tests should run the actual widget tree in a headless Hex1b terminal, wait for rendered screen state, capture terminal snapshots, verify keyboard exits/navigation, and exercise practical desktop and narrow terminal dimensions.

Input and Contrast

The TUI follows WCAG 2.2 AA principles adapted to terminal UI:

• every action is keyboard reachable,
• focus is visible for controls, navigation, and focused rows,
• color is never the only status signal,
• normal text contrast targets at least 4.5:1,
• borders, focus indicators, and other non-text UI target at least 3:1,
• progress and long-running states include text status.