pi-codex-marketplace 0.1.0

package/src/reconciliation/startup.ts

@@ -0,0 +1,144 @@
+/**
+ * Startup Reconciliation — global-first verification and reconciliation pass on session start.
+ * See CONTEXT.md: Startup reconciliation, Global Pending Barrier, Pending Application.
+ *
+ * Rules:
+ * - At most one reconciliation pass per startup.
+ * - Global-first: Global scope is reconciled first.
+ * - Only scopes with enabled contributions, active recovery, or journal repair execute and produce a receipt.
+ * - If no work needed (clean/empty), no-op and does NOT generate empty receipts.
+ * - If Global recovery cannot reach a clean terminal state, Global Pending Barrier blocks Project reconciliation.
+ * - Reconciles Pending Application without implicit activation or auto-rollback.
+ */
+
+import { readBridgeStateSync } from '../bridge-state/store.js';
+import type { Scope } from '../bridge-state/types.js';
+import { checkGlobalPendingBarrier, globalBarrierFinding } from '../barrier/global-barrier.js';
+import { appendReceipt, readReceiptJournal } from '../journal/journal.js';
+import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
+
+export interface StartupReconciliationOptions {
+  cwd?: string;
+  agentDir?: string;
+  projectTrusted?: boolean;
+  verifyReload?: (scope: Scope) => Promise<boolean> | boolean;
+}
+
+export interface StartupReconciliationResult {
+  globalReconciled: boolean;
+  globalReceipt?: AttemptReceipt;
+  projectReconciled: boolean;
+  projectReceipt?: AttemptReceipt;
+}
+
+export async function runStartupReconciliation(
+  opts: StartupReconciliationOptions = {},
+): Promise<StartupReconciliationResult> {
+  const result: StartupReconciliationResult = {
+    globalReconciled: false,
+    projectReconciled: false,
+  };
+
+  const defaultVerify = async (_s: Scope) => true;
+  const verify = opts.verifyReload ?? defaultVerify;
+
+  // 1. Global Scope Pass
+  const globalState = readBridgeStateSync('global', opts);
+  const globalJournal = await readReceiptJournal('global', opts);
+
+  const globalPendingChain = globalJournal.activeChains.find(
+    (c) => c.condition === 'pending-application',
+  );
+
+  const globalHasEnabledInstallations =
+    globalState.status === 'ok' &&
+    globalState.state!.installations.some((i) => i.installationState === 'enabled');
+
+  if (globalPendingChain || (globalHasEnabledInstallations && globalJournal.receipts.length > 0)) {
+    const rev = globalState.status === 'ok' ? globalState.state!.stateRevision : '0';
+    const applied = await verify('global');
+    const summary = applied ? 'Completed' : 'Pending Application';
+
+    const receipt = createReceipt({
+      kind: 'Reconciliation',
+      operation: 'Startup Reconciliation',
+      scope: 'global',
+      trigger: 'startup reconciliation global',
+      expectedStateRevision: rev,
+      observedStateRevision: applied ? rev : undefined,
+      durableOutcome: 'unchanged',
+      runtimeOutcome: applied ? 'applied' : 'pending-application',
+      summary,
+      recoversReceiptId: globalPendingChain?.rootReceiptId,
+    });
+
+    await appendReceipt('global', receipt, opts);
+    result.globalReconciled = true;
+    result.globalReceipt = receipt;
+  }
+
+  // 2. Check Global Barrier before attempting Project Scope
+  const barrier = await checkGlobalPendingBarrier(opts);
+
+  // 3. Project Scope Pass
+  const projectState = readBridgeStateSync('project', opts);
+  const projectJournal = await readReceiptJournal('project', opts);
+
+  const projectPendingChain = projectJournal.activeChains.find(
+    (c) => c.condition === 'pending-application',
+  );
+
+  const projectHasEnabledInstallations =
+    projectState.status === 'ok' &&
+    projectState.state!.installations.some((i) => i.installationState === 'enabled');
+
+  const projectNeedsWork =
+    Boolean(projectPendingChain) ||
+    (projectHasEnabledInstallations && projectJournal.receipts.length > 0);
+
+  if (projectNeedsWork) {
+    const rev = projectState.status === 'ok' ? projectState.state!.stateRevision : '0';
+
+    if (barrier.active) {
+      // Blocked by Global Pending Barrier
+      const receipt = createReceipt({
+        kind: 'Reconciliation',
+        operation: 'Startup Reconciliation',
+        scope: 'project',
+        trigger: 'startup reconciliation project',
+        expectedStateRevision: rev,
+        durableOutcome: 'unchanged',
+        runtimeOutcome: 'none',
+        summary: 'Blocked',
+        findings: [barrier.finding ?? globalBarrierFinding(barrier.reason ?? 'Global Barrier active')],
+        recoversReceiptId: projectPendingChain?.rootReceiptId,
+      });
+
+      await appendReceipt('project', receipt, opts);
+      result.projectReconciled = true;
+      result.projectReceipt = receipt;
+    } else if (opts.projectTrusted === true) {
+      const applied = await verify('project');
+      const summary = applied ? 'Completed' : 'Pending Application';
+
+      const receipt = createReceipt({
+        kind: 'Reconciliation',
+        operation: 'Startup Reconciliation',
+        scope: 'project',
+        trigger: 'startup reconciliation project',
+        expectedStateRevision: rev,
+        observedStateRevision: applied ? rev : undefined,
+        durableOutcome: 'unchanged',
+        runtimeOutcome: applied ? 'applied' : 'pending-application',
+        summary,
+        recoversReceiptId: projectPendingChain?.rootReceiptId,
+      });
+
+      await appendReceipt('project', receipt, opts);
+      result.projectReconciled = true;
+      result.projectReceipt = receipt;
+    }
+  }
+
+  return result;
+}

package/src/registration/budget.ts

@@ -0,0 +1,28 @@
+/**
+ * Validation Ruleset / Validation Budget — versioned Bridge contracts applied during validation.
+ * See CONTEXT.md: Validation Ruleset, Validation Budget.
+ *
+ * A changed ruleset or budget requires revalidation even when source bytes are unchanged.
+ * Exceeding a budget produces a Blocking Finding at the owning boundary (source/catalog/entry),
+ * never partial or best-effort validation.
+ */
+
+export const VALIDATION_RULESET = 'ruleset:v1';
+export const VALIDATION_BUDGET = 'budget:v1';
+/** Compatibility Profile reference bound into every snapshot (full profile contract is #19). */
+export const COMPATIBILITY_PROFILE = 'profile:v1';
+
+export const BUDGET = {
+  /** Maximum tree depth under the Marketplace Root (1 = immediate children). */
+  maxTreeDepth: 32,
+  /** Maximum inspected files (regular files) under the root. */
+  maxFiles: 10_000,
+  /** Maximum total bytes of inspected file content. */
+  maxTotalBytes: 512 * 1024 * 1024,
+  /** Maximum Marketplace Catalog file bytes. */
+  maxCatalogBytes: 1 * 1024 * 1024,
+  /** Maximum plugins entries in a catalog. */
+  maxEntries: 1024,
+  /** Maximum declared marketplace name length. */
+  maxNameLength: 64,
+} as const;

package/src/registration/catalog.ts

@@ -0,0 +1,224 @@
+/**
+ * Marketplace Catalog — canonical `.agents/plugins/marketplace.json` object within a Marketplace Root.
+ * See CONTEXT.md: Marketplace Catalog, Marketplace Entry, Marketplace Entry ID.
+ *
+ * Only the canonical object participates in Bridge ingestion; legacy/antigravity shapes are ignored
+ * (detected as catalog missing). Each entry is enumerated with a snapshot-scoped Marketplace Entry ID
+ * `/plugins/<zero-based ordinal>`. Non-local entry source kinds are recognized only as Unavailable
+ * Entries rather than recursively acquired.
+ */
+
+import { CODE, RULE, blocking, type ValidationFinding } from './findings.js';
+import { BUDGET } from './budget.js';
+
+export type EntryType = 'local' | 'git' | 'unsupported';
+
+const LOCAL_KINDS = new Set(['local', 'directory', 'dir', 'file', 'path', 'src']);
+const NONLOCAL_KINDS = new Set(['git', 'github', 'repo', 'url', 'remote', 'http', 'https']);
+
+/** Matches lowercase kebab-case names (Codex marketplace declared name). */
+export const KEBAB_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export interface MarketplaceEntry {
+  /** Snapshot-scoped identity: `/plugins/<ordinal>`. */
+  entryId: string;
+  /** Zero-based ordinal in the plugins[] array. */
+  ordinal: number;
+  /** Declared entry name if present. */
+  name?: string;
+  /** Recognized source kind. */
+  type: EntryType;
+  /** Declared `./`-relative Contained Path for local entries. */
+  path?: string;
+  /** Whether this entry can supply an activatable plugin (else Unavailable). */
+  available: boolean;
+  /** Human reason when unavailable. */
+  unavailableReason?: string;
+}
+
+export interface Catalog {
+  /** Declared validated lowercase kebab-case name. */
+  name: string;
+  /** Enumerated entries (snapshot-scoped). */
+  entries: MarketplaceEntry[];
+}
+
+export interface CatalogResult {
+  ok: boolean;
+  catalog?: Catalog;
+  findings: ValidationFinding[];
+}
+
+function classifyKind(raw: unknown): { type: EntryType; reason?: string } {
+  if (raw === undefined || raw === null || raw === '') return { type: 'local' };
+  const s = String(raw).toLowerCase();
+  if (LOCAL_KINDS.has(s)) return { type: 'local' };
+  if (NONLOCAL_KINDS.has(s)) return { type: 'git' };
+  return { type: 'unsupported' };
+}
+
+/**
+ * Parse a parsed `.agents/plugins/marketplace.json` object structurally.
+ * Structural/catalog-identity failures are Blocking (deny Registration); per-entry inability to
+ * resolve to a plugin is an Unavailable Entry (disclosed, non-blocking).
+ */
+export function parseCatalog(obj: unknown, opts: { scope: 'global' | 'project' }): CatalogResult {
+  const findings: ValidationFinding[] = [];
+
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+    return {
+      ok: false,
+      findings: [
+        blocking({
+          code: CODE.CATALOG_MALFORMED,
+          phase: 'validation',
+          target: 'catalog',
+          scope: opts.scope,
+          pointer: '/',
+          rule: RULE.CATALOG_MALFORMED,
+          outcome: 'marketplace.json is not an object',
+        }),
+      ],
+    };
+  }
+  const o = obj as Record<string, unknown>;
+
+  if (typeof o.name !== 'string' || o.name.trim().length === 0) {
+    findings.push(
+      blocking({
+        code: CODE.CATALOG_NAME_INVALID,
+        phase: 'validation',
+        target: 'catalog',
+        scope: opts.scope,
+        pointer: '/name',
+        rule: RULE.CATALOG_NAME_INVALID,
+        outcome: 'declared marketplace name is missing',
+      }),
+    );
+  } else if (!KEBAB_NAME_RE.test(o.name.trim())) {
+    findings.push(
+      blocking({
+        code: CODE.CATALOG_NAME_INVALID,
+        phase: 'validation',
+        target: 'catalog',
+        scope: opts.scope,
+        pointer: '/name',
+        rule: RULE.CATALOG_NAME_INVALID,
+        outcome: `declared marketplace name '${o.name}' is not lowercase kebab-case`,
+      }),
+    );
+  }
+
+  if (!Array.isArray(o.plugins)) {
+    findings.push(
+      blocking({
+        code: CODE.CATALOG_MALFORMED,
+        phase: 'validation',
+        target: 'catalog',
+        scope: opts.scope,
+        pointer: '/plugins',
+        rule: RULE.CATALOG_MALFORMED,
+        outcome: 'plugins is not an array',
+      }),
+    );
+    return {
+      ok: false,
+      findings,
+    };
+  }
+
+  if (o.plugins.length > BUDGET.maxEntries) {
+    return {
+      ok: false,
+      findings: [blocking({
+        code: CODE.BUDGET_EXCEEDED,
+        phase: 'validation',
+        target: 'catalog',
+        scope: opts.scope,
+        pointer: '/plugins',
+        rule: RULE.BUDGET_EXCEEDED,
+        outcome: `Validation Budget exceeded: ${o.plugins.length} entries > ${BUDGET.maxEntries}`,
+      })],
+    };
+  }
+
+  const entries: MarketplaceEntry[] = [];
+  o.plugins.forEach((entryRaw, index) => {
+    const entryId = `/plugins/${index}`;
+    if (typeof entryRaw !== 'object' || entryRaw === null || Array.isArray(entryRaw)) {
+      findings.push(
+        blocking({
+          code: CODE.CATALOG_ENTRY_MALFORMED,
+          phase: 'validation',
+          target: 'entry',
+          scope: opts.scope,
+          pointer: entryId,
+          rule: RULE.CATALOG_ENTRY_MALFORMED,
+          outcome: 'marketplace entry is not an object',
+        }),
+      );
+      entries.push({ entryId, ordinal: index, type: 'unsupported', available: false, unavailableReason: 'malformed entry' });
+      return;
+    }
+    const e = entryRaw as Record<string, unknown>;
+    // Codex Marketplace v1 uses `source: { source: "local", path: "./…" }`.
+    // Retain the earlier flat shape as a backward-compatible input, but derive the canonical
+    // source kind/path from the nested object when present.
+    const nestedSource = typeof e.source === 'object' && e.source !== null && !Array.isArray(e.source)
+      ? e.source as Record<string, unknown>
+      : undefined;
+    const nestedKind = nestedSource ? classifyKind(nestedSource.source ?? nestedSource.type) : undefined;
+    const flatKind = classifyKind(e.type ?? e.kind);
+    const nestedPath = typeof nestedSource?.path === 'string' ? nestedSource.path : undefined;
+    const flatPath = typeof e.path === 'string' ? e.path : undefined;
+    // The canonical nested v1 source is an indivisible declaration.  Never mix a flat kind/path
+    // with it: a conflicting flat `type: local` must not disguise nested `source: git`.
+    if (nestedSource && ((e.type !== undefined || e.kind !== undefined) && flatKind.type !== nestedKind!.type || (flatPath !== undefined && flatPath !== nestedPath))) {
+      entries.push({ entryId, ordinal: index, type: 'unsupported', available: false, unavailableReason: 'conflicting nested and flat source declaration' });
+      return;
+    }
+    const kind = nestedKind ?? flatKind;
+    const name = typeof e.name === 'string' ? e.name : undefined;
+    const path = nestedSource ? nestedPath : flatPath;
+
+    if (kind.type !== 'local') {
+      // Recognized only as an Unavailable Entry (never recursively acquired). Disclosed, not a finding.
+      entries.push({
+        entryId,
+        ordinal: index,
+        name,
+        type: kind.type,
+        path,
+        available: false,
+        unavailableReason: 'unsupported source kind',
+      });
+      return;
+    }
+
+    // local entry
+    if (!path) {
+      entries.push({
+        entryId,
+        ordinal: index,
+        name,
+        type: 'local',
+        path,
+        available: false,
+        unavailableReason: 'cannot resolve to a Plugin: no local path declared',
+      });
+      return;
+    }
+    entries.push({ entryId, ordinal: index, name, type: 'local', path, available: true });
+  });
+
+  // Duplicate entry names are distinguished by Entry ID; not a Blocking here (identity is ordinal-based).
+  const blocked = findings.some((f) => f.classification === 'blocking');
+  if (!blocked) {
+    return {
+      ok: true,
+      catalog: { name: String(o.name).trim(), entries },
+      findings,
+    };
+  }
+  return { ok: false, catalog: { name: typeof o.name === 'string' ? o.name.trim() : '', entries }, findings };
+}

package/src/registration/contained.ts

@@ -0,0 +1,140 @@
+/**
+ * Contained Path / Contained Symlink — strict containment within an owning root.
+ * See CONTEXT.md: Contained Path, Contained Symlink.
+ *
+ * Contained Path: a declared `./`-relative path with no absolute, backslash, NUL, dot, or parent
+ * segment whose canonical target remains within its owning root. Existence without containment is
+ * insufficient.
+ *
+ * Contained Symlink: a symlink whose canonical target is a regular file or directory within the same
+ * owning root. Broken, looping, special-file, or root-external symlinks are Blocking Findings.
+ */
+
+import { realpathSync, readlinkSync, lstatSync, statSync } from 'node:fs';
+import { isAbsolute, sep } from 'node:path';
+
+export interface PathSyntax {
+  ok: boolean;
+  reason?: string;
+}
+
+/** Validate `./`-relative path syntax (no absolute, backslash, NUL, dot, or parent segments). */
+export function containedPathSyntax(p: string): PathSyntax {
+  if (typeof p !== 'string' || p.length === 0) return { ok: false, reason: 'empty path' };
+  if (p.includes('\0')) return { ok: false, reason: 'NUL byte' };
+  if (p.includes('\\')) return { ok: false, reason: 'backslash' };
+  if (isAbsolute(p)) return { ok: false, reason: 'absolute path' };
+  if (!p.startsWith('./')) return { ok: false, reason: 'not ./ relative' };
+  const segments = p.split('/');
+  // "./x" -> segments ['', '.', 'x']; a bare "." or ".." component anywhere is rejected
+  const rest = segments.slice(1);
+  for (const seg of rest) {
+    if (seg === '' || seg === '.' || seg === '..') {
+      return { ok: false, reason: `dot or parent segment '${seg}'` };
+    }
+  }
+  return { ok: true };
+}
+
+export type ContainmentBlockClass = 'path' | 'symlink';
+
+export type ContainmentOutcome =
+  | { kind: 'ok'; canonicalPath: string }
+  | { kind: 'blocking'; reason: string; blockClass: ContainmentBlockClass } // safety violation
+  | { kind: 'missing' } // cannot resolve (Unavailable, not blocking)
+
+export interface ContainmentResult {
+  outcome: ContainmentOutcome;
+  /** Symlink target when the resolved target is a symlink, else undefined. */
+  symlinkTarget?: string;
+  type: 'file' | 'directory' | 'symlink' | 'special';
+}
+
+function isWithin(root: string, target: string): boolean {
+  if (target === root) return true;
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  return target.startsWith(prefix);
+}
+
+/**
+ * Resolve a `./`-relative declared path against a canonical owning root and verify strict
+ * containment (including symlink targets) within the root.
+ */
+export function resolveContained(root: string, relPath: string, checkType: 'any' | 'file' | 'directory' = 'any'): ContainmentResult {
+  const syntax = containedPathSyntax(relPath);
+  if (!syntax.ok) {
+    return {
+      outcome: { kind: 'blocking', blockClass: 'path', reason: `path containment syntax violation: ${syntax.reason}` },
+      type: 'special',
+    };
+  }
+
+  const abs = root + sep + relPath.slice(2);
+  let canonical: string;
+  try {
+    canonical = realpathSync.native(abs);
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') return { outcome: { kind: 'missing' }, type: 'special' };
+    return { outcome: { kind: 'blocking', blockClass: 'symlink', reason: `unable to resolve: ${err.message}` }, type: 'special' };
+  }
+
+  // containment check
+  if (!isWithin(root, canonical)) {
+    return {
+      outcome: { kind: 'blocking', blockClass: 'path', reason: `canonical target '${canonical}' escapes owning root '${root}'` },
+      type: 'special',
+    };
+  }
+
+  let type: ContainmentResult['type'];
+  let symlinkTarget: string | undefined;
+  try {
+    const lst = lstatSync(abs);
+    if (lst.isSymbolicLink()) {
+      type = 'symlink';
+      symlinkTarget = readlinkSync(abs);
+      // canonical already resolved; for symlink, target file must be a regular file or directory
+      try {
+        const st = statSync(abs);
+        if (!st.isFile() && !st.isDirectory()) {
+          return {
+            outcome: { kind: 'blocking', blockClass: 'symlink', reason: 'contained symlink resolves to a special file' },
+            type: 'symlink',
+            symlinkTarget,
+          };
+        }
+      } catch (e) {
+        const err = e as NodeJS.ErrnoException;
+        if (err.code === 'ENOENT') {
+          return {
+            outcome: { kind: 'blocking', blockClass: 'symlink', reason: 'broken symlink (target does not exist)' },
+            type: 'symlink',
+            symlinkTarget,
+          };
+        }
+        return {
+          outcome: { kind: 'blocking', blockClass: 'symlink', reason: `symlink error: ${err.message}` },
+          type: 'symlink',
+          symlinkTarget,
+        };
+      }
+    } else if (lst.isFile()) {
+      type = 'file';
+    } else if (lst.isDirectory()) {
+      type = 'directory';
+    } else {
+      return { outcome: { kind: 'blocking', blockClass: 'path', reason: 'not a regular file or directory' }, type: 'special' };
+    }
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') return { outcome: { kind: 'missing' }, type: 'special' };
+    return { outcome: { kind: 'blocking', blockClass: 'path', reason: `lstat error: ${err.message}` }, type: 'special' };
+  }
+
+  if (checkType !== 'any' && type !== checkType && type !== 'symlink') {
+    return { outcome: { kind: 'blocking', blockClass: 'path', reason: `expected ${checkType} but got ${type}` }, type };
+  }
+
+  return { outcome: { kind: 'ok', canonicalPath: canonical }, type, symlinkTarget };
+}

package/src/registration/fence.ts

@@ -0,0 +1,86 @@
+/**
+ * Attempt Fence — per-scope exclusivity boundary for Lifecycle Operations.
+ * See CONTEXT.md: Attempt Fence, Global Pending Barrier, Blocking Finding.
+ *
+ * Admits only one attempt at a time per scope. The fence is acquired before preflight and held
+ * until the attempt reaches a terminal outcome (committed / declined / blocked / stale). A second
+ * concurrent attempt on the same scope is denied with an ATTEMPT_IN_PROGRESS Blocking Finding.
+ *
+ * For Project Scope: Global Pending Barrier is checked prior to fence acquisition. If active,
+ * the attempt is blocked with GLOBAL_PENDING_BARRIER.
+ *
+ * Cross-process: a lock file sibling to the scope's state document is used (O_EXCL advisory lock).
+ */
+
+import { acquireLock, releaseLock } from '../bridge-state/atomic.js';
+import { getFencePath, getStatePath } from '../bridge-state/paths.js';
+import type { Scope } from '../bridge-state/types.js';
+import { checkGlobalPendingBarrier } from '../barrier/global-barrier.js';
+import { CODE, RULE, blocking, type ValidationFinding } from './findings.js';
+
+export interface AttemptFenceHandle {
+  scope: Scope;
+  release(): void;
+  released: boolean;
+}
+
+export interface AttemptFenceResult {
+  ok: boolean;
+  handle?: AttemptFenceHandle;
+  finding?: ValidationFinding;
+}
+
+const FENCE_LOCK_TIMEOUT_MS = 300;
+
+/** Acquire the per-scope Attempt Fence (lock file). Denied when another attempt holds it or Global Barrier active. */
+export async function acquireAttemptFence(
+  scope: Scope,
+  opts: { cwd?: string; agentDir?: string; fenceTimeoutMs?: number; projectTrusted?: boolean } = {},
+): Promise<AttemptFenceResult> {
+  // Global Pending Barrier: blocks Project Scope attempts
+  if (scope === 'project') {
+    const barrier = await checkGlobalPendingBarrier(opts);
+    if (barrier.active) {
+      return {
+        ok: false,
+        finding: barrier.finding,
+      };
+    }
+  }
+
+  const statePath = getStatePath(scope, opts);
+  const fencePath = getFencePath(statePath);
+  const timeout = opts.fenceTimeoutMs ?? FENCE_LOCK_TIMEOUT_MS;
+
+  let fd: number;
+  try {
+    fd = await acquireLock(fencePath, timeout);
+  } catch {
+    return {
+      ok: false,
+      finding: blocking({
+        code: CODE.ATTEMPT_IN_PROGRESS,
+        phase: 'admission',
+        target: 'attempt',
+        scope,
+        pointer: '',
+        rule: RULE.ATTEMPT_IN_PROGRESS,
+        outcome: `another ${scope} attempt is in progress; only one attempt at a time per scope (no queue)`,
+      }),
+    };
+  }
+
+  let released = false;
+  const handle: AttemptFenceHandle = {
+    scope,
+    get released(): boolean {
+      return released;
+    },
+    release(): void {
+      if (released) return;
+      released = true;
+      releaseLock(fd, fencePath);
+    },
+  };
+  return { ok: true, handle };
+}