feat(cli): maintenance-windows topic + monitors test --config

[caballeto]

Summary

Two CLI features for v1 launch, both touching only the CLI repo (no
SDK / MCP / mono changes).

1. devhelm maintenance-windows topic — NEW

Maintenance windows let users suppress alerts during planned downtime.
Per the v1 launch decision, they're state, not infrastructure: imperative
CLI commands only. Intentionally not added to devhelm.yml /
config-loader, and intentionally not a Terraform resource — this PR
does not touch src/lib/yaml/** or any deploy-YAML schema.

Five new commands wire the existing /api/v1/maintenance-windows endpoints:

Command	API	Notes
maintenance-windows list	GET /api/v1/maintenance-windows	`--status active
maintenance-windows get <id>	GET .../{id}	strict envelope parse
maintenance-windows create	POST .../	`--start --end --reason {--monitor
maintenance-windows update <id>	PUT .../{id}	fetches existing window first to back-fill start/end on partial updates
maintenance-windows cancel <id>	DELETE .../{id}	semantic verb (you cancel scheduled / active windows, not "delete")

Divergence from the original task spec (constrained by the API):

• The API stores one monitorId per window (or null for org-wide), so
  --monitor is single-value and we added --org-wide instead of repeatable
  flags. There's no --component because the API doesn't model that.
• Status filter is active|upcoming (the only values the server understands).
  cancelled doesn't apply (cancel = DELETE → 404 on the list endpoint).
• CreateMaintenanceWindowRequest has no managedBy field on the wire,
  so we don't synthesise one client-side.

The package.json oclif.topics entry uses the requested copy:

Schedule downtime windows that suppress alerts during planned changes

2. devhelm monitors test --config <file> — NEW flag

monitors test <id> already runs a live probe against an existing monitor.
This adds the sibling flow:

• Pass a YAML or JSON file containing a CreateMonitorRequest payload.
• The CLI validates it locally against the generated Zod schema, with
  field-path error messages.
• On success, it strips the persistence-only fields and POSTs the
  MonitorTestRequest subset to the existing /api/v1/monitors/test
  endpoint so the user sees a real probe result for the proposed config.
• Mutual exclusion: passing both <id> and --config is a hard error.

Sample invocations

# List currently-active windows for one monitor
devhelm maintenance-windows list --status active --monitor <uuid>

# Schedule a 30-minute deploy window
devhelm maintenance-windows create \
  --start 2026-06-01T14:00:00Z --end 2026-06-01T14:30:00Z \
  --reason "Backend deploy" --monitor <uuid>

# Org-wide MAINTENANCE — no monitor scoping
devhelm maintenance-windows create \
  --start 2026-06-01T14:00:00Z --end 2026-06-01T14:30:00Z \
  --reason "DC failover drill" --org-wide

# Reschedule
devhelm maintenance-windows update <id> --start 2026-06-01T15:00:00Z --end 2026-06-01T15:30:00Z

# Cancel
devhelm maintenance-windows cancel <id> --yes

# Pre-save validation of a YAML monitor config
devhelm monitors test --config monitor.yml

# Same, but JSON + machine-readable output for CI
devhelm monitors test --config monitor.json --output json

Test plan

• npm run typecheck clean
• npm run lint clean
• npm test — 36 files / 998 tests pass (20 new tests across 3 new files)
• npm run build && oclif manifest — manifest registers all 5
  maintenance-windows:* commands
• Smoke --help against bin/dev.js for each new command + the
  modified monitors test
• Smoke negative paths: missing flags, mutually-exclusive flags,
  malformed config files, missing config files, invalid Zod payloads —
  all produce clear actionable errors
• CI green (will populate once the workflow runs)

Constraints honoured

• No changes to src/lib/yaml/** (deploy YAML / config-loader untouched)
• No changes to apiSchemas.generated.ts shape — only fed two existing
  request DTOs into extract-descriptions.mjs so flag help text tracks
  the OpenAPI spec
• Stayed inside cli/ — no SDK, MCP, or mono changes

Made with Cursor