logseq/docs/agent-guide/084-logseq-cli-server-cleanup.md

# 084 — Replace `server status` with `server cleanup` for revision-mismatch processes

## Summary

This plan updates the CLI server command set by removing `server status` and adding `server cleanup`.

`server cleanup` will terminate discovered `db-worker-node` processes that are both:

- owned by `:cli`
- revision-mismatched with the current CLI revision

The implementation will reuse current `logseq-cli` and `db-worker-node` lifecycle primitives:

- server discovery from lock files (`logseq.cli.server/list-servers`)
- revision metadata persisted in locks by db-worker-node (`:revision`)
- shutdown/kill paths already used by server stop/restart flows

## Requested behavior changes

1. Remove `logseq server status --graph <name>`.
2. Add `logseq server cleanup`.
3. `server cleanup` kills only discovered `:cli`-owned server processes where `server revision != current CLI revision`.

## Current baseline

- `server` command entries are defined in `src/main/logseq/cli/command/server.cljs` and currently include `list/status/start/stop/restart`.
- CLI parse/build/execute routing is centralized in `src/main/logseq/cli/commands.cljs`.
- Running server discovery already includes revision in `src/main/logseq/cli/server.cljs` (`list-servers` returns `:revision`).
- Revision mismatch semantics already exist and use exact string comparison (`compute-revision-mismatches`).
- db-worker-node writes revision into lock metadata in `src/main/frontend/worker/db_worker_node_lock.cljs`; legacy locks may have missing revision.

## Product decisions (locked)

1. **`server status` is removed, not deprecated.**
   - No alias.
   - Parsing `server status` should fail as unknown command after removal.

2. **Mismatch rule remains exact string comparison.**
   - If `cli-revision != server-revision`, it is a mismatch.
   - `nil`/missing server revision is treated as mismatch.

3. **Cleanup scope is discovered servers in current data-dir.**
   - Source of truth is lock-file-backed discovery from `list-servers`.
   - We do not add global OS-wide process scanning for all possible data dirs.

4. **Cleanup ownership scope is `:cli` only.**
   - Cleanup targets only servers where `:owner-source` is `:cli`.
   - Mismatched servers owned by `:electron` (or other owners) are reported but not terminated.

5. **Termination strategy is graceful-first for eligible targets.**
   - Attempt graceful shutdown first.
   - Fallback to process kill if needed.

## CLI contract for `server cleanup`

### Command surface

- New command: `logseq server cleanup`
- No `--graph` required.
- Works with existing global options (`--data-dir`, `--config`, `--output`, etc.).

### Result shape (proposed)

Return structured data for stable JSON/EDN automation:

- `:cli-revision`
- `:checked` (count of discovered servers)
- `:mismatched` (count)
- `:eligible` (count of mismatched servers with `:owner-source :cli`)
- `:skipped-owner` (mismatched servers not owned by `:cli`)
- `:killed` (servers/pids successfully terminated)
- `:failed` (servers/pids that could not be terminated)

Human output should summarize counts and list failed targets if any.

## Implementation design

### 1) Remove `server status` wiring

- Remove `server status` entry from `command/server.cljs`.
- Remove `:server-status` branches in:
  - parse-time graph-required validation set
  - build-action dispatch
  - execute dispatch
- Remove status-specific formatter branch/tests.

### 2) Add `server cleanup` command entry and action

In `command/server.cljs`:

- Add entry `['server' 'cleanup']` with description and example.
- Add `build-action` branch for `:server-cleanup` (no repo requirement).
- Add executor `execute-cleanup`.

In `commands.cljs`:

- Route `:server-cleanup` in build-action and execute.
- Ensure graph-required command set excludes cleanup.

### 3) Add cleanup orchestration in `logseq.cli.server`

Introduce a new function (e.g. `cleanup-revision-mismatched-servers!`) that:

1. resolves CLI revision (`logseq.cli.version/revision`, passed from command layer)
2. calls `list-servers`
3. computes mismatches using existing exact compare helper
4. partitions mismatches into eligible (`:owner-source :cli`) vs skipped-owner targets
5. terminates each eligible mismatched server process
6. removes stale locks when PID no longer exists
7. returns structured result data

Implementation should reuse existing stop/shutdown logic where possible to avoid duplicate lifecycle behavior.

### 4) Ownership-aware termination behavior

Cleanup must not bypass ownership rules globally; it should only target mismatched servers owned by `:cli`.

Recommended approach:

- Filter mismatch targets to `:owner-source :cli` before termination.
- Reuse existing stop/shutdown flow for eligible targets.
- Keep existing owner-aware behavior unchanged for `stop`/`restart`.
- Report non-CLI mismatched servers in `:skipped-owner` for visibility.

### 5) Formatting and docs

- Add human formatting branch for `:server-cleanup` in `format.cljs`.
- Remove obsolete `:server-status` human formatting and associated tests.
- Update CLI docs and examples in `docs/cli/logseq-cli.md`.

## File scope (expected)

- `src/main/logseq/cli/command/server.cljs`
- `src/main/logseq/cli/commands.cljs`
- `src/main/logseq/cli/server.cljs`
- `src/main/logseq/cli/format.cljs`
- `src/main/logseq/cli/command/core.cljs` (if help grouping text needs update)
- `src/test/logseq/cli/commands_test.cljs`
- `src/test/logseq/cli/command/server_test.cljs`
- `src/test/logseq/cli/server_test.cljs`
- `src/test/logseq/cli/format_test.cljs`
- `cli-e2e/spec/non_sync_inventory.edn`
- `cli-e2e/spec/non_sync_cases.edn`
- `docs/cli/logseq-cli.md`

## TDD execution plan

1. Add failing parse/build tests for removing `server status` and adding `server cleanup`.
2. Add failing command execute tests for cleanup action wiring.
3. Add failing server lifecycle tests for mismatch selection and termination behavior.
4. Add failing formatter tests for new human cleanup output and remove status output expectations.
5. Implement command and server orchestration changes.
6. Update docs and cli-e2e inventory/cases.
7. Run focused tests, then full lint+test.

## Testing plan

### Unit tests

- `commands_test.cljs`
  - `server status` becomes unknown command.
  - `server cleanup` parses/builds/dispatches.
  - cleanup does not require `--graph`.

- `command/server_test.cljs`
  - cleanup execute returns structured summary.
  - mismatch semantics remain exact compare.

- `server_test.cljs`
  - cleanup kills only mismatched revision servers with `:owner-source :cli`.
  - mismatched servers owned by non-CLI owners are reported in `:skipped-owner` and remain untouched.
  - matching revision servers are untouched.
  - missing revision is treated as mismatch.
  - failures are reported in `:failed`.

- `format_test.cljs`
  - human cleanup output includes counts and failure lines.
  - status formatting tests removed/replaced.

### CLI E2E

- Remove `server status` coverage case.
- Add `server cleanup` coverage case (at least smoke path with zero or controlled mismatches).
- Update non-sync inventory command list under `:server`.

### Verification commands

```bash
bb dev:test -v logseq.cli.commands-test
bb dev:test -v logseq.cli.command.server-test
bb dev:test -v logseq.cli.server-test
bb dev:test -v logseq.cli.format-test
bb -f cli-e2e/bb.edn test --skip-build
bb dev:lint-and-test
```

## Risks and mitigations

- **Risk:** Ownership metadata may be missing/legacy (`:unknown`) and reduce cleanup coverage.
  - **Mitigation:** keep cleanup intentionally strict (`:cli` only) and report skipped-owner targets explicitly for operator follow-up.

- **Risk:** Legacy locks without revision cause aggressive cleanup.
  - **Mitigation:** keep behavior intentional and documented (`missing revision = mismatch`).

- **Risk:** Duplicate stop logic divergence.
  - **Mitigation:** reuse existing stop/shutdown flow for `:cli`-owned targets and keep ownership filtering in one cleanup helper.

## Acceptance criteria

1. `logseq server status ...` is no longer available.
2. `logseq server cleanup` exists and executes without `--graph`.
3. Cleanup terminates only discovered mismatch servers with `:owner-source :cli` (`server revision != CLI revision`).
4. Mismatched servers with non-CLI ownership are not terminated and are reported as `:skipped-owner`.
5. Matching-revision servers are not terminated.
6. Structured JSON/EDN output reports `checked/mismatched/eligible/skipped-owner/killed/failed` summaries.
7. Human output is clear and actionable.
8. Unit tests and relevant cli-e2e coverage are updated and passing.