synabun 1.3.0 → 2.0.0

package/neural-interface/lib/path-confine.js

@@ -0,0 +1,213 @@
+// ── Paths built from something a browser sent ──
+// An id or a name that ends up in a filesystem path is validated here first:
+// a session id is a UUID and its transcript stays inside the project's own
+// transcript folder; a Skills Studio artifact stays inside the skills, commands
+// and agents folders; a name is one path segment. Pure functions over
+// node:path (the filesystem calls are injected), so they are unit-tested.
+//
+// "Inside" is judged twice: as written (no `..` out of the folder) and as the
+// filesystem resolves it (no link out of the folder). The second is what a read
+// or a write actually follows.
+
+import { existsSync, realpathSync, lstatSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+
+export class PathConfineError extends Error {
+  constructor(status, message) { super(message); this.status = status; }
+}
+
+export const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isSessionId = (id) => typeof id === 'string' && SESSION_ID_RE.test(id);
+
+const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+
+/** True when `target` is below `root` (or is `root` itself, with allowRoot). Lexical: both are resolved first. */
+export function isInside(root, target, { allowRoot = false } = {}) {
+  if (!root || !target) return false;
+  const r = fold(resolve(String(root)));
+  const t = fold(resolve(String(target)));
+  if (t === r) return allowRoot;
+  return t.startsWith(r.endsWith(sep) ? r : r + sep);
+}
+
+/** One path segment: no separator, no NUL, not `.` or `..`. */
+export function isPlainName(name) {
+  return typeof name === 'string' && name.length > 0 && name.length <= 200
+    && name !== '.' && name !== '..' && !/[\\/\0]/.test(name);
+}
+
+const realFs = { realpath: realpathSync, lstat: lstatSync };
+
+/**
+ * `target` with every link resolved. The part that does not exist yet is kept as
+ * written under its real parent, so a file about to be created is judged by where
+ * it would land. A link that cannot be resolved (dangling, a loop) is refused:
+ * writing through it would create its target.
+ */
+export function realPathOf(target, fs = realFs) {
+  let cur = resolve(String(target ?? ''));
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpath(cur);
+      return tail.length ? join(real, ...tail.reverse()) : real;
+    } catch {
+      let present = false;
+      try { fs.lstat(cur); present = true; } catch { present = false; }
+      if (present) throw new PathConfineError(403, 'That path goes through a link that cannot be resolved.');
+      const parent = dirname(cur);
+      if (parent === cur) throw new PathConfineError(403, 'That path cannot be resolved.');
+      tail.push(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/** isInside() after links are resolved on both sides. False when either cannot be resolved. */
+export function isInsideReal(root, target, { allowRoot = false, fs = realFs } = {}) {
+  if (!root || !target) return false;
+  try { return isInside(realPathOf(root, fs), realPathOf(target, fs), { allowRoot }); } catch { return false; }
+}
+
+/**
+ * The transcript of one session, or null. The id must be a UUID (thrown as 400
+ * otherwise), the file is looked for only in the transcript folders of the
+ * registered projects, and what is found must still be inside its folder after
+ * symlinks are resolved. A named project is honoured strictly: it must be
+ * registered (400 otherwise) and only its folder is searched. Without one,
+ * every registered project is.
+ *
+ * @param o.sessionId   the browser's session id
+ * @param o.project     the project the tab runs in, optional
+ * @param o.projects    [{ path }] the registered projects
+ * @param o.projectsDir <config dir>/projects of the account
+ * @param o.pathToKey   (projectPath) => the folder name Claude Code uses for it
+ */
+export function findSessionTranscript({ sessionId, project = '', projects = [], projectsDir, pathToKey, exists = existsSync, realpath = realpathSync } = {}) {
+  if (!isSessionId(sessionId)) throw new PathConfineError(400, 'Not a session id');
+  if (!projectsDir || typeof pathToKey !== 'function') return null;
+  const known = (Array.isArray(projects) ? projects : []).filter(p => p?.path);
+  const wanted = typeof project === 'string' && project ? resolve(project) : '';
+  let order = known;
+  if (wanted) {
+    const named = known.find(p => resolve(p.path) === wanted);
+    if (!named) throw new PathConfineError(400, 'Not a registered project');
+    order = [named];
+  }
+  for (const proj of order) {
+    const key = String(pathToKey(proj.path) || '');
+    // Claude Code has written the drive letter in both cases on Windows.
+    const keys = [...new Set([key.replace(/^([A-Z])/, m => m.toLowerCase()), key])].filter(isPlainName);
+    for (const k of keys) {
+      const folder = join(projectsDir, k);
+      const candidate = join(folder, `${sessionId}.jsonl`);
+      if (!exists(candidate)) continue;
+      let realFile; let realFolder;
+      try { realFile = realpath(candidate); realFolder = realpath(folder); } catch { continue; }
+      if (!isInside(realFolder, realFile)) continue;
+      // `realPath` / `realFolder`: the canonical paths that were just checked.
+      // The transcript is read from those (lib/confined-fs.js), not from the
+      // name it was found under, which could be swapped for a link afterwards.
+      return { filePath: candidate, project: proj.path, realPath: realFile, realFolder };
+    }
+  }
+  return null;
+}
+
+/**
+ * The registered projects whose transcript folder, in one account's
+ * `projectsDir`, holds a session: findSessionTranscript() asked per project
+ * (same id check, same "really inside its folder" check). For saying where a
+ * session is when it is not under the project a tab names.
+ * @returns {string[]} project paths, in registered order
+ */
+export function sessionProjects({ sessionId, projects = [], projectsDir, pathToKey, exists = existsSync, realpath = realpathSync } = {}) {
+  if (!isSessionId(sessionId)) throw new PathConfineError(400, 'Not a session id');
+  const out = [];
+  for (const proj of (Array.isArray(projects) ? projects : []).filter(p => p?.path)) {
+    let found = null;
+    try { found = findSessionTranscript({ sessionId, project: proj.path, projects: [proj], projectsDir, pathToKey, exists, realpath }); } catch { found = null; }
+    if (found) out.push(proj.path);
+  }
+  return out;
+}
+
+const ARTIFACT_TYPES = new Set(['skill', 'command', 'agent']);
+
+const rootOf = (r) => (typeof r === 'string' ? { dir: r } : (r && typeof r === 'object' ? r : {}));
+
+// Where an artifact under `root` really lives, or null when a link leads out.
+function artifactBase(type, target, root, fs) {
+  let realRoot; let realTarget;
+  try {
+    realRoot = realPathOf(root.dir, fs);
+    // A project's folders arrive with its repository: they must really be in it.
+    if (root.anchor && !isInside(realPathOf(root.anchor, fs), realRoot)) return null;
+    realTarget = realPathOf(target, fs);
+  } catch { return null; }
+  if (type !== 'skill') return isInside(realRoot, realTarget) ? realRoot : null;
+  // A skill folder the user linked into their own skills folder is theirs to
+  // link (`links`, direct children only): it is confined to where it really is.
+  const linked = root.links === true && dirname(target) === resolve(root.dir);
+  if (!linked && !isInside(realRoot, realTarget)) return null;
+  try { if (!isInside(realTarget, realPathOf(join(target, 'SKILL.md'), fs))) return null; } catch { return null; }
+  return realTarget;
+}
+
+/**
+ * A Skills Studio artifact id (`skill:<dir>`, `command:<file.md>`, `agent:<file.md>`)
+ * → its paths, only when it lies inside one of the folders of its type, as
+ * written and after links are resolved. `realBase` is the folder everything
+ * below the artifact is confined to (confineSubPath, staysInside).
+ * @param roots { skill: [root…], command: [root…], agent: [root…] } where a root is a
+ *              folder, or { dir, anchor?, links? }: `anchor` is a folder the root must
+ *              really be inside (a project), `links` honours a linked skill folder.
+ */
+export function confineArtifact(decodedId, roots = {}, { fs = realFs } = {}) {
+  const text = String(decodedId ?? '');
+  const cut = text.indexOf(':');
+  const type = cut > 0 ? text.slice(0, cut) : '';
+  const rawPath = cut > 0 ? text.slice(cut + 1) : '';
+  if (!ARTIFACT_TYPES.has(type) || !rawPath || rawPath.includes('\0')) throw new PathConfineError(400, 'Not an artifact id');
+  const target = resolve(rawPath);
+  const allowed = (Array.isArray(roots[type]) ? roots[type] : []).filter(Boolean).map(rootOf).filter(r => r.dir);
+  const lexical = allowed.filter(root => isInside(root.dir, target));
+  if (!lexical.length) throw new PathConfineError(403, 'That path is outside the skills, commands and agents folders.');
+  if (type !== 'skill' && !/\.md$/i.test(target)) throw new PathConfineError(400, 'Not a command or agent file');
+  for (const root of lexical) {
+    const realBase = artifactBase(type, target, root, fs);
+    if (!realBase) continue;
+    if (type === 'skill') return { type, dirPath: target, filePath: join(target, 'SKILL.md'), realBase };
+    return { type, dirPath: dirname(target), filePath: target, realBase };
+  }
+  throw new PathConfineError(403, 'That path leaves the skills, commands and agents folders through a link.');
+}
+
+/** True when `fullPath` (built by the server: an icon, a tree entry) really is below the artifact. Never throws. */
+export function staysInside(artifact, fullPath, { fs = realFs } = {}) {
+  if (!artifact?.realBase || !fullPath) return false;
+  try { return isInside(artifact.realBase, realPathOf(fullPath, fs)); } catch { return false; }
+}
+
+/** A file or folder below an artifact, named by the browser → its path, when it really stays below. */
+export function confineSubPath(artifact, subPath, { fs = realFs } = {}) {
+  if (typeof subPath !== 'string' || !subPath || subPath.includes('\0')) throw new PathConfineError(400, 'Not a file path');
+  const full = join(String(artifact?.dirPath || ''), subPath);
+  if (!artifact?.dirPath || !isInside(artifact.dirPath, full)) throw new PathConfineError(403, 'Path traversal not allowed.');
+  if (!staysInside(artifact, full, { fs })) throw new PathConfineError(403, 'That path leaves the artifact through a link.');
+  return full;
+}
+
+/** A path about to be created under one root (create, import) → the path, when it would really land there. */
+export function confineToRoot(root, target, { fs = realFs } = {}) {
+  const r = rootOf(root);
+  const full = resolve(String(target ?? ''));
+  if (!r.dir || !isInside(r.dir, full)) throw new PathConfineError(403, 'That path is outside the skills, commands and agents folders.');
+  let ok = false;
+  try {
+    const realRoot = realPathOf(r.dir, fs);
+    ok = (!r.anchor || isInside(realPathOf(r.anchor, fs), realRoot)) && isInside(realRoot, realPathOf(full, fs));
+  } catch { ok = false; }
+  if (!ok) throw new PathConfineError(403, 'That path leaves the skills, commands and agents folders through a link.');
+  return full;
+}

package/neural-interface/lib/plugin-installer.js

@@ -0,0 +1,264 @@
+import { spawnSync } from 'child_process';
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync,
+  lstatSync, renameSync, rmSync,
+} from 'fs';
+import { join, resolve, dirname } from 'path';
+import os from 'node:os';
+
+const PLUGINS_ROOT = () => join(os.homedir(), '.claude', 'plugins');
+const INSTALLED_PLUGINS_FILE = () => join(PLUGINS_ROOT(), 'installed_plugins.json');
+const KNOWN_MARKETPLACES_FILE = () => join(PLUGINS_ROOT(), 'known_marketplaces.json');
+
+let trackerPath = null;
+export function setTrackerPath(p) { trackerPath = p; }
+const trackerFile = () => trackerPath || join(process.cwd(), 'data', 'synabun-plugins.json');
+
+function ensureDir(p) { if (!existsSync(p)) mkdirSync(p, { recursive: true }); }
+
+function readJson(p, fallback) {
+  try { return existsSync(p) ? JSON.parse(readFileSync(p, 'utf-8')) : fallback; }
+  catch { return fallback; }
+}
+
+function writeJsonAtomic(p, obj) {
+  ensureDir(dirname(p));
+  const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+  try { renameSync(tmp, p); }
+  catch { writeFileSync(p, JSON.stringify(obj, null, 2) + '\n', 'utf-8'); try { unlinkSync(tmp); } catch {} }
+}
+
+function runClaude(args, { timeoutMs = 180000 } = {}) {
+  const r = spawnSync('claude', args, {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+  });
+  const stdout = (r.stdout || '').toString();
+  const stderr = (r.stderr || '').toString();
+  const combined = `${stdout}${stderr ? '\n' + stderr : ''}`.trim();
+  if (r.error && r.error.code === 'ENOENT') {
+    return { ok: false, code: -1, stdout, stderr, combined, notFound: true };
+  }
+  return { ok: r.status === 0, code: r.status ?? -1, stdout, stderr, combined };
+}
+
+function claudeNotFoundErr() {
+  return { ok: false, error: 'Claude Code CLI not found on PATH. Install `claude` to manage plugins.' };
+}
+
+function gitHeadSha(repoPath) {
+  if (!repoPath || !existsSync(repoPath)) return 'unknown';
+  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repoPath, encoding: 'utf-8' });
+  const out = (r.stdout || '').trim();
+  return out || 'unknown';
+}
+
+function readTracker() { return readJson(trackerFile(), { version: 1, plugins: {} }); }
+function writeTracker(obj) { writeJsonAtomic(trackerFile(), obj); }
+
+function isSynabunSymlinkMarketplace(entry) {
+  return entry && entry.source && entry.source.source === 'synabun-symlink';
+}
+
+// Purge legacy "synabun-symlink" entries that break CC's marketplace loader,
+// plus orphaned installed_plugins rows whose cache path no longer exists.
+function cleanLegacyState() {
+  try {
+    const known = readJson(KNOWN_MARKETPLACES_FILE(), null);
+    if (known && typeof known === 'object') {
+      let changed = false;
+      for (const [name, entry] of Object.entries(known)) {
+        if (isSynabunSymlinkMarketplace(entry)) {
+          delete known[name];
+          changed = true;
+          const mkLink = join(PLUGINS_ROOT(), 'marketplaces', name);
+          try { if (lstatSync(mkLink).isSymbolicLink()) unlinkSync(mkLink); } catch {}
+          try { rmSync(join(PLUGINS_ROOT(), 'cache', name), { recursive: true, force: true }); } catch {}
+        }
+      }
+      if (changed) writeJsonAtomic(KNOWN_MARKETPLACES_FILE(), known);
+    }
+
+    const installed = readJson(INSTALLED_PLUGINS_FILE(), null);
+    if (installed && installed.plugins && typeof installed.plugins === 'object') {
+      let changed2 = false;
+      for (const key of Object.keys(installed.plugins)) {
+        const list = installed.plugins[key] || [];
+        const filtered = list.filter(e => e && e.installPath && existsSync(e.installPath));
+        if (filtered.length !== list.length) {
+          if (filtered.length) installed.plugins[key] = filtered;
+          else delete installed.plugins[key];
+          changed2 = true;
+        }
+      }
+      if (changed2) writeJsonAtomic(INSTALLED_PLUGINS_FILE(), installed);
+    }
+  } catch {}
+}
+
+function parsePluginManifest(repoPath) {
+  const pluginJson = readJson(join(repoPath, '.claude-plugin', 'plugin.json'), null);
+  if (!pluginJson || !pluginJson.name) return { ok: false, error: `Missing .claude-plugin/plugin.json at ${repoPath}` };
+  const marketplaceJson = readJson(join(repoPath, '.claude-plugin', 'marketplace.json'), null);
+  const pluginName = String(pluginJson.name).trim();
+  const marketplaceName = (marketplaceJson && marketplaceJson.name) || pluginName;
+  const hooks = pluginJson.hooks && typeof pluginJson.hooks === 'object' ? Object.keys(pluginJson.hooks) : [];
+  return { ok: true, pluginName, marketplaceName, hooks, manifest: pluginJson };
+}
+
+// Install via `claude plugin marketplace add` + `claude plugin install`.
+// Prefers githubUrl (CC manages its own clone); falls back to local repoPath.
+export function installClaudePlugin({ repoPath, githubUrl } = {}) {
+  cleanLegacyState();
+
+  if (!repoPath || !existsSync(repoPath)) {
+    return { ok: false, error: `Repo path required to read plugin manifest: ${repoPath}` };
+  }
+  const meta = parsePluginManifest(repoPath);
+  if (!meta.ok) return meta;
+  const { pluginName, marketplaceName, hooks } = meta;
+
+  const source = githubUrl || resolve(repoPath);
+
+  const addRes = runClaude(['plugin', 'marketplace', 'add', source, '--scope', 'user']);
+  if (addRes.notFound) return claudeNotFoundErr();
+  const alreadyAdded = /already (added|exists|configured|registered)/i.test(addRes.combined);
+  if (!addRes.ok && !alreadyAdded) {
+    return { ok: false, error: `claude plugin marketplace add failed: ${addRes.combined || `exit ${addRes.code}`}` };
+  }
+
+  const installRes = runClaude(['plugin', 'install', `${pluginName}@${marketplaceName}`, '--scope', 'user']);
+  if (installRes.notFound) return claudeNotFoundErr();
+  const alreadyInstalled = /already installed/i.test(installRes.combined);
+  if (!installRes.ok && !alreadyInstalled) {
+    return { ok: false, error: `claude plugin install failed: ${installRes.combined || `exit ${installRes.code}`}` };
+  }
+
+  const installed = readJson(INSTALLED_PLUGINS_FILE(), { plugins: {} });
+  const key = `${pluginName}@${marketplaceName}`;
+  const ccList = installed.plugins?.[key] || [];
+  const ccEntry = ccList.find(e => e && e.scope === 'user') || ccList[0] || null;
+  const installPath = ccEntry?.installPath || null;
+  const gitCommitSha = ccEntry?.gitCommitSha || gitHeadSha(repoPath);
+
+  const tracker = readTracker();
+  if (!tracker.plugins || typeof tracker.plugins !== 'object') tracker.plugins = {};
+  tracker.plugins[key] = {
+    pluginName,
+    marketplaceName,
+    source,
+    githubUrl: githubUrl || null,
+    repoPath: resolve(repoPath),
+    gitCommitSha,
+    installedAt: tracker.plugins[key]?.installedAt || new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  };
+  writeTracker(tracker);
+
+  return {
+    ok: true,
+    pluginName,
+    marketplaceName,
+    installPath,
+    marketplacePath: join(PLUGINS_ROOT(), 'marketplaces', marketplaceName),
+    key,
+    hooks,
+    gitCommitSha,
+    alreadyInstalled,
+  };
+}
+
+export function uninstallClaudePlugin({ marketplaceName, pluginName } = {}) {
+  cleanLegacyState();
+  if (!marketplaceName) return { ok: false, error: 'marketplaceName required' };
+
+  const tracker = readTracker();
+  const managedKeys = Object.keys(tracker.plugins || {}).filter(k => {
+    const [pName, mName] = k.split('@');
+    if (mName !== marketplaceName) return false;
+    if (pluginName && pName !== pluginName) return false;
+    return true;
+  });
+  if (!managedKeys.length) return { ok: false, error: `No SynaBun-managed plugin found for ${marketplaceName}${pluginName ? '/' + pluginName : ''}` };
+
+  const removedPlugins = [];
+  for (const key of managedKeys) {
+    const [pName] = key.split('@');
+    const r = runClaude(['plugin', 'uninstall', key]);
+    if (r.notFound) return claudeNotFoundErr();
+    const notFound = /not (installed|found)/i.test(r.combined);
+    if (!r.ok && !notFound) {
+      return { ok: false, error: `claude plugin uninstall failed: ${r.combined || `exit ${r.code}`}` };
+    }
+    delete tracker.plugins[key];
+    removedPlugins.push(pName);
+  }
+
+  const remaining = Object.keys(tracker.plugins || {}).some(k => k.endsWith(`@${marketplaceName}`));
+  if (!remaining) {
+    runClaude(['plugin', 'marketplace', 'remove', marketplaceName]);
+  }
+  writeTracker(tracker);
+  return { ok: true, removedPlugins };
+}
+
+export function listSynabunPlugins() {
+  const tracker = readTracker();
+  const installed = readJson(INSTALLED_PLUGINS_FILE(), { plugins: {} });
+  const out = [];
+  for (const [key, meta] of Object.entries(tracker.plugins || {})) {
+    const ccList = installed.plugins?.[key] || [];
+    const ccEntry = ccList.find(e => e && e.scope === 'user') || ccList[0] || null;
+    const installPath = ccEntry?.installPath || null;
+    const installPresent = installPath ? existsSync(installPath) : false;
+    const repoExists = meta.repoPath ? existsSync(meta.repoPath) : true;
+    out.push({
+      key,
+      pluginName: meta.pluginName,
+      marketplaceName: meta.marketplaceName,
+      scope: ccEntry?.scope || 'user',
+      installPath,
+      installedAt: meta.installedAt,
+      lastUpdated: meta.lastUpdated,
+      gitCommitSha: ccEntry?.gitCommitSha || meta.gitCommitSha,
+      repoPath: meta.repoPath || null,
+      githubUrl: meta.githubUrl || null,
+      broken: !ccEntry || !installPresent || !repoExists,
+    });
+  }
+  return out;
+}
+
+// Migration: purge legacy synabun-symlink state + reinstall via CLI for any
+// entries whose original repo path still exists.
+export function repairSynabunPlugins() {
+  const before = readJson(KNOWN_MARKETPLACES_FILE(), {}) || {};
+  const legacy = Object.entries(before)
+    .filter(([, v]) => isSynabunSymlinkMarketplace(v))
+    .map(([name, v]) => ({ name, path: v.source?.path || null }));
+
+  cleanLegacyState();
+
+  const repaired = [];
+  const failed = [];
+  for (const { name, path } of legacy) {
+    if (!path || !existsSync(path)) {
+      failed.push({ marketplaceName: name, error: 'Original repo path missing — cannot reinstall automatically' });
+      continue;
+    }
+    const meta = parsePluginManifest(path);
+    if (!meta.ok) { failed.push({ marketplaceName: name, error: meta.error }); continue; }
+    let githubUrl = null;
+    try {
+      const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: path, encoding: 'utf-8' });
+      const u = (r.stdout || '').trim();
+      if (/^https?:\/\//.test(u)) githubUrl = u.replace(/\.git$/, '');
+    } catch {}
+    const res = installClaudePlugin({ repoPath: path, githubUrl });
+    if (res.ok) repaired.push({ marketplaceName: name, pluginName: res.pluginName });
+    else failed.push({ marketplaceName: name, error: res.error });
+  }
+  return { repaired, failed };
+}