gentle-shell-bridge 0.0.0-stage → 0.3.0

package/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

package/PRD.md

@@ -0,0 +1,144 @@
+# PRD — gentle-shell-bridge
+
+## Problem
+
+gentle-shell renders `/gentle:customize` from an array it builds itself and never exposes:
+the `ctx.ui.custom` factory constructs a `VisualCustomizeView` and returns a six-method
+adapter, so the rows exist only inside closures
+(`extensions/gentle-shell.ts:3550`, `:3554-3561`). Any plugin that wants a settings line
+therefore reaches for the only reachable moment — the factory call — and patches the host
+to get at the rows.
+
+That works once. It does not compose. Two independent wrappers each swap
+`Array.prototype.map` around the same factory: the inner wrapper installs its patch last
+and wins the capture, the outer wrapper captures nothing and degrades to a warning. With
+the naive approach only one plugin's rows ever appear, and neither plugin can tell the
+difference until someone looks at the menu. This is the collision the bridge exists to
+remove, and it is observed behaviour, not a hypothesis: the first prototype using
+duck-typing on the returned component silently injected nothing because the view is sealed
+behind the adapter.
+
+## Users
+
+- **Plugin authors** (loon, and any future gentle-shell plugin) who want a settings row
+  without owning an interception layer, a rebind lifecycle, or a conflict policy.
+- **gentle-shell users** who want every installed plugin's settings in the one menu they
+  already open, with no plugin silently missing.
+
+## Goals
+
+1. One interception layer per process, shared by every plugin.
+2. A small, typed contract: publish a provider, get rows; dispose to remove them.
+3. Rows that reflect live state, so the `●` marker never lies.
+4. No silent failure: every absent row has a reportable reason.
+5. One place to repair when gentle-shell's internals change.
+
+## Non-goals
+
+- Not a theme pack, banner engine or card renderer; it adds rows to existing categories.
+- Not a UI framework: no widgets, layout engine, or rendering of its own.
+- Not a configuration service for gentle-shell; gentle-shell keeps its own files.
+- Not an upstream replacement: if Pi or gentle-shell ships a row-provider hook, the bridge
+  should shrink to a thin adapter over it rather than compete.
+
+## Requirements
+
+| ID | Requirement | Contract | Status |
+| --- | --- | --- | --- |
+| R1 | `registerRows(provider)` accepts providers and returns a disposer that removes exactly that provider's rows. | `registerRows`, provider shape | Implemented; unit tests plus the end-to-end suite |
+| R2 | Providers are evaluated lazily when the menu is built, in subscription order, with a context carrying at least the active theme and the resolved config home. | Provider `rows(ctx)`, ordering | Implemented; `ctx` carries the factory's theme and the resolved config home, tested |
+| R3 | The bridge supports every row kind gentle-shell's renderer understands: `category`, `label`, `choice`, `preview`, `visible`, `keyhint`, `action`. | Row kinds | Implemented as typed pass-through fields; exercised against the fake host, not the real renderer |
+| R4 | A toggle is expressed as consecutive rows sharing `choice.setting`, and works with the renderer's own `●`/`○` and arrow/Enter handling. | Toggle recipe | Implemented; the end-to-end suite shows the `●` moving after `action()` on a fake host |
+| R5 | Arm-time state is idempotent: repeated `session_start`, rebinds and double loads never double-wrap or double-inject. | Idempotency | Implemented; tested across two `session_start` events and a double entry load |
+| R6 | A throwing provider loses its rows, is reported, and never breaks the menu or other providers. | Failure isolation | Implemented; tested per provider, with the failure reported by `/bridge-status` |
+| R7 | A diagnostics command reports providers, active backend, last capture outcome and last failures. | `/bridge-status` | Implemented as `/bridge-status`; formatter and entry tested, including store problems and duplicate settings from the last menu build |
+| R8 | Composition is stateless; persistence is the plugin's, with an optional namespaced store helper. | `createStore`, [docs/state.md](docs/state.md) | Implemented; `createStore` tested against temporary directories. One documented exception: a sidebar section's visibility is bridge-owned (see R12) |
+| R9 | `registerSection(section)` adds a card to gentle-shell's sidebar and returns a disposer that removes it, with no extra step from the plugin. | `registerSection`, section shape | Implemented; end-to-end over the public API against the fake rail, never in a real TUI |
+| R10 | Each registered section automatically contributes two consecutive rows to `Sections` (a readable label derived from its title or an explicit `rowLabel`, plus `shown`/`hidden`), reading and persisting the same value the rail renders; the id stays internal and never appears in a row. | Automatic toggle rows | Implemented; the menu, the persistence file and the next rail frame are asserted together — against the fake host and fake rail — including the label derivation and the collision rule |
+| R11 | A hidden section is neither rendered nor built (`lines()`/`meta()` not called); a throwing section loses only its own body and is reported. | S7 failure isolation | Implemented; pinned with call counters and `/bridge-status` section failures, against the fake host |
+| R12 | Section visibility persists in the bridge's own store, not the host's `visual-customization.json`, which rejects unknown keys. | `bridge-sections.json`, [docs/state.md](docs/state.md) | Implemented; the document shape is asserted byte-for-byte, and the reason for the separate file is recorded |
+| R13 | `registerCardStyle(style)` accepts `{ id, label, frame: { top, line, bottom }, preview?, order? }`, validates id/label/frame before storing, replaces in place on the same id, and returns a disposer that removes exactly that style. | `registerCardStyle`, frame contract | Implemented; validation, ordering, replacement and disposal are unit-tested, and the published-API path is exercised end to end |
+| R14 | A registered style joins the host's own `Card style` line (spliced in place, one coalesced line, the host's values untouched), with a `Bridge → card style` fallback line only when the host's line is not reachable; the selection is bridge-owned state, pressing a host value returns to native rendering, and a disposed style degrades to `native`/`missing`. | `bridge-card-style.json`, [docs/contract.md](docs/contract.md) §12 | Implemented; one bullet at a time, the way back, the fallback line and the missing-selection degrade are pinned against the fake host and reported by `/bridge-status` |
+| R15 | When a registered style is selected, the bridge repaints the conversation frames the host already drew — detection, title/hint extraction, one style at a time, width clipping, and a pass-through for `native`, for a missing selection and for any throw — and reports the frame outcome. | [docs/architecture.md](docs/architecture.md) §14 | Implemented; proven against a fake conversation built from real `shell-card.ts` output, plus the end-to-end suite through the public API. A downstream post-processor can override the frame, which `/bridge-status` states |
+| R16 | `registerTransform(transform)` accepts `{ id, order?, transform(lines, ctx) }`, validates the id and the function before storing, replaces in place on the same id and returns a disposer that removes exactly that transform; the conversation wrapper runs the card-style repaint first and then every transform in order, each receiving the previous output, clipping the result to the host width, isolating a throw or a non-lines return to that transform, and returning the host's own array when nothing changed; `/bridge-status` lists the pipeline in order with the last frame's outcome per transform. | `registerTransform`, [docs/contract.md](docs/contract.md) §13 | Implemented; ordering, replacement, disposal, identity, clipping, throw isolation and the status block are unit-tested, and the worked example's toggle is proven to restyle cards already on screen, with past and new cards byte-identical |
+
+Sixteen requirements are implemented and covered by the 367-test `node --test` suite, 26 of them
+end to end through the public API and the real extension entry. What is proven and what is not:
+
+- **Proven against a fake host.** The row side drives a fake menu host that models
+  `gentle-shell.ts:3550-3562`: injection, ordering, toggles, failure isolation and the
+  diagnostics lines.
+- **Proven against a fake conversation.** The card-style side drives a fake transcript built from
+  real `gentle-shell/lib/shell-card.ts` output at a fixed width, plus a fake `tui` that models Pi's
+  documented tree: detection, repaint, clipping, the pass-through paths, the disposal degrade, the
+  host line splice, the fallback line and the generation guard. The transform pipeline drives the
+  same conversation through the real wrapper: ordering, identity, clipping, per-transform throw
+  isolation and the `/bridge-status` block — plus the worked example's `Bash rendering` toggle, end
+  to end, where a card drawn before the switch and one drawn after it come out byte-identical.
+- **Proven against a fake rail.** The sidebar side drives a fake terminal that models
+  `lib/shell-sidebar.ts`'s state symbol and `parts` map plus the layout's card frame
+  (`lib/shell-sidebar-layout.ts:35-44,392-410`): section cards, ordering, the `Sections` rows,
+  the store file, hiding and failure isolation.
+- **Not proven in a running TUI.** Neither surface has been re-run inside a real Pi +
+  gentle-shell session through the package. In particular the sidebar's `tui` is acquired
+  through `ctx.ui.setWidget`, and whether a widget whose component renders no rows leaves the
+  editor area visually untouched is **unconfirmed**. R7's hook branch has never met a host
+  that exposes the registry it looks for.
+- The capture technique itself is proven in the real TUI by the reference probe, not by these
+  tests.
+- **The card-style repaint has not been seen in a live TUI.** It depends on the host's `float`
+  grammar and on Pi's component tree; both are cited, neither is observed at runtime here, and a
+  downstream post-processor can erase the frame — reported, not prevented.
+
+## Success criteria
+
+- Two independent providers coexist in one menu, each with its own rows and no lost
+  capture.
+- A toggle persists through `action()`, the menu re-renders, and the `●` moves to the
+  applied value.
+- No silent failure: an uncaptured menu, a broken provider or a duplicate `setting` is
+  visible in `/bridge-status`.
+- When gentle-shell changes its menu construction, exactly one module needs repair.
+- A plugin can add a card style with one call: the value appears on the host's own `Card style`
+  line, selecting it repaints every card the host drew, and selecting a host value or losing the
+  plugin returns the conversation to the host's rendering.
+- A plugin can apply a rendering choice to the WHOLE conversation with one call: the choice reaches
+  cards drawn before the switch, not only the next one, and the worked example proves that a bash
+  card drawn before and one drawn after are byte-identical.
+- The reference probe's observed result reproduces through the package against the fake host
+  that models the real call chain: a `Cards` category showing the injected line
+  `Card bash   ● activity ○ output`. It has not yet been re-run in the real TUI through the
+  package.
+
+## Risks and open questions
+
+- **Upstream hook availability.** If Pi or gentle-shell adds a supported row-provider
+  registry, the capture backend becomes dead weight; the contract should stay stable
+  across that switch. A hook backend now exists (`src/hook.ts`) and prefers a recognized
+  registry over patching, but no host has been observed emitting
+  `Symbol.for("gentle-pi.customize-row-providers")` — that branch is implemented and
+  unverified.
+- **Namespace policy.** Requiring namespaced `setting` names (`"Loon → Banner source"`)
+  avoids accidental merges but depends on authors complying; the bridge can warn on
+  duplicates but cannot rename rows without breaking identity.
+- **Whether the store belongs in the package at all.** It is the only piece that writes to
+  disk and the only piece a plugin could implement itself. Shipping it is a convenience
+  bet, recorded with its alternatives in [docs/state.md](docs/state.md).
+- **Diagnostics spelling.** Settled in code: the command is `/bridge-status`. Pi has no
+  built-in `/status`, and gentle-shell's commands live under the `gentle:` prefix, so a bare
+  `bridge-status` collides with neither. It has not yet been typed into a real host.
+- **Compatibility drift.** The capture depends on one constructor line and one adapter
+  shape; every gentle-shell upgrade is a potential silent break until an upstream hook
+  exists. The sidebar surface depends on the same class of internals: the state symbol, the
+  `parts` map and the hard-coded rail key order.
+- **The sidebar widget's visual footprint is unconfirmed.** Pi exposes no `tui` getter, so the
+  bridge acquires one through `ctx.ui.setWidget` and returns a component that paints nothing.
+  Whether that component leaves the editor area untouched has not been observed; if it does
+  not, the fix is the widget's rendering, not the contract.
+- **Sections cannot be interleaved with the native cards.** The host builds its status
+  sections inside a closure, so "after every native section" is the honest contract; a user
+  request to slot a section between `CHANGES` and `STATS` cannot be met without an upstream
+  change.
+- **Bridge-owned visibility is new state.** It is one namespaced file the bridge writes; a
+  future host that opens `VISUAL_SECTION_KEYS` would make it redundant and it should then be
+  migrated rather than duplicated.