opendoor-plugin 0.1.0 → 0.4.0

package/README.md

@@ -19,15 +19,33 @@ Full feature spec: [`docs/feature-doorstop-plugin.md`](docs/feature-doorstop-plu
 
 ## Status
 
-The plugin is fully wired and green, in two halves:
+Requires **pi-web 1.202609.1 or newer** (browser plugin API v4 / server
+plugin API v3). Tested through **pi-web 1.202610.8**, which remains
+**additive** for this plugin — its browser v4/server v3 entries still load,
+with once-per-plugin deprecation diagnostics expected (see **Rollout** below
+for the upgrade order and the 1.202610.x sessiond-restart note). The Phase 3 pairing
+on top of that migration (public session metadata + session-list row
+labels, plan §2.1) stays on the same v4/v3 contracts. The package is one npm
+package (`opendoor-plugin`) that ships a PI WEB plugin AND a Pi extension:
+the plugin's browser/server halves below, plus the review-dispatch extension
+that starts labeled review conversations (`/opendoor-review`, see **Review
+dispatch (Pi extension)** below). The plugin loads on older hosts unchanged;
+only the extension's dispatch bridge, the public metadata, and the row
+labels need a 1.202610.x session daemon (see **Rollout**). The plugin is
+fully wired and green:
 
-- **Browser entry** (`src/pi-web-plugin.ts`, apiVersion 2, name `Opendoor`)
+- **Browser entry** (`src/browser/pi-web-plugin.ts`, apiVersion 4, name `Opendoor`)
   delegates to `createOpendoorBrowserContributions` in
-  `src/doorstop-contributions.ts`, which contributes:
+  `src/browser/doorstop-contributions.ts`, which contributes:
 
-  - **panel** `workspace.doorstop` (title **Requirements**, order 60) — the Lit
+  - **panel** `workspace.doorstop` (title **Requirements**, order 5 — deliberately
+    below the bundled Files panel's order 10, which answers every chat file link
+    unconditionally in the host's first-accepting-panel dispatch; this is what
+    makes the `fileOpenQuery` claim — chat links to doorstop item files open the
+    item's detail view in this panel instead of Files — reachable, at the cost
+    of the Requirements tab preceding Files) — the Lit
     body element `<pi-web-opendoor-panel-body>`, driven by the per-workspace
-    controller registry (`src/doorstop-panel.ts`): five vertical sections —
+    controller registry (`src/browser/doorstop-panel.ts`): five vertical sections —
     `project-actions` (title, Items/Findings toggle, Refresh / Run validation
     / Publish HTML), `item-list` (filters row + item rows with state chips),
     `item-details` (links in/out, references, extended attributes,
@@ -40,9 +58,14 @@ The plugin is fully wired and green, in two halves:
   - **actions** `view.doorstop` (mod+7) and `workspace.refresh-doorstop`
     (mod+shift+d);
   - **label** `doorstop-status` — the informational requirement-health counts
-    (async-cache idiom, feature spec §7.4).
+    (async-cache idiom, feature spec §7.4);
+  - **session-row label** `doorstop.review` — a compact indicator on session
+    rows carrying public `opendoor` metadata; clicking it reopens the
+    Requirements tab on the row's machine/workspace (works for unselected and
+    archived rows, no live Pi connection needed). See **Session metadata and
+    session-list row labels** below.
 
-- **Server entry** (`src/server-plugin.ts`, default export `PiWebServerPlugin`)
+- **Server entry** (`src/server-plugin.ts`, apiVersion 3, default export `PiWebServerPlugin`)
   contributes a workspace provider that claims only projects whose root
   contains a `.doorstop.yml` (cheap `fs.access` probe — everything else stays
   with the bundled Git provider) and serves a six-operation backend:
@@ -57,24 +80,42 @@ The plugin is fully wired and green, in two halves:
   server-side (the browser never sends shell strings), and runs through the
   host's `execFile()` helper with `cwd` = the workspace path, timeouts
   clamped to 8.5 s (the review+git pipeline shares one deadline budget under
-  the host's 10 s callback bound), and per-workspace run serialization.
+  the host's 10 s callback bound), and per-workspace run serialization. The
+  server entry permanently declares no `requires` and no `start()`: the
+  capability-driven `doorstop.ask-agent` dispatch it once carried was
+  unreachable by construction on a workspace-provider-contributing entry
+  (PI WEB rejects the provider-dependency capability cycle) and has been
+  retired. The review dispatch now runs in the Pi extension below.
+- **Pi extension** (`src/pi-extension/opendoor-review.ts`, bundled to
+  `dist/pi-extension/index.js` and declared by `pi.extensions`) registers
+  `/opendoor-review <UID> [instruction…]`. It publishes the shipped public
+  `opendoor` session metadata (`{ schema: 1, op: "review", uids }`) and asks
+  PI WEB's own per-session dispatch bridge to start an independent
+  conversation in the same registered project — the same spawn semantics and
+  delegation restrictions as `spawn_session`, with model/thinking inherited
+  from the initiating conversation. Every outcome (started / refused / no
+  bridge) is reported as a message in the initiating conversation. This is
+  the pathway the panel's **Start review session** entry drives (see **Review
+  dispatch (Pi extension)** below).
 
-Dispatch (per action, in `src/doorstop-panel-elements.ts`): when the workspace
+Dispatch (per action, in `src/browser/doorstop-panel-element.ts`): when the workspace
 is opendoor-owned with an active backend, the action sends a structured
-request via `context.backend.request("doorstop.run", …)` (the review-commit
+request via `context.peer.request("doorstop.run", …)` (the review-commit
 flag rides along when the setting is enabled; the "Changes since review"
-section fetches via `context.backend.request("doorstop.item-baseline", …)`)
+section fetches via `context.peer.request("doorstop.item-baseline", …)`)
 and the captured output appears in the panel's status bar (auto-expanded);
 the panel auto-rescans on completion. When the backend is absent (unpaired
 install, or a workspace the provider does not own), the action falls back to
 `terminal.runCommand()` with the same shell command, so output stays visible
 and auditable in the terminal.
 
-  `doorstop.run` and `doorstop.item-baseline`) shared by both halves, plus the
-  four git-action contracts (`doorstop.git-status`, `doorstop.git-stage`,
-  `doorstop.git-unstage`, `doorstop.git-commit`), live in
-  `src/doorstop-backend-contract.ts`. Later modules import these and must not
-  redefine them.
+The shared types + function-signature contracts live in
+`src/doorstop-contract.ts`; the two backend operation contracts
+(`doorstop.run` and `doorstop.item-baseline`) shared by both halves, plus
+the four git-action contracts (`doorstop.git-status`, `doorstop.git-stage`,
+`doorstop.git-unstage`, `doorstop.git-commit`), live in
+`src/doorstop-backend-contract.ts`. Later modules import these and must not
+redefine them.
 
 ## Workspace settings (`.pi-web/opendoor.json`)
 
@@ -92,6 +133,7 @@ bundled workspace-tasks plugin. The *server* entry's host-scoped knobs
   "version": 1,
   "publish": { "target": "./public" },
   "discovery": { "excludedDirectories": ["published", "vendor"] },
+  "showAdditionalAttribute": ["text", "component"],
   "commitAfterReview": false
 }
 ```
@@ -104,6 +146,18 @@ bundled workspace-tasks plugin. The *server* entry's host-scoped knobs
 - `discovery.excludedDirectories` — additional directory names the
   `.doorstop.yml` walk never enters (merged with the built-in
   `.git`/`node_modules` skips, max 16 names).
+- `showAdditionalAttribute` — array of attribute NAMES rendered in every
+  item-list row as `key: value` (values jsonish-quoted, joined with ` · `, in
+  the configured order). Entries may be any extended attribute key; an
+  attribute an item does not have is skipped for that row, and no unconfigured
+  attribute ever appears. The modeled `text` is special-cased: instead of a
+  `text: "…"` pair in the attribute column, the item body renders raw and
+  unquoted on its own indented second line below the row, clamped to two lines
+  with an ellipsis (the full body lives in the detail pane); it is skipped when
+  the item body is empty. Default `[]` leaves today's rows unchanged. Invalid
+  entries are dropped with a warning each, duplicates are deduplicated, the
+  list is capped at 16 names, and unknown keys are accepted (they simply match
+  nothing).
 - `commitAfterReview` — opt-in boolean (default `false`): when enabled on a
   paired workspace, the **Review** action's `doorstop review <uid>` is
   followed by a pathspec-limited git commit of the item file with the
@@ -150,12 +204,13 @@ bottom:
    all** button, and the **Git commit** control (message input + button); see
    **Git actions** below.
 2. **`item-list`** — a filters row (document chips, state filter, search)
-   above the item rows.
+   above the item rows; each row shows its level, UID, excerpt, any attributes
+   configured through `showAdditionalAttribute`, and its state chips.
 3. **`item-details`** — the selected item's full detail pane (unchanged).
 4. **`item-action-palette`** — the item actions (**Review**, **Clear suspect
-   links**, **Edit**, **Unlink**/**Link** + target UID inputs, **Ask agent**
-   menu), moved out of the detail pane so the row spans the panel at the same
-   height as the center-panel chat prompt footer. A muted "Select an item…"
+   links**, **Link** + target UID input, **Ask agent** menu), moved out of
+   the detail pane so the row spans the panel at the same height as the
+   center-panel chat prompt footer. A muted "Select an item…"
    placeholder keeps the palette at constant height while nothing is
    selected; the palette is hidden in the Findings view.
 5. **`status-bar`** — the run status row (badge, duration, **Dismiss**),
@@ -258,7 +313,18 @@ bottom:
     expanded status bar body.
 - **Ask the agent** menu: inserts ready-made prompts (explain, fix suspect
   links, draft child requirement, review readiness) into the session prompt
-  editor using the item's paths and state (feature spec §7.3).
+  editor using the item's paths and state (feature spec §7.3). **Start
+  review session** composes `/opendoor-review <UID>` plus the item context
+  into that same editor and needs no paired backend: sending it lets the
+  opendoor Pi extension start an independent review conversation whose list
+  row carries a **`firstUid +n` label** that reopens the Requirements tab on
+  the row's workspace — including for unselected and archived rows and with
+  no live Pi connection — landing on the item detail pane. After the insert
+  the panel's status bar shows a quiet `ok` **review dispatch** run row.
+  Without the extension installed the inserted text is still a
+  self-sufficient review instruction, so the review happens in the current
+  conversation; a refused dispatch is reported in the chat by the extension.
+  See **Session metadata and session-list row labels** in the feature spec.
 - Fingerprints and the requirement state are recomputed in the browser from
   the YAML files; everything mutating goes through the visible `doorstop`
   CLI — paired, headlessly via the server entry (output captured in the
@@ -271,14 +337,30 @@ bottom:
 ```sh
 npm install        # install dependencies
 npm test           # vitest (unit tests under src/**/*.test.ts)
+npm run test:coverage  # v8 coverage report
 npm run typecheck  # tsc --noEmit (strict)
 npm run build      # esbuild: dist/browser/pi-web-plugin.js + dist/server-plugin.js
-                   # (+ verbatim package.json manifest copy into dist/)
+                   # + dist/pi-extension/index.js, then the dist-root
+                   # package.json plugin manifest (see the build script header)
 npm run dev        # watch mode build
 ```
 
 ## Installing the plugin locally (id `opendoor`)
 
+The package carries two independently enabled halves: the **PI WEB plugin**
+(browser + server entries) and the **Pi extension** (`/opendoor-review`).
+The repository-root `package.json` is the npm-package-root manifest, so both
+halves come from ONE install through **Settings → Pi packages** (npm name,
+git/URL, or a local package source). The `ln -s dist` route below remains
+available for plugin-only development.
+
+### PI WEB plugin (browser + server entries)
+
+Install the package once — **Settings → Pi packages** with source
+`opendoor-plugin` (or this repository's path / git URL) — then enable
+**Opendoor** under **Settings → PI WEB plugins**. For a plugin-only local
+build the symlink route still works:
+
 ```sh
 npm run build
 ln -s "$(pwd)/dist" ~/.pi-web/plugins/opendoor
@@ -297,3 +379,54 @@ The manifest should list an `opendoor` plugin entry **with a
 `backendRevision`** (signing the paired server module). If `backendRevision`
 is missing, the server module failed to load — check the sessiond log; the
 plugin still works fully via the terminal fallback.
+
+### Review dispatch (Pi extension)
+
+Installing the package is what loads the extension; enabling the PI WEB
+plugin is a separate decision. After installing or updating the package on a
+machine, run `/reload` in each idle conversation so the `/opendoor-review`
+command is registered there (an ordinary Pi-resource change — no provider
+restart involved). The extension needs PI WEB **1.202610.x** for the
+session-dispatch bridge; on an older host it reports "requires PI WEB's
+session dispatch bridge" in the conversation and starts nothing. The panel's
+**Start review session** entry needs no paired backend — it only composes the
+command into the prompt editor.
+
+## Rollout (pi-web 1.202609.1)
+
+pi-web 1.202609.1 is a **hard break** for plugins — there is no
+compatibility shim in either direction: a v4/v3 host rejects v2/v1 plugin
+modules, and a v2/v1 host rejects the migrated v4/v3 modules. Upgrade the
+opendoor package and pi-web **together**, then restart
+`pi-web-sessiond.service` and reload the PI WEB page. During the transition
+the opendoor panel is **entirely absent** (both plugin entries rejected), not
+degraded. Federated gateways/targets must be upgraded in lockstep.
+
+### pi-web 1.202610.3 (and later 1.202610.x)
+
+Unlike 1.202609.1, release **1.202610.3** is **additive** for opendoor: the
+untouched v4/v3 plugin keeps loading on a v1.202610.3 host, with a
+once-per-plugin deprecation diagnostic (no removal date). No source changes
+were needed — the only mindful adaptation was a no-op `navigate` stub in the
+test fixtures (`src/test-fixtures.ts`, `src/browser/pi-web-plugin.test.ts`),
+because 1.202610.x made `navigate` a required member of
+`PluginRuntimeContext` / `WorkspacePanelContext`.
+
+Host upgrade order for 1.202610.x: refresh the pi-web checkout, then
+**manually restart `pi-web-sessiond.service`** — a UI/API autoreload alone
+is **not sufficient** (the release touched the session-serving paths
+heavily). The restart interrupts active sessions and terminals; reload the
+PI WEB page afterwards and confirm the manifest shows the opendoor entry
+with a `backendRevision`.
+
+#### Review dispatch and session-row labels (1.202610.x floor)
+
+The **Start review session** dispatch and the session-list row labels require
+a **1.202610.x** session daemon: that release introduced the public session
+metadata, the session-list label contribution, and the per-session dispatch
+bridge the extension emits on. The opendoor **server** entry declares no
+capabilities and loads across the whole supported range. `opendoor-plugin`
+**0.4.0** is the first release carrying the extension. Restart
+`pi-web-sessiond.service` once to load the server-side change, then run
+`/reload` in each idle conversation to load the extension's
+`/opendoor-review` command; the browser side only needs a page reload.