pi-codex-marketplace 0.6.1 → 0.7.0

package/README.md

@@ -53,6 +53,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；偵測結果只限該次呼叫、永不持久化）：

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

package/src/bridge/command.ts

@@ -16,19 +16,22 @@ import {
   readMinimalBridgeState,
   writeMinimalBridgeState,
   type MinimalBridgeState,
-  type MarketplaceFormat,
 } from './state.js';
-import { BUDGET } from '../registration/budget.js';
 import { localSourceKey } from '../registration/source-key.js';
 import {
-  catalogContractFor,
   detectMarketplaceFormat,
   CODEX_MARKETPLACE_CATALOG_RELPATH,
   CLAUDE_MARKETPLACE_CATALOG_RELPATH,
 } from '../registration/format.js';
 import { resolveContained } from '../registration/contained.js';
-import { findEntryByManifestName, GIT_FAMILY_UNAVAILABLE_REASON, type Catalog, type MarketplaceEntry } from '../registration/catalog.js';
-import type { ValidationFinding } from '../registration/findings.js';
+import { findEntryByManifestName } from '../registration/catalog.js';
+import {
+  queryMarketplacePlugins,
+  readMarketplaceCatalog,
+  resolveMarketplaceRoot,
+  type MarketplaceCatalogReadResult,
+  type MarketplacePluginCandidate,
+} from './plugin-query.js';
 import { normalizeGitLocator } from '../registration/git-locator.js';
 import { acquireGitSource, cleanupAcquisition, type GitExecutor } from '../registration/git-acquisition.js';
 import {
@@ -39,7 +42,6 @@ import {
 import { gitSourceKey } from '../registration/source-key.js';
 import { buildGitSnapshot } from '../registration/snapshot.js';
 import { SourceCache } from '../cache/source-cache.js';
-import { getCacheDir, getCacheEntriesDir } from '../cache/paths.js';
 
 export interface CommandOptions {
   statePath?: string;
@@ -61,7 +63,9 @@ export interface CommandResult {
 
 const USAGE_LINE = '用法：/codex-marketplace <add|list|install|update|disable|enable|remove|forget|help>';
 
-const HELP_TEXT = [
+// Exported so the Bridge completion seam can be verified against the same description
+// vocabulary it mirrors (#121) — alignment is pinned by tests, not by manual syncing.
+export const HELP_TEXT = [
   '用法：/codex-marketplace <子命令> [參數]',
   '',
   '子命令：',
@@ -94,29 +98,6 @@ function expandOwnerRepo(input: string): string {
   return `https://github.com/${input.trim()}`;
 }
 
-function catalogRootForReg(
-  reg: MinimalBridgeState['registrations'][number],
-  opts: CommandOptions,
-): string | undefined {
-  if (reg.sourceKind === 'git') {
-    const snap = (reg as unknown as { snapshot?: string }).snapshot;
-    if (!snap || !/^[0-9a-f]{64}$/.test(snap)) return undefined;
-    const entriesDir = getCacheEntriesDir(getCacheDir(opts.agentDir));
-    const p = join(entriesDir, snap);
-    if (!existsSync(p)) return undefined;
-    return p;
-  }
-  return reg.source;
-}
-
-function sourceRootForReg(
-  reg: MinimalBridgeState['registrations'][number],
-  opts: CommandOptions,
-): string | undefined {
-  if (reg.sourceKind === 'git') return catalogRootForReg(reg, opts);
-  return reg.source;
-}
-
 function padRight(str: string, length: number): string {
   return str.length >= length ? str : str + ' '.repeat(length - str.length);
 }
@@ -173,138 +154,18 @@ function formatCatalogError(findings: { code?: string; outcome?: string; rule?:
   return detail;
 }
 
-// ---- Plugin enumeration helpers (#90, #91) ----
-
-interface EnumeratedPlugin {
-  number: number;
-  reg: MinimalBridgeState['registrations'][number];
-  entry: MarketplaceEntry;
-  pluginName: string;
-  status: '可安裝' | '已裝啟用' | '已裝停用' | 'unavailable';
-  unavailableReason?: string;
-}
-
-/**
- * Whether an entry can supply a locally installable plugin on the command surface. Git-family
- * and unsupported source kinds are Unavailable Entries (#91): disclosed with a reason, never
- * silently skipped and never installable.
- */
-function entryLocallyInstallable(entry: MarketplaceEntry): boolean {
-  return (
-    entry.type === 'local' && entry.available === true && typeof entry.path === 'string' && entry.path.length > 0
-  );
-}
-
-function entryUnavailableReason(entry: MarketplaceEntry): string {
-  if (entry.type === 'git' && entry.available !== false) return GIT_FAMILY_UNAVAILABLE_REASON;
-  return entry.unavailableReason ?? 'unsupported source kind';
-}
-
-interface CatalogReadResult {
-  /** Parsed catalog on success (name + entries); also present for some parse failures. */
-  catalog?: Catalog;
-  /** Structural findings from the format-bound parser (present for parse failures too). */
-  findings: ValidationFinding[];
-  /** Disclosed read failure (catalog 缺失／超上限／malformed); never silently skipped. */
-  error?: string;
-}
-
-/**
- * The single catalog reader for the command surface: budget-bounded read + format-bound parse.
- * Read failures produce a disclosed `error` instead of silently skipping (#91).
- */
-function readCatalogForReg(root: string, format: MarketplaceFormat): CatalogReadResult {
-  const contract = catalogContractFor(format);
-  const catalogPath = join(root, ...contract.relPath.split('/'));
-  let raw: string;
-  try {
-    if (!existsSync(catalogPath)) {
-      return { findings: [], error: `catalog 缺失（${contract.relPath}）` };
-    }
-    const size = statSync(catalogPath).size;
-    if (size > BUDGET.maxCatalogBytes) {
-      return {
-        findings: [],
-        error: `catalog 檔案過大（${size} bytes > ${BUDGET.maxCatalogBytes}）— 超過 Validation Budget 上限，catalog 無法解析`,
-      };
-    }
-    raw = readFileSync(catalogPath, 'utf-8');
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { findings: [], error: `catalog 無法讀取：${msg}` };
-  }
-  if (!raw.trim()) {
-    return { findings: [], error: `catalog 解析失敗：檔案為空 — catalog malformed` };
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { findings: [], error: `catalog 解析失敗：${msg} — catalog malformed` };
-  }
-  const res = contract.parse(parsed);
-  if (!res.ok) {
-    const codes = res.findings.map((f) => f.code).join(', ');
-    return {
-      catalog: res.catalog,
-      findings: res.findings,
-      error: `catalog 解析失敗${codes ? ` (${codes})` : ''} — catalog malformed`,
-    };
-  }
-  return { catalog: res.catalog, findings: res.findings };
-}
-
-interface Enumeration {
-  plugins: EnumeratedPlugin[];
-  catalogErrors: Array<{ marketplace: string; error: string }>;
-}
+// ---- Plugin enumeration presentation (#90, #91, #120) ----
 
-function enumeratePlugins(state: MinimalBridgeState, opts: CommandOptions = {}): Enumeration {
-  const result: EnumeratedPlugin[] = [];
-  const catalogErrors: Enumeration['catalogErrors'] = [];
-  let counter = 1;
-  for (const reg of state.registrations) {
-    const catalogRoot = catalogRootForReg(reg, opts);
-    if (!catalogRoot) {
-      const isGit = reg.sourceKind === 'git';
-      const snap = (reg as unknown as { snapshot?: string }).snapshot;
-      const reason = isGit
-        ? (!snap ? 'git marketplace 缺少 cache 指紋' : `cache 快照缺失（${snap.slice(0, 12)}…）`)
-        : 'catalog 根路徑無法解析';
-      catalogErrors.push({ marketplace: reg.marketplaceName || reg.alias || reg.id, error: reason });
-      continue;
-    }
-    const read = readCatalogForReg(catalogRoot, reg.format ?? 'codex');
-    if (read.error) {
-      // Disclosed read failure (#91): the error line is shown and the marketplace contributes
-      // no entries — a broken catalog never yields installable plugins.
-      catalogErrors.push({ marketplace: reg.marketplaceName || reg.alias || reg.id, error: read.error });
-      continue;
-    }
-    for (const entry of read.catalog?.entries ?? []) {
-      const pluginName = entry.name ?? (entry.path ? basename(entry.path) : `plugin-${entry.ordinal}`);
-      const inst = state.installations.find(
-        (i) => i.registrationId === reg.id && (i.manifestName === pluginName || i.pluginId === pluginName),
-      );
-      let status: EnumeratedPlugin['status'];
-      let unavailableReason: string | undefined;
-      if (!entryLocallyInstallable(entry)) {
-        status = 'unavailable';
-        unavailableReason = entryUnavailableReason(entry);
-      } else if (!inst) status = '可安裝';
-      else if (isInstallationEnabled(inst as any)) status = '已裝啟用';
-      else status = '已裝停用';
-      result.push({ number: counter, reg, entry, pluginName, status, unavailableReason });
-      counter++;
-    }
-  }
-  return { plugins: result, catalogErrors };
+function pluginStatus(plugin: MarketplacePluginCandidate): '可安裝' | '已裝啟用' | '已裝停用' | 'unavailable' {
+  if (!plugin.structurallyInstallable) return 'unavailable';
+  if (plugin.installationState === 'enabled') return '已裝啟用';
+  if (plugin.installationState === 'disabled') return '已裝停用';
+  return '可安裝';
 }
 
 function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts: CommandOptions = {}): string[] {
-  const { plugins: enumeration, catalogErrors } = enumeratePlugins(state, opts);
-  const errorLines = catalogErrors.map((e) => `⚠ marketplace [${e.marketplace}] ${e.error}`);
+  const { plugins: enumeration, diagnostics } = queryMarketplacePlugins(state, opts);
+  const errorLines = diagnostics.map((diagnostic) => `⚠ marketplace [${diagnostic.marketplace}] ${diagnostic.error}`);
   if (enumeration.length === 0) {
     // No plugins at all (e.g., empty catalog, no registrations, or unreadable catalogs):
     // read failures are disclosed, never silently skipped (#91).
@@ -313,7 +174,9 @@ function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts:
   let filtered = enumeration;
   if (filter) {
     filtered = enumeration.filter(
-      (e) => e.reg.marketplaceName === filter || e.reg.alias === filter || e.reg.id === filter,
+      (plugin) => plugin.registration.marketplaceName === filter
+        || plugin.registration.alias === filter
+        || plugin.registration.id === filter,
     );
     if (filtered.length === 0) {
       return [
@@ -324,11 +187,14 @@ function formatPluginListLines(state: MinimalBridgeState, filter?: string, opts:
   }
   const lines: string[] = ['Plugins（編號／所屬 marketplace／狀態）'];
   const show = filter ? filtered : enumeration;
-  for (const e of show) {
-    const num = padRight(` ${e.number}`, 4);
-    const name = padRight(e.pluginName, 18);
-    const mkt = padRight(`[${e.reg.marketplaceName || e.reg.alias || e.reg.id}]`, 20);
-    const status = e.status === 'unavailable' ? `unavailable（${e.unavailableReason ?? 'unavailable'}）` : e.status;
+  for (const plugin of show) {
+    const num = padRight(` ${plugin.number}`, 4);
+    const name = padRight(plugin.candidateName, 18);
+    const mkt = padRight(`[${plugin.marketplaceName}]`, 20);
+    const stateLabel = pluginStatus(plugin);
+    const status = stateLabel === 'unavailable'
+      ? `unavailable（${plugin.unavailableReason ?? 'unavailable'}）`
+      : stateLabel;
     lines.push(`${num}${name}${mkt}${status}`);
   }
   lines.push(...errorLines);
@@ -367,21 +233,20 @@ function findRegistrationIndex(state: MinimalBridgeState, name: string): number
 }
 
 /**
- * Best-effort reread for enable: mirrors install Step1-3 (sourceRoot -> catalogRoot -> readCatalog -> entry -> resolveContained -> collectSkillNames).
+ * Best-effort reread for enable: mirrors install Step1-3 (Marketplace Root -> readCatalog -> entry -> resolveContained -> collectSkillNames).
  * Returns undefined on any missing cache/catalog/entry/path — caller falls back to stored skills.
- * Pure-logic branches (find/entry.path/resolveContained outcome) do not throw; only I/O (readCatalogForReg/collectSkillNames) is try/catch guarded.
+ * Pure-logic branches (find/entry.path/resolveContained outcome) do not throw; only I/O (readMarketplaceCatalog/collectSkillNames) is try/catch guarded.
  */
 function tryRereadSkills(
   reg: MinimalBridgeState['registrations'][number],
   inst: MinimalBridgeState['installations'][number],
   opts: CommandOptions,
 ): string[] | undefined {
-  const sourceRoot = sourceRootForReg(reg, opts);
-  const catalogRoot = catalogRootForReg(reg, opts);
-  if (!sourceRoot || !catalogRoot) return undefined;
-  let read: CatalogReadResult | undefined;
+  const marketplaceRoot = resolveMarketplaceRoot(reg, opts);
+  if (!marketplaceRoot) return undefined;
+  let read: MarketplaceCatalogReadResult | undefined;
   try {
-    read = readCatalogForReg(catalogRoot, reg.format ?? 'codex');
+    read = readMarketplaceCatalog(marketplaceRoot, reg.format ?? 'codex');
   } catch {
     // best-effort: catalog 讀取/解析失敗（cache 缺失或損毀）則沿用舊 skills
     return undefined;
@@ -389,7 +254,7 @@ function tryRereadSkills(
   if (read.error || !read.catalog) return undefined;
   const entry = findEntryByManifestName(read.catalog, inst.manifestName);
   if (!entry?.path) return undefined;
-  const contained = resolveContained(sourceRoot, entry.path, 'directory');
+  const contained = resolveContained(marketplaceRoot, entry.path, 'directory');
   if (contained.outcome.kind !== 'ok') return undefined;
   try {
     return collectSkillNames(contained.outcome.canonicalPath, (reg.format ?? 'codex') as 'codex' | 'claude');
@@ -426,7 +291,7 @@ interface PluginRereadOutcome {
 /**
  * 重裝＝更新（#94）：對已安裝 plugin 在最新材料root（本機 live 路徑或 git 新 cache entry）重讀
  * catalog → 重解析 manifest＋skills，回傳刷新結果由呼叫端套用。純邏輯分支不拋；
- * 僅 I/O（readCatalogForReg／readManifestName／collectSkillNames）由各函式內部 try/catch 守護。
+ * 僅 I/O（readMarketplaceCatalog／readManifestName／collectSkillNames）由各函式內部 try/catch 守護。
  */
 function rereadInstalledPlugin(
   root: string,
@@ -434,7 +299,7 @@ function rereadInstalledPlugin(
   inst: MinimalBridgeState['installations'][number],
   installations: MinimalBridgeState['installations'],
 ): PluginRereadOutcome {
-  const read = readCatalogForReg(root, format);
+  const read = readMarketplaceCatalog(root, format);
   if (read.error || !read.catalog) {
     return {
       ok: false,
@@ -725,7 +590,7 @@ export async function runCommand(
               break;
             }
 
-            const catalogResult = readCatalogForReg(acquiredPath, detectedFormat);
+            const catalogResult = readMarketplaceCatalog(acquiredPath, detectedFormat);
             if (catalogResult.error || !catalogResult.catalog) {
               messages.push(`錯誤：${catalogResult.error ?? 'catalog 解析失敗'}`);
               if (catalogResult.findings.length > 0) {
@@ -821,7 +686,7 @@ export async function runCommand(
               break;
             }
 
-            const catalogResult = readCatalogForReg(canonicalPath, detectedFormat);
+            const catalogResult = readMarketplaceCatalog(canonicalPath, detectedFormat);
             if (catalogResult.error || !catalogResult.catalog) {
               messages.push(`錯誤：${catalogResult.error ?? 'catalog 解析失敗'}`);
               if (catalogResult.findings.length > 0) {
@@ -910,9 +775,11 @@ export async function runCommand(
             messages.push('錯誤：尚未註冊任何 marketplace，請先使用 `/codex-marketplace add <路徑>` 註冊');
             break;
           }
-          const { plugins: enumeration, catalogErrors } = enumeratePlugins(state, opts);
+          const { plugins: enumeration, diagnostics } = queryMarketplacePlugins(state, opts);
           const pushCatalogErrors = (): void => {
-            for (const e of catalogErrors) messages.push(`⚠ marketplace [${e.marketplace}] ${e.error}`);
+            for (const diagnostic of diagnostics) {
+              messages.push(`⚠ marketplace [${diagnostic.marketplace}] ${diagnostic.error}`);
+            }
           };
           if (enumeration.length === 0) {
             messages.push('錯誤：目前沒有可安裝的 plugin（marketplace 內無可用 entry）');
@@ -920,7 +787,7 @@ export async function runCommand(
             break;
           }
 
-          let target: EnumeratedPlugin | undefined;
+          let target: MarketplacePluginCandidate | undefined;
           const num = Number(arg);
           const isNumeric = !isNaN(num) && String(num) === arg && Number.isInteger(num) && num >= 1;
           if (isNumeric) {
@@ -931,8 +798,8 @@ export async function runCommand(
               break;
             }
           } else {
-            // treat as name: match pluginName exactly
-            const candidates = enumeration.filter((e) => e.pluginName === arg);
+            // treat as name: match the query's Plugin candidate name exactly
+            const candidates = enumeration.filter((plugin) => plugin.candidateName === arg);
             if (candidates.length === 0) {
               // Also try to match manifestName of already installed? But enumeration already covers all catalog entries.
               messages.push(`錯誤：找不到名稱 "${arg}" 對應的 plugin`);
@@ -941,32 +808,26 @@ export async function runCommand(
             }
             if (candidates.length > 1) {
               // Ambiguous: list candidates
-              const list = candidates.map((c) => `${c.number}:${c.pluginName}[${c.reg.marketplaceName}]`).join('、');
+              const list = candidates
+                .map((candidate) => `${candidate.number}:${candidate.candidateName}[${candidate.registration.marketplaceName}]`)
+                .join('、');
               messages.push(`錯誤：名稱 "${arg}" 對應多個 plugin（${list}），請改用編號安裝`);
               break;
             }
             target = candidates[0];
           }
 
-          const targetReg = target.reg;
+          const targetReg = target.registration;
           const targetEntry = target.entry;
 
           // ---- Step 1: Unavailable Entry refusal (#91) + contained path check ----
-          if (!entryLocallyInstallable(targetEntry)) {
+          if (!target.structurallyInstallable) {
             messages.push(
-              `錯誤：plugin "${target.pluginName}" unavailable，無法安裝：${entryUnavailableReason(targetEntry)}`,
+              `錯誤：plugin "${target.candidateName}" unavailable，無法安裝：${target.unavailableReason}`,
             );
             break;
           }
-          const sourceRoot = sourceRootForReg(targetReg, opts);
-          if (!sourceRoot) {
-            const snap = (targetReg as unknown as { snapshot?: string }).snapshot;
-            const reason = targetReg.sourceKind === 'git'
-              ? (!snap ? 'git cache 指紋缺失' : `cache 快照缺失（${snap.slice(0, 12)}…）請先重新 add`)
-              : 'marketplace 根路徑無法解析';
-            messages.push(`錯誤：無法解析 marketplace 根 — ${reason}`);
-            break;
-          }
+          const sourceRoot = target.marketplaceRoot;
           const contained = resolveContained(sourceRoot, targetEntry.path!, 'directory');
           if (contained.outcome.kind === 'blocking') {
             messages.push(`錯誤：plugin 路徑檢查失敗（Contained Path 違規）— ${contained.outcome.reason}`);
@@ -1176,7 +1037,7 @@ export async function runCommand(
             gitAdvanced = true;
 
             // 重裝＝更新：從最新 cache 材料重裝全部已安裝 plugin（投影直讀新位址）
-            const cacheRoot = catalogRootForReg(reg, opts);
+            const cacheRoot = resolveMarketplaceRoot(reg, opts);
             if (cacheRoot) {
               for (const inst of insts) {
                 const outcome = rereadInstalledPlugin(cacheRoot, format, inst, state.installations);
@@ -1212,7 +1073,7 @@ export async function runCommand(
               continue;
             }
             // 先 probe catalog：不可讀時不能聲稱「無變化」，必須明示（不靜默略過）
-            const probe = readCatalogForReg(reg.source, format);
+            const probe = readMarketplaceCatalog(reg.source, format);
             if (probe.error) {
               updateLines.push(`⚠ marketplace [${display}] ${probe.error}`);
               continue;