fbrcm

Imported from yumauri/fbrcm (AGENTS.md). Install upstream with npx skills add yumauri/fbrcm. Copyright stays with the author.

Repository conventions

Reuse and shared logic

• Before implementing parsing, filtering, sorting, terminal sizing, rendering, confirmation, or Remote Config transformations, search the repository for existing behavior and tests that already define the convention.
• Reuse existing shared and domain helpers whenever the required behavior matches. Do not create command-local copies or slightly different implementations of established behavior.
• When matching logic exists but is not accessible from the new caller, extract it to the lowest appropriate shared package and update existing callers instead of duplicating it.
• Add new local logic only when the behavior is genuinely specific to that component; keep the distinction explicit and covered by tests.

CLI tables

• Every human-readable CLI table must use the same Lip Gloss table style as the existing get, projects list, and cache list commands.
• Use lipgloss.NormalBorder(), a header separator, padded cells, the shared colors from internal/terminal/styles, alternating row backgrounds, and NoColorEnabled() support.
• Size every table and column to the narrowest width that fits its full content. Consult ops/shared.TerminalWidth() only when that natural table would overflow. Choose specific flexible columns and an explicit overflow policy for each: either crop with an ellipsis or wrap into multiline cells, while leaving other columns single-line and content-width whenever possible. Do not assume wrapping is preferred; when the requested behavior is unspecified, identify the likely flexible column and ask the user whether it should wrap or use an ellipsis. Never rely on the terminal to soft-wrap a wider table, and add natural-width plus narrow-terminal regression tests for every new table.
• Do not implement CLI tables with text/tabwriter, manually padded columns, or another ad hoc renderer.
• Keep machine-readable output behind the command's JSON flag and free of terminal styling.

CLI confirmations

• Every interactive CLI yes/no confirmation must use ops/shared.NewConfirmation; do not construct prompt-kit confirmations directly.
• Yes must be selected by default for every CLI confirmation. Keep that default centralized in the shared constructor.

CLI documentation

• Update docs/CLI.md in the same change whenever the CLI interface surface changes, including commands, subcommands, positional arguments, flags, defaults, output contracts, confirmations, or other user-visible behavior.
• Keep both the command tree and the detailed command sections synchronized with the implemented Cobra command structure and its tests.

CLI machine contract

• Every new executable CLI command must follow docs/cli-contract.md: it must participate in the global versioned --json envelope for success and failure, emit typed DTOs and structured problems, remain non-interactive in JSON mode, use the documented semantic exit statuses, register every successful data DTO with ops/contract (or explicitly register no successful data), and expose accurate capability metadata for arguments, flags, schemas, side effects, destructive behavior, idempotency, dry-run/draft support, stdin, and interaction requirements.
• Create machine errors as typed errors at their source and classify them with errors.As; never infer a problem code, category, retryability, or exit status from message wording. Collect non-fatal machine warnings in command context with structured details and safe remediation argv. Mutation DTOs must preserve selection breadth, matched-item count, and no-op provenance.
• Keep generated input and response schemas semantic: model enums, bounds, formats, mutual exclusions, conditional requirements, concrete stdin payloads, selector/filter/expression grammars, and reusable definitions. Runtime conformance tests must validate actual success, empty/no-op, typed failure, interaction, partial-publication, warning, redaction, and boundary envelopes against the published Draft 2020-12 schemas.
• Do not add command-local JSON formats, map[string]any machine payloads, human tables or usage text on JSON stdout, or prompts, editors, file pickers, and browser launches in JSON mode. Raw content must use the contract artifact DTO.
• For every new command or machine-contract change, update docs/CLI.md and docs/cli-contract.md, run go run ./cmd/schemagen, review the generated schemas and cli/app/testdata/contract_v1_capabilities.golden.json, and add success, failure, interaction, exit-code, and schema/golden coverage appropriate to the command.

Pre-1.0 contract evolution

• Until fbrcm version 1.0.0, breaking changes to persisted configuration and versioned machine contracts are allowed. Keep their format and contract version numbers at 1, and do not add backward-compatibility migrations solely for a pre-1.0 breaking change unless the user explicitly requests them.
• Version 1.0.0 freezes those versioned contracts. Treat compatibility, migrations, and version bumps as required design concerns for changes made after that release.

User-visible wording

• Use grammatically correct singular and plural forms in all CLI, TUI, error, log, and documentation text. Never display shortcuts such as project(s).
• Use the shared core/rc/display.FormatCount helper for counted nouns, and ensure the surrounding verbs, pronouns, and sentence structure are also correct for both singular and plural counts.
• When adding or changing counted text, search for related wording across the repository and add regression coverage for both singular and plural output where practical.

TUI mouse interactions

• Every selectable TUI item must support left-click selection. Double-clicking the same item must invoke the same action as Enter on that item.
• Every visible TUI button must support immediate left-click activation.
• Use the shared tui/components/mouseutil behavior for double-click detection and mouse adaptation instead of component-local timing or duplicate implementations.
• Keep mouse hit regions aligned with the rendered layout, including popup positions, borders, padding, scrolling, and wrapped or filtered rows. Add regression tests for new or changed mouse interactions.
• Keep mouse reporting disabled while the Logs panel is active and no mouse-interactive popup is open, so terminal-native log text selection continues to work. A mouse-interactive popup may temporarily enable reporting and must capture its mouse events without passing them to the Logs panel.

Remote Config groups

• Preserve empty and description-only parameter groups across all parameter mutations, filtering, condition cleanup, drafts, imports, merges, and promotions.
• Removing or replacing a group must be an explicit group-level operation. In the TUI, group removal must originate from the configured delete action. It opens confirmation when no draft exists and stages immediately when a draft already exists, consistent with other TUI edits.

Validation

• After every implementation change, run the repository-wide golangci-lint run before handing off the result. Do not rely on tests or go vet alone.