fix(console): explain filtered configurations

[mohanagy]

Closes #203

Summary

• return aggregate discovered, ready, and need-attention counts for the bounded Console configuration catalog
• classify omitted candidates with safe reason categories while continuing to hide names, paths, values, parser details, and filesystem identities
• show the counts and repair guidance in the Console, including the zero-ready case
• preserve POSIX ownership/mode checks, Windows DACL verification, symlink/race/dedupe protections, exact selected-file binding, and first-run behavior
• document the private-file and bounded-directory requirements

TDD evidence

The existing unsafe-candidate contract was tightened first to require the missing aggregate fields. It failed on the prior implementation, then passed after the catalog/UI change. A separate Console shell contract and documentation contract were also observed failing before their matching UI/docs changes.

Validation

• npm test — 1,784 passed, 33 skipped (platform/fixture-gated)
• npm run test:core — 425 passed, 26 skipped
• npm run test:coverage — clean rerun passed; 95.65% statements, 91.93% branches, 98.66% functions
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack — 48 files verified
• npm run test:package — 26 passed

The first aggregate coverage attempt hit two unchanged timing/contention failures in upstream-manager-teardown and doctor. Both exact tests passed alone, and both passed in the unchanged full coverage rerun. No timeout, worker, skip, containment, or coverage setting was changed.

Security boundary

The browser receives only fixed reason enums and aggregate counts. Rejected candidate names, paths, configuration bytes, values, parser errors, file identities, and ACL details remain unavailable. No trust check or selected-file revalidation was weakened.

Summary by CodeRabbit

• New Features

  • The Console now reports counts for local configuration discovery (found), readiness (ready), and issues requiring review (need attention).
  • Attention reasons are grouped into clear categories (e.g., permissions, invalid settings, unsafe paths, duplicates, unreadable files).
  • When attention is required, the dashboard guides you to review the summary and prompts correcting the expected files before proceeding.
  • Rejected configuration details (names, paths, values, and parser errors) remain hidden.

• Documentation

  • Updated the Console --config local discovery documentation to document closed-fail behavior, platform-specific permission/ownership expectations, and safe first-time setup flow.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Console now categorizes rejected configuration candidates, reports aggregate discovery counts, hides sensitive rejection details, and renders attention summaries in the dashboard. Documentation and tests cover the updated discovery, redaction, permissions, and UI behavior.

Changes

Console discovery attention reporting

Layer / File(s)	Summary
Trusted catalog attention accounting src/console/console-config-metadata.ts, src/console/console-config-catalog.ts, tests/console-dashboard-application-service.test.ts	Trusted candidate reads now return categorized attention outcomes; catalog responses include discovered, ready, and attention counts with aggregated reasons. Tests cover permission, path, configuration, duplicate, unreadable, and redaction behavior.
Dashboard attention rendering src/console/console-assets.ts, tests/console-server.test.ts	The dashboard renders discovery counts and safe per-reason guidance, and directs refresh flow to resolve attention outcomes before showing setup or workspace views.
Discovery safety documentation docs/console-api.md, tests/oauth-console-threat-model-docs-contract.test.ts	Documentation and contract assertions describe bounded discovery, platform-specific trust checks, categorized failures, and rejected-candidate detail concealment.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Console
  participant discoverConsoleConfigCatalog
  participant readTrustedConfiguration
  participant Dashboard
  Console->>discoverConsoleConfigCatalog: discover local candidates
  discoverConsoleConfigCatalog->>readTrustedConfiguration: validate each candidate
  readTrustedConfiguration-->>discoverConsoleConfigCatalog: accepted config or safe reason
  discoverConsoleConfigCatalog-->>Dashboard: catalog counts and attentionReasons
  Dashboard->>Dashboard: render summary and refresh guidance

Loading

Possibly related PRs

• mohanagy/miftah#206: Introduces the trusted-config discovery pipeline extended by these catalog changes.
• mohanagy/miftah#223: Covers related Windows ACL and candidate-stage diagnostics.
• mohanagy/miftah#287: Modifies the same trusted discovery and ACL verification logic.

Poem

A bunny checks each file with care,
Counts the safe ones hiding there.
Bad paths get names, but secrets stay,
The dashboard guides the proper way.
Refresh, and hop onward! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the main change: console configuration discovery and filtering behavior.
Description check	✅ Passed	The description covers summary, security boundary, and validation, though it uses a non-template heading for security impact.
Linked Issues check	✅ Passed	The changes satisfy #203 by adding safe discovery counts, attention reasons, preserved trust checks, UI guidance, and documentation.
Out of Scope Changes check	✅ Passed	No clear out-of-scope changes are apparent; the docs, UI, metadata, and tests all support the stated configuration-discovery objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/203-visible-filter-diagnostics

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/console/console-assets.ts`:
- Around line 833-849: The pluralization in the attention entry rendering
appends an extra “s” to the already-plural “private file permissions” label.
Update the labels handling in the configurationCatalogAttention block so the
file-permissions entry does not receive the suffix for counts above one, while
preserving existing singular/plural behavior for all other labels.

In `@src/console/console-config-catalog.ts`:
- Around line 584-587: Update the catch-all handling around
consoleInitializedConfigMetadata and createConfigMigrationSource so failures
after file readability is established are recorded as "invalid-configuration"
rather than "unreadable". Preserve the "unreadable" label only for genuine read
or candidate-access failures, and keep the existing candidate-stage observation
and attention recording behavior otherwise.
- Around line 423-437: Update catalogAttention so the reason ordering is backed
by an exhaustively checked structure for ConsoleConfigCatalogAttentionReason,
ensuring every union member is represented and newly added reasons cause a
compile-time failure until included. Preserve the existing output order and
filtering behavior for zero counts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5a727a2a-e132-4205-9851-1330ceac6b86

📥 Commits

Reviewing files that changed from the base of the PR and between fcdf3a2 and 428249c.

📒 Files selected for processing (7)

• docs/console-api.md
• src/console/console-assets.ts
• src/console/console-config-catalog.ts
• src/console/console-config-metadata.ts
• tests/console-dashboard-application-service.test.ts
• tests/console-server.test.ts
• tests/oauth-console-threat-model-docs-contract.test.ts

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/console/console-config-catalog.ts (1)

375-380: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Classify post-read file changes as unreadable.

When identity and permissions remain valid but the size/content changes between handle.stat() and readFile(), this is a changing-file race—not an unsafe path. It currently increments unsafe-path and gives incorrect repair guidance. Map those mutation cases to unreadable; reserve unsafe-path for identity/path replacement.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/console/console-config-catalog.ts` around lines 375 - 380, Update the
post-read status classification in the identity and permission validation flow
so size/content mutations detected between handle.stat() and readFile() return
reason "unreadable". Keep "unsafe-path" only for identity or path replacement
cases, while preserving the existing "file-permissions" classification for
invalid permissions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/console/console-config-catalog.ts`:
- Around line 375-380: Update the post-read status classification in the
identity and permission validation flow so size/content mutations detected
between handle.stat() and readFile() return reason "unreadable". Keep
"unsafe-path" only for identity or path replacement cases, while preserving the
existing "file-permissions" classification for invalid permissions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a2d40381-449b-48b4-b091-0e8bafb9d277

📥 Commits

Reviewing files that changed from the base of the PR and between 428249c and 33d244c.

📒 Files selected for processing (4)

• src/console/console-assets.ts
• src/console/console-config-catalog.ts
• tests/console-dashboard-application-service.test.ts
• tests/console-server.test.ts