65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
---
|
|
id: 20260531-005557-single-binary-insomnia-cli
|
|
slug: single-binary-insomnia-cli
|
|
title: 'CLI: migrate toward a single insomnia binary'
|
|
status: closed
|
|
kind: task
|
|
priority: P2
|
|
labels: [cli, architecture, nix]
|
|
created_at: 2026-05-31T00:55:57Z
|
|
updated_at: 2026-05-31T12:15:50Z
|
|
assignee: null
|
|
---
|
|
|
|
## Background
|
|
|
|
The repository currently installs two command names:
|
|
|
|
- `insomnia` from the `tui` package: user-facing TUI/CLI entry point, including headless subcommands such as `insomnia memory lint`.
|
|
- `insomnia-pod` from the `pod` package: Pod runtime process entry point used by the TUI, restore flows, and `SpawnPod` to start detached Pod controller processes.
|
|
|
|
The desired direction is one primary installed executable, `insomnia`, that can act as both the user-facing CLI/TUI and the Pod runtime process entry point. Pod runtime should remain a separate process; the unification is about packaging/entrypoint, not merging TUI and Pod controller into one process.
|
|
|
|
The Pod runtime does not need a separate human-friendly `insomnia-pod` alias. It was never intended as a user-facing command. Prefer an explicit subcommand such as `insomnia pod ...` over a hidden `__pod-runtime` command.
|
|
|
|
## Requirements
|
|
|
|
- Plan and implement a staged migration toward a single primary installed `insomnia` executable.
|
|
- Target CLI shape:
|
|
- `insomnia` / `insomnia <pod>` / `insomnia --pod ...` / `insomnia --multi` keep current user-facing behavior;
|
|
- `insomnia memory lint ...` remains a headless command;
|
|
- `insomnia pod ...` invokes the Pod runtime using the existing Pod runtime flags/semantics.
|
|
- Pod runtime remains a detached child process when spawned by TUI/RestorePod/SpawnPod.
|
|
- `insomnia-pod` is not kept as a long-term compatibility alias. If a transition step leaves it temporarily, the follow-up/removal boundary must be explicit.
|
|
- Refactor Pod runtime startup so both old and new entrypoints, if temporarily present, share one library entrypoint.
|
|
- Update internal spawn/restore paths to support executable + prefix args, so `insomnia pod ...` can replace executable-only `insomnia-pod ...` invocations.
|
|
- Preserve the `INSOMNIA-READY` stderr handshake and detached process behavior.
|
|
- Preserve headless command invariants: headless subcommands must not initialize ratatui/raw terminal, connect Pod sockets, or spawn Pod processes unless requested by that command.
|
|
- Preserve Nix/Home Manager packaging expectations and make the intended installed command set explicit.
|
|
- Evaluate `tui` package rename separately. It is not required for runtime unification and should not be mixed into early migration phases unless it becomes mechanically unavoidable.
|
|
|
|
## Suggested phases
|
|
|
|
1. Extract Pod runtime startup into a library entrypoint and add `insomnia pod ...` dispatch.
|
|
2. Extend Pod runtime command resolution to support `program + prefix_args` and switch TUI/RestorePod/SpawnPod defaults to `current_exe() + ["pod"]` where appropriate.
|
|
3. Update Nix/devshell/docs so the canonical installed runtime path is `insomnia pod ...`; remove `insomnia-pod` from installed package outputs when internal callers no longer need it.
|
|
4. Consider `tui` package/crate rename as a later cleanup only after binary/process unification is stable.
|
|
|
|
## Non-goals
|
|
|
|
- Running Pod controller inside the TUI process.
|
|
- Keeping `insomnia-pod` as a long-term public compatibility command.
|
|
- Feature-gating ratatui/crossterm for a headless-only build before there is a measured need.
|
|
- Large CLI UX redesign beyond the runtime entrypoint migration.
|
|
- Renaming `tui` package/crate in the first implementation step.
|
|
|
|
## Acceptance criteria
|
|
|
|
- The repository has a concrete staged plan and implementation tickets for moving Pod runtime startup under `insomnia pod`.
|
|
- First implementation step lands without changing unrelated CLI behavior.
|
|
- `insomnia pod --help` reaches the Pod runtime parser.
|
|
- Existing headless command behavior (`insomnia memory lint`) remains headless.
|
|
- Internal callers can be migrated from `insomnia-pod` to `insomnia pod` through typed command resolution rather than shell-string parsing.
|
|
- Follow-up/removal of `insomnia-pod` is explicit if not completed in the first implementation step.
|
|
- `cargo fmt --check`, relevant `cargo test`/`cargo check`, `./tickets.sh doctor`, and `git diff --check` pass for each step.
|