gentle-shell-bridge 0.3.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/docs/contract.md

@@ -304,7 +304,7 @@ told once, on Pi's cross-extension bus.
 Object.freeze({
   schema: "gentle-shell-bridge/api", // identity, so a foreign payload is never mistaken for ours
   version: 1,                        // the major; a breaking change is a NEW symbol key
-  VERSION: "0.3.0",                  // the publishing release; informational only
+  VERSION: "0.3.1",                  // the publishing release; informational only
   registerRows,
   registerSection,
   registerCardStyle,                 // since 0.2.0; optional on an older published object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-shell-bridge",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared provider bus for gentle-shell's /gentle:customize settings rows: plugins register rows, the bridge owns the single interception layer.",
   "type": "module",
   "keywords": [
@@ -10,6 +10,18 @@
     "gentle-ai",
     "extension"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonasotoaguilar/gentle-shell-bridge.git"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "docs/contract.md",
+    "docs/state.md",
+    "docs/architecture.md",
+    "README.md"
+  ],
   "pi": {
     "extensions": [
       "./src/extension.ts"

package/src/api.ts

@@ -67,7 +67,7 @@ import { createStore } from "./store.ts";
 import { registerToolDesign } from "./tool-designs.ts";
 
 /** The release that published the object; informational, never the compatibility check. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.1";
 
 /** Identity of the object, so a foreign payload at the symbol is never mistaken for ours. */
 export const API_SCHEMA = "gentle-shell-bridge/api";

package/.codegraph/.gitignore

@@ -1,5 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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.