From 0dd48f61521b3a3cd9cdd3eb780223fb784fbb37 Mon Sep 17 00:00:00 2001 From: Hare Date: Sun, 31 May 2026 13:33:37 +0900 Subject: [PATCH] cli: plan insomnia pod runtime entrypoint --- .../item.md | 65 ++++++++++++------- .../thread.md | 17 +++++ .../artifacts/.gitkeep | 0 .../item.md | 63 ++++++++++++++++++ .../thread.md | 22 +++++++ 5 files changed, 142 insertions(+), 25 deletions(-) create mode 100644 work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/artifacts/.gitkeep create mode 100644 work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/item.md create mode 100644 work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/thread.md 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 index fc7a341a..364fe500 100644 --- a/work-items/open/20260531-005557-single-binary-insomnia-cli/item.md +++ b/work-items/open/20260531-005557-single-binary-insomnia-cli/item.md @@ -1,50 +1,65 @@ --- id: 20260531-005557-single-binary-insomnia-cli slug: single-binary-insomnia-cli -title: CLI: clarify single-binary insomnia architecture +title: CLI: migrate toward a single insomnia binary status: open kind: task priority: P2 labels: [cli, architecture, nix] created_at: 2026-05-31T00:55:57Z -updated_at: 2026-05-31T00:56:38Z +updated_at: 2026-05-31T04:32:30Z 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 repository currently installs two command names: -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. +- `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 -- 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. +- Plan and implement a staged migration toward a single primary installed `insomnia` executable. +- Target CLI shape: + - `insomnia` / `insomnia ` / `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 -- Reworking the Pod daemon binary protocol. -- Removing `insomnia-pod` unless a separate architecture decision covers Pod process lifecycle. +- 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 clarifying the single-binary structure. +- Large CLI UX redesign beyond the runtime entrypoint migration. +- Renaming `tui` package/crate in the first implementation step. ## 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. +- 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. 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 index 29bbe814..30831630 100644 --- a/work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md +++ b/work-items/open/20260531-005557-single-binary-insomnia-cli/thread.md @@ -19,4 +19,21 @@ Decision note from discussion: - 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. +--- + + + +## Decision + +Revised decision from user discussion: + +- The intended single-binary work is not merely “put headless subcommands in the existing `insomnia` binary”; it is to migrate the current `insomnia` + `insomnia-pod` two-binary architecture toward one primary executable. +- Pod runtime should remain a separate process. The unification is at the executable/entrypoint/packaging level. +- `insomnia-pod` does not need to remain as a long-term alias. It was not designed as a human-facing command. +- Prefer a normal subcommand `insomnia pod ...` for Pod runtime startup instead of a hidden `__pod-runtime` command. +- `tui` package/crate rename remains separate from binary unification unless it becomes necessary. + +Initial implementation should start by extracting the Pod runtime into a library entrypoint and adding `insomnia pod ...`; subsequent steps can migrate spawn defaults and remove `insomnia-pod` from packaging. + + --- diff --git a/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/artifacts/.gitkeep b/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/item.md b/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/item.md new file mode 100644 index 00000000..3795b69b --- /dev/null +++ b/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/item.md @@ -0,0 +1,63 @@ +--- +id: 20260531-043239-insomnia-pod-subcommand-runtime +slug: insomnia-pod-subcommand-runtime +title: CLI: add insomnia pod runtime entrypoint +status: open +kind: task +priority: P2 +labels: [cli, pod, nix] +created_at: 2026-05-31T04:32:39Z +updated_at: 2026-05-31T04:33:28Z +assignee: null +legacy_ticket: null +--- + +## Background + +Parent/umbrella ticket: `single-binary-insomnia-cli`. + +The project currently has two installed command names: + +- `insomnia` from the `tui` package for user-facing CLI/TUI/headless commands; +- `insomnia-pod` from the `pod` package for Pod runtime processes. + +The target direction is one primary executable, `insomnia`, with `insomnia pod ...` as the Pod runtime entrypoint. Pod runtime remains a separate process when spawned; only the binary/entrypoint is unified. + +This ticket is the first implementation step. It should add the new `insomnia pod ...` runtime entrypoint and share Pod runtime startup code, without yet requiring all internal spawn paths or packaging to drop `insomnia-pod` in the same diff. + +## Requirements + +- Extract the current `crates/pod/src/main.rs` runtime startup into a library-callable entrypoint in the `pod` crate. + - Keep existing Pod runtime flags/semantics. + - Preserve `INSOMNIA-READY` stderr handshake and detached process behavior. +- Keep the existing `insomnia-pod` binary only as a temporary transition wrapper if needed for tests/current spawn defaults. + - Do not present it as the long-term compatibility alias. + - Do not change Nix installed command set in this ticket unless it is mechanically necessary. +- Add `insomnia pod ...` to the existing `insomnia` binary in the `tui` crate. + - `insomnia pod --help` should reach the Pod runtime parser/help. + - `insomnia pod ` should invoke the same library entrypoint as the old runtime path. + - This means `insomnia pod` becomes reserved as a subcommand; a Pod literally named `pod` can still be addressed through explicit `--pod pod` if needed. +- Preserve existing user-facing TUI/CLI behavior for non-`pod` commands: + - `insomnia memory lint` remains headless and returns before terminal/TUI/Pod side effects; + - existing `insomnia ` / `--pod` / `--multi` / resume behavior remains unchanged except for the reserved `pod` subcommand. +- Do not yet switch `client::spawn_pod`, `SpawnPod`, or `RestorePod` default command resolution to `insomnia pod` unless doing so is small and fully tested. + - If not switched, create/fill a follow-up note for command resolution `program + prefix_args` migration. +- Do not rename the `tui` package/crate in this ticket. + +## Non-goals + +- Removing `insomnia-pod` from packaging in this first step. +- Keeping `insomnia-pod` as a long-term alias. +- Merging Pod controller into the TUI process. +- Reworking Pod protocol or CLI UX beyond the new runtime subcommand. +- Feature-gating TUI dependencies. + +## Acceptance criteria + +- `insomnia pod --help` works and uses the Pod runtime parser/help. +- `insomnia-pod --help` still works if the temporary binary remains. +- `insomnia memory lint` still runs headlessly without TUI/raw-terminal/Pod startup side effects. +- Existing TUI parser tests are updated for the reserved `pod` subcommand and preserve other positional Pod-name behavior. +- Pod runtime startup code has one shared library path rather than duplicated main logic. +- Follow-up work for switching internal spawn defaults and removing `insomnia-pod` packaging is recorded if not completed here. +- `cargo fmt --check`, focused `cargo test` for affected TUI/Pod CLI parsing, `cargo check -p tui -p pod -p client`, `./tickets.sh doctor`, and `git diff --check` pass. diff --git a/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/thread.md b/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/thread.md new file mode 100644 index 00000000..32d8ddea --- /dev/null +++ b/work-items/open/20260531-043239-insomnia-pod-subcommand-runtime/thread.md @@ -0,0 +1,22 @@ + + +## Created + +Created by tickets.sh create. + +--- + + + +## Plan + +Implementation plan: + +1. Move current `crates/pod/src/main.rs` startup logic behind a `pod` crate library entrypoint, leaving the existing binary as a thin temporary wrapper. +2. Add a reserved `pod` subcommand to the `insomnia` binary that delegates to the same Pod runtime entrypoint. +3. Keep internal spawn defaults and Nix installed commands unchanged in this first step unless the change is smaller than expected; the long-term plan is still to remove `insomnia-pod` after internal callers use `insomnia pod`. +4. Add/update parser tests so `insomnia pod` is reserved and `insomnia --pod pod` remains available for a Pod literally named `pod`. +5. Validate focused CLI/parser/runtime help behavior and affected crates. + + +---