ticket: use base32 project record ids
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "CLI: migrate toward a single insomnia binary"
|
||||
state: "closed"
|
||||
created_at: "2026-05-31T00:55:57Z"
|
||||
updated_at: "2026-05-31T12:15:50Z"
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,27 @@
|
||||
Completed the umbrella migration from the previous two-command installed layout toward a single primary `insomnia` executable.
|
||||
|
||||
Completed phases:
|
||||
- `insomnia-pod-subcommand-runtime`: moved Pod runtime startup behind `pod::entrypoint` and added `insomnia pod ...` dispatch.
|
||||
- `spawn-through-insomnia-pod-subcommand`: changed internal spawn/restore defaults to typed runtime command resolution using current executable plus the `pod` prefix argument.
|
||||
- `remove-insomnia-pod-binary`: removed the long-term `insomnia-pod` binary/package/devshell/flake output.
|
||||
- Follow-up cleanup removed `INSOMNIA_POD_COMMAND` and `INSOMNIA_RESOURCE_DIR`, keeping the runtime command/config surface narrower.
|
||||
|
||||
Outcome:
|
||||
- The installed package exposes `bin/insomnia` only.
|
||||
- `insomnia pod ...` is the Pod runtime entrypoint; Pods remain separate processes.
|
||||
- Internal spawn/restore uses typed command construction rather than shell string parsing.
|
||||
- `insomnia-pod` is not kept as a compatibility alias.
|
||||
- Headless `insomnia memory lint` behavior remains part of the `insomnia` CLI surface.
|
||||
|
||||
Validation/evidence across completed phases included:
|
||||
- `insomnia pod --help`
|
||||
- focused parser/spawn/restore tests
|
||||
- `cargo fmt --check`
|
||||
- `cargo check -p tui -p pod -p client`
|
||||
- `nix build .#insomnia`
|
||||
- checks that `bin/insomnia-pod` is absent
|
||||
- `./tickets.sh doctor`
|
||||
- `git diff --check`
|
||||
|
||||
Follow-up intentionally remains separate:
|
||||
- `insomnia-crate-cli-owner` now tracks the architectural cleanup where the `insomnia` crate owns the product CLI/binary entrypoint and `tui` becomes a library implementation crate. That is not required for this umbrella's original single-installed-binary migration to be complete.
|
||||
@@ -0,0 +1,74 @@
|
||||
<!-- event: create author: tickets.sh at: 2026-05-31T00:55:57Z -->
|
||||
|
||||
## Created
|
||||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-05-31T00:56:38Z -->
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-05-31T04:32:30Z -->
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: close author: hare at: 2026-05-31T12:15:50Z status: closed -->
|
||||
|
||||
## Closed
|
||||
|
||||
Completed the umbrella migration from the previous two-command installed layout toward a single primary `insomnia` executable.
|
||||
|
||||
Completed phases:
|
||||
- `insomnia-pod-subcommand-runtime`: moved Pod runtime startup behind `pod::entrypoint` and added `insomnia pod ...` dispatch.
|
||||
- `spawn-through-insomnia-pod-subcommand`: changed internal spawn/restore defaults to typed runtime command resolution using current executable plus the `pod` prefix argument.
|
||||
- `remove-insomnia-pod-binary`: removed the long-term `insomnia-pod` binary/package/devshell/flake output.
|
||||
- Follow-up cleanup removed `INSOMNIA_POD_COMMAND` and `INSOMNIA_RESOURCE_DIR`, keeping the runtime command/config surface narrower.
|
||||
|
||||
Outcome:
|
||||
- The installed package exposes `bin/insomnia` only.
|
||||
- `insomnia pod ...` is the Pod runtime entrypoint; Pods remain separate processes.
|
||||
- Internal spawn/restore uses typed command construction rather than shell string parsing.
|
||||
- `insomnia-pod` is not kept as a compatibility alias.
|
||||
- Headless `insomnia memory lint` behavior remains part of the `insomnia` CLI surface.
|
||||
|
||||
Validation/evidence across completed phases included:
|
||||
- `insomnia pod --help`
|
||||
- focused parser/spawn/restore tests
|
||||
- `cargo fmt --check`
|
||||
- `cargo check -p tui -p pod -p client`
|
||||
- `nix build .#insomnia`
|
||||
- checks that `bin/insomnia-pod` is absent
|
||||
- `./tickets.sh doctor`
|
||||
- `git diff --check`
|
||||
|
||||
Follow-up intentionally remains separate:
|
||||
- `insomnia-crate-cli-owner` now tracks the architectural cleanup where the `insomnia` crate owns the product CLI/binary entrypoint and `tui` becomes a library implementation crate. That is not required for this umbrella's original single-installed-binary migration to be complete.
|
||||
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user