# M7.7 — `mem source` CLI

| Field | Value |
|---|---|
| Phase | M7 — Source connectors |
| Size | M — 1–3 days |
| Status | ⬜ Not started |
| Flags | — |
| Spec | inlined below |
| Blocks | M7.8, M7.10 |
| Depends | M7.6 |

## Goal

Provide CLI commands to manage source connectors: sync documents, check status,
list connectors, add/remove connectors.

## Facts (inlined — no spec read needed)

```
mem source list                          # all registered connectors + health
mem source status                        # drift report per connector, no mutations
mem source sync --all                    # sync all connectors
mem source sync --name homelab-vault     # sync one connector
mem source sync --name homelab-vault --dry-run  # show plan, no mutations
mem source add --kind paperless --name docs --config '{"base_url":"...","token":"..."}'
mem source rm --name old-source          # deregister + tombstone all chunks
mem source health                        # connectivity check per connector
```

**Output format.** CLI outputs human-readable tables by default, `--json` for
machine consumption. Example:

```
$ mem source list
NAME              KIND       DOCS  LAST SYNC            HEALTH
homelab-vault     obsidian    42   2026-08-26T10:00:00Z  ✅ reachable
homelab-paperless paperless  127   2026-08-26T09:00:00Z  ✅ reachable
infra-docs        git_repo    18   2026-08-25T20:00:00Z  ⚠️ pull failed

$ mem source status
NAME              NEW  CHANGED  UNCHANGED  REMOVED
homelab-vault       0        2         40        0
homelab-paperless   3        0        124        0
infra-docs          1        1         16        0
```

## Steps

1. Add `Source` subcommand group to clap CLI in `mem-cli/src/main.rs`.
2. Implement `cmd_source_list()` — load registry, health check each, tabulate.
3. Implement `cmd_source_status()` — load registry, run drift report per
   connector, tabulate.
4. Implement `cmd_source_sync()` — load registry, run sync engine for selected
   connector(s), report results.
5. Implement `cmd_source_add()` — validate kind, parse config, register in
   `connectors.yaml`, run initial health check.
6. Implement `cmd_source_rm()` — tombstone all chunks from connector, remove
   from `connectors.yaml`.
7. Implement `cmd_source_health()` — connectivity check per connector.
8. Add `--dry-run` to sync (show plan only).
9. Add `--json` flag for machine-readable output.

## Acceptance

- All subcommands execute without panic.
- `sync --dry-run` shows plan without mutations.
- `add` validates kind exists in registry before writing config.
- `rm` tombstones chunks and removes config entry.
- `status` shows drift without mutations.
- Exit codes: 0 on success, non-zero on failure.

## Verify

**Harness:** `VecConnector` registered in registry, temp connectors.yaml.

**Integration test** — `tests/it_source_cli.rs`:
1. `a1_list_shows_connectors` — register two connectors; assert list output
   contains both names and kinds.
2. `a2_status_shows_drift` — modify connector docs; assert status shows correct
   new/changed/unchanged/removed counts.
3. `a3_sync_processes_changes` — sync with changes; assert documents processed.
4. `a4_sync_dry_run_no_mutations` — sync --dry-run; assert no log entries written.
5. `a5_add_registers_connector` — add a new connector; assert it appears in list.
6. `a6_add_bad_kind_fails` — add with unknown kind; assert non-zero exit.
7. `a7_rm_tombstones_and_deregisters` — rm a connector; assert tombstone records
   written and connector removed from list.
8. `a8_health_reports_status` — assert health output includes reachable/unreachable.
9. `a9_json_output` — assert --json flag produces valid JSON.

**Command:** `cargo test --test it_source_cli`

**False pass:**
- Testing `list` without checking that connectors are actually registered (not
  just config parsed).

## Traps

- `sync --all` with a broken connector should not halt all syncs. Sync each
  independently, report failures per connector at the end.
- `rm` without `--yes` should prompt for confirmation (destructive operation).
- Don't write `connectors.yaml` atomically — a crash mid-write corrupts config.
  Write to temp file, then rename.

---

Background: [DESIGN.md](../DESIGN.md) — source connectors, CLI commands