Org KB Status and Version Check

[rucka]

Story Statement

As a developer using pair CLI
I want to check the status and version of my installed organizational KB
So that I can verify I'm using the correct and latest organizational standards

Where: pair CLI — pair kb status command

Epic Context

Parent Epic: CLI Knowledge-Service Integration #67
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

1. Given org KB v1.0.0 is installed and v1.2.0 is available on service
   When the developer runs pair kb status --org acme
   Then the CLI prints: org name, installed version (1.0.0), latest available (1.2.0), status "Update available", installed date, content summary (N skills, N guidelines)

2. Given org KB is at latest version
   When the developer runs pair kb status --org acme
   Then the CLI prints status "Up to date" with version and installed date

3. Given no org KB is installed
   When the developer runs pair kb status --org acme
   Then the CLI prints "Not installed" with latest available version and install hint

4. Given the developer has multiple orgs configured
   When they run pair kb status (no --org flag)
   Then the CLI prints a summary table for all configured orgs

5. Given the developer needs machine-readable output
   When they run pair kb status --org acme --json
   Then the CLI prints JSON: { "org": "acme", "installed_version": "1.0.0", "latest_version": "1.2.0", "update_available": true, "installed_at": "...", "connection": "ok" }

Business Rules

• Local version from .pair/.kb-meta.json
• Remote version from GET /api/v1/organizations/:slug/packages?limit=1
• Connection status: "ok" if service responds, "unreachable" if not (with cached last-known version)
• --json flag for CI/CD integration
• Status check should complete in <3s (timeout for service check)

Edge Cases and Error Handling

• Service unreachable: Show local info + "Service unreachable — cannot check for updates"
• Corrupted metadata: "KB metadata corrupted. Run pair kb install --force to repair."
• No orgs configured: "No organizations configured. Run pair kb config set to add one."

Definition of Done Checklist

Development Completion

• All 5 acceptance criteria implemented and verified
• Single-org and all-orgs status views
• --json flag for machine-readable output
• Graceful degradation when service is unreachable
• Unit tests for status logic
• Integration tests for various states

Quality Assurance

• Status check completes in <3s (with 2s timeout for service)
• All states displayed correctly (up to date, update available, not installed, unreachable)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: M(3)
Confidence Level: High
Sizing Justification: Read local metadata + one API call + format output. Simple composition of existing infrastructure.

Sprint Capacity Validation

Sprint Fit Assessment: Fits in single sprint
Total Effort Assessment: Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #157 (Install — .kb-meta.json), #156 (Auth — authenticated client), #159 (Config — org discovery)
Dependent Stories: #161 (Auto-notifications — reuses version check logic)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: Unit tests for status formatting; integration tests for each state (installed+update, up-to-date, not installed, unreachable)
Test Data Requirements: Various .kb-meta.json states, mocked service responses
Environment Requirements: Mock HTTP server, temp .pair directory

Notes

Refinement Insights: The --json flag is critical for CI/CD pipelines that need to detect KB currency.

Technical Analysis

Implementation Approach

Technical Strategy: Read .kb-meta.json for local state, query service for remote state, compare and format. Reuses auth HTTP client from #156 and version comparison from #158.
Key Components: Status command, local metadata reader, remote version checker, output formatter (table + JSON)
Data Flow: Read local meta → query remote latest → compare → format output

Technical Requirements

• Command: pair kb status [--org <name>] [--json]
• Service timeout: 2s for version check (graceful degradation on timeout)
• Table formatting: use existing CLI table utilities (chalk + manual alignment or cli-table)

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Slow service response blocks CLI	Low	Medium	2s timeout with graceful fallback

Spike Requirements

Required Spikes: None