pi-codex-marketplace 0.1.0

package/extensions/pi/scope-overrides.ts

@@ -0,0 +1,170 @@
+/**
+ * TUI flow for Scope Override management and the Effective State / projection view.
+ *
+ * Scope Overrides suppress inherited Global Scope records without modifying them: a
+ * Registration override suppresses its marketplace subtree, an Installation override
+ * suppresses only that single Plugin, and removing either reveals the inherited record again.
+ * The Effective State view marks every record's participating source and suppression reason,
+ * and lists Projected Skills with their collision outcome and Skill Availability.
+ */
+
+import type { ExtensionCommandContext, ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+
+import { readBridgeState } from '../../src/bridge-state/store.js';
+import type { BridgeState } from '../../src/bridge-state/types.js';
+import { computeEffectiveState, type EffectiveState } from '../../src/projection/effective-state.js';
+import { createScopeOverride, removeScopeOverride, type OverrideKind, type OverrideOutcome } from '../../src/projection/overrides.js';
+import { projectEffectiveState } from '../../src/projection/project.js';
+import { reportOutcome } from './registration.js';
+
+function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** One row of the inherited-Global listing shown before creating an override. */
+export interface InheritedRecordRow {
+  label: string;
+  kind: OverrideKind;
+  targetId: string;
+  /** true when a Project Scope Override currently suppresses this record. */
+  suppressedByOverride: boolean;
+  /** true when an enabled project Installation supersedes this record by precedence. */
+  supersededByProject: boolean;
+  selectable: boolean;
+}
+
+/**
+ * Build the inherited Global Scope listing: every global Registration and enabled global
+ * Installation annotated with why it is not participating in Effective State.
+ */
+export function inheritedRecordRows(
+  global: BridgeState,
+  project: BridgeState,
+  projectTrusted: boolean,
+): InheritedRecordRow[] {
+  const effective = computeEffectiveState(global, project, { projectTrusted });
+  const suppressedKinds = new Map(effective.suppressed.map((item) => [`${item.kind}/${item.targetId}`, item.reason]));
+  const rows: InheritedRecordRow[] = [];
+  for (const registration of global.registrations) {
+    const reason = suppressedKinds.get(`registration/${registration.id}`);
+    rows.push({
+      kind: 'registration',
+      targetId: registration.id,
+      label: `${quote(registration.alias ?? registration.marketplaceName ?? registration.id)} · Registration ${registration.id.slice(0, 8)}…${reason === 'scope-override-registration' ? ' — 已抑制（子樹）' : ''}`,
+      suppressedByOverride: reason === 'scope-override-registration',
+      supersededByProject: false,
+      selectable: true,
+    });
+  }
+  for (const installation of global.installations) {
+    if (installation.installationState !== 'enabled') continue; // disabled never participates
+    const reason = suppressedKinds.get(`installation/${installation.id}`);
+    rows.push({
+      kind: 'installation',
+      targetId: installation.id,
+      label: `${quote(installation.manifestName ?? installation.pluginId)} · Installation ${installation.id.slice(0, 8)}…${
+        reason === 'scope-override-installation' ? ' — 已抑制（單一 Plugin）'
+          : reason === 'scope-override-registration' ? ' — 已抑制（隸屬被覆蓋的 Registration 子樹）'
+            : reason === 'project-precedence' ? ' — 由 Project 同名 Plugin 優先取代' : ''
+      }`,
+      suppressedByOverride: reason === 'scope-override-installation' || reason === 'scope-override-registration',
+      supersededByProject: reason === 'project-precedence',
+      selectable: true,
+    });
+  }
+  return rows;
+}
+
+/** Compact multi-line summary of one projection result for disclosure / notification. */
+export function formatProjectionSummary(state: EffectiveState, plugins: ReturnType<typeof projectEffectiveState>['plugins'], findings: ReturnType<typeof projectEffectiveState>['findings']): string {
+  const lines = [
+    `Effective State: ${state.registrations.length} registrations · ${state.installations.length} installations 參與`,
+    ...state.suppressed.map((item) => `⊘ suppressed ${item.kind} ${item.targetId.slice(0, 8)}… (${item.reason})`),
+  ];
+  if (plugins.length === 0) lines.push('Projected Plugins: none');
+  for (const plugin of plugins) {
+    lines.push(`▸ ${quote(plugin.pluginId)} · ${plugin.sourceScope}`);
+    for (const skill of plugin.skills) {
+      const status = skill.status === 'projected' ? 'projected' : 'unavailable（碰撞）';
+      lines.push(`    ${quote(skill.name)} · ${status} · availability: ${skill.availability}`);
+    }
+  }
+  if (findings.length > 0) {
+    lines.push(`Findings: ${findings.map((f) => `${f.classification} ${f.code}`).join(' | ')}`);
+  }
+  return lines.join('\n');
+}
+
+async function readBoth(ctx: { cwd?: string; agentDir?: string }): Promise<{ ok: boolean; global?: BridgeState; project?: BridgeState; error?: string }> {
+  const opts = { cwd: ctx.cwd, agentDir: ctx.agentDir };
+  const [globalRead, projectRead] = await Promise.all([readBridgeState('global', opts), readBridgeState('project', opts)]);
+  const bad = [globalRead, projectRead].find((read) => read.status !== 'ok' && read.status !== 'missing');
+  if (bad) return { ok: false, error: bad.error ?? 'Bridge State is not readable (Persistence Indeterminate)' };
+  return { ok: true, global: globalRead.state!, project: projectRead.state! };
+}
+
+/** Create fine-grained Scope Overrides against inherited Global registrations / installations. */
+export async function runScopeOverrideFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const ui: ExtensionUIContext = ctx.ui;
+  const opts = { cwd: ctx.cwd, agentDir: undefined, projectTrusted: ctx.isProjectTrusted() };
+  const docs = await readBoth({ cwd: ctx.cwd });
+  if (!docs.ok) return void ui.notify(`Bridge State 不可讀：${docs.error}`, 'error');
+
+  if (!ctx.isProjectTrusted()) {
+    return void ui.notify('Project Trust 未由 Pi host 授予——無法執行任何 Project Scope Lifecycle Operation（紀錄仍保存但不參與 Effective State）。', 'warning');
+  }
+
+  const rows = inheritedRecordRows(docs.global!, docs.project!, ctx.isProjectTrusted());
+  const chosen = await ui.select('建立 Scope Override — 選擇要抑制的繼承全域紀錄', rows.map((row) => row.label));
+  if (!chosen) return;
+  const row = rows.find((item) => item.label === chosen)!;
+  if (row.suppressedByOverride) return void ui.notify('此紀錄已被現有 Scope Override 抑制。', 'warning');
+
+  const cascade = row.kind === 'registration'
+    ? '\n\nRegistration Override 會抑制整顆 Marketplace 子樹（該 Registration 及其所有 Installations）。'
+    : '\n\nInstallation Override 僅抑制此單一 Plugin。';
+  const confirmed = await ui.confirm(
+    'Scope Override Disclosure — 預設 No',
+    `將於 Project Scope 建立 ${row.kind} Scope Override，抑制繼承的全域紀錄：\n${row.targetId}${cascade}\n\n不會修改全域文件；移除 Override 即可還原繼承。`,
+  );
+  if (!confirmed) return void ui.notify('Attempt Summary: Declined — state unchanged.', 'info');
+
+  const outcome = await createScopeOverride(row.kind, row.targetId, opts);
+  reportOutcome(ctx, outcome);
+}
+
+/** Remove existing Scope Overrides; inheritance restores immediately via recomputation. */
+export async function runRemoveScopeOverrideFlow(ctx: ExtensionCommandContext): Promise<void> {
+  const ui: ExtensionUIContext = ctx.ui;
+  const opts = { cwd: ctx.cwd, agentDir: undefined, projectTrusted: ctx.isProjectTrusted() };
+  const docs = await readBoth({ cwd: ctx.cwd });
+  if (!docs.ok) return void ui.notify(`Bridge State 不可讀：${docs.error}`, 'error');
+  const overrides = docs.project!.scopeOverrides;
+  if (overrides.length === 0) return void ui.notify('Project Scope 目前沒有任何 Scope Override。', 'info');
+
+  const labels = overrides.map((item) => `${item.kind} Override → ${item.targetId.slice(0, 8)}…`);
+  const chosen = await ui.select('移除 Scope Override — 移除後立即還原繼承（不改寫全域文件）', labels);
+  if (!chosen) return;
+  const target = overrides[labels.indexOf(chosen)]!;
+
+  const confirmed = await ui.confirm('Override Removal — 預設 No', `移除 ${target.kind} Scope Override？\n被抑制的繼承全域紀錄將立即在 Effective State 中恢復。`);
+  if (!confirmed) return void ui.notify('Attempt Summary: Declined — state unchanged.', 'info');
+
+  const outcome = await removeScopeOverride(target.kind, target.targetId, opts);
+  reportOutcome(ctx, outcome);
+}
+
+/** Read-only Effective State + Projected Skills / collision diagnostics view. */
+export async function runEffectiveStateView(ctx: ExtensionCommandContext): Promise<void> {
+  const ui: ExtensionUIContext = ctx.ui;
+  const trusted = ctx.isProjectTrusted();
+  const docs = await readBoth({ cwd: ctx.cwd });
+  if (!docs.ok) return void ui.notify(`Bridge State 不可讀：${docs.error}`, 'error');
+  const effective = computeEffectiveState(docs.global!, docs.project!, { projectTrusted: trusted });
+  const projection = projectEffectiveState(docs.global!, docs.project!, { projectTrusted: trusted });
+  const trustNote = trusted ? '' : '\n\n⚠ Project Trust 未授予——Project Scope 紀錄仍保存但不參與 Effective State。';
+  ui.notify(
+    `${formatProjectionSummary(effective, projection.plugins, projection.findings)}${trustNote}\n\nAvailable 僅由宿主獨立證據確立；碰撞僅影響技能粒度，不改變 Plugin 分類。`,
+    projection.findings.length > 0 ? 'warning' : 'info',
+  );
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pi-codex-marketplace",
+  "version": "0.1.0",
+  "description": "Bridge Package for Codex Marketplace compatibility in Pi — Global/Project Bridge State, atomic persistence, and /codex-marketplace TUI",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "codex",
+    "marketplace"
+  ],
+  "license": "MIT",
+  "author": "Sam Wang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamWang32191/pi-codex-marketplace.git"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/pi/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": false
+    }
+  },
+  "overrides": {},
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "@types/node": "^26.2.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage=false",
+    "test:watch": "vitest",
+    "test:acceptance": "vitest run tests/acceptance --coverage=false",
+    "build": "echo 'no build step — extensions loaded via jiti'",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/barrier/global-barrier.ts

@@ -0,0 +1,105 @@
+/**
+ * Global Pending Barrier — Compatibility Profile v1 policy.
+ * See CONTEXT.md: Global Pending Barrier.
+ *
+ * Active when:
+ * - Global Scope Attempt Fence is currently held, OR
+ * - Global Scope has Pending Application, Persistence Indeterminate, or Receipt Journal degradation.
+ *
+ * Blocks all Project Scope mutations and Runtime Applications (Lifecycle Operations,
+ * Repair State, project startup reconciliation). Inspection and Marketplace Refresh remain available.
+ */
+
+import { existsSync, openSync, closeSync, unlinkSync } from 'node:fs';
+
+import { readBridgeStateSync } from '../bridge-state/store.js';
+import { getFencePath, getGlobalStatePath, getStatePath } from '../bridge-state/paths.js';
+import { readReceiptJournal } from '../journal/journal.js';
+import { blocking, CODE, RULE, type ValidationFinding } from '../registration/findings.js';
+
+export interface GlobalBarrierStatus {
+  active: boolean;
+  reason?: string;
+  finding?: ValidationFinding;
+}
+
+export function globalBarrierFinding(reason: string): ValidationFinding {
+  return blocking({
+    code: CODE.GLOBAL_PENDING_BARRIER,
+    phase: 'admission',
+    target: 'attempt',
+    scope: 'project',
+    pointer: '',
+    rule: RULE.GLOBAL_PENDING_BARRIER,
+    outcome: `Global Pending Barrier is active: ${reason}; project state mutations and runtime applications are blocked until global recovery completes (Inspection and Marketplace Refresh remain available)`,
+  });
+}
+
+/** Check if the Global Attempt Fence lock is currently held. */
+function isGlobalFenceHeld(opts: { agentDir?: string; cwd?: string }): boolean {
+  const globalStatePath = getGlobalStatePath(opts.agentDir);
+  const fencePath = getFencePath(globalStatePath);
+  if (!existsSync(fencePath)) return false;
+
+  // Try opening with 'wx' flag to see if file exists / is held
+  // In our fence implementation, the lock file exists while the fence is held and is unlinked on release.
+  // If fencePath exists, check if we can acquire it or if it exists.
+  return existsSync(fencePath);
+}
+
+/** Check if the Global Pending Barrier is active. */
+export async function checkGlobalPendingBarrier(
+  opts: { agentDir?: string; cwd?: string } = {},
+): Promise<GlobalBarrierStatus> {
+  // 1. Check if Global Attempt Fence is held
+  if (isGlobalFenceHeld(opts)) {
+    const reason = 'Global Attempt Fence is held by an in-flight operation';
+    return {
+      active: true,
+      reason,
+      finding: globalBarrierFinding(reason),
+    };
+  }
+
+  // 2. Check Global State readability / integrity
+  const globalState = readBridgeStateSync('global', opts);
+  if (globalState.status === 'corrupted' || globalState.status === 'incompatible') {
+    const reason = `Global Bridge State is ${globalState.status} (${globalState.error ?? 'Persistence Indeterminate'})`;
+    return {
+      active: true,
+      reason,
+      finding: globalBarrierFinding(reason),
+    };
+  }
+
+  // 3. Check Global Receipt Journal for active recovery chains or degradation
+  const journal = await readReceiptJournal('global', opts);
+  if (journal.activeChains.length > 0) {
+    const root = journal.activeChains[0];
+    const conditionLabel =
+      root.condition === 'pending-application'
+        ? 'Pending Application'
+        : root.condition === 'persistence-indeterminate'
+          ? 'Persistence Indeterminate'
+          : root.condition === 'persistence-failed'
+            ? 'Persistence Failed'
+            : 'Receipt Journal degradation';
+    const reason = `Global Scope has active recovery condition '${conditionLabel}' (root receipt: ${root.rootReceiptId})`;
+    return {
+      active: true,
+      reason,
+      finding: globalBarrierFinding(reason),
+    };
+  }
+
+  if (journal.isDegraded) {
+    const reason = `Global Receipt Journal is degraded (${journal.corruptedLineCount} corrupted lines)`;
+    return {
+      active: true,
+      reason,
+      finding: globalBarrierFinding(reason),
+    };
+  }
+
+  return { active: false };
+}

package/src/bridge-state/atomic.ts

@@ -0,0 +1,237 @@
+/**
+ * Atomic file utilities: WAL + write-to-temp → fsync → rename + file lock + read-after-verify
+ *
+ * Guarantees:
+ * - Cross-process concurrent writers do not corrupt the file (lock + atomic rename)
+ * - Readers never observe a torn write (rename is atomic on POSIX)
+ * - Durability: fsync temp file and parent dir before/after rename
+ * - Verification: read back persisted content and compare
+ *
+ * Fail-closed contract:
+ * - If neither previous nor target State Revision can be verified, caller should treat as Persistence Indeterminate
+ * - If previous revision still verified, it's Persistence Failed
+ *
+ * Lock strategy: advisory lock file via O_CREAT|O_EXCL (".lock" sibling). Stale locks are not auto-removed
+ * except on timeout; callers hold lock for the shortest interval (write+verify).
+ */
+
+import { closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { mkdirSync, existsSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+export interface AtomicWriteResult {
+  success: boolean;
+  error?: string;
+  /** Whether target was verified by read-after */
+  verified?: boolean;
+}
+
+/**
+ * Acquire an advisory lock file. Creates lockPath with O_EXCL and writes pid.
+ * Retries until timeoutMs (default 5000). Caller must release via releaseLock or the returned fd.
+ * Returns fd of lock file (already open). Caller should close+unlink on success/failure.
+ */
+export async function acquireLock(lockPath: string, timeoutMs = 5000): Promise<number> {
+  const start = Date.now();
+  const dir = dirname(lockPath);
+  mkdirSync(dir, { recursive: true });
+
+  while (true) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      try {
+        writeSync(fd, String(process.pid));
+        fsyncSync(fd);
+      } catch {
+        // ignore write failure but keep lock
+      }
+      return fd;
+    } catch (e: unknown) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== 'EEXIST') throw e;
+      if (Date.now() - start > timeoutMs) {
+        throw new Error(`Failed to acquire lock ${lockPath} after ${timeoutMs}ms`);
+      }
+      await new Promise<void>((resolve) => setTimeout(resolve, 20));
+    }
+  }
+}
+
+export function acquireLockSync(lockPath: string, timeoutMs = 5000): number {
+  const start = Date.now();
+  const dir = dirname(lockPath);
+  mkdirSync(dir, { recursive: true });
+  while (true) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      try {
+        writeSync(fd, String(process.pid));
+        fsyncSync(fd);
+      } catch {}
+      return fd;
+    } catch (e: unknown) {
+      const err = e as NodeJS.ErrnoException;
+      if (err.code !== 'EEXIST') throw e;
+      if (Date.now() - start > timeoutMs) {
+        throw new Error(`Failed to acquire lock ${lockPath} after ${timeoutMs}ms`);
+      }
+      // brief spin for sync path (used rarely)
+      const end = Date.now() + 10;
+      while (Date.now() < end) {}
+    }
+  }
+}
+
+export function releaseLock(fd: number, lockPath: string): void {
+  try {
+    closeSync(fd);
+  } catch {}
+  try {
+    unlinkSync(lockPath);
+  } catch {}
+}
+
+/** Run fn while holding the lock file. */
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T> | T,
+  timeoutMs = 5000,
+): Promise<T> {
+  const fd = await acquireLock(lockPath, timeoutMs);
+  let released = false;
+  const doRelease = () => {
+    if (!released) {
+      released = true;
+      releaseLock(fd, lockPath);
+    }
+  };
+  try {
+    const result = await fn();
+    doRelease();
+    return result;
+  } catch (e) {
+    doRelease();
+    throw e;
+  }
+}
+
+/**
+ * Atomic write: write data to temp file, fsync, rename to target, fsync dir, verify.
+ * Must be called while holding the sibling .lock if protecting against RMW races;
+ * but even without lock, this prevents torn reads.
+ */
+export function atomicWriteFile(targetPath: string, data: string): AtomicWriteResult {
+  const dir = dirname(targetPath);
+  mkdirSync(dir, { recursive: true });
+
+  const tmpName = `.${Date.now()}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  const tmpPath = join(dir, tmpName);
+
+  let tmpFd: number | undefined;
+  try {
+    tmpFd = openSync(tmpPath, 'wx', 0o600);
+    writeSync(tmpFd, data, null, 'utf-8');
+    fsyncSync(tmpFd);
+    closeSync(tmpFd);
+    tmpFd = undefined;
+
+    // Atomic rename
+    renameSync(tmpPath, targetPath);
+
+    // Fsync parent dir for durability (best-effort)
+    try {
+      const dirFd = openSync(dir, 'r');
+      try {
+        fsyncSync(dirFd);
+      } finally {
+        closeSync(dirFd);
+      }
+    } catch {
+      // fsync dir may fail on some filesystems; not fatal
+    }
+
+    // Read-after-verify
+    try {
+      const persisted = readFileSync(targetPath, 'utf-8');
+      if (persisted !== data) {
+        return {
+          success: false,
+          verified: false,
+          error: 'Read-after-verify mismatch: persisted content differs from written',
+        };
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { success: false, verified: false, error: `Read-after-verify failed: ${msg}` };
+    }
+
+    return { success: true, verified: true };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { success: false, verified: false, error: msg };
+  } finally {
+    if (tmpFd !== undefined) {
+      try {
+        closeSync(tmpFd);
+      } catch {}
+    }
+    // cleanup tmp if still exists
+    if (existsSync(tmpPath)) {
+      try {
+        unlinkSync(tmpPath);
+      } catch {}
+    }
+  }
+}
+
+/**
+ * Higher-level atomic commit that combines lock + write + verify,
+ * and classifies outcome as success / Persistence Failed / Persistence Indeterminate
+ * by checking whether previous revision is still readable.
+ * For scaffold, we defer Indeterminate classification to store.ts (needs read context).
+ */
+export async function atomicWriteWithLock(
+  targetPath: string,
+  data: string,
+  lockPath: string,
+  timeoutMs = 5000,
+): Promise<AtomicWriteResult & { lockHeld: boolean }> {
+  const fd = await acquireLock(lockPath, timeoutMs);
+  try {
+    const result = atomicWriteFile(targetPath, data);
+    releaseLock(fd, lockPath);
+    return { ...result, lockHeld: true };
+  } catch (e) {
+    try {
+      releaseLock(fd, lockPath);
+    } catch {}
+    const msg = e instanceof Error ? e.message : String(e);
+    return { success: false, verified: false, error: msg, lockHeld: true };
+  }
+}
+
+export function atomicWriteWithLockSync(
+  targetPath: string,
+  data: string,
+  lockPath: string,
+  timeoutMs = 5000,
+): AtomicWriteResult & { lockHeld: boolean } {
+  const fd = acquireLockSync(lockPath, timeoutMs);
+  try {
+    const result = atomicWriteFile(targetPath, data);
+    releaseLock(fd, lockPath);
+    return { ...result, lockHeld: true };
+  } catch (e) {
+    try {
+      releaseLock(fd, lockPath);
+    } catch {}
+    const msg = e instanceof Error ? e.message : String(e);
+    return { success: false, verified: false, error: msg, lockHeld: true };
+  }
+}
+
+// For testability: export fsync helper
+export function fsyncFileSync(fd: number): void {
+  fsyncSync(fd);
+}

package/src/bridge-state/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './paths.js';
+export * from './schema.js';
+export * from './atomic.js';
+export * from './store.js';