pi-codex-marketplace 0.1.4 → 0.1.6

package/README.md

@@ -2,20 +2,24 @@
 
 Bridge Package for Codex Marketplace compatibility in Pi (`Pi 0.84.2`).
 
-> **One-line:** `pi install pi-codex-marketplace` → `/codex-marketplace` shows Global / Project partitioned Bridge State and lifecycle controls with Validation Disclosure, dual Confirmation, and three-orthogonal Receipt reporting.
+> **One-line:** `pi install npm:pi-codex-marketplace` → `/codex-marketplace` shows Global / Project partitioned Bridge State and lifecycle controls with Validation Disclosure, dual Confirmation, and three-orthogonal Receipt reporting.
 
 ## Install
 
 ```bash
-pi install pi-codex-marketplace            # Global Scope (writes to ~/.pi/agent/settings.json)
-pi install -l pi-codex-marketplace         # Project Scope (.pi/settings.json)
-pi install -e ./path/to/pi-codex-marketplace  # External link (try without publishing)
-pi update pi-codex-marketplace             # Update to latest compatible Bridge Package
-pi remove pi-codex-marketplace             # Remove Registration + Installations atomically
-pi -e ./path/to/repo                       # Ephemeral run without installing
+pi install npm:pi-codex-marketplace                    # Global Scope (writes to ~/.pi/agent/settings.json)
+pi install npm:pi-codex-marketplace -l                 # Project Scope (.pi/settings.json)
+pi install ./path/to/pi-codex-marketplace              # Local path (try without publishing)
+pi install ./path/to/pi-codex-marketplace -l           # Local path, Project Scope
+pi -e npm:pi-codex-marketplace                         # Ephemeral try without installing (temporary)
+pi update npm:pi-codex-marketplace                     # Update one package
+pi update --all                                        # Update pi + all packages
+pi remove npm:pi-codex-marketplace                     # Remove package
+pi list                                                # List installed packages
+pi config                                              # Enable/disable resources (Tab switches scope)
 ```
 
-All `pi install / -e / -l / update / remove` semantics are handled by the Pi host; this package declares a single `pi` extension entry (`extensions/pi/index.ts`) loaded via `jiti` and requires no build step.
+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.
 
 Requirements: **Pi 0.84.2**, **Node >=22.19.0**, **macOS / Linux** (Windows not supported).
 
@@ -78,7 +82,7 @@ Project Scope mutations and Effective-State participation require Pi's `Project
 | 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 |
 | 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 install -e` / `pi install -l` / `pi update` / `pi remove` | 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` | Single `pi` extension package; `files` ships `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.
 

package/extensions/pi/installation.ts

@@ -13,6 +13,7 @@ import {
   type InstallationOutcome,
 } from '../../src/installation/flow.js';
 import { inspectMarketplaceEntries } from '../../src/installation/inspection.js';
+import type { SourceCache } from '../../src/cache/source-cache.js';
 import type { Registration, Scope } from '../../src/bridge-state/types.js';
 import { reportOutcome } from './registration.js';
 
@@ -23,9 +24,9 @@ function labelText(value: string): string { return JSON.stringify(value); }
 export async function entryChoices(
   registration: Registration,
   scope: Scope,
-  _opts: { cwd?: string; projectTrusted?: boolean },
+  opts: { cwd?: string; agentDir?: string; projectTrusted?: boolean; cache?: SourceCache } = {},
 ): Promise<EntryChoice[]> {
-  const inspection = inspectMarketplaceEntries(registration, scope);
+  const inspection = inspectMarketplaceEntries(registration, scope, { agentDir: opts.agentDir, cache: opts.cache });
   if (!inspection.marketplaceId) return [{ label: `${labelText(registration.alias ?? registration.id)} — Unavailable (${labelText(inspection.findings[0]?.outcome ?? 'Marketplace Catalog cannot be read')})` }];
   return inspection.entries.map((item) => {
     const status = item.unavailableReason ? `Unavailable (${item.unavailableReason})` : '可安裝';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-marketplace",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Bridge Package for Codex Marketplace compatibility in Pi — Global/Project Bridge State, atomic persistence, and /codex-marketplace TUI",
   "type": "module",
   "keywords": [

package/src/cache/source-cache.ts

@@ -27,7 +27,7 @@ import {
 import { cpSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { acquireLock, releaseLock, atomicWriteFile } from '../bridge-state/atomic.js';
+import { acquireLock, acquireLockSync, releaseLock, atomicWriteFile } from '../bridge-state/atomic.js';
 import { readBridgeState } from '../bridge-state/store.js';
 import type { BridgeState } from '../bridge-state/types.js';
 import type { Scope } from '../bridge-state/types.js';
@@ -123,6 +123,19 @@ export class SourceCache {
     }
   }
 
+  /**
+   * Synchronous per-fingerprint mutual exclusion around store/prune/touch for that entry.
+   */
+  withFingerprintLockSync<T>(fingerprint: string, fn: () => T, timeoutMs = 5000): T {
+    const lockPath = this.lockPath(fingerprint);
+    const fd = acquireLockSync(lockPath, timeoutMs);
+    try {
+      return fn();
+    } finally {
+      releaseLock(fd, lockPath);
+    }
+  }
+
   /** Register an in-flight pin (reference-counted); returns its release function. In-flight entries are never evicted. */
   pinInFlight(fingerprint: string): () => void {
     this.inFlight.set(fingerprint, (this.inFlight.get(fingerprint) ?? 0) + 1);
@@ -148,6 +161,18 @@ export class SourceCache {
     return { path: dir, fingerprint };
   }
 
+  /** Synchronous exact fingerprint hit: entry directory + matching meta must exist. Touches lastAccess. */
+  hitExactSync(fingerprint: string): CacheHit | null {
+    if (!isSafeFingerprint(fingerprint)) return null;
+    const dir = this.entryPath(fingerprint);
+    const meta = this.readMeta(fingerprint);
+    if (!existsSync(dir) || !meta || meta.fingerprint !== fingerprint) return null;
+    this.withFingerprintLockSync(fingerprint, () => {
+      this.touchMeta(fingerprint);
+    });
+    return { path: dir, fingerprint };
+  }
+
   /**
    * Store an acquired source tree under its fingerprint. The stored fingerprint is pinned
    * for the duration of the store ("in flight"), so its own prune can never evict it.

package/src/installation/flow.ts

@@ -13,12 +13,14 @@ import { CODE, RULE, blocking, hasBlocking, sortFindings, type ValidationFinding
 import { acquireAttemptFence, type AttemptFenceHandle } from '../registration/fence.js';
 import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
 import { appendReceipt } from '../journal/journal.js';
+import type { SourceCache } from '../cache/source-cache.js';
 import type { ValidationSnapshot } from '../registration/snapshot.js';
 import { inspectMarketplaceEntries } from './inspection.js';
 
 export interface InstallationFlowOptions {
   cwd?: string;
   agentDir?: string;
+  cache?: SourceCache;
   projectTrusted?: boolean;
   fenceTimeoutMs?: number;
   /** Integration synchronization seam; production callers leave this undefined. */
@@ -148,18 +150,16 @@ async function makePreflight(
       operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Registration '${registrationId}' is not in ${scope} Bridge State`, 'registration'),
     ], null, opts);
   }
-  if (registration.sourceKind !== 'local' || !registration.source) {
-    return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
-      operationFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'This Registration has no retained local Validation Snapshot tree; Git Installation waits for the Source Cache lifecycle', 'registration'),
-    ], null, opts);
-  }
 
   const fenceResult = await acquireAttemptFence(scope, { cwd: opts.cwd, agentDir: opts.agentDir, fenceTimeoutMs: opts.fenceTimeoutMs, projectTrusted: opts.projectTrusted });
   if (!fenceResult.ok) return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [fenceResult.finding!], null, opts);
   const fence = fenceResult.handle!;
 
   try {
-    const inspection = inspectMarketplaceEntries(registration, scope);
+    const inspection = inspectMarketplaceEntries(registration, scope, {
+      agentDir: opts.agentDir,
+      cache: opts.cache,
+    });
     const inspected = inspection.entries.find((item) => item.entry.entryId === entryPointer);
     const rejectedFindings = inspected?.findings ?? (inspection.findings.length > 0 ? inspection.findings : [
       operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Marketplace Entry '${entryPointer}' is Unavailable`, 'entry'),
@@ -315,7 +315,10 @@ export async function confirmPluginInstallation(
   if (current.state!.stateRevision !== preflight.stateRevision) {
     return rejectedAsStale(preflight, 'State Revision changed since Installation disclosure; re-run preflight and confirmation', opts);
   }
-  const fresh = inspectMarketplaceEntries(preflight.registration, preflight.scope);
+  const fresh = inspectMarketplaceEntries(preflight.registration, preflight.scope, {
+    agentDir: opts.agentDir,
+    cache: opts.cache,
+  });
   if (!fresh.snapshot || fresh.snapshot.fingerprint !== preflight.snapshot.fingerprint) {
     return rejectedAsStale(preflight, 'Validation Snapshot changed since Installation disclosure; re-run preflight and confirmation', opts);
   }

package/src/installation/inspection.ts

@@ -6,7 +6,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import { lstatSync, readFileSync } from 'node:fs';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { classifyPlugin, type CompatiblePlugin } from '../compatibility/profile.js';
@@ -15,8 +15,9 @@ import type { MarketplaceEntry } from '../registration/catalog.js';
 import { parseCatalog } from '../registration/catalog.js';
 import { resolveContained } from '../registration/contained.js';
 import { CODE, RULE, blocking, hasBlocking, sortFindings, type ValidationFinding } from '../registration/findings.js';
-import { localSourceKey } from '../registration/source-key.js';
-import { bindCapturedMaterial, buildLocalSnapshot, type ValidationSnapshot } from '../registration/snapshot.js';
+import { SourceCache } from '../cache/source-cache.js';
+import { localSourceKey, type SourceKey } from '../registration/source-key.js';
+import { bindCapturedMaterial, buildGitSnapshot, buildLocalSnapshot, type ValidationSnapshot } from '../registration/snapshot.js';
 import { BUDGET } from '../registration/budget.js';
 
 export interface InspectedMarketplaceEntry {
@@ -43,6 +44,8 @@ export interface InspectionOptions {
   baseSnapshot?: ValidationSnapshot;
   /** Suppress the recorded-snapshot drift Blocking Finding — Refresh compares fingerprints explicitly instead. */
   ignoreRecordedDrift?: boolean;
+  agentDir?: string;
+  cache?: SourceCache;
 }
 
 function inspectionFinding(scope: Scope, code: string, rule: string, target: ValidationFinding['target'], outcome: string): ValidationFinding {
@@ -55,11 +58,60 @@ export function inspectMarketplaceEntries(registration: Registration, scope: Sco
   let root: string;
   let snapshotResult: { ok: boolean; snapshot?: ValidationSnapshot; findings: ValidationFinding[] };
   if (override) {
-    root = opts.root!;
+    try {
+      root = realpathSync.native(opts.root!);
+    } catch {
+      root = opts.root!;
+    }
     snapshotResult = { ok: true, snapshot: opts.baseSnapshot, findings: [] };
-  } else {
-    if (registration.sourceKind !== 'local' || !registration.source) {
-      return { entries: [], findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', 'Git Source Cache lifecycle is not available yet')] };
+  } else if (registration.sourceKind === 'git') {
+    if (!registration.validationSnapshot) {
+      return {
+        entries: [],
+        findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', 'Git Registration has no retained Validation Snapshot; re-registration or Marketplace Refresh is required')],
+      };
+    }
+    const cache = opts.cache ?? new SourceCache({ agentDir: opts.agentDir });
+    const hit = cache.hitExactSync(registration.validationSnapshot);
+    if (!hit) {
+      return {
+        entries: [],
+        findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', `Git Source Cache miss: Validation Snapshot '${registration.validationSnapshot.slice(0, 16)}…' is not retained in Source Cache; Marketplace Refresh or re-acquisition is required`)],
+      };
+    }
+    try {
+      root = realpathSync.native(hit.path);
+    } catch {
+      root = hit.path;
+    }
+    const canonicalLocator = registration.canonicalLocator ?? registration.source ?? '';
+    const selectorCanonical = registration.gitSelector?.canonical ?? '';
+    const resolvedRevision = registration.resolvedRevision ?? '';
+    const sourceKey: SourceKey = registration.sourceKey ?? {
+      kind: 'git',
+      key: `git:${canonicalLocator}#${selectorCanonical}`,
+      canonicalUrl: canonicalLocator,
+      selector: selectorCanonical,
+      resolvedRevision,
+    };
+    const snapResult = buildGitSnapshot(root, sourceKey, scope, {
+      canonicalLocator,
+      resolvedRevision,
+      selectorCanonical,
+    });
+    if (!snapResult.ok || !snapResult.snapshot) {
+      return { entries: [], findings: snapResult.findings };
+    }
+    if (snapResult.snapshot.fingerprint !== registration.validationSnapshot) {
+      return {
+        entries: [],
+        findings: [inspectionFinding(scope, CODE.SOURCE_DRIFT, RULE.SOURCE_DRIFT, 'registration', `Source Drift: cached tree at fingerprint ${registration.validationSnapshot.slice(0, 16)}… no longer hashes to the recorded Validation Snapshot; Marketplace Refresh is required`)],
+      };
+    }
+    snapshotResult = snapResult;
+  } else if (registration.sourceKind === 'local' || (!registration.sourceKind && registration.source && !registration.canonicalLocator)) {
+    if (!registration.source) {
+      return { entries: [], findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', 'Local Registration has no source path')] };
     }
     const key = localSourceKey(registration.source);
     if (!key.ok) return { entries: [], findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', key.error ?? 'Marketplace Root cannot be revalidated')] };
@@ -74,6 +126,11 @@ export function inspectMarketplaceEntries(registration: Registration, scope: Sco
     }
     snapshotResult = buildLocalSnapshot(root, key.sourceKey!, scope);
     if (!snapshotResult.ok) return { entries: [], findings: snapshotResult.findings };
+  } else {
+    return {
+      entries: [],
+      findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', `Unknown or unsupported sourceKind '${registration.sourceKind}'`)],
+    };
   }
 
   const catalogPath = join(root, '.agents', 'plugins', 'marketplace.json');

package/src/projection/project.ts

@@ -125,7 +125,7 @@ export function projectEffectiveState(
   const findings: ValidationFinding[] = [];
 
   const inspections = new Map<string, MarketplaceInspection>();
-  const inspect = opts.inspectRegistration ?? ((registration: EffectiveRegistration) => inspectMarketplaceEntries(registration, registration.sourceScope));
+  const inspect = opts.inspectRegistration ?? ((registration: EffectiveRegistration) => inspectMarketplaceEntries(registration, registration.sourceScope, { agentDir: opts.agentDir }));
   const inspectionFor = (registration: EffectiveRegistration): MarketplaceInspection => {
     const key = `${registration.sourceScope}:${registration.id}`;
     let value = inspections.get(key);

package/src/registration/contained.ts

@@ -69,7 +69,12 @@ export function resolveContained(root: string, relPath: string, checkType: 'any'
     };
   }
 
-  const abs = root + sep + relPath.slice(2);
+  let canonicalRoot = root;
+  try {
+    canonicalRoot = realpathSync.native(root);
+  } catch {}
+
+  const abs = canonicalRoot + sep + relPath.slice(2);
   let canonical: string;
   try {
     canonical = realpathSync.native(abs);
@@ -80,7 +85,7 @@ export function resolveContained(root: string, relPath: string, checkType: 'any'
   }
 
   // containment check
-  if (!isWithin(root, canonical)) {
+  if (!isWithin(canonicalRoot, canonical)) {
     return {
       outcome: { kind: 'blocking', blockClass: 'path', reason: `canonical target '${canonical}' escapes owning root '${root}'` },
       type: 'special',