pi-codex-marketplace 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Bridge Package for Codex and Claude Marketplace compatibility in Pi (`Pi 0.84.2`).
 
-> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace` opens a responsive Bridge Ledger with Global authority, guarded lifecycle transactions, and three-orthogonal Receipt reporting.
+> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace add <本機資料夾|GitHub 網址>` 註冊 marketplace → `install <編號>` 裝到當下最新並立刻在 Pi 可用。
 
 ## Install
 
@@ -26,64 +26,88 @@ Source types follow `docs/packages.md`: `npm:` for registry, `git:`/`https://` f
 
 Requirements: **Pi 0.84.2**, **Node >=22.19.0**, **macOS / Linux** (Windows not supported).
 
-## Usage — `/codex-marketplace` (聚合指令)
+## Usage — `/codex-marketplace`（純文字，無 TUI）
 
-Single aggregated command in Pi TUI, faithful to `prototype/tui-management-flow@c9107d2`:
+Nine subcommands, no arguments = 總覽：
 
 ```
 /codex-marketplace
+/codex-marketplace help
 ```
 
-TUI mode opens a persistent **Bridge Ledger** instead of a flat action list. The workspace presents the Global authority with its State Revision, counts, and health. Navigation is grouped into **Observe**, **Sources**, **Plugins**, and **Recovery & receipts**; every action is attached to a canonical object identity rather than dispatched from its translated label.
+| 子命令 | 行為 |
+|--------|------|
+| `add <路徑\|網址>` | 註冊 marketplace（本機資料夾、GitHub 完整網址、`owner/repo` 簡寫皆收），自動偵測 codex／claude 格式並告知 `偵測：<format> marketplace · N plugins`。重複註冊同來源被拒絕並提示下一步。Git 來源以安全線取得（`core.hooksPath=/dev/null`、`GIT_LFS_SKIP_SMUDGE=1`、`GIT_TERMINAL_PROMPT=0`），catalog 解析失敗明示錯誤、不註冊。私有 HTTPS repo 預設 credential-free（有權限也可能 401）——先以 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` 核准 credential helper 再 add（逐次生效、永不持久化），或改用 SSH 定位器；用法與範例見下方〈私有 Git repo：Credentialed Acquisition〉。 |
+| `list [名稱]` | 列出 plugins（編號／所屬 marketplace／狀態：可安裝・已裝啟用・已裝停用・unavailable＋原因），可帶 marketplace 名稱過濾。 |
+| `install <編號\|名稱>` | 裝到**當下最新**並自動啟用＋reload。成功話術如 `安裝 "name"（N skills：a, b, c）· 已重新載入生效`；同名衝突列出 `⚠ skill "b" 與既有同名，未投影（名稱衝突）`。**重複安裝＝重抓最新覆寫**（重裝＝更新，不報錯）。 |
+| `update` | 對全部已註冊 marketplace 重抓最新：有變化的 plugin 升到最新、無變化各自顯示「無變化」；整體以「已重新載入生效」收尾（有變時）。 |
+| `disable <名稱>` / `enable <名稱>` | 停用／啟用 plugin（enable 重新投影＋reload）。 |
+| `remove <名稱>` | 移除單支 plugin（不動 marketplace、不動來源資料）。 |
+| `forget <名稱>` | 移除整個 marketplace（含其全部安裝）。 |
+| `help` | 子命令清單。 |
 
-At 120/80 columns the Ledger uses navigation and detail panes; below 64 columns it switches to a single-column drill-down. Use arrows or `j/k` to move, `Enter` to open/activate, `Esc` to go back or cancel, `q`/Ctrl-C to exit, and `?` for help. On Validation sheets, `d` expands or collapses the full ordered disclosure after the initial verdict and finding counts.
+語意鐵則：
 
-Every mutation uses the shared transaction sequence **`Intent → Validation → Consent → Plan → Commit → Receipt`**. The target authority, State Revision, Validation Snapshot, separate Default-No confirmations, atomic commit boundary, and final Durable / Findings / Runtime outcomes remain visible across the flow. After every completed, declined, blocked, stale, or cancelled action, the workspace re-reads the authoritative state document and receipts before rendering again. Existing `list` / `inspect` and non-TUI summary paths remain non-interactive.
+- 安裝語意不分「安裝／啟用」兩步；輸出不得宣稱 reload 後 skill 已在 host 內可見（host 無內省 API），只說「已重新載入生效」。
+- catalog 內 git 型或不支援來源的 entry 一律 `unavailable` 並顯示原因；解析失敗顯示明確錯誤、不給裝。
+- 安裝成功後由指令層主動要求 reload；reload 失敗不影響已記錄狀態，下次 session start 或 `/reload` 仍生效。
+- `--no-skills` 啟動 Pi 不影響 Bridge 投影。
 
-The Ledger exposes these existing capabilities without changing their lifecycle semantics:
+### 私有 Git repo：Credentialed Acquisition（核准式取得）
 
-- **檢視 Global 分區** — single `Global Scope` (`{getAgentDir()}/codex-marketplace/state.json`) workspace. Shows `schemaVersion` (v3), `stateRevision`, registrations/installations, empty-state guidance, and provenance notes.
-- **註冊本地 / Git Marketplace…** — local or Git Marketplace Source Registration supporting dual Marketplace Formats (`codex` via `.agents/plugins/marketplace.json` and `claude` via `.claude-plugin/marketplace.json`, with codex precedence when both exist; missing both fails closed as `CATALOG_MISSING`). The derived `format` is fixed to the Registration record. Local uses canonical real path; Git uses Canonical Git Locator (credential-free) + Normalized Git Selector (`default` / `branch refs/heads/*` / `tag refs/tags/*` / `commit` lower 40/64 hex) → Resolved Revision. Validation Disclosure shows source, Marketplace name, Marketplace Format, State Revision, Validation Snapshot fingerprint, entry outcomes, findings summary. **Registration Confirmation** is snapshot+revision bound, Default No. Blocking Findings (Contained Path / Contained Symlink / Budget / duplicate Source Key / locator/selector trust) block the attempt; concurrent attempt is blocked by Attempt Fence (`FENCE-01`); changed State Revision or snapshot yields `Rejected as Stale` (`STALE-01/02`).
-- **安裝 Compatible Plugin…** — the Plugins ledger is keyed directly by stable **Marketplace Entry ID** (`/plugins/<序號>`), classification, skills, Invocation Policies, and resources; each compatible row exposes `Install Disabled` and `Install and Enable` without reopening a display-label Entry selector. Unavailable rows remain visible with their exact reason (unsupported source kind / entry-defined strict:false / parse failure / Invalid / Incompatible / Plugin ID collision). Compatibility Profile v2 classifies every Plugin atomically across Codex and Claude manifests as Compatible / Incompatible / Invalid; collision never changes classification. `Install Disabled` persists provenance without Activation Confirmation; `Install and Enable` discloses exact Plugin, skill list, Skill Resources, Invocation Policies, `Pi → Global` precedence and findings, then requires a separate **Default No** Activation Confirmation (bound to same snapshot+revision). Re-enabling a disabled Installation repeats validation and confirmation; disabling preserves its Installation ID.
-- **管理已安裝 Plugin（Enable / Disable）…** — toggle Installation State; disabling preserves provenance, enabling re-validates under current profile/ruleset/budget.
-- **檢視 Effective State 與 Projected Skills…** — read-time derived Effective State (Global Scope enabled installations) and Projected Skills with Runtime Skill Collision resolution (`Pi → Global Scope` exact name layering: pre-existing Pi skills reserve their names; non-colliding Bridge skills are projected; colliding Bridge skills within the same layer are unavailable). Whole-Plugin Blocking Findings block the Plugin; collision affects only that skill; `Available` is established only by independent host evidence (`AVAIL-01`).
-- **Refresh / 更新 Registration… (Marketplace Refresh → Update Candidate → Update Plan Checklist → Apply Update)** — Refresh is non-mutating and produces an Update Candidate when the validated source state differs (Plugin version alone does not; full-commit Git selector ref movement alone does not). Update Plan Checklist requires fresh **Registration Confirmation** + one explicit outcome per Installation (`update` / `disable` / `remove`, with `update` only when a Compatible candidate exists) + **Activation Confirmation** per enabled installation that remains enabled. Commit is a single atomic Lifecycle Operation replacing the Registration's Validation Snapshot and applying every disclosed consequence without mixing revisions.
-- **Rebind Registration…** — explicitly replace a Registration's locator/selector with fresh validation, Registration Confirmation, and a complete Update Plan for every existing Installation; prior activation consent never carries over.
-- **移除 Registration / Installation…** — Registration Removal discloses that all associated Installations will be atomically removed; Installation Removal removes the selected Installation.
-- **檢視 Receipt Journal…** — bounded immutable Receipt Journal (redacted, non-authoritative, with active recovery chain preservation across restarts); degraded journal surfaces `JOURNAL-01/02` without changing Persistence Failed outcome, and Repair State can atomically reconstruct validated lines while preserving parsed active chains. An exact active Pending Application chain exposes an Attempt Fence-held Retry Application transaction bound to State Revision and Validation Snapshot; missing snapshots remain visible but Retry is disabled in favor of a fresh validated intent, interaction-time drift fails closed without reload, reload failure remains Pending Application, and the chain resolves only after exact post-reload verification.
-- **執行 State Repair…** — explicit, fence-guarded verification for an unreadable state or an exact Persistence Indeterminate recovery chain; it stays visibly disabled for Pending Application, Persistence Failed, and healthy states because those require a different Recovery Action. It is never auto-retried.
+預設 `add`／`update` 對 Git 來源完全 credential-free：不執行任何 credential helper，因此「有權限卻失敗」時，私有 HTTPS repo 會以 401 失敗（並提示核准或改用 SSH）。若要核准 credential helper，以逗號分隔設定環境變數（**逐次生效、永不持久化**，`add` 與 `update` 共用同一核准來源）：
 
-Diagnostics throughout are shown with **synchronized ordering** `class → phase → target → pointer → rule` and **closed rule codes** (`CONT-01`, `COMP-02`, `FENCE-01`, `MIGRATE-01`, etc.), grouped by severity (`Blocking` / `Validation Warning` / `Operational Notice`). Closed **Recovery Actions** (`Retry` / `Revalidate` / `Refresh` / `Rebind` / `Retry Application` / `Disable` / `Remove` / `Repair State` / `Inspect`) list only the currently safe next step under the exact current State Revision. Every committed operation reports a **three-orthogonal Attempt Summary** (`Completed` / `Completed with diagnostics` / `Declined` / `Blocked` / `Rejected as Stale` / `Persistence Failed` / `Persistence Indeterminate` / `Pending Application`) with separate persistence, findings, and runtime (`Applied` / `Pending Application` / `none`) diagnostics. A post-commit `reload` is attempted immediately; if not host-verifiable at the expected revision it is reported as `Pending Application` and no inspection or Refresh supersedes it. Pending state is carried by active recovery chains (Retry Application and other Recovery Actions) and is reconciled at startup by producing a new reconciling receipt without implicit retry or rollback.
+```
+PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS='store, !f() { echo "username=${GITHUB_USER}"; echo "password=${GITHUB_TOKEN}"; }; f'
+/codex-marketplace add https://github.com/acme/private-mkt
+```
+
+Credentialed Acquisition 語意（安全線）：
+
+- 核准僅限該次呼叫（per-invocation）：環境變數逐指令讀取，**不寫入** Bridge State、設定檔或任何持久化位置；重開 session 後需重新設定。
+- 值為 git `credential.helper` 字串，逗號分隔、各項 trim、空項目忽略；未設定或空白＝未核准（行為與 credential-free 完全相同，安全線其餘禁制不變）。
+- 憑證與核准清單**永不**進入指令輸出、Bridge State、Canonical Git Locator（定位器）、Validation Snapshot（快照）或 cache identity（快取身份）——取得流程的 identity 判定與憑證完全無關。
+- 已核准 helper 仍被遠端拒絕（401）時，錯誤訊息提示檢查憑證；未核准時提示核准或改用 SSH。
+
+#### SSH 定位器：私有 repo 的替代路徑
+
+私有 repo 可以完全繞過此環境變數，直接用 SSH 定位器註冊（HTTPS 與 SSH 同屬允許的 credential-free 定位器）：
 
-## Bridge State storage & migration
+```
+/codex-marketplace add git@github.com:acme/private-mkt       # scp-like 簡寫（canonical：ssh://git@github.com/acme/private-mkt）
+/codex-marketplace add ssh://git@github.com/acme/private-mkt
+```
+
+前提（與既有 Acquisition Trust Base 一致）：
 
-Bridge State is the sole authority, stored in a **single Global Scope document** at `{getAgentDir()}/codex-marketplace/state.json` (`~/.pi/agent/codex-marketplace/state.json`):
+- host key 必須**預先存在** `~/.ssh/known_hosts`——安全線以 `StrictHostKeyChecking=yes` 只信任既有 host key，遇到未知或變更的主機金鑰直接拒絕，不會提示接受；
+- 憑證由 SSH agent 提供，整個取得過程不互動（`BatchMode=yes`）、無任何提示；
+- SSH 定位器本身仍維持 credential-free：不得內嵌密碼（`user:pass@` 拒絕）；憑證只能經由 SSH agent 或 Credentialed Acquisition 到達取得流程。
+
+## Bridge State storage
+
+Bridge State 是唯一權威，存於**單一 Global Scope 文件** `{getAgentDir()}/codex-marketplace/state.json`（`~/.pi/agent/codex-marketplace/state.json`）：
 
 ```jsonc
 {
-  "schemaVersion": 3,
-  "stateRevision": "1", // opaque monotonic (string "0" -> "1" -> "2" ...)
-  "registrations": [],  // immutable Registration ID = UUIDv4, with format: "codex" | "claude"
-  "installations": []   // Installed Plugins (enabled/disabled), each bound to a Validation Snapshot
+  "schemaVersion": 1,   // 固定，永不遷移
+  "registrations": [],  // immutable Registration ID = UUIDv4；sourceKind: "local" | "git"；git 帶 snapshot fingerprint（cache 位址）
+  "installations": []   // Installed Plugins（enabled/disabled），含 manifestName、skills 與 snapshot（git）
 }
 ```
 
-Only authoritative fields are persisted. `Effective State`, catalogs, compatibility results, diagnostics are **derived at read time**.
-
-- `State Revision` increments monotonically under file lock; commit is CAS-guarded by `expectedStateRevision` when supplied.
-- Writes are **atomic**: `write-to-temp → fsync → rename` + `fsync` parent dir + **file lock** (`.lock` sibling) + **WAL** (`state.json.wal`) + **read-after-verify**.
-- Cross-process concurrency is safe: lock serializes RMW; rename prevents torn reads; per-fingerprint `flock` guards Source Cache fetches with `p50 <200ms` on cache hit.
-- **WAL migration** (`src/bridge-state/migrate.ts`): supported forward migrations are applied atomically via WAL (`state.json.wal` fsynced before commit, replayed on the next read after a crash, cleaned after commit success). Migrations are **non-waivable, opt-in per version**, require no implicit activation, and preserve the active recovery chain. Schema v1 → v2 migration strips legacy `scopeOverrides` (non-empty overrides generate a non-blocking `MIGRATE-01` diagnostic finding without fail-closed) and normalizes Installation IDs (stripping legacy `global/` prefix). Schema v2 → v3 migration populates `format: "codex"` on existing registrations without data loss while newly written registrations store `format: "codex" | "claude"`. Unknown/older-without-path and newer (`schemaVersion > CURRENT_SCHEMA_VERSION`) versions are treated as **incompatible** — fail-closed, no auto-migration, no rollback. **Downgrade never writes back** (`isDowngradeAttempt` guard): a newer durable file is never overwritten by an older Bridge Package; the operator must update the package first.
-- Corrupted / unknown `schemaVersion` → classified as **corrupted / incompatible (Persistence Indeterminate)**, **never auto-rollback** — fail-closed. `validateSchema` and `migrateForward` enforce the closed set `CORRUPTED_JSON` / `INVALID_SCHEMA` / `INCOMPATIBLE_SCHEMA_VERSION` / `UNKNOWN_OLD_VERSION` / `MIGRATION_FAILED`.
+- **重建＝重置**：壞檔或不認識的格式一律重置為空、重新註冊重裝；沒有 repair、沒有 migration、沒有 State Revision。
+- 寫入防護：`write-to-temp → fsync → rename`（原子）＋ 檔案鎖（`.lock` sibling，last-write-wins、無 stale 偵測）＋ read-after-verify。
+- Git marketplace 的 snapshot fingerprint 是 **Source Cache 位址鑰匙**（`cache/entries/<fingerprint>`）；投影直讀該 cache entry，指紋不可替換成別種身份值。Cache 只對非 pinned entry 做 LRU 驅逐。
 
-See `src/bridge-state/` for `store.ts`, `atomic.ts`, `schema.ts`, `migrate.ts`, `paths.ts`.
+See `src/bridge/state.ts`（Minimal Bridge State）、`src/bridge-state/atomic.ts`（原子寫入＋檔案鎖）、`src/cache/source-cache.ts`。
 
 ## Support matrix
 
 | Dimension | Supported | Notes |
 |-----------|-----------|-------|
 | OS | **macOS**, **Linux** | Windows not supported (path containment, symlink, `flock` semantics are POSIX-only) |
-| Node | **>=22.19.0** | `engines.node` enforced; `npm-shrinkwrap.json` pins Pi 0.84.2 host |
+| Node | **>=22.19.0** | `engines.node` enforced |
 | Pi host | **0.84.2** | `peerDependencies` exact `0.84.2`; expected compatible range `^0.84.2` (devDeps). `pi-ai`/`pi-tui` peers `*` per Pi extension docs. |
 | Semantics | `pi install` / `pi -e` / `pi install -l` / `pi update` / `pi remove` / `pi list` / `pi config` | Single `pi` extension package; `files` ships `extensions/`, `src/`, `README.md`, `LICENSE` only |
 
@@ -93,34 +117,27 @@ Peer declaration (dual): **精確 `0.84.2`** in `peerDependencies` (exact host t
 
 - **Package**: `pi-codex-marketplace` published to **npm** as primary, **Git tag** `v*` as mirror.
 - **SemVer**: starts at `0.1.0`; `0.y` maintenance window until `1.0.0` signals a stable Bridge State contract.
-- **schemaVersion is bound to the package version**: bumping `schemaVersion` requires a package version bump and a WAL migration entry in `src/bridge-state/migrate.ts`; unknown `schemaVersion` is incompatible and never silently accepted.
 - **Publishing**: `v*` tag → CI **full matrix green** (below) is a **release gate** → `npm publish --provenance` (OIDC). `latest` tracks stable tags (`v0.*` stable line and later `v1.*`); `next` tracks pre-release tags. Provenance is required (`--provenance`) and verified post-publish by the publish workflow. See `.github/workflows/ci.yml` and `.github/workflows/publish.yml`.
-- **Maintenance windows**: `0.y` (current) may include additive schema migrations with WAL forward paths; `1.0` will freeze the `schemaVersion` contract and only accept forward-compatible additive changes via new `schemaVersion`s.
 
 ## Verification matrix (發版阻擋 gate)
 
 Every row is a **release blocker**: `v*` may not publish unless the full matrix is green.
 
-| Layer | Fixture | OS | Node | Pi host | What is covered |
-|-------|---------|----|------|---------|-----------------|
-| unit | **synthetic** | macOS + Linux | 22.19.0 | — | selector/locator normalization, Contained Path/Symlink, budget, compatibility atomic classification, precedence, collision, fence/sync ordering |
-| unit | **pinned** `SamWang32191/codex-plugins@98e78ca` | macOS + Linux | 22.19.0 | — | catalog parsing + validation against a real pinned marketplace snapshot (fingerprint-stable) |
-| unit | **adversarial** | macOS + Linux | 22.19.0 | — | malformed manifests, path-escapes, symlink loops, budget overflows, ID collisions, parser depth |
-| integration | synthetic | macOS + Linux | 22.19.0 | 0.84.2 | Bridge State atomic WAL + file lock + read-after-verify, Cache pinning/LRU/flock, Receipt Journal rebuild & prune (active chain) |
-| integration | pinned | macOS + Linux | 22.19.0 | 0.84.2 | Git acquisition (non-executing), Snapshot fingerprinting, Installation dual-path, Effective State, projection/collision, Refresh/Rebind/Removal WAL commit |
-| integration | adversarial | macOS + Linux | 22.19.0 | 0.84.2 | Source Drift (Blocking), Stale Snapshot rejection, Persistence Indeterminate fail-closed, Fence admission, Cache stale-snapshot never promotes |
-| E2E (highest seam — **TUI**) | synthetic | macOS + Linux | 22.19.0 | **0.84.2** | `/codex-marketplace` → Bridge Ledger custom component → structured object intent → transaction sheet → commit → authoritative reload → three-orthogonal Receipt |
-| E2E (highest seam — **TUI**) | pinned | macOS + Linux | 22.19.0 | **0.84.2** | full lifecycle (Register → Install Disabled / Install and Enable → Disable/Enable → Refresh → Update Plan Checklist → Apply Update / Rebind → Removal) with fence/cache/external observability |
-| E2E (highest seam — **TUI**) | adversarial | macOS + Linux | 22.19.0 | **0.84.2** | collision (`Pi → Global`), cache (`offline exact fingerprint hit` vs `stale never success`) |
+| Layer | What is covered |
+|-------|-----------------|
+| unit — 縫層 | `runCommand` 指令分派（add/list/install/update/disable/enable/remove/forget/help、重複註冊拒絕、重裝覆寫、衝突未投影清單、corrupt→重置、unavailable 顯示、git 重抓）、Minimal Bridge State 原子持久化 |
+| unit — 低層 | 雙格式 catalog 解析（codex＋claude、open 政策、unavailable entry）、git locator／source-key（fixed `default` selector）、contained path／symlink、collision、投影（exposure）、source-cache（store/hit/LRU/pin/flock）、git acquisition（mock executor） |
+| integration | 真 Pi 縫：extension 註冊 `resources_discover` → 投影 skillPaths（startup/reload 一致、trust flag 無關、被動不變異） |
+| E2E | `/codex-marketplace` 薄 Pi adapter：overview/help 輸出路由、corrupt 重置通知、reload 門控 |
 
-Fixtures: `tests/fixtures/synthetic/` (including synthetic Claude and mattpocock-shaped marketplace fixtures), `tests/fixtures/pinned/` (captured `SamWang32191/codex-plugins@98e78ca` snapshot + fingerprint manifest), `tests/fixtures/adversarial/` (path-escape / symlink-loop / budget-overflow / malformed frontmatter corpora). See `tests/acceptance/` for the matrix runner that enforces per-row gating (any row failure blocks publish).
+Fixtures: `tests/fixtures/synthetic/`, `tests/fixtures/pinned/`（captured `SamWang32191/codex-plugins@98e78ca` snapshot）、`tests/fixtures/adversarial/`。See `tests/acceptance/` for the matrix runner that enforces per-row gating (any row failure blocks publish).
 
 Run locally:
 
 ```bash
 npm run typecheck
 npm test                          # full matrix (unit + integration + E2E)
-npm run test:acceptance           # acceptance matrix only (three-tier × three-fixture)
+npm run test:acceptance           # acceptance matrix only
 ```
 
 ## Development
@@ -134,8 +151,8 @@ npm run test:acceptance
 
 ## Domain vocabulary
 
-Canonical terms are defined in [`CONTEXT.md`](./CONTEXT.md) — use them verbatim (Bridge Package vs Bridge Extension, Bridge State vs Effective State, State Revision, Registration ID, Source Key, etc.).
+Canonical terms are defined in [`CONTEXT.md`](./CONTEXT.md) — use them verbatim (Bridge Package vs Bridge Extension, Bridge State vs Effective State, Marketplace Source, Source Key, Validation Snapshot, Projected Skill, etc.).
 
 ## Changelog & Releases
 
-See [`CHANGELOG.md`](./CHANGELOG.md) and [GitHub Releases](../../releases). Version `0.1.0` is the first SemVer release; Git tags mirror npm versions (`v0.1.0` → `0.1.0`).
+See [`CHANGELOG.md`](./CHANGELOG.md) and [GitHub Releases](../../releases). Version `0.1.0` is the first SemVer release; Git tags mirror npm versions (`v0.1.0` → `0.1.0`).

package/extensions/pi/index.ts

@@ -3,253 +3,24 @@
  * Single extension "pi" package, Pi 0.84.2 compatible.
  *
  * Provides:
- * - /codex-marketplace command: persistent Bridge Ledger workspace
- * - Bridge State reading via the single-document store (Global)
- * - Startup Reconciliation on session_start
- * - Receipt Journal inspection & State Repair flows
+ * - /codex-marketplace command: Thin Pi adapter delegating to pure runCommand
+ * - resources_discover: Runtime Skill Exposure contributing Projected Skill paths
  *
- * Domain vocabulary follows CONTEXT.md (Bridge Package, Bridge Extension, Bridge State, State Revision, etc.)
+ * 極簡表面（#87）：無 TUI、無 ledger/journal/生命周期機械。指令輸出與 reload 旗標
+ * 完全由 runCommand 決定；reload 是唯一生效動作，失敗不影響已記錄狀態。
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
-import { stripTerminalSequences } from '@earendil-works/pi-tui';
 
-import { readBridgeStateSync } from '../../src/bridge-state/store.js';
-import type { ReadResult } from '../../src/bridge-state/types.js';
+import { runCommand } from '../../src/bridge/command.js';
 import { discoverProjectedSkillPaths } from '../../src/projection/exposure.js';
-import { runStartupReconciliation } from '../../src/reconciliation/startup.js';
-import type { AttemptReceipt } from '../../src/registration/receipt.js';
-import { runLocalRegistrationFlow } from './registration.js';
-import { runGitRegistrationFlow } from './git-registration.js';
-import { runPluginInstallationFlow, runPluginStateFlow } from './installation.js';
-import { runRefreshFlow, runRebindFlow, runRemovalFlow } from './lifecycle.js';
-import { runEffectiveStateView } from './effective-state-view.js';
-import {
-  runReceiptJournalView,
-  runRepairStateFlow,
-  runRetryApplicationFlow,
-} from './journal.js';
-import {
-  BridgeLedgerComponent,
-  buildBridgeLedgerModel,
-  loadBridgeLedgerSnapshot,
-  type LedgerActionIntent,
-} from './bridge-ledger.js';
-import { quoteTerminalText } from './terminal-presentation.js';
-import { renderTransactionSheet } from './transaction-sheet.js';
-import { uiText } from './ui-strings.js';
-
-const STARTUP_RECEIPT_THEME = {
-  fg: (_color: string, text: string) => text,
-  bg: (_token: string, text: string) => text,
-  bold: (text: string) => text,
-};
-
-export function formatStartupReceipt(receipt: AttemptReceipt): string {
-  return renderTransactionSheet({
-    step: 'Receipt',
-    actionLabel: receipt.operation,
-    authority: 'global',
-    target: receipt.trigger,
-    stateRevision: receipt.observedStateRevision ?? receipt.expectedStateRevision,
-    validationSnapshot: receipt.validationSnapshot,
-    receipt,
-  }, STARTUP_RECEIPT_THEME, 80).map(stripTerminalSequences).join('\n');
-}
-
-function requiredTarget(intent: LedgerActionIntent): string {
-  if (intent.targetId) return intent.targetId;
-  throw new Error(`Ledger action ${intent.actionId} requires a stable target identity`);
-}
-
-function requiredStateRevision(intent: LedgerActionIntent): string {
-  if (intent.stateRevision) return intent.stateRevision;
-  throw new Error(`Ledger action ${intent.actionId} requires a selected State Revision`);
-}
-
-function requiredMarketplaceEntryTarget(intent: LedgerActionIntent): {
-  registrationId: string;
-  entryPointer: string;
-  marketplaceEntryId: string;
-  validationSnapshot: string;
-} {
-  if (
-    intent.targetKind === 'marketplace-entry'
-    && intent.registrationId
-    && intent.entryPointer
-    && intent.targetId
-  ) {
-    if (!intent.validationSnapshot) {
-      throw new Error(`Ledger action ${intent.actionId} requires a bound Validation Snapshot`);
-    }
-    return {
-      registrationId: intent.registrationId,
-      entryPointer: intent.entryPointer,
-      marketplaceEntryId: intent.targetId,
-      validationSnapshot: intent.validationSnapshot,
-    };
-  }
-  throw new Error(`Ledger action ${intent.actionId} requires a stable Marketplace Entry identity`);
-}
-
-/** Localized state summary for TUI surfaces (the non-TUI list/inspect output stays canonical English). */
-function formatLocalizedStateSummary(result: ReadResult): string {
-  const scopeLabel = uiText('common.scope.global');
-  if (result.status === 'missing') {
-    const s = result.state!;
-    return uiText('cmd.state.empty', {
-      scope: scopeLabel,
-      version: s.schemaVersion,
-      revision: s.stateRevision,
-    });
-  }
-  if (result.status === 'ok') {
-    const s = result.state!;
-    const regCount = s.registrations.length;
-    const instEnabled = s.installations.filter((i) => i.installationState === 'enabled').length;
-    const instDisabled = s.installations.filter((i) => i.installationState === 'disabled').length;
-    const base = uiText('cmd.state.ok', {
-      scope: scopeLabel,
-      revision: s.stateRevision,
-      registrations: regCount,
-      enabled: instEnabled,
-      disabled: instDisabled,
-    });
-    return base;
-  }
-  if (result.status === 'incompatible') {
-    return uiText('cmd.state.incompatible', {
-      scope: scopeLabel,
-      error: quoteTerminalText(result.error ?? uiText('common.unknown')),
-    });
-  }
-  return uiText('cmd.state.corrupted', {
-    scope: scopeLabel,
-    error: quoteTerminalText(result.error ?? uiText('common.unknown')),
-  });
-}
-
-/** Dispatches only by stable semantic identity; display labels never select behavior. */
-export async function dispatchLedgerAction(
-  ctx: ExtensionCommandContext,
-  intent: LedgerActionIntent,
-): Promise<void> {
-  switch (intent.actionId) {
-    case 'observe-authority': {
-      const global = readBridgeStateSync();
-      ctx.ui.notify(formatLocalizedStateSummary(global), 'info');
-      return;
-    }
-    case 'observe-effective-state':
-      await runEffectiveStateView(ctx);
-      return;
-    case 'register-local':
-      await runLocalRegistrationFlow(ctx);
-      return;
-    case 'register-git':
-      await runGitRegistrationFlow(ctx);
-      return;
-    case 'refresh-registration':
-      await runRefreshFlow(ctx, {
-        registrationId: requiredTarget(intent),
-      });
-      return;
-    case 'rebind-registration':
-      await runRebindFlow(ctx, {
-        registrationId: requiredTarget(intent),
-      });
-      return;
-    case 'remove-registration':
-      await runRemovalFlow(ctx, {
-        targetKind: 'registration',
-        targetId: requiredTarget(intent),
-      });
-      return;
-    case 'install-disabled':
-    case 'install-and-enable': {
-      const entry = requiredMarketplaceEntryTarget(intent);
-      await runPluginInstallationFlow(ctx, {
-        registrationId: entry.registrationId,
-        entryPointer: entry.entryPointer,
-        marketplaceEntryId: entry.marketplaceEntryId,
-        targetState: intent.actionId === 'install-and-enable' ? 'enabled' : 'disabled',
-        expectedStateRevision: requiredStateRevision(intent),
-        expectedValidationSnapshot: entry.validationSnapshot,
-      });
-      return;
-    }
-    case 'enable-installation':
-    case 'disable-installation':
-      await runPluginStateFlow(ctx, {
-        installationId: requiredTarget(intent),
-        desiredState: intent.actionId === 'enable-installation' ? 'enabled' : 'disabled',
-        expectedStateRevision: requiredStateRevision(intent),
-      });
-      return;
-    case 'remove-installation':
-      await runRemovalFlow(ctx, {
-        targetKind: 'installation',
-        targetId: requiredTarget(intent),
-      });
-      return;
-    case 'view-receipt-journal':
-      await runReceiptJournalView(ctx);
-      return;
-    case 'inspect-receipt':
-      await runReceiptJournalView(ctx, {
-        receiptId: requiredTarget(intent),
-      });
-      return;
-    case 'repair-state':
-      await runRepairStateFlow(ctx, {
-        expectedStateRevision: intent.stateRevision,
-      });
-      return;
-    case 'retry-application':
-      await runRetryApplicationFlow(ctx, {
-        receiptId: requiredTarget(intent),
-      });
-      return;
-  }
-}
-
-// Closed helper to format state summary for disclosure
-function formatStateSummary(result: ReadResult, scopeLabel: string): string {
-  if (result.status === 'missing') {
-    const s = result.state!;
-    return `${scopeLabel}: empty · schema v${s.schemaVersion} · revision ${s.stateRevision} · 0 registrations · 0 installations`;
-  }
-  if (result.status === 'ok') {
-    const s = result.state!;
-    const regCount = s.registrations.length;
-    const instEnabled = s.installations.filter((i) => i.installationState === 'enabled').length;
-    const instDisabled = s.installations.filter((i) => i.installationState === 'disabled').length;
-    return `${scopeLabel}: revision ${s.stateRevision} · ${regCount} registrations · ${instEnabled} enabled / ${instDisabled} disabled`;
-  }
-  if (result.status === 'incompatible') {
-    return `${scopeLabel}: incompatible — ${quoteTerminalText(result.error ?? 'unknown schema')} (requires newer Bridge Package)`;
-  }
-  return `${scopeLabel}: corrupted — ${quoteTerminalText(result.error ?? 'unreadable Bridge State')} (Persistence Indeterminate, no auto-rollback)`;
-}
 
 export default function (pi: ExtensionAPI) {
-  pi.on('session_start', async (_event, ctx) => {
-    // Startup reconciliation: Global pass
-    try {
-      const recon = await runStartupReconciliation({});
-      if (recon.reconciled && recon.receipt) {
-        ctx.ui.notify(formatStartupReceipt(recon.receipt), recon.receipt.summary === 'Completed' ? 'info' : 'warning');
-      }
-    } catch {
-      // Non-blocking in extension bootstrap
-    }
-  });
-
   // Runtime Skill Exposure (ADR 0001): contribute Projected Skills through Pi's
   // resource-discovery seam at every startup and reload. Passive existence inspection over the
-  // current Effective State only — no fingerprint validation, no Bridge State mutation, and no
-  // Attempt Receipt. Missing snapshot material is skipped individually; discovery never fails
-  // the host's resource pass.
+  // current Effective State only — no fingerprint validation and no Bridge State mutation.
+  // Missing snapshot material is skipped individually; discovery never fails the host's
+  // resource pass.
   pi.on('resources_discover', async (_event, _ctx) => {
     try {
       return {
@@ -261,37 +32,18 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand('codex-marketplace', {
-    description: uiText('cmd.description'),
-    handler: async (args, ctx) => {
-      // Hybrid discovery/guided: support /codex-marketplace list|inspect <args> for non-TUI quick paths
+    description: 'codex / claude marketplace 管理（add/list/install/update/disable/enable/remove/forget/help）',
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
       const rawArgs = (args ?? '').trim();
-      if (rawArgs.length > 0 && (rawArgs.startsWith('list') || rawArgs.startsWith('inspect') || rawArgs === '--help' || rawArgs === '-h')) {
-        const global = readBridgeStateSync();
-        const g = formatStateSummary(global, 'Global Scope');
-        ctx.ui.notify(`${g}\n(完整導向流請於 TUI 內執行 /codex-marketplace)`, 'info');
-        return;
-      }
+      const argv = rawArgs.length > 0 ? rawArgs.split(/\s+/) : [];
+      const result = await runCommand(argv);
 
-      // Non-TUI fallback: notify with summary
-      if (ctx.mode !== 'tui' || !ctx.hasUI) {
-        const global = readBridgeStateSync();
-        const g = formatStateSummary(global, 'Global Scope');
-        ctx.ui.notify(`${g}\n互動流程需 TUI 模式（/codex-marketplace 於 TUI 內）`, 'info');
-        return;
+      if (result.output) {
+        ctx.ui.notify(result.output, 'info');
       }
-
-      // The workspace is deliberately reopened from a fresh snapshot after every action.
-      // Neither cached revisions nor presentation-derived eligibility become authority.
-      while (true) {
-        const snapshot = await loadBridgeLedgerSnapshot({});
-        const model = buildBridgeLedgerModel(snapshot);
-        const intent = await ctx.ui.custom<LedgerActionIntent | undefined>(
-          (tui, theme, _keybindings, done) =>
-            new BridgeLedgerComponent(model, theme, tui, done),
-        );
-        if (!intent) return;
-        await dispatchLedgerAction(ctx, intent);
+      if (result.reload) {
+        await ctx.reload();
       }
     },
   });
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.3.0",
-  "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — Global Bridge State, atomic persistence, and /codex-marketplace TUI",
+  "version": "0.5.0",
+  "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — 極簡 /codex-marketplace 純文字指令（add/list/install/update/disable/enable/remove/forget）、單一 Global Bridge State、當下最新安裝與即時投影",
   "type": "module",
   "keywords": [
     "pi-package",