pi-codex-marketplace 0.6.2 → 0.8.0

package/README.md

@@ -2,10 +2,12 @@
 
 Bridge Package for Codex and Claude Marketplace compatibility in Pi (`Pi 0.84.2`).
 
-> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace add <本機資料夾|GitHub 網址>` 註冊 marketplace → `install <編號>` 裝到當下最新並立刻在 Pi 可用。
+> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace add <本機資料夾|GitHub 網址>`（或 Shell 下 `npx pi-codex-marketplace add ...`）註冊 marketplace → `install <編號>` 裝到當下最新並在 Pi 可用。
 
 ## Install
 
+### Pi Extension（TUI / 互動環境）
+
 ```bash
 pi install npm:pi-codex-marketplace                    # Global package (writes to ~/.pi/agent/settings.json)
 pi install npm:pi-codex-marketplace -l                 # Project package location (.pi/settings.json; Pi host package setting only)
@@ -19,6 +21,17 @@ pi list                                                # List installed packages
 pi config                                              # Enable/disable resources
 ```
 
+### Headless CLI（Shell / CI/CD 自動化）
+
+```bash
+# 免安裝直接以 npx 執行
+npx pi-codex-marketplace [subcommand]
+
+# 或全域安裝使用
+npm install -g pi-codex-marketplace
+pi-codex-marketplace [subcommand]
+```
+
 Source types follow `docs/packages.md`: `npm:` for registry, `git:`/`https://` for git, and absolute/relative paths for local. Ephemeral runs use `pi -e <source>` (not `pi install -e`). This package declares a single `pi` extension entry (`extensions/pi/index.ts`) loaded via `jiti` and requires no build step.
 
 > [!NOTE]
@@ -53,6 +66,28 @@ Nine subcommands, no arguments = 總覽：
 - 安裝成功後由指令層主動要求 reload；reload 失敗不影響已記錄狀態，下次 session start 或 `/reload` 仍生效。
 - `--no-skills` 啟動 Pi 不影響 Bridge 投影。
 
+### Autocomplete（Pi 原生，TUI 限定）
+
+互動（TUI）模式下，`/codex-marketplace` 以 **Pi 原生 autocomplete** 提供兩層、狀態感知的候選。**純文字指令表面維持權威不變**：九個子命令、指令參數、輸出與語意完全不受 autocomplete 影響；RPC／JSON／print 模式根本不註冊 terminal-only provider。
+
+**第一層——九個根層子命令。** 輸入完整的 `/codex-marketplace` 後按 Tab，候選清單顯示全部九個子命令（`add`／`list`／`install`／`update`／`disable`／`enable`／`remove`／`forget`／`help`）與各自說明，支援不分大小寫的模糊搜尋。選取需要參數的子命令（`add`／`list`／`install`／`disable`／`enable`／`remove`／`forget`）會自動補上一個尾隨空格，可直接繼續輸入；`update` 與 `help` 不加。
+
+**第二層——再按一次 Tab 開啟狀態感知候選。** 需要參數的子命令套用後，**再按一次 Tab** 依當下 Bridge State 只列出當下可執行的選項（空集合不給假候選）；**不承諾自動重開 selector**（Pi 0.84.2 在套用候選後不會自動再開一層補完選單，鍵盤流程固定是「輸入 command → Tab 選子命令 → 需要參數時再按一次 Tab」）：
+
+| 子命令 | 候選範圍 | 歧義處理 |
+|--------|----------|----------|
+| `install` | 可安裝／可重裝的 plugin（**不含 Unavailable Entry**） | 名稱在完整 enumeration 唯一＝插入名稱；同名（含 unavailable sibling）＝插入 enumeration 編號（`#N`），描述顯示 `[marketplace]` 與狀態 |
+| `enable` | 僅**已停用**的 Installation | 名稱無法唯一解析的記錄不給候選 |
+| `disable` | 僅**已啟用**的 Installation | 同上 |
+| `remove` | 全部已安裝 plugin（不分啟用／停用） | 同上 |
+| `list` | Marketplace Registrations | 名稱無法唯一解析＝依序改插唯一可解析的 alias、其次 Registration id |
+| `forget` | Marketplace Registrations | 同上 |
+| `add` | **不提供 Bridge 候選**：Tab 委派 Pi 原生路徑 completion，Git locator 維持自由輸入 | — |
+
+補完只提議當下可執行的動作，候選反映最新 Bridge State，且**被動讀取**——按 Tab 絕不會重置或重寫損壞的 state 文件。其餘輸入（其他 slash 指令、一般文字、檔案／路徑補完）一律原樣委派 Pi 既有 provider；安裝本套件不影響任何其他指令的 autocomplete。
+
+> 沒有 custom TUI、沒有自動第二層 selector：所有操作也都可以照舊以純文字輸入完成，autocomplete 只是 discoverability 與輸入效率層。
+
 ### 私有 Git repo：Credentialed Acquisition（核准式取得）
 
 對私有 HTTPS repo，`add`／`update` **開箱即用**：預設會自動偵測本機已存在的憑證來源並逐次核准（**固定白名單**，不讀本機 gitconfig 的任意 helper；偵測結果只限該次呼叫、永不持久化）：
@@ -93,6 +128,61 @@ Credentialed Acquisition 語意（安全線）：
 - 憑證由 SSH agent 提供，整個取得過程不互動（`BatchMode=yes`）、無任何提示；
 - SSH 定位器本身仍維持 credential-free：不得內嵌密碼（`user:pass@` 拒絕）；憑證只能經由 SSH agent 或 Credentialed Acquisition 到達取得流程。
 
+## Headless Bridge CLI — `pi-codex-marketplace`
+
+Bridge Package 除了提供 Pi Extension TUI 指令，亦內建純 Node 輕量 CLI bin shim（`pi-codex-marketplace` / `npx pi-codex-marketplace`），專為 CI/CD 流程、自動化腳本與純 Shell 環境設計。無須啟動 Pi TUI 或 Pi runtime，即可直接管理 Marketplace 註冊與外掛安裝。
+
+### 執行方式
+
+```bash
+# 1. 無參數：總覽（列出已註冊 Marketplace、已安裝外掛與指令用法）
+npx pi-codex-marketplace
+
+# 2. 版本與說明
+npx pi-codex-marketplace --version    # 或 -v
+npx pi-codex-marketplace help
+
+# 3. 執行子命令（與 TUI 指令完全一致）
+npx pi-codex-marketplace add <路徑|網址>
+npx pi-codex-marketplace list [名稱]
+npx pi-codex-marketplace install <編號|名稱>
+npx pi-codex-marketplace update
+npx pi-codex-marketplace disable <名稱>
+npx pi-codex-marketplace enable <名稱>
+npx pi-codex-marketplace remove <名稱>
+npx pi-codex-marketplace forget <名稱>
+```
+
+### 九個子命令一覽
+
+| 子命令 | 行為 |
+|--------|------|
+| `add <路徑\|網址>` | 註冊 marketplace（本機資料夾、GitHub 完整網址、`owner/repo` 簡寫或 SSH 定位器），自動偵測並回報格式。重複來源拒絕。私有 HTTPS repo 支援固定白名單自動偵測與 `PI_CODEX_MARKETPLACE_CREDENTIAL_HELPERS` 環境變數。 |
+| `list [名稱]` | 列出 plugins（編號／所屬 marketplace／狀態：可安裝・已裝啟用・已裝停用・unavailable＋原因），支援 marketplace 名稱過濾。 |
+| `install <編號\|名稱>` | 裝到當下最新並自動啟用。重複安裝＝重抓最新覆寫（重裝＝更新）。衝突時提示同名未投影警告。 |
+| `update` | 對全部已註冊 marketplace 重抓最新並更新有變化的外掛。 |
+| `disable <名稱>` / `enable <名稱>` | 停用／啟用 plugin。 |
+| `remove <名稱>` | 移除單支 plugin（不動 marketplace 與來源資料）。 |
+| `forget <名稱>` | 移除整個 marketplace 及其全部安裝。 |
+| `help` | 輸出子命令清單與用法。 |
+
+### 輸出與退出代碼契約（Output & Exit Contract）
+
+CLI 遵循嚴格的標準命令列契約，確保 CI/CD 與腳本整合的確定性：
+
+- **標準輸出（stdout）**：所有正常操作輸出（總覽、說明、版本、查詢清單、成功訊息）寫入 `stdout`，退出代碼為 `0`。
+- **標準錯誤（stderr）**：所有錯誤情況（未知子命令、缺少或非法參數、重複註冊、目標不存在或歧義、Git 取得失敗等）寫入 `stderr`，退出代碼為非零（`1`）。
+- **絕對免提示（Never prompt）**：全流程不發起任何終端互動提示（no interactive prompts），遇到歧義或錯誤立即明確報錯並退出，背景執行安全無虞。
+
+### 狀態生效時機（Same-State Caveat）
+
+- **單一 Global Scope 一致性**：CLI 與 Extension 共用相同的 `getAgentDir()` 與 Bridge State 儲存位址（`~/.pi/agent/codex-marketplace/state.json`），完全支援 `PI_CODING_AGENT_DIR` / `PI_AGENT_DIR` 環境變數覆寫。
+- **無 In-process Reload 提示語轉換**：CLI 執行於 Pi 外部獨立 Node 行程，無 Pi runtime 內部的即時 reload 機制（`ctx.reload`）。狀態變更指令（`install`、`enable`、`update`）輸出將 TUI 的「已重新載入生效」替換為：
+  ```
+  已寫入 Bridge State · 下次 pi session／/reload 生效
+  ```
+- **投影時機**：CLI 寫入的變更已持久化至 Bridge State，將在下次啟動 Pi session 或於 Pi TUI 內執行 `/reload` 時，經由 Pi host 資源發現接縫（`resources_discover`）自動完成技能投影。
+
 ## Bridge State storage
 
 Bridge State 是唯一權威，存於**單一 Global Scope 文件** `{getAgentDir()}/codex-marketplace/state.json`（`~/.pi/agent/codex-marketplace/state.json`）：
@@ -118,7 +208,7 @@ See `src/bridge/state.ts`（Minimal Bridge State）、`src/bridge-state/atomic.t
 | OS | **macOS**, **Linux** | Windows not supported (path containment, symlink, `flock` semantics are POSIX-only) |
 | 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 |
+| Semantics | `pi install` / `pi -e` / `pi install -l` / `pi update` / `pi remove` / `pi list` / `pi config` ＋ `npx pi-codex-marketplace` / `bin/pi-codex-marketplace.js` CLI | Single `pi` extension package + headless CLI bin; `files` ships `bin/`, `extensions/`, `src/`, `README.md`, `LICENSE` only |
 
 Peer declaration (dual): **精確 `0.84.2`** in `peerDependencies` (exact host that this version was validated against) + **預期 `^0.84.2`** in `devDependencies` (range expected to remain compatible). `pi-ai` and `pi-tui` remain `*` because they are bundled by Pi.
 
@@ -137,7 +227,7 @@ Every row is a **release blocker**: `v*` may not publish unless the full matrix
 | 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 門控 |
+| E2E | `/codex-marketplace` 薄 Pi adapter 與 `pi-codex-marketplace` CLI 適配層（overview/help、--version、雙格式 add/list、install/update、lifecycle 停用啟用移除、狀態變更 reload 提示轉換、確定性退出碼與環境隔離） |
 
 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).
 

package/bin/pi-codex-marketplace.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { register } from "node:module";
+
+try {
+  register("./ts-resolver.mjs", import.meta.url);
+} catch {
+  // Module registration unsupported or already active
+}
+
+const { runCli } = await import("../src/cli/index.js");
+const code = await runCli(process.argv.slice(2), process);
+process.exitCode = code;

package/bin/ts-resolver.mjs

@@ -0,0 +1,15 @@
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context);
+  } catch (err) {
+    if (specifier.endsWith(".js")) {
+      const tsSpecifier = specifier.slice(0, -3) + ".ts";
+      try {
+        return await nextResolve(tsSpecifier, context);
+      } catch {
+        // Fall back to original error
+      }
+    }
+    throw err;
+  }
+}

package/extensions/pi/autocomplete.ts

@@ -0,0 +1,90 @@
+/**
+ * Narrow Bridge autocomplete provider — thin Pi adapter (TUI session only) (#119, #121–#124).
+ *
+ * Pi 0.84.2's built-in combined provider completes the slash-command name and inserts a
+ * trailing space without exposing empty-prefix argument completion (root subcommands) when
+ * the editor holds exactly `/codex-marketplace`. This wrapper intercepts that exact editor
+ * content and presents the nine root candidates. It also owns the second-level argument
+ * contexts (`install` #122, the Installation lifecycle `enable` / `disable` / `remove` #123,
+ * and the Marketplace Registration `list` / `forget` #124) on forced (Tab) requests, which
+ * Pi 0.84.2 routes to file completion instead of slash-command argument completion (its
+ * argument path only runs when `force` is false) — the wrapper returns the state-aware
+ * candidates there. `add` stays free-form (#124): its forced Tab keeps Pi's native
+ * filesystem completion, and a typed Git locator or path is never constrained by Bridge
+ * candidates. Everything else — other slash commands, text, file/path completion, suggestion
+ * generation and completion application — delegates unchanged to the host's current provider.
+ *
+ * The wrapper is installed from a `session_start` handler via `ctx.ui.addAutocompleteProvider`,
+ * which interactive (TUI) mode wires into the editor and RPC/JSON/print modes no-op, so a
+ * terminal-only provider is never registered outside a TUI session.
+ */
+
+import type { AutocompleteProvider } from '@earendil-works/pi-tui';
+
+import { completeArguments, type CompletionReadOptions } from '../../src/bridge/completion.js';
+
+/** The exact editor content this provider owns. */
+export const EXACT_COMMAND = '/codex-marketplace';
+
+/**
+ * The Bridge-owned second-level argument contexts on forced requests: `install` plus the
+ * installation lifecycle actions plus the Marketplace Registration commands — each followed
+ * by the trailing space root candidates insert. `add` is deliberately absent (#124): its
+ * argument is an arbitrary path or Git locator that stays under Pi's native completion.
+ */
+export const SECOND_LEVEL_ARGUMENT_RE = /^\/codex-marketplace (?:install|list|forget|enable|disable|remove) /;
+
+/**
+ * Wrap the host's current autocomplete provider. Suggestion generation intercepts only the
+ * Bridge-owned editor contexts (the exact `/codex-marketplace` line and the forced `install `
+ * argument context); completion application and file-trigger decisions delegate to the
+ * current provider's semantics, so selection behavior stays Pi-native.
+ */
+export function createBridgeAutocompleteProvider(
+  current: AutocompleteProvider,
+  readOptions: CompletionReadOptions = {},
+): AutocompleteProvider {
+  return {
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const line = lines[cursorLine] ?? '';
+      // Root-level interception (#121): only when the editor content is exactly the complete
+      // command text — a mid-command cursor or trailing text after the command is not
+      // "editor 內容恰為 /codex-marketplace" and must fall through to the host provider.
+      if (line === EXACT_COMMAND && cursorCol === EXACT_COMMAND.length) {
+        const items = completeArguments('', readOptions);
+        if (items && items.length > 0) {
+          // The intercepted prefix is the whole line before the cursor (prefix ''), so the
+          // insertion value must carry the separator space the editor content lacks.
+          return {
+            items: items.map((item) => ({ ...item, value: ` ${item.value}` })),
+            prefix: '',
+          };
+        }
+      }
+      // Second-level argument interception (#122, #123, #124): forced (Tab) requests inside a
+      // Bridge-owned argument context (`install ` / `enable ` / `disable ` / `remove ` /
+      // `list ` / `forget `) are Bridge-owned — the host's combined provider would route them
+      // to file completion. Natural typing (force=false) is delegated and reaches the same
+      // candidates through the command's getArgumentCompletions. Like the root branch, the
+      // cursor must be at the end of the line: a mid-line cursor with trailing text would
+      // otherwise produce a malformed line after applying a candidate. The prefix returned is
+      // the text after the command name (`install <query>` etc.), matching the host's
+      // argument-text semantics. `add ` is not Bridge-owned (#124), so a forced Tab there
+      // falls through to the host provider's filesystem completion unchanged.
+      if (options.force && cursorCol === line.length && SECOND_LEVEL_ARGUMENT_RE.test(line)) {
+        const argumentText = line.slice(EXACT_COMMAND.length + 1, cursorCol);
+        const items = completeArguments(argumentText, readOptions);
+        if (items) {
+          return { items, prefix: argumentText };
+        }
+      }
+      return current.getSuggestions(lines, cursorLine, cursorCol, options);
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}

package/extensions/pi/index.ts

@@ -14,8 +14,22 @@ import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-c
 
 import { runCommand } from '../../src/bridge/command.js';
 import { discoverProjectedSkillPaths } from '../../src/projection/exposure.js';
+import { completeArguments } from '../../src/bridge/completion.js';
+import { createBridgeAutocompleteProvider } from './autocomplete.js';
 
 export default function (pi: ExtensionAPI) {
+  // Root-level autocomplete (#121) + second-level autocomplete (#122–#124): stack a narrow
+  // provider for the exact `/codex-marketplace` editor text and the forced `install `,
+  // Installation lifecycle (`enable ` / `disable ` / `remove `), and Marketplace Registration
+  // (`list ` / `forget `) argument contexts (Pi otherwise completes just the command name
+  // plus a space, and routes forced argument Tabs to file completion). `add ` stays free-form
+  // (#124): forced Tabs keep Pi's native filesystem completion and typed Git locators are
+  // never constrained. session_start supplies the full TUI ui context;
+  // RPC/JSON/print modes no-op ctx.ui.addAutocompleteProvider, so a terminal-only provider is
+  // never registered outside a TUI session and command execution is unchanged.
+  pi.on('session_start', (_event, ctx) => {
+    ctx.ui.addAutocompleteProvider((current) => createBridgeAutocompleteProvider(current));
+  });
   // 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 and no Bridge State mutation.
@@ -33,6 +47,11 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand('codex-marketplace', {
     description: 'codex / claude marketplace 管理（add/list/install/update/disable/enable/remove/forget/help）',
+    // Standard argument completion (#121–#124): typed subcommand and `install <query>` /
+    // lifecycle `<query>` / Registration (`list` / `forget`) `<query>` prefixes go through
+    // Pi's normal autocomplete; unowned syntax (including `add`'s free-form argument) returns
+    // null so Pi falls through to its own behavior.
+    getArgumentCompletions: (argumentPrefix: string) => completeArguments(argumentPrefix),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const rawArgs = (args ?? '').trim();
       const argv = rawArgs.length > 0 ? rawArgs.split(/\s+/) : [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.6.2",
-  "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — 極簡 /codex-marketplace 純文字指令（add/list/install/update/disable/enable/remove/forget）、單一 Global Bridge State、當下最新安裝與即時投影",
+  "version": "0.8.0",
+  "description": "Bridge Package for Codex and Claude Marketplace compatibility in Pi — 極簡 /codex-marketplace 純文字指令與 Headless CLI（add/list/install/update/disable/enable/remove/forget）、單一 Global Bridge State、當下最新安裝與即時投影",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -20,6 +20,9 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "bin": {
+    "pi-codex-marketplace": "./bin/pi-codex-marketplace.js"
+  },
   "pi": {
     "extensions": [
       "./extensions/pi/index.ts"
@@ -56,6 +59,7 @@
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "files": [
+    "bin",
     "extensions",
     "src",
     "README.md",