@worca/app 0.0.1

package/src/core/guardrails.mjs

@@ -0,0 +1,302 @@
+// src/core/guardrails.mjs
+// Per-project guardrails: the pure policy layer.
+//   - 5-key settings shape: { honorProjectSettings, envScrub, envAllowlist,
+//     protectedPaths, deny } — what enforcement consumes.
+//   - stored config shape:  { level, custom } — what the DB holds. Preset levels
+//     resolve from GUARDRAIL_PRESETS at read time so preset improvements ship
+//     with worca upgrades; `custom` is the user's pinned blob (dormant unless
+//     level === 'custom', preserved across level switches).
+// Storage: project_config.extra.guardrails (config.mjs). Enforcement: a Claude
+// Code `permissions` object in ONE --settings payload + a scrubbed spawn env
+// (claude-runner.mjs). Everything here is pure and throw-free except the
+// validate* functions, which report instead of throwing.
+//
+// Rule-spelling invariants (see plan Global Constraints):
+//   - Bash denies are exact+prefix PAIRS: Bash(cmd) + Bash(cmd:*).
+//   - protectedPaths: slash-less patterns match at any depth; slash-containing
+//     patterns MUST carry a **/ prefix or they anchor to cwd and miss members
+//     on detached workspace runs.
+
+export const DEFAULT_GUARDRAILS = Object.freeze({
+  honorProjectSettings: true,
+  envScrub: false,
+  envAllowlist: Object.freeze([]),
+  protectedPaths: Object.freeze([]),
+  deny: Object.freeze([]),
+});
+
+export const GUARDRAIL_LEVELS = Object.freeze(['permissive', 'normal', 'secure', 'custom']);
+
+const deepFreeze = (o) => {
+  for (const v of Object.values(o)) {
+    if (v && typeof v === 'object' && !Object.isFrozen(v)) deepFreeze(v);
+  }
+  return Object.freeze(o);
+};
+
+// Credential-material file patterns every non-permissive level protects.
+const NORMAL_PROTECTED = [
+  '.env*',                 // .env, .env.local, .env.production, .envrc — any depth
+  '*.pem', '*.key',        // TLS / private key material
+  'id_rsa', 'id_ed25519',  // bare SSH keys checked into odd places
+  '*.p12', '*.pfx',        // bundled cert+key stores
+];
+
+// Irreversible-publication commands no pipeline role ever needs.
+const NORMAL_DENY = [
+  'Bash(git push)', 'Bash(git push:*)',
+  'Bash(npm publish)', 'Bash(npm publish:*)',
+  'Bash(yarn publish)', 'Bash(yarn publish:*)',
+  'Bash(pnpm publish)', 'Bash(pnpm publish:*)',
+];
+
+/**
+ * The built-in levels. `custom` is not here — it resolves from storage.
+ * permissive IS DEFAULT_GUARDRAILS (same object): an unconfigured project and a
+ * permissive project are indistinguishable, including byte-identical spawn argv.
+ * Normal: protect credential files, block publication; never breaks a pipeline
+ * (git commit / npm install / npm test / curl localhost all untouched).
+ * Secure++: Normal + env scrub (the real exfil control) + egress binaries +
+ * publish channels + cloud-credential CLIs + WebFetch/WebSearch (defense against
+ * frontmatter-widened agents). Still functional: project file Read/Write/Edit,
+ * npm install/test, and local git commits are untouched.
+ */
+export const GUARDRAIL_PRESETS = deepFreeze({
+  permissive: DEFAULT_GUARDRAILS,
+  normal: {
+    honorProjectSettings: true,
+    envScrub: false,
+    envAllowlist: [],
+    protectedPaths: [...NORMAL_PROTECTED],
+    deny: [...NORMAL_DENY],
+  },
+  secure: {
+    honorProjectSettings: true,
+    envScrub: true,
+    envAllowlist: [],
+    protectedPaths: [
+      ...NORMAL_PROTECTED,
+      '.npmrc', '.netrc',            // token-bearing rc files (project-level)
+      '*.tfstate*',                  // terraform state embeds raw secrets
+      '*.keystore', '*.jks',
+      '**/secrets/**',               // slash-containing ⇒ needs **/ (anchoring)
+      '**/.git/config',              // can embed https://user:token@ remotes
+      '~/.git-credentials',          // git credential-store: plaintext https://user:token@ lines
+      '~/.ssh/**', '~/.aws/**', '~/.config/gcloud/**', '~/.kube/**', '~/.config/gh/**',  // gh hosts.yml holds the OAuth token
+      '~/.npmrc', '~/.netrc', '~/.docker/config.json',
+    ],
+    deny: [
+      ...NORMAL_DENY,
+      'Bash(curl)', 'Bash(curl:*)', 'Bash(wget)', 'Bash(wget:*)',
+      'Bash(nc)', 'Bash(nc:*)', 'Bash(ncat)', 'Bash(ncat:*)', 'Bash(netcat)', 'Bash(netcat:*)',
+      'Bash(telnet)', 'Bash(telnet:*)',
+      'Bash(ssh)', 'Bash(ssh:*)', 'Bash(scp)', 'Bash(scp:*)', 'Bash(sftp)', 'Bash(sftp:*)',
+      'Bash(rsync)', 'Bash(rsync:*)', 'Bash(ftp)', 'Bash(ftp:*)',
+      'Bash(gh)', 'Bash(gh:*)',
+      'Bash(docker push)', 'Bash(docker push:*)',
+      'Bash(aws)', 'Bash(aws:*)', 'Bash(gcloud)', 'Bash(gcloud:*)', 'Bash(az)', 'Bash(az:*)',
+      'WebFetch', 'WebSearch',
+    ],
+  },
+});
+
+// A permission rule is `Tool(pattern)` (pattern non-empty), a bare tool name, a
+// tool-name glob (`*` = all tools, `Bash*`), or an mcp__ tool id. Deliberately
+// permissive inside the parens — the CLI owns pattern semantics; we only reject
+// obvious shell text / malformed shapes. (The `*`/`Tool*` forms are valid deny
+// globs per Claude Code docs; accepting them keeps the custom editor from 400ing
+// a legitimate rule.)
+const RULE_RE = /^(?:[A-Za-z*][A-Za-z0-9_*]*(?:\(.+\))?|mcp__[A-Za-z0-9_.*-]+(?:__[A-Za-z0-9_.*-]+)*)$/;
+
+export function isPermissionRule(s) {
+  return typeof s === 'string' && RULE_RE.test(s.trim());
+}
+
+const cleanStrings = (v) =>
+  Array.isArray(v) ? v.map((s) => (typeof s === 'string' ? s.trim() : '')).filter(Boolean) : [];
+
+/** Read-path sanitizer for the 5-key settings shape. Malformed → defaults; invalid deny rules drop. */
+export function sanitizeGuardrails(raw) {
+  const src = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  return {
+    honorProjectSettings:
+      typeof src.honorProjectSettings === 'boolean' ? src.honorProjectSettings : true,
+    envScrub: src.envScrub === true,
+    envAllowlist: cleanStrings(src.envAllowlist),
+    protectedPaths: cleanStrings(src.protectedPaths),
+    deny: cleanStrings(src.deny).filter(isPermissionRule),
+  };
+}
+
+/** Write-path validator for the 5-key settings shape: strict, collects errors, never throws. */
+export function validateGuardrails(raw) {
+  const errors = [];
+  if (raw === undefined || raw === null) return { ok: true, errors };
+  if (typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, errors: ['guardrails must be an object'] };
+  for (const k of ['honorProjectSettings', 'envScrub']) {
+    if (k in raw && typeof raw[k] !== 'boolean') errors.push(`${k} must be a boolean`);
+  }
+  for (const k of ['envAllowlist', 'protectedPaths', 'deny']) {
+    if (k in raw) {
+      if (!Array.isArray(raw[k])) errors.push(`${k} must be an array of strings`);
+      else for (const s of raw[k]) if (typeof s !== 'string' || !s.trim()) errors.push(`${k} entries must be non-empty strings`);
+    }
+  }
+  if (Array.isArray(raw.deny)) {
+    for (const r of raw.deny) {
+      if (typeof r === 'string' && r.trim() && !isPermissionRule(r)) {
+        errors.push(`deny rule "${r}" is not a valid permission rule (expected Tool(pattern))`);
+      }
+    }
+  }
+  const known = new Set(['honorProjectSettings', 'envScrub', 'envAllowlist', 'protectedPaths', 'deny']);
+  for (const k of Object.keys(raw)) if (!known.has(k)) errors.push(`unknown key "${k}"`);
+  return { ok: errors.length === 0, errors };
+}
+
+const FIVE_KEYS = ['honorProjectSettings', 'envScrub', 'envAllowlist', 'protectedPaths', 'deny'];
+
+/**
+ * Read-path sanitizer for the STORED config shape.
+ * { level, custom } passes through (bad level fails open to permissive — parity);
+ * a v1-era bare 5-key blob upgrades losslessly to { level:'custom', custom };
+ * anything else → { level:'permissive', custom:null }.
+ * Lenient about unknown wrapper keys by design (a future v3 blob read by v2
+ * degrades gracefully); the WRITE path (validateGuardrailsConfig) stays strict.
+ */
+export function sanitizeGuardrailsConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { level: 'permissive', custom: null };
+  const custom = raw.custom && typeof raw.custom === 'object' && !Array.isArray(raw.custom)
+    ? sanitizeGuardrails(raw.custom)
+    : null;
+  if (typeof raw.level === 'string') {
+    return GUARDRAIL_LEVELS.includes(raw.level)
+      ? { level: raw.level, custom }
+      : { level: 'permissive', custom };
+  }
+  if (FIVE_KEYS.some((k) => k in raw)) return { level: 'custom', custom: sanitizeGuardrails(raw) };
+  return { level: 'permissive', custom: null };
+}
+
+/**
+ * Write-path validator for the { level, custom? } shape (the API's 400 source).
+ * @param {object} raw
+ * @param {{hasStoredCustom?: boolean}} opts  whether the DB already holds a custom blob
+ */
+export function validateGuardrailsConfig(raw, { hasStoredCustom = false } = {}) {
+  const errors = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ok: false, errors: ['guardrails must be an object'] };
+  }
+  if (!GUARDRAIL_LEVELS.includes(raw.level)) {
+    errors.push(`level must be one of: ${GUARDRAIL_LEVELS.join(', ')}`);
+  }
+  const hasCustomPayload = raw.custom !== undefined && raw.custom !== null;
+  if (hasCustomPayload) {
+    const v = validateGuardrails(raw.custom);
+    errors.push(...v.errors);
+  } else if (raw.level === 'custom' && !hasStoredCustom) {
+    errors.push('custom guardrail settings required when level is "custom"');
+  }
+  const known = new Set(['level', 'custom']);
+  for (const k of Object.keys(raw)) if (!known.has(k)) errors.push(`unknown key "${k}"`);
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Stored config → EFFECTIVE 5-key settings. Preset levels resolve from the code
+ * table (fresh copies — the frozen table never leaks); custom resolves from the
+ * stored blob (null custom degrades to the empty policy).
+ */
+export function resolveGuardrails(stored) {
+  const cfg = sanitizeGuardrailsConfig(stored);
+  if (cfg.level === 'custom') return cfg.custom ? { ...cfg.custom, envAllowlist: [...cfg.custom.envAllowlist], protectedPaths: [...cfg.custom.protectedPaths], deny: [...cfg.custom.deny] } : sanitizeGuardrails(undefined);
+  return sanitizeGuardrails(GUARDRAIL_PRESETS[cfg.level]);
+}
+
+const presetKey = (g) => {
+  const s = sanitizeGuardrails(g);
+  return JSON.stringify({
+    honorProjectSettings: s.honorProjectSettings,
+    envScrub: s.envScrub,
+    envAllowlist: [...new Set(s.envAllowlist)].sort(),
+    protectedPaths: [...new Set(s.protectedPaths)].sort(),
+    deny: [...new Set(s.deny)].sort(),
+  });
+};
+
+/**
+ * Which built-in preset a 5-key settings object equals, or null (⇒ Custom).
+ * Order-insensitive: the lists are semantically sets (everything downstream
+ * de-dupes/unions), so a reordered list must not read as "customised".
+ */
+export function detectPreset(settings) {
+  const key = presetKey(settings);
+  for (const level of ['permissive', 'normal', 'secure']) {
+    if (presetKey(GUARDRAIL_PRESETS[level]) === key) return level;
+  }
+  return null;
+}
+
+/** Expand 5-key settings into Claude Code permission rules. null when empty. */
+export function guardrailsToPermissionRules(g) {
+  const gg = sanitizeGuardrails(g);
+  const deny = [];
+  const push = (r) => { if (!deny.includes(r)) deny.push(r); };
+  // Read + Edit ONLY. Claude Code consults only Read/Edit path rules for file
+  // permissions (Edit covers all file-editing tools: Write/NotebookEdit); a
+  // Write() rule is never consulted AND prints a stderr warning per rule per
+  // spawn on CLI 2.1.210+ (which runReal folds into the failure message). Read
+  // is the load-bearing secret guard; a Read deny also blocks Edit (≥2.1.208).
+  for (const p of gg.protectedPaths) { push(`Read(${p})`); push(`Edit(${p})`); }
+  for (const r of gg.deny) push(r);
+  return deny.length ? { deny } : null;
+}
+
+/** De-duped union of two {deny?,allow?,ask?} rule objects. null when empty. */
+export function mergePermissionRules(a, b) {
+  const out = {};
+  for (const key of ['deny', 'allow', 'ask']) {
+    const seen = new Set();
+    const arr = [];
+    for (const src of [a, b]) {
+      for (const r of Array.isArray(src?.[key]) ? src[key] : []) {
+        if (typeof r === 'string' && r.trim() && !seen.has(r)) { seen.add(r); arr.push(r); }
+      }
+    }
+    if (arr.length) out[key] = arr;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Deny-safe union across workspace members' EFFECTIVE settings: any member
+ * scrubbing scrubs the run; the RESTRICTION lists (protectedPaths, deny) union
+ * de-duped across ALL members; the envAllowlist — a WIDENER — unions ONLY over
+ * members that actually scrub, so a non-scrubbing member's dormant allowlist can
+ * never punch a hole in another member's scrub. More guarding always wins; a
+ * member can never relax another member's policy. (Permissive member + Secure
+ * member ⇒ Secure for the whole run — by design; surfaced in docs (Task 12) and
+ * the panel hint (Task 10).)
+ * NOTE: `honorProjectSettings` is unioned here for shape completeness only and is
+ * ADVISORY — the repo-settings lift is gated PER MEMBER by each member's own
+ * honorProjectSettings (Task 6/7), never by this any-true scalar.
+ */
+export function unionGuardrails(list) {
+  const gs = (Array.isArray(list) ? list : []).map(sanitizeGuardrails);
+  if (!gs.length) return sanitizeGuardrails(undefined);
+  const unionList = (src, key) => {
+    const seen = new Set();
+    const arr = [];
+    for (const g of src) for (const s of g[key]) if (!seen.has(s)) { seen.add(s); arr.push(s); }
+    return arr;
+  };
+  const scrubbers = gs.filter((g) => g.envScrub);
+  return {
+    honorProjectSettings: gs.some((g) => g.honorProjectSettings),
+    envScrub: scrubbers.length > 0,
+    envAllowlist: unionList(scrubbers, 'envAllowlist'),
+    protectedPaths: unionList(gs, 'protectedPaths'),
+    deny: unionList(gs, 'deny'),
+  };
+}

package/src/core/marketplaces.mjs

@@ -0,0 +1,267 @@
+// src/core/marketplaces.mjs
+// Persisted plugin-marketplace registry (marketplace spec §4.2): a git repo
+// (URL, owner/repo, or local path) registered as a discovery source, with a
+// cached discovery snapshot so the Plugins view renders with zero network.
+// File conventions mirror plugins-lock.mjs: reads never throw, writes are
+// temp+rename atomic, unknown keys survive read-modify-write.
+// Installed plugins do NOT depend on this registry — the lock's own
+// repo/subdir/pinnedSha provenance keeps update/uninstall working after a
+// marketplace is removed (spec §4.5).
+
+import {
+  existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, rmSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { pluginsRoot, readPluginsLock } from './plugins-lock.mjs';
+import { addPluginRepo, repoCacheDir, repoSlug } from './plugin-repo.mjs';
+import { inventoryFromCache } from './plugin-inventory.mjs';
+
+export function marketplacesFile() { return join(pluginsRoot(), 'marketplaces.json'); }
+
+/** owner/repo -> GitHub URL (unless a real local path); URLs lose trailing /
+ *  and .git; local paths resolve to absolute. null for empty input. */
+export function normalizeMarketplaceUrl(input) {
+  let s = String(input ?? '').trim();
+  if (!s) return null;
+  if (/^[\w.-]+\/[\w.-]+$/.test(s) && !existsSync(s)) s = `https://github.com/${s}`;
+  if (/^[a-z+]+:\/\//i.test(s)) return s.replace(/\/+$/, '').replace(/\.git$/i, '');
+  // scp-style git remote ([user@]host:path) — a git URL, never a local path.
+  if (/^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:(?!\/)/.test(s)) return s.replace(/\/+$/, '').replace(/\.git$/i, '');
+  return resolve(s);
+}
+
+// normalizeMarketplaceUrl is idempotent (C2), so hashing the normalized url is
+// stable even when addMarketplace has already normalized before calling.
+export function marketplaceId(url) { return repoSlug(normalizeMarketplaceUrl(url) ?? String(url)); }
+
+/** Missing/corrupt/non-object -> empty state. Entries not normalized on read. */
+export function readMarketplaces() {
+  try {
+    const v = JSON.parse(readFileSync(marketplacesFile(), 'utf8'));
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      return {
+        ...v, // unknown keys survive read-modify-write; normalized fields below win
+        seededBuiltin: v.seededBuiltin === true,
+        marketplaces: v.marketplaces && typeof v.marketplaces === 'object' && !Array.isArray(v.marketplaces)
+          ? Object.assign(Object.create(null), v.marketplaces) : Object.create(null),
+      };
+    }
+  } catch { /* fall through */ }
+  return { seededBuiltin: false, marketplaces: Object.create(null) };
+}
+
+export function writeMarketplaces(state) {
+  const file = marketplacesFile();
+  mkdirSync(pluginsRoot(), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString('hex')}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state ?? { seededBuiltin: false, marketplaces: {} }, null, 2) + '\n', 'utf8');
+  renameSync(tmp, file);
+  return state;
+}
+
+// relTimeCore(iso, now) -> "just now"/"5m ago"/"3h ago"/"2d ago"/ISO date. Pure;
+// mirrors plugins-view.mjs relTime so core has no DOM dependency (C4).
+function relTimeCore(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return String(iso || 'unknown');
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 45) return 'just now';
+  const m = Math.round(s / 60); if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60); if (h < 24) return `${h}h ago`;
+  const d = Math.round(h / 24); if (d < 30) return `${d}d ago`;
+  return String(iso).slice(0, 10);
+}
+
+/** Reduce a multi-line git failure to its first `fatal:` line; map the empty-repo
+ *  case to plain language. Avoids leaking the internal .cache path into the UI. */
+function firstFatal(err) {
+  const raw = String(err?.stderr || err?.message || err || '');
+  if (/unknown revision|ambiguous argument 'HEAD'/.test(raw)) return 'repository has no commits yet';
+  return raw.split('\n').map((l) => l.trim()).find((l) => l.startsWith('fatal:'))?.replace(/^fatal:\s*/, '')
+    || (raw.split('\n')[0] || 'unknown error');
+}
+
+/** Discovery + per-plugin consent inventories -> fresh snapshot on the entry.
+ *  Failure keeps the previous snapshot and records a warning (stale-but-usable). */
+async function syncEntry(entry, { exec } = {}) {
+  try {
+    const found = await addPluginRepo(entry.url, ...(exec ? [{ exec }] : []));
+    const plugins = [];
+    for (const d of found.discovered) {
+      plugins.push({
+        name: d.name,
+        subdir: d.subdir,
+        description: d.manifest.description ?? '',
+        version: d.manifest.version ?? null,
+        inventory: await inventoryFromCache(found.repoUrl, found.sha, d.subdir, ...(exec ? [{ exec }] : [])),
+      });
+    }
+    if (found.marketplace) {
+      entry.name = found.marketplace.name;
+      entry.description = found.marketplace.description;
+    }
+    entry.lastSync = { sha: found.sha, at: new Date().toISOString() };
+    entry.plugins = plugins;
+    entry.warnings = found.warnings;
+  } catch (err) {
+    const when = entry.lastSync ? `last sync ${relTimeCore(entry.lastSync.at)}` : 'never synced';
+    const msg = firstFatal(err);
+    entry.warnings = [`${when}; refresh failed: ${msg}`,
+      ...(entry.warnings || []).filter((w) => !/refresh failed:/.test(w))];
+  }
+  return entry;
+}
+
+/** Register + immediately sync. Throws EXISTS on a duplicate (normalized) url.
+ *  A first-sync failure throws WITHOUT recording — a typo'd url never leaves a
+ *  junk entry (spec §4.2). The insert RE-READS the registry after the long git
+ *  sync (B8) — inserting into the pre-sync snapshot would resurrect entries
+ *  removed meanwhile and drop concurrent adds (lost update). */
+export async function addMarketplace(url, { exec } = {}) {
+  const norm = normalizeMarketplaceUrl(url);
+  if (!norm) throw Object.assign(new Error('marketplace url is required'), { code: 'BAD_REQUEST' });
+  const id = marketplaceId(norm);
+  if (readMarketplaces().marketplaces[id]) { // cheap pre-check: fail before any git work
+    throw Object.assign(new Error(`marketplace already added: ${norm}`), { code: 'EXISTS' });
+  }
+  const entry = {
+    id, url: norm, name: id, description: '',
+    addedAt: new Date().toISOString(), lastSync: null, plugins: [], warnings: [],
+  };
+  await syncEntry(entry, { exec });
+  if (!entry.lastSync) {
+    // C8: drop the orphan bare cache the failed clone left — but never a cache an
+    // installed plugin still shares (transient failures must not evict it).
+    const inUse = Object.values(readPluginsLock()).some((e) =>
+      e && e.repo && (e.repo === norm || normalizeMarketplaceUrl(e.repo) === norm));
+    if (!inUse) rmSync(repoCacheDir(norm), { recursive: true, force: true });
+    throw Object.assign(new Error(entry.warnings[0] || `could not read ${norm}`), { code: 'BAD_REQUEST' });
+  }
+  const state = readMarketplaces(); // B8: LATEST state, not the pre-sync snapshot
+  if (state.marketplaces[id]) {
+    throw Object.assign(new Error(`marketplace already added: ${norm}`), { code: 'EXISTS' });
+  }
+  state.marketplaces[id] = entry;
+  writeMarketplaces(state);
+  return entry;
+}
+
+/** Read-modify-write the LATEST state, one entry only — so a long git sync can't
+ *  clobber a concurrent remove/add. Drops the write if the entry vanished. */
+function mutateEntry(id, apply) {
+  const state = readMarketplaces();
+  if (!Object.hasOwn(state.marketplaces, id)) return null;
+  apply(state.marketplaces[id]);
+  writeMarketplaces(state);
+  return state.marketplaces[id];
+}
+
+export async function syncMarketplace(id, { exec } = {}) {
+  const cur = readMarketplaces().marketplaces[id];
+  if (!cur) throw Object.assign(new Error(`marketplace "${id}" not found`), { code: 'NOT_FOUND' });
+  const clone = { ...cur, plugins: [...(cur.plugins || [])], warnings: [...(cur.warnings || [])] };
+  await syncEntry(clone, { exec });
+  const saved = mutateEntry(id, (e) => Object.assign(e, {
+    name: clone.name, description: clone.description, lastSync: clone.lastSync,
+    plugins: clone.plugins, warnings: clone.warnings,
+  }));
+  if (!saved) throw Object.assign(new Error(`marketplace "${id}" not found`), { code: 'NOT_FOUND' });
+  return saved;
+}
+
+/** Sequential, per-entry tolerant: a dead repo (sync warning) AND an entry removed
+ *  mid-refresh (NOT_FOUND) both leave the others intact. */
+export async function refreshAllMarketplaces({ exec } = {}) {
+  const out = [];
+  for (const id of Object.keys(readMarketplaces().marketplaces).sort()) {
+    try { out.push(await syncMarketplace(id, { exec })); }
+    catch (err) { if (err?.code !== 'NOT_FOUND') throw err; }
+  }
+  return out;
+}
+
+/** Remove the registry entry + snapshot. Installed plugins are untouched; the
+ *  bare cache goes only when no plugins.lock.json entry shares the repo. */
+export function removeMarketplace(id) {
+  const state = readMarketplaces();
+  const entry = state.marketplaces[id];
+  if (!entry) throw Object.assign(new Error(`marketplace "${id}" not found`), { code: 'NOT_FOUND' });
+  const inUse = Object.values(readPluginsLock()).some((e) =>
+    e && e.repo && (e.repo === entry.url || normalizeMarketplaceUrl(e.repo) === entry.url));
+  delete state.marketplaces[id];
+  writeMarketplaces(state);
+  if (!inUse) rmSync(repoCacheDir(entry.url), { recursive: true, force: true });
+  return { ok: true, id };
+}
+
+export function listMarketplaces() {
+  const state = readMarketplaces();
+  return Object.values(state.marketplaces)
+    .sort((a, b) => String(a.name || a.id).localeCompare(String(b.name || b.id)));
+}
+
+/** Install-source resolution (spec §4.10): explicit --repo > lock provenance >
+ *  unique snapshot match > {candidates} on ambiguity > null. */
+export function resolveInstallSource(name, { repo } = {}) {
+  if (repo) return { repoUrl: normalizeMarketplaceUrl(repo), subdir: null, sha: null, marketplace: null };
+  const lockEntry = readPluginsLock()[name];
+  if (lockEntry && lockEntry.repo) {
+    return { repoUrl: lockEntry.repo, subdir: lockEntry.subdir ?? null, sha: null, marketplace: lockEntry.marketplace ?? null };
+  }
+  const hits = [];
+  for (const m of listMarketplaces()) {
+    for (const p of m.plugins || []) {
+      if (p.name === name) {
+        hits.push({ repoUrl: m.url, subdir: p.subdir, sha: m.lastSync ? m.lastSync.sha : null, marketplace: m.id });
+      }
+    }
+  }
+  if (hits.length === 1) return hits[0];
+  if (hits.length > 1) return { candidates: hits };
+  return null;
+}
+
+/** The checkout the host code runs from: two dirs above src/core/. Only a real
+ *  marketplace checkout counts (must have worca-cc-marketplace.json + .git) —
+ *  an npm-dist install without either returns null and seeding is skipped. */
+export function hostRepoRoot() {
+  const root = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  return existsSync(join(root, 'worca-cc-marketplace.json')) && existsSync(join(root, '.git'))
+    ? root : null;
+}
+
+/** First-run builtin seed (spec §4.2): register the host checkout as a
+ *  local-path marketplace. NO git operations — plugins:[] / lastSync:null; the
+ *  first sync happens via the Plugins view's background refresh or an explicit
+ *  `worca marketplace refresh`. seededBuiltin is set only on success, so a
+ *  removed builtin never auto-returns, while a non-checkout host stays eligible
+ *  to seed on a later run from a real checkout. */
+export function seedBuiltinMarketplace({ rootDir = hostRepoRoot() } = {}) {
+  const state = readMarketplaces();
+  if (state.seededBuiltin) return { seeded: false, reason: 'already-seeded' };
+  // Same contract as hostRepoRoot for an INJECTED rootDir too: a real checkout must
+  // carry both the manifest and .git, else this is an npm-dist dir — skip (E7).
+  if (!rootDir || !existsSync(join(rootDir, 'worca-cc-marketplace.json')) || !existsSync(join(rootDir, '.git'))) {
+    return { seeded: false, reason: 'no-host-checkout' };
+  }
+  const url = resolve(rootDir);
+  const id = marketplaceId(url);
+  let name = 'Worca CC Official';
+  let description = '';
+  try {
+    const raw = JSON.parse(readFileSync(join(rootDir, 'worca-cc-marketplace.json'), 'utf8'));
+    if (typeof raw?.name === 'string' && raw.name.trim()) name = raw.name.trim();
+    if (typeof raw?.description === 'string') description = raw.description.trim();
+  } catch { /* keep defaults */ }
+  if (!state.marketplaces[id]) {
+    state.marketplaces[id] = {
+      id, url, name, description, builtin: true,
+      addedAt: new Date().toISOString(), lastSync: null, plugins: [], warnings: [],
+    };
+  }
+  state.seededBuiltin = true;
+  writeMarketplaces(state);
+  return { seeded: true, id };
+}