From 681216742213ff57e9c673fc287e51480c21e678 Mon Sep 17 00:00:00 2001 From: Hare Date: Sun, 31 May 2026 09:57:01 +0900 Subject: [PATCH] cli: create single binary architecture ticket --- .../artifacts/.gitkeep | 0 .../item.md | 50 +++++++++++++++++++ .../thread.md | 22 ++++++++ 3 files changed, 72 insertions(+) create mode 100644 work-items/open/20260531-005557-single-binary-insomnia-cli/artifacts/.gitkeep create mode 100644 work-items/open/20260531-005557-single-binary-insomnia-cli/item.md create mode 100644 work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md diff --git a/work-items/open/20260531-005557-single-binary-insomnia-cli/artifacts/.gitkeep b/work-items/open/20260531-005557-single-binary-insomnia-cli/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/work-items/open/20260531-005557-single-binary-insomnia-cli/item.md b/work-items/open/20260531-005557-single-binary-insomnia-cli/item.md new file mode 100644 index 00000000..fc7a341a --- /dev/null +++ b/work-items/open/20260531-005557-single-binary-insomnia-cli/item.md @@ -0,0 +1,50 @@ +--- +id: 20260531-005557-single-binary-insomnia-cli +slug: single-binary-insomnia-cli +title: CLI: clarify single-binary insomnia architecture +status: open +kind: task +priority: P2 +labels: [cli, architecture, nix] +created_at: 2026-05-31T00:55:57Z +updated_at: 2026-05-31T00:56:38Z +assignee: null +legacy_ticket: null +--- + +## Background + +The installed user-facing command is already `insomnia`, while the Cargo package/crate that owns it is still named `tui`. Headless CLI commands such as `insomnia memory lint` are starting to live in that same binary. This is acceptable short-term, but the architecture should be made explicit before more commands accumulate. + +The preferred product direction is a single user-facing `insomnia` binary that can run TUI screens and headless commands. The main downside is that headless commands inherit ratatui/crossterm and related dependencies, but binary size is not expected to dominate runtime memory compared with LLM clients, HTTP/TLS, JSON/session/memory processing, and spawned process orchestration. A single binary also improves distribution and “minimal standalone install” ergonomics. + +## Requirements + +- Decide and document the intended command architecture: + - one installed `insomnia` binary as the primary user-facing entry point; + - headless subcommands under that binary; + - TUI/interactive paths as subcommands or default modes; + - relationship to `insomnia-pod`. +- Refactor only if necessary to keep headless commands cleanly separated from terminal/TUI initialization. +- Ensure headless commands do not initialize ratatui, enter raw mode, connect Pod sockets, or spawn Pod processes unless explicitly requested by that command. +- Evaluate whether to rename the Cargo package/crate from `tui` to `insomnia`. + - If the rename is straightforward, implement it with scoped Nix/docs updates. + - If it is broad/risky, leave the rename as a follow-up and document the boundary. +- Keep installed command names stable unless a separate explicit decision says otherwise. +- Preserve Nix/Home Manager packaging expectations: installing the flake package should put the intended commands on `PATH`. +- Avoid introducing separate binaries for every headless command unless there is a measured startup/binary-size/runtime-memory reason. + +## Non-goals + +- Reworking the Pod daemon binary protocol. +- Removing `insomnia-pod` unless a separate architecture decision covers Pod process lifecycle. +- Feature-gating ratatui/crossterm for a headless-only build before there is a measured need. +- Large CLI UX redesign beyond clarifying the single-binary structure. + +## Acceptance criteria + +- The repository has a clear documented decision or implementation path for the single-binary `insomnia` CLI architecture. +- Existing TUI flows and headless command flows remain tested. +- If crate/package rename is implemented, Cargo/Nix/docs references are updated consistently. +- If crate/package rename is deferred, a precise follow-up or documented rationale explains why. +- `cargo fmt --check`, relevant `cargo test`/`cargo check`, `./tickets.sh doctor`, and `git diff --check` pass. diff --git a/work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md b/work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md new file mode 100644 index 00000000..29bbe814 --- /dev/null +++ b/work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md @@ -0,0 +1,22 @@ + + +## Created + +Created by tickets.sh create. + +--- + + + +## Decision + +Decision note from discussion: + +- Short-term direction: keep adding headless commands to the existing user-facing `insomnia` binary owned by the current `tui` crate. +- Product preference: a single standalone `insomnia` binary is easier to distribute and explain than many small binaries. +- Known tradeoff: headless commands inherit TUI dependencies such as ratatui/crossterm. This is acceptable until binary size/startup/runtime memory is measured as a real problem. +- Internal structure should still separate headless command dispatch from terminal/TUI initialization. +- Future cleanup: consider renaming the Cargo package/crate from `tui` to `insomnia`; treat it as part of this ticket only if the scope remains contained. + + +---