Skip to content

[diagnostics] Migrate CLI diagnostics to stable CROCO_* codes #971

Description

@kang-heewon

Priority

P2

Problem

Croco documents and implements a stable diagnostic-code contract, but some CLI diagnostics still emit slash-form identifiers such as doctor/... and usage-dashboard/.... That splits the diagnostic surface and makes it harder for docs, agents, and support tooling to recognize failures consistently.

Evidence

  • docs/troubleshooting/diagnostics.md describes stable diagnostics in the CROCO_<AREA>_<NNN> shape.
  • packages/diagnostics-core/src/libs/DiagnosticCodes.ts defines the diagnostic code pattern and registry primitives.
  • packages/cli/src/commands/doctor.ts emits slash-form codes such as doctor/workspace-not-found, doctor/workspace-packages-empty, doctor/repository-core-drizzle-boundary, doctor/lambda-telemetry-flush-missing, and doctor/workspace-package-invalid.
  • packages/cli/src/commands/generateUsageDashboard.ts uses generated Problem codes such as usage-dashboard/tenant-required.
  • Closed issue dx: CROCO_* 진단 코드와 수정 예시를 표준화한다 #871 established the diagnostic code system; this is the follow-up migration for concrete CLI producers.

Desired outcome

CLI diagnostics use the stable CROCO_* registry consistently, while any legacy aliases are deliberate, documented, and tested.

Proposed implementation

  1. Inventory CLI commands that emit diagnostics or generated Problem codes.
  2. Assign registered CROCO_* codes for the current slash-form CLI diagnostics.
  3. Preserve backward compatibility only through explicit aliases if existing consumers depend on old codes.
  4. Update troubleshooting docs and tests so examples match the stable code format.
  5. Add a regression check that prevents new slash-form CLI diagnostic codes from entering the CLI surface unintentionally.

Acceptance criteria

  • CLI diagnostic outputs use registered CROCO_* codes for known failure modes.
  • Tests cover doctor and usage-dashboard diagnostic output.
  • Documentation examples match emitted codes.
  • Legacy slash-form codes are either removed or explicitly mapped as aliases with a migration note.

Validation

  • Run CLI command tests.
  • Run diagnostics-core tests.
  • Run a targeted static check or grep-based fixture proving no unregistered slash-form CLI diagnostic codes remain.

Scope boundaries

This should not redesign the diagnostics subsystem. It should migrate current CLI producers onto the existing stable-code contract.

Metadata

Metadata

Assignees

Labels

P2Priority 2 issuedeveloper-experienceDeveloper ergonomics and local workflow improvementsenhancementNew feature or requestllm-friendlyArchitecture and diagnostics designed for LLM-assisted developmentobservabilityTracing, metrics, lifecycle inspection, and debug visibility

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions