Maintenance

The drift problem

Over time, .stack.toml and your source code can fall out of sync. Someone removes a Supabase import but forgets to run stack remove. Or a service gets added to the config but the SDK was never used. stack doctor --reconcile and stack remove --all-orphans catch and fix this drift.

stack doctor --reconcile

Scans your source files for imports that match known provider patterns, then compares the findings against .stack.toml. Reports three categories:

stack doctor --reconcile

┌  stack doctor --reconcile
│
◇  Scan complete
│
│  ✓ In sync:    supabase, resend
│  ⚠ Orphaned:  posthog     (in .stack.toml but no import found in src/)
│  ⚠ Untracked: clerk       (imported in src/ but not in .stack.toml)
│
└  Run `stack remove --all-orphans` to clean up, or `stack add clerk` to track.

The command is read-only — it reports but does not modify anything. Pair it with stack scan --json in CI to gate on drift.

stack remove --all-orphans

Rescans the source and removes orphaned services from local .stack.toml and MCP configuration, while attempting Phantom secret cleanup. It keeps upstream resources; it does not reuse a saved doctor --reconcile result.

# Preview first
stack doctor --reconcile

# Then remove orphans
stack remove --all-orphans

Using both in CI

Combine doctor --reconcile with scan --json for a full drift check on every push. See CI integration → scan in CI for an example workflow.