synabun 1.3.0 → 2.0.0

package/neural-interface/lib/cli-update-planner.js

@@ -0,0 +1,312 @@
+// ═══════════════════════════════════════════
+// SynaBun — CLI Update Planner
+//
+// Works out HOW each external CLI (Claude Code, Codex, OpenCode, Gemini) was
+// installed, and therefore which command actually updates it and which
+// "latest version" it should be compared against.
+//
+// The rule that drives everything here:
+//
+//   If an EXTERNAL package manager owns the binary, use that manager.
+//   Only fall back to the tool's own self-updater when the tool installed
+//   itself (native installer / curl script) or detection failed.
+//
+// A self-updater writing into its own directory cannot replace a
+// Homebrew-managed binary — brew's symlink in /opt/homebrew/bin still wins
+// PATH, so the update silently does nothing and the badge never clears.
+// ═══════════════════════════════════════════
+
+/** npm package name per tool key. */
+export const NPM_PKGS = {
+  'claude-code': '@anthropic-ai/claude-code',
+  'codex': '@openai/codex',
+  'gemini': '@google/gemini-cli',
+  'opencode': 'opencode-ai',
+};
+
+/**
+ * Homebrew token per tool, used only when the token cannot be derived from
+ * the binary path (see brewTokenFromPath). Tap-installed formulae resolve
+ * correctly from the path, so prefer that.
+ */
+export const BREW_FALLBACK_TOKENS = {
+  'claude-code': 'claude-code',
+  'codex': 'codex',
+  'gemini': 'gemini-cli',
+  'opencode': 'opencode',
+};
+
+/**
+ * Whether each tool ships as a Homebrew cask or a formula. This is a property
+ * of the package, not of the machine — claude-code and codex exist ONLY as
+ * casks, gemini-cli and opencode ONLY as formulae. Needed when a tool is not
+ * installed and there is no path to classify: guessing the wrong flavour
+ * produces a command that simply errors ("Cask 'gemini-cli' is unavailable").
+ */
+export const BREW_KINDS = {
+  'claude-code': 'cask',
+  'codex': 'cask',
+  'gemini': 'formula',
+  'opencode': 'formula',
+};
+
+/** Tools that can update themselves when they own their own install. */
+const SELF_UPDATERS = {
+  'claude-code': 'claude update',
+  'codex': 'codex update',
+  'opencode': 'opencode upgrade',
+  // gemini has no self-updater.
+};
+
+/**
+ * OpenCode's `upgrade --method` accepts exactly these values. Mapping our
+ * detected source onto it lets OpenCode do its own install-aware work for
+ * the channels we cannot drive directly.
+ */
+const OPENCODE_METHODS = {
+  'standalone': 'curl',
+  'npm': 'npm',
+  'pnpm': 'pnpm',
+  'bun': 'bun',
+  'brew-formula': 'brew',
+  'brew-cask': 'brew',
+  'choco': 'choco',
+  'scoop': 'scoop',
+};
+
+/** Sources that mean "a package manager other than the tool itself owns this". */
+const MANAGED_SOURCES = new Set([
+  'brew-cask', 'brew-formula', 'npm', 'bun', 'pnpm', 'yarn', 'volta', 'scoop', 'choco', 'winget',
+]);
+
+export function isBrewSource(source) {
+  return source === 'brew-cask' || source === 'brew-formula';
+}
+
+export function isManagedSource(source) {
+  return MANAGED_SOURCES.has(source);
+}
+
+/**
+ * Classify an install from the resolved (symlink-followed) binary path.
+ *
+ * ORDER MATTERS. Every alternative JS package manager stores its globals
+ * under a `node_modules` directory, so the generic npm test has to come
+ * last — otherwise a bun-global install is misreported as npm and handed
+ * `npm install -g`, which writes to a prefix that does not own the binary
+ * currently on PATH.
+ */
+export function detectInstallSource(binPath) {
+  if (!binPath) return 'unknown';
+  const p = String(binPath).replace(/\\/g, '/').toLowerCase();
+
+  // Homebrew — Caskroom must be tested before the generic /opt/homebrew/
+  // rule, since a cask path contains both.
+  if (p.includes('/caskroom/')) return 'brew-cask';
+  if (p.includes('/cellar/')) return 'brew-formula';
+  if (p.includes('/opt/homebrew/') || p.includes('/linuxbrew/') || p.includes('/homebrew/')) return 'brew-formula';
+
+  // Alternative JS package managers — all before the npm rule.
+  if (p.includes('/.bun/')) return 'bun';
+  if (p.includes('/pnpm/') || p.includes('/.local/share/pnpm/')) return 'pnpm';
+  if (p.includes('/.yarn/') || p.includes('/yarn/global/')) return 'yarn';
+  if (p.includes('/.volta/')) return 'volta';
+
+  // Tool-owned installers.
+  if (p.includes('/.opencode/')) return 'standalone';
+  if (p.includes('/.claude/local/') || p.includes('/anthropicclaude/')) return 'native';
+
+  // Windows package managers — before the Program Files native rule, since
+  // scoop/choco shims can live under a user profile that also matches.
+  if (p.includes('/winget/') || p.includes('/microsoft/winget/')) return 'winget';
+  if (p.includes('/scoop/')) return 'scoop';
+  if (p.includes('/chocolatey/')) return 'choco';
+
+  // Native installers.
+  if (/\/\.local\/bin\//.test(p)) return 'native';
+  if (/\/program files( \(x86\))?\//.test(p)) return 'native';
+
+  // Generic npm global — LAST.
+  if (p.includes('/node_modules/')) return 'npm';
+
+  return 'other';
+}
+
+/**
+ * Derive the Homebrew token from a Caskroom/Cellar path, e.g.
+ *   /opt/homebrew/Caskroom/claude-code/2.1.224/claude  -> claude-code
+ *   /opt/homebrew/Cellar/opencode/1.18.18/bin/opencode -> opencode
+ *
+ * Reading it from the path rather than a hardcoded map is what makes
+ * tap-installed formulae work (e.g. OpenCode ships from anomalyco/tap, whose
+ * version differs from homebrew/core's).
+ */
+export function brewTokenFromPath(binPath) {
+  if (!binPath) return null;
+  const p = String(binPath).replace(/\\/g, '/');
+  const m = p.match(/\/(?:Caskroom|Cellar)\/([^/]+)\//i);
+  return m ? m[1] : null;
+}
+
+/** Resolve the brew token for a tool, preferring the path-derived one. */
+export function resolveBrewToken(toolKey, binPath) {
+  return brewTokenFromPath(binPath) || BREW_FALLBACK_TOKENS[toolKey] || toolKey;
+}
+
+/**
+ * Build the command that actually updates a tool, given how it was installed.
+ * Returns null when there is no safe automated path (e.g. winget with no
+ * self-updater) — the caller should show a "use your installer" hint instead.
+ */
+export function buildUpdateCommand(toolKey, installSource, { brewToken = null } = {}) {
+  const npmPkg = NPM_PKGS[toolKey];
+  const selfUpdate = SELF_UPDATERS[toolKey] || null;
+
+  // A package manager owns the binary — only that manager can replace it.
+  if (isBrewSource(installSource)) {
+    const token = brewToken || BREW_FALLBACK_TOKENS[toolKey] || toolKey;
+    // `brew upgrade <token>` does resolve casks, but be explicit so a
+    // formula/cask name collision can never pick the wrong one.
+    return installSource === 'brew-cask'
+      ? `brew upgrade --cask ${token}`
+      : `brew upgrade ${token}`;
+  }
+
+  if (!npmPkg) return selfUpdate;
+
+  switch (installSource) {
+    case 'npm':   return `npm install -g ${npmPkg}@latest`;
+    case 'yarn':  return `yarn global add ${npmPkg}@latest`;
+    case 'volta': return `volta install ${npmPkg}@latest`;
+    case 'bun':
+    case 'pnpm':
+      // OpenCode drives these itself; the others take the plain global add.
+      if (toolKey === 'opencode') return `opencode upgrade --method ${OPENCODE_METHODS[installSource]}`;
+      return installSource === 'bun'
+        ? `bun add -g ${npmPkg}@latest`
+        : `pnpm add -g ${npmPkg}@latest`;
+    case 'scoop':
+    case 'choco':
+      if (toolKey === 'opencode') return `opencode upgrade --method ${OPENCODE_METHODS[installSource]}`;
+      return null; // no safe automated path — caller shows a hint
+    case 'winget':
+      return null;
+    case 'standalone':
+      // The tool's own installer put it here, so its own updater is right.
+      return toolKey === 'opencode' ? 'opencode upgrade --method curl' : selfUpdate;
+    case 'native':
+      return selfUpdate;
+    default:
+      // 'other' / 'unknown' — let the tool self-detect if it can, else
+      // fall back to npm, which is how the vast majority are installed.
+      return selfUpdate || `npm install -g ${npmPkg}@latest`;
+  }
+}
+
+/**
+ * Parse `brew outdated --json=v2` into a token -> current_version map.
+ * Indexes both the bare token and any tap-qualified full name so lookups
+ * work regardless of which form the caller derived from the path.
+ */
+export function parseBrewOutdated(raw) {
+  if (raw == null) return null;
+  let data = raw;
+  if (typeof raw === 'string') {
+    const text = raw.trim();
+    if (!text) return null;
+    try { data = JSON.parse(text); } catch { return null; }
+  }
+  if (!data || typeof data !== 'object') return null;
+
+  const out = new Map();
+  for (const group of ['formulae', 'casks']) {
+    for (const entry of Array.isArray(data[group]) ? data[group] : []) {
+      const version = entry?.current_version || entry?.current_versions?.[0] || null;
+      if (!version) continue;
+      for (const nameField of [entry.name, entry.token, entry.full_name, entry.full_token]) {
+        if (!nameField) continue;
+        const name = String(nameField);
+        out.set(name, version);
+        const bare = name.split('/').pop();
+        if (bare) out.set(bare, version);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Decide which "latest" a tool should be compared against.
+ *
+ * For a brew install the npm registry is the wrong yardstick: Homebrew often
+ * trails upstream by a few releases, so comparing against npm produces a
+ * badge that lights up while `brew upgrade` answers "already installed" —
+ * a permanently stuck badge that the post-update poll loop spins on.
+ *
+ * When the brew probe itself failed we fail CLOSED (latest = installed)
+ * rather than falling back to npm, for the same reason.
+ */
+export function resolveLatest({
+  installSource,
+  brewToken = null,
+  brewOutdated = null,
+  npmLatest = null,
+  installed = null,
+} = {}) {
+  if (!isBrewSource(installSource)) return npmLatest;
+  if (!installed) return null;
+  if (!brewOutdated) return installed;
+  const token = brewToken || null;
+  const hit = (token && brewOutdated.get(token))
+    || (token && brewOutdated.get(String(token).split('/').pop()))
+    || null;
+  return hit || installed;
+}
+
+/**
+ * Human-readable install-source label for UI copy — "update via Homebrew"
+ * reads better than "update via brew-cask".
+ */
+export function installSourceLabel(source) {
+  switch (source) {
+    case 'brew-cask':
+    case 'brew-formula': return 'Homebrew';
+    case 'npm': return 'npm';
+    case 'bun': return 'Bun';
+    case 'pnpm': return 'pnpm';
+    case 'yarn': return 'Yarn';
+    case 'volta': return 'Volta';
+    case 'standalone': return 'the official installer';
+    case 'native': return 'the native installer';
+    case 'winget': return 'winget';
+    case 'scoop': return 'Scoop';
+    case 'choco': return 'Chocolatey';
+    default: return 'your installer';
+  }
+}
+
+/**
+ * The command that INSTALLS a tool that is missing. Mirrors the update
+ * matrix so a Homebrew user is not told to `npm install -g`, which would
+ * create a second, conflicting install.
+ */
+export function buildInstallCommand(toolKey, installSource = 'unknown') {
+  const npmPkg = NPM_PKGS[toolKey];
+  if (isBrewSource(installSource)) {
+    const token = BREW_FALLBACK_TOKENS[toolKey] || toolKey;
+    // Use the package's OWN flavour, not the one inferred from sibling tools:
+    // a machine whose other CLIs are casks says nothing about whether THIS
+    // package is a cask.
+    return BREW_KINDS[toolKey] === 'cask'
+      ? `brew install --cask ${token}`
+      : `brew install ${token}`;
+  }
+  if (!npmPkg) return '';
+  switch (installSource) {
+    case 'bun':   return `bun add -g ${npmPkg}`;
+    case 'pnpm':  return `pnpm add -g ${npmPkg}`;
+    case 'yarn':  return `yarn global add ${npmPkg}`;
+    case 'volta': return `volta install ${npmPkg}`;
+    default:      return `npm install -g ${npmPkg}`;
+  }
+}

package/neural-interface/lib/codex-capabilities.d.ts

@@ -0,0 +1,41 @@
+export interface CodexRuntime {
+  cliVersion?: string | null;
+  sdkVersion?: string | null;
+  codexBin?: string;
+  codexBinSource?: string;
+  accountId?: string;
+  codexHome?: string;
+  protocolBaseline: string;
+  experimentalApi: boolean;
+  serverInfo?: Record<string, unknown>;
+}
+export interface CodexCapability {
+  method: string;
+  supported: boolean;
+  experimental: boolean;
+  reason: string | null;
+}
+export interface CodexCapabilityPacket {
+  type: 'capabilities';
+  requestId?: string | null;
+  capabilities: Record<string, CodexCapability>;
+  runtime: CodexRuntime;
+  sessionId?: string;
+  connectionEpoch?: string;
+}
+export const CODEX_PROTOCOL_BASELINE: '0.160.0';
+export const CODEX_CAPABILITY_METHODS: Readonly<Record<string, { method: string; experimental: boolean; unavailable?: string }>>;
+export function parseCodexVersion(value: unknown): string | null;
+export function isCodexUnsupportedMethod(error: unknown): boolean;
+export function classifyCodexRpcError(error: unknown, methodName?: string): { code: string | number | null; category: 'unsupported' | 'invalid_request' | 'authentication' | 'restricted' | 'transient' | 'runtime'; message: string };
+export function validateCodexConfigRequirements<T extends Record<string, unknown>>(config: T, requirements: unknown): T;
+export class CodexCapabilityRegistry {
+  constructor(runtime?: Partial<CodexRuntime>);
+  runtime: CodexRuntime;
+  requirements: Record<string, unknown> | null;
+  reset(runtime?: Partial<CodexRuntime>): void;
+  updateRequirements(result: unknown): void;
+  observe(method: string, error?: unknown): boolean;
+  snapshot(): Record<string, CodexCapability>;
+  assertAvailable(name: string): void;
+}

package/neural-interface/lib/codex-capabilities.js

@@ -0,0 +1,148 @@
+/** Tested local app-server contract. No RPC is used as a method-discovery probe. */
+export const CODEX_PROTOCOL_BASELINE = '0.160.0';
+
+const pluginReason = 'Plugin controls are under development and unavailable in this sidepanel.';
+const method = (rpc, experimental = false) => ({ method: rpc, experimental });
+export const CODEX_CAPABILITY_METHODS = Object.freeze({
+  thread_list: method('thread/list'), thread_resume: method('thread/resume'),
+  thread_start: method('thread/start'), thread_rename: method('thread/name/set'),
+  thread_fork: method('thread/fork'), thread_archive: method('thread/archive'),
+  thread_unarchive: method('thread/unarchive'), thread_loaded_list: method('thread/loaded/list'),
+  thread_revert: method('thread/revert'),
+  thread_read: method('thread/read'), thread_turns_list: method('thread/turns/list'),
+  thread_items_list: method('thread/items/list'), compact: method('thread/compact/start'),
+  query: method('turn/start'), turn_steer: method('turn/steer'), interrupt: method('turn/interrupt'),
+  review_start: method('review/start'), model_list: method('model/list'),
+  collaboration_modes: method('collaborationMode/list', true),
+  account_read: method('account/read'), rate_limits_read: method('account/rateLimits/read'),
+  config_read: method('config/read'), config_write: method('config/batchWrite'),
+  config_requirements: method('configRequirements/read'),
+  mcp_status: method('mcpServerStatus/list'), mcp_refresh: method('config/mcpServer/reload'),
+  mcp_app_resource_read: method('mcpServer/resource/read'), mcp_app_tool_call: method('mcpServer/tool/call'),
+  mcp_oauth_login: method('mcpServer/oauth/login'), mcp_approval_set: method('config/batchWrite'),
+  skills_list: method('skills/list'), skills_config_write: method('skills/config/write'),
+  app_list: method('app/list'), app_read: method('app/read'),
+  experimental_features: method('experimentalFeature/list'),
+  experimental_features_set: method('experimentalFeature/enablement/set'),
+  background_clean: method('thread/backgroundTerminals/clean', true),
+  background_list: method('thread/backgroundTerminals/list', true),
+  background_terminate: method('thread/backgroundTerminals/terminate', true),
+  goal_get: method('thread/goal/get'), goal_set: method('thread/goal/set'),
+  goal_clear: method('thread/goal/clear'), hooks_list: method('hooks/list'),
+  thread_settings_update: method('thread/settings/update', true),
+  attachment_list: method('thread/attachment/list'), attachment_remove: method('thread/attachment/remove'),
+  attachment_add: method('thread/attachment/add'),
+  memory_status: method('memory/status', true),
+  rollout_compress: { ...method('rollout/compress', true), unavailable: 'Global rollout storage compression has no sidepanel control.' },
+  gateway_oauth_read: method('account/gatewayOAuth/read'),
+  gateway_oauth_login: method('account/gatewayOAuth/login'),
+  gateway_oauth_cancel: method('account/gatewayOAuth/cancel'),
+  verification_status: method('userVerification/status', true),
+  verification_enroll: method('userVerification/enroll', true),
+  verification_delete: method('userVerification/delete', true),
+  verification_verify: method('userVerification/verify', true),
+  verification_cancel: method('userVerification/cancel', true),
+  feedback_upload: method('feedback/upload'),
+  plugin_list: { ...method('plugin/list'), unavailable: pluginReason },
+  plugin_read: { ...method('plugin/read'), unavailable: pluginReason },
+  plugin_install: { ...method('plugin/install'), unavailable: pluginReason },
+  plugin_uninstall: { ...method('plugin/uninstall'), unavailable: pluginReason },
+});
+
+export function parseCodexVersion(value) {
+  return String(value || '').match(/\b(\d+\.\d+\.\d+)(?:[-+][\w.-]+)?\b/)?.[1] || null;
+}
+
+export function isCodexUnsupportedMethod(error) {
+  return error?.code === -32601
+    || (error?.code === -32600 && /unknown variant/i.test(String(error?.message || '')));
+}
+
+export function classifyCodexRpcError(error, methodName = '') {
+  let message = String(error?.message || error || 'Codex request failed');
+  const code = error?.code ?? null;
+  const category = isCodexUnsupportedMethod(error) ? 'unsupported'
+    : code === -32602 ? 'invalid_request'
+    : /unauthenticated|not logged in|authentication required|unauthorized|401\b/i.test(message) ? 'authentication'
+    : /managed|restricted|requirements|not allowed|forbidden|permission denied|403\b/i.test(message) ? 'restricted'
+    : /timed out|timeout|rate.limit|temporar|connection|disconnected|exited|503\b|429\b/i.test(message) ? 'transient'
+    : 'runtime';
+  const unsupportedMethod = methodName || message.match(/unknown variant\s+[`'"]([^`'"]+)[`'"]/i)?.[1];
+  if (category === 'unsupported' && unsupportedMethod) message = `The installed Codex CLI does not support ${unsupportedMethod}`;
+  return { code, category, message };
+}
+
+/** @typedef {{supported:boolean,experimental:boolean,method:string,reason:string|null}} CodexCapability */
+export class CodexCapabilityRegistry {
+  constructor(runtime = {}) { this.reset(runtime); }
+  reset(runtime = {}) {
+    this.runtime = { ...runtime, protocolBaseline: CODEX_PROTOCOL_BASELINE, experimentalApi: true };
+    this.observed = new Map();
+    this.requirements = null;
+  }
+  updateRequirements(result) { this.requirements = result?.requirements || result || null; }
+  observe(methodName, error = null) {
+    // Authentication/transport/configuration failures say nothing about method support.
+    if (error && classifyCodexRpcError(error).category !== 'unsupported') return false;
+    const next = error ? { supported: false, reason: classifyCodexRpcError(error, methodName).message }
+      : { supported: true, reason: null };
+    const prior = this.observed.get(methodName);
+    this.observed.set(methodName, next);
+    return prior?.supported !== next.supported;
+  }
+  snapshot() {
+    return Object.fromEntries(Object.entries(CODEX_CAPABILITY_METHODS).map(([name, descriptor]) => {
+      const observed = this.observed.get(descriptor.method);
+      let reason = descriptor.unavailable || observed?.reason || null;
+      let supported = !reason;
+      const appVersion = parseCodexVersion(this.runtime.cliVersion || this.runtime.version);
+      if (name.startsWith('mcp_app_') && appVersion
+        && appVersion.split('.').map(Number).some((value, index, parts) =>
+          parts.slice(0, index).every((prior, i) => prior === [0, 160, 0][i]) && value < [0, 160, 0][index])) {
+        reason = 'Embedded MCP apps require Codex CLI 0.160.0 or newer.'; supported = false;
+      }
+      if (name === 'feedback_upload' && this.requirements?.feedback?.enabled === false) {
+        supported = false;
+        reason = 'Feedback is disabled by managed requirements.';
+      }
+      return [name, { supported, experimental: descriptor.experimental, method: descriptor.method, reason }];
+    }));
+  }
+  assertAvailable(name) {
+    const capability = this.snapshot()[name];
+    if (!capability?.supported) {
+      const error = new Error(capability?.reason || `Unknown Codex action: ${name}`);
+      error.code = -32601;
+      throw error;
+    }
+  }
+}
+
+export function validateCodexConfigRequirements(config, result) {
+  const requirements = result?.requirements || result || {};
+  const allowLists = {
+    approval_policy: 'allowedApprovalPolicies', approvals_reviewer: 'allowedApprovalsReviewers',
+    sandbox_mode: 'allowedSandboxModes', web_search: 'allowedWebSearchModes',
+  };
+  for (const [key, requirement] of Object.entries(allowLists)) {
+    if (config[key] == null || !Array.isArray(requirements[requirement])) continue;
+    if (!requirements[requirement].some(value => JSON.stringify(value) === JSON.stringify(config[key]))) {
+      const error = new Error(`${key} is restricted by managed requirements.`);
+      error.code = 'MANAGED_REQUIREMENT';
+      throw error;
+    }
+  }
+  if (config.web_search != null && !['disabled', 'cached', 'indexed', 'live'].includes(config.web_search)) {
+    const error = new Error('web_search must be disabled, cached, indexed, or live.');
+    error.code = -32602;
+    throw error;
+  }
+  for (const [name, required] of Object.entries(requirements.featureRequirements || {})) {
+    if (config.features?.[name] !== undefined && config.features[name] !== required) {
+      const error = new Error(`Feature ${name} is restricted by managed requirements.`);
+      error.code = 'MANAGED_REQUIREMENT';
+      throw error;
+    }
+  }
+  return config;
+}

package/neural-interface/lib/codex-collaboration-mode.js

@@ -0,0 +1,17 @@
+export function buildCodexCollaborationMode({ mode, model, effort, developerInstructions = null } = {}) {
+  const normalizedMode = mode === 'plan' ? 'plan' : 'default';
+  const normalizedModel = String(model || '').trim();
+  if (!normalizedModel) return null;
+  const instructions = typeof developerInstructions === 'string' && developerInstructions.trim()
+    ? developerInstructions
+    : null;
+
+  return {
+    mode: normalizedMode,
+    settings: {
+      model: normalizedModel,
+      reasoning_effort: effort && effort !== 'off' ? String(effort) : null,
+      developer_instructions: instructions,
+    },
+  };
+}