pi-codex-marketplace 0.7.0 → 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]
@@ -115,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`）：
@@ -140,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.
 
@@ -159,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.7.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、當下最新安裝與即時投影",
+  "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",

package/src/bridge/command.ts

@@ -6,8 +6,9 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { basename, isAbsolute, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
 
@@ -59,6 +60,17 @@ export interface CommandResult {
   output: string;
   reload: boolean;
   stateReset?: boolean;
+  ok: boolean;
+}
+
+export function getPackageVersion(): string {
+  try {
+    const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+    const pkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkgJson.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
 }
 
 const USAGE_LINE = '用法：/codex-marketplace <add|list|install|update|disable|enable|remove|forget|help>';
@@ -495,7 +507,7 @@ export async function runCommand(
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     const messages = [`錯誤：讀取 Bridge State 失敗：${msg}`];
-    return { messages, lines: messages, output: messages.join('\n\n'), reload: false, stateReset: false };
+    return { messages, lines: messages, output: messages.join('\n\n'), reload: false, stateReset: false, ok: false };
   }
 
   const messages: string[] = [];
@@ -513,6 +525,12 @@ export async function runCommand(
     const subargs = rawArgs.slice(1);
 
     switch (subcmd) {
+      case '--version':
+      case '-v':
+      case 'version': {
+        messages.push(getPackageVersion());
+        break;
+      }
       case 'help':
       case '-h':
       case '--help': {
@@ -732,13 +750,17 @@ export async function runCommand(
           const filteredRegs = state.registrations.filter(
             (r) => r.marketplaceName === filter || r.alias === filter || r.id === filter,
           );
-          if (filteredRegs.length === 0 && state.registrations.length > 0) {
+          if (filteredRegs.length === 0) {
             messages.push(`找不到 marketplace "${filter}"`);
-            // Still show all for discoverability
-            messages.push(...formatOverview(state));
-            const pluginLines = formatPluginListLines(state, undefined, opts);
-            if (pluginLines.length > 0) messages.push(pluginLines.join('\n'));
-          } else if (filteredRegs.length > 0) {
+            if (state.registrations.length > 0) {
+              // Still show all for discoverability
+              messages.push(...formatOverview(state));
+              const pluginLines = formatPluginListLines(state, undefined, opts);
+              if (pluginLines.length > 0) messages.push(pluginLines.join('\n'));
+            } else {
+              messages.push(USAGE_LINE);
+            }
+          } else {
             // Show filtered overview (reuse format but only filtered regs)
             const filteredState: MinimalBridgeState = {
               ...state,
@@ -748,10 +770,6 @@ export async function runCommand(
             messages.push(...formatOverview(filteredState));
             const pluginLines = formatPluginListLines(state, filter, opts);
             if (pluginLines.length > 0) messages.push(pluginLines.join('\n'));
-          } else {
-            // No registrations at all
-            messages.push('尚無可列出的 plugin 或 marketplace。');
-            messages.push(USAGE_LINE);
           }
         } else {
           if (state.registrations.length === 0 && state.installations.length === 0) {
@@ -1274,11 +1292,26 @@ export async function runCommand(
     }
   }
 
+  const ok = !messages.some(
+    (m) =>
+      m.startsWith('錯誤：') ||
+      m.startsWith('未知子命令') ||
+      m.startsWith('用法：/codex-marketplace add') ||
+      m.startsWith('用法：/codex-marketplace install') ||
+      m.startsWith('用法：/codex-marketplace disable') ||
+      m.startsWith('用法：/codex-marketplace enable') ||
+      m.startsWith('用法：/codex-marketplace remove') ||
+      m.startsWith('用法：/codex-marketplace forget') ||
+      m.startsWith('已註冊過相同來源') ||
+      m.startsWith('找不到 marketplace'),
+  );
+
   return {
     messages,
     lines: messages,
     output: messages.join('\n\n'),
     reload,
     stateReset: wasReset,
+    ok,
   };
 }

package/src/cli/index.ts

@@ -0,0 +1,85 @@
+/**
+ * CLI Adapter — Pure headless command-line entry seam for pi-codex-marketplace (#132, #133)
+ *
+ * Provides:
+ * - runCli(argv, io, opts): Pure adapter driving runCommand with stdout/stderr/exit code contract
+ * - formatCliOutput(result): Formats CommandResult for CLI output, replacing in-process reload notices
+ * - getPackageVersion(): Retrieves package version from package.json
+ */
+
+import { runCommand, getPackageVersion, type CommandOptions, type CommandResult } from "../bridge/command.js";
+
+export { getPackageVersion };
+
+export interface CliIO {
+  stdout?: { write: (chunk: string) => unknown } | ((chunk: string) => unknown);
+  stderr?: { write: (chunk: string) => unknown } | ((chunk: string) => unknown);
+  exit?: (code: number) => unknown;
+}
+
+export const RELOAD_NOTICE = "已寫入 Bridge State · 下次 pi session／/reload 生效";
+export const RELOAD_PLACEHOLDER = "已重新載入生效";
+
+export function formatCliOutput(result: CommandResult): string {
+  let text = result.output;
+  if (result.reload) {
+    if (text.includes(RELOAD_PLACEHOLDER)) {
+      text = text.replaceAll(RELOAD_PLACEHOLDER, RELOAD_NOTICE);
+    } else {
+      text = text.length > 0 ? `${text}\n\n${RELOAD_NOTICE}` : RELOAD_NOTICE;
+    }
+  }
+  return text;
+}
+
+function writeStream(
+  target: { write: (chunk: string) => unknown } | ((chunk: string) => unknown) | undefined,
+  message: string,
+): void {
+  if (!target) return;
+  const chunk = message.endsWith("\n") ? message : `${message}\n`;
+  if (typeof target === "function") {
+    target(chunk);
+  } else if (typeof target.write === "function") {
+    target.write(chunk);
+  }
+}
+
+export async function runCli(
+  argv: string[],
+  io: CliIO = process,
+  opts: CommandOptions = {},
+): Promise<number> {
+  const exitWith = (code: number): number => {
+    if (typeof io.exit === "function") {
+      io.exit(code);
+    }
+    return code;
+  };
+
+  try {
+    if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version")) {
+      writeStream(io.stdout, getPackageVersion());
+      return exitWith(0);
+    }
+
+    const result = await runCommand(argv, opts);
+    const output = formatCliOutput(result);
+
+    if (result.ok) {
+      if (output) {
+        writeStream(io.stdout, output);
+      }
+      return exitWith(0);
+    } else {
+      if (output) {
+        writeStream(io.stderr, output);
+      }
+      return exitWith(1);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    writeStream(io.stderr, `錯誤：${msg}`);
+    return exitWith(1);
+  }
+}