@schlessera/brain-ui-server 0.27.0 → 0.28.0

package/src/routes/skills.ts

@@ -0,0 +1,203 @@
+/**
+ * Custom-skill management routes — the Settings pane's CRUD over the brain
+ * repo's canonical skill home (see skills/manager.ts for the store contract).
+ *
+ * Every mutation is followed by `brain skills sync`, which re-materializes
+ * the per-agent integration dirs (.claude/skills, .pi/skills, codex, gemini)
+ * and the AGENTS.md index block — so a change here reaches EVERY backend's
+ * next turn/session with no restart. A failed sync degrades to a `warning`
+ * in the response (the canonical write already happened; the next nightly
+ * sync repairs the links) instead of failing the request.
+ *
+ * Mount BEHIND the /api auth guard: skills instruct the agent.
+ */
+
+import { Hono } from "hono";
+import type { Logger } from "@opentelemetry/api-logs";
+import {
+  createSkillManager,
+  SkillConflictError,
+  SkillNotFoundError,
+  SkillValidationError,
+} from "../skills/manager.js";
+import {
+  InstallError,
+  installSkillsFromGitHub,
+  installSkillsFromZip,
+  MAX_ARCHIVE_BYTES,
+  parseGitHubSource,
+  type Fetcher,
+} from "../skills/install.js";
+import { resolveGitHubToken } from "../config/env.js";
+
+export interface SkillRoutesDeps {
+  brainPath: string;
+  /** Runs `brain skills sync`; resolves with a human-readable summary. */
+  syncSkills: () => Promise<string>;
+  log?: Logger;
+  /** Test seam — GitHub zipball fetcher. */
+  fetcher?: Fetcher;
+  /** Test seam — token source; default reads GITHUB_TOKEN at call time. */
+  githubToken?: () => string | undefined;
+}
+
+export function createSkillRoutes(deps: SkillRoutesDeps): Hono {
+  const manager = createSkillManager(deps.brainPath);
+
+  function errorResponse(err: unknown): { status: 400 | 404 | 409 | 500; message: string } {
+    if (err instanceof SkillValidationError) return { status: 400, message: err.message };
+    if (err instanceof SkillNotFoundError) return { status: 404, message: err.message };
+    if (err instanceof SkillConflictError) return { status: 409, message: err.message };
+    return { status: 500, message: err instanceof Error ? err.message : "Skill operation failed." };
+  }
+
+  async function syncAfterMutation(): Promise<string | undefined> {
+    try {
+      await deps.syncSkills();
+      return undefined;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      deps.log?.emit({
+        severityText: "WARN",
+        body: "brain skills sync failed after a skill mutation; agent links may lag until the next sync",
+        attributes: { error: message },
+      });
+      return `Skill saved, but \`brain skills sync\` failed: ${message}`;
+    }
+  }
+
+  const githubToken = deps.githubToken ?? resolveGitHubToken;
+
+  return new Hono()
+    .get("/skills", (c) => c.json({ skills: manager.list() }))
+    .post("/skills/install/zip", async (c) => {
+      let file: File | null = null;
+      let overwrite = false;
+      try {
+        const form = await c.req.formData();
+        const entry = form.get("file");
+        file = entry instanceof File ? entry : null;
+        overwrite = form.get("overwrite") === "true";
+      } catch {
+        return c.json({ error: "Send multipart/form-data with a `file` field." }, 400);
+      }
+      if (!file) return c.json({ error: "Missing `file` (a .zip archive)." }, 400);
+      if (file.size > MAX_ARCHIVE_BYTES) {
+        return c.json({ error: `Archive exceeds ${MAX_ARCHIVE_BYTES / 1024 / 1024}MB.` }, 400);
+      }
+      try {
+        const outcomes = installSkillsFromZip(
+          { brainPath: deps.brainPath },
+          new Uint8Array(await file.arrayBuffer()),
+          { overwrite }
+        );
+        const warning = outcomes.some((o) => o.status !== "skipped")
+          ? await syncAfterMutation()
+          : undefined;
+        return c.json({ outcomes, ...(warning ? { warning } : {}) });
+      } catch (err) {
+        if (err instanceof InstallError) return c.json({ error: err.message }, 400);
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .post("/skills/install/github", async (c) => {
+      const body = (await c.req.json().catch(() => null)) as {
+        source?: unknown;
+        ref?: unknown;
+        overwrite?: unknown;
+      } | null;
+      if (typeof body?.source !== "string" || !body.source.trim()) {
+        return c.json(
+          { error: "Body needs `source`: owner/repo or a github.com URL." },
+          400
+        );
+      }
+      const parsed = parseGitHubSource(body.source);
+      if (!parsed) {
+        return c.json(
+          { error: "Could not parse the source — use owner/repo or a github.com URL." },
+          400
+        );
+      }
+      if (typeof body.ref === "string" && body.ref.trim()) parsed.ref = body.ref.trim();
+      try {
+        const outcomes = await installSkillsFromGitHub({ brainPath: deps.brainPath }, parsed, {
+          overwrite: body.overwrite === true,
+          token: githubToken(),
+          ...(deps.fetcher ? { fetcher: deps.fetcher } : {}),
+        });
+        const warning = outcomes.some((o) => o.status !== "skipped")
+          ? await syncAfterMutation()
+          : undefined;
+        return c.json({ outcomes, ...(warning ? { warning } : {}) });
+      } catch (err) {
+        if (err instanceof InstallError) return c.json({ error: err.message }, 400);
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .get("/skills/:name", (c) => {
+      try {
+        return c.json(manager.get(c.req.param("name")));
+      } catch (err) {
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .post("/skills", async (c) => {
+      const body = (await c.req.json().catch(() => null)) as {
+        name?: unknown;
+        content?: unknown;
+      } | null;
+      if (typeof body?.name !== "string" || typeof body?.content !== "string") {
+        return c.json({ error: "Body needs string `name` and `content`." }, 400);
+      }
+      try {
+        const entry = manager.create(body.name, body.content);
+        const warning = await syncAfterMutation();
+        return c.json({ skill: entry, ...(warning ? { warning } : {}) }, 201);
+      } catch (err) {
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .put("/skills/:name", async (c) => {
+      const body = (await c.req.json().catch(() => null)) as { content?: unknown } | null;
+      if (typeof body?.content !== "string") {
+        return c.json({ error: "Body needs string `content`." }, 400);
+      }
+      try {
+        const entry = manager.update(c.req.param("name"), body.content);
+        const warning = await syncAfterMutation();
+        return c.json({ skill: entry, ...(warning ? { warning } : {}) });
+      } catch (err) {
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .post("/skills/:name/enabled", async (c) => {
+      const body = (await c.req.json().catch(() => null)) as { enabled?: unknown } | null;
+      if (typeof body?.enabled !== "boolean") {
+        return c.json({ error: "Body needs boolean `enabled`." }, 400);
+      }
+      try {
+        const entry = manager.setEnabled(c.req.param("name"), body.enabled);
+        const warning = await syncAfterMutation();
+        return c.json({ skill: entry, ...(warning ? { warning } : {}) });
+      } catch (err) {
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    })
+    .delete("/skills/:name", async (c) => {
+      try {
+        manager.remove(c.req.param("name"));
+        const warning = await syncAfterMutation();
+        return c.json({ ok: true, ...(warning ? { warning } : {}) });
+      } catch (err) {
+        const { status, message } = errorResponse(err);
+        return c.json({ error: message }, status);
+      }
+    });
+}

package/src/routes/tool-permissions.ts

@@ -0,0 +1,37 @@
+/**
+ * Management surface for the user's remembered "always allow" tool grants —
+ * the Settings screen's view of what the approval cards' "Always allow"
+ * button has accumulated, and the way to take a grant back.
+ *
+ * The grants themselves are consulted by the ws bridge (an auto-allowed tool
+ * never raises a card); this surface only lists and removes. Mount BEHIND
+ * the /api auth guard: the list shapes what the agent can do unprompted.
+ */
+
+import { Hono } from "hono";
+import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
+import { getAutoAllowedTools, setAutoAllowedTools } from "../db/settings.js";
+
+export function createToolPermissionRoutes(deps: {
+  db: Database;
+  log?: Logger;
+}): Hono {
+  const { db, log } = deps;
+  return new Hono()
+    .get("/tool-permissions", (c) =>
+      c.json({ tools: getAutoAllowedTools(db, log) })
+    )
+    .delete("/tool-permissions/:tool", (c) => {
+      const tool = decodeURIComponent(c.req.param("tool"));
+      const current = getAutoAllowedTools(db, log);
+      if (!current.includes(tool)) {
+        return c.json({ error: "Not an auto-allowed tool." }, 404);
+      }
+      setAutoAllowedTools(
+        db,
+        current.filter((t) => t !== tool)
+      );
+      return c.json({ tools: getAutoAllowedTools(db, log) });
+    });
+}

package/src/skills/install.ts

@@ -0,0 +1,332 @@
+/**
+ * Skill installation from archives — the "install" half of the Settings →
+ * Skills surface: a user-uploaded ZIP, or a GitHub repository (public, or
+ * private via the deployment's GITHUB_TOKEN) fetched as a zipball. Both run
+ * through ONE pipeline so they share the same guarantees:
+ *
+ * - A skill is any directory in the archive containing a SKILL.md (the
+ *   archive root included). One archive may carry several skills.
+ * - The INSTALLED name comes from the SKILL.md frontmatter (validated like a
+ *   created skill), not from whatever the archive called the folder.
+ * - Zip-slip is structurally impossible: entry paths are normalized and any
+ *   `..`, absolute path, backslash, or NUL rejects the archive; files are
+ *   written only under `.agents/skills/<name>/`, staged then swapped so a
+ *   half-written skill is never discoverable.
+ * - Caps: archive ≤ 20 MB compressed, ≤ 50 MB inflated, ≤ 400 files per
+ *   skill, per-file ≤ 10 MB.
+ * - Conflicts are SKIPPED by default and reported; `overwrite: true` may
+ *   replace an existing CUSTOM skill (enabled or disabled) but can never
+ *   touch a package skill — those are symlinks and stay refused.
+ */
+
+import { unzipSync } from "fflate";
+import { existsSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import matter from "gray-matter";
+
+export const MAX_ARCHIVE_BYTES = 20 * 1024 * 1024;
+export const MAX_INFLATED_BYTES = 50 * 1024 * 1024;
+export const MAX_FILES_PER_SKILL = 400;
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export class InstallError extends Error {}
+
+export interface InstallOutcome {
+  /** Installed-as name (frontmatter), or the archive folder for failures. */
+  name: string;
+  status: "installed" | "replaced" | "skipped";
+  reason?: string;
+  files?: number;
+}
+
+export interface InstallOptions {
+  overwrite?: boolean;
+  /** Only consider entries under this archive subpath (GitHub `tree` URLs). */
+  subpath?: string;
+}
+
+export interface InstallDeps {
+  brainPath: string;
+}
+
+/** A safe, normalized archive path or null. Rejects slip vectors outright. */
+function safeEntryPath(raw: string): string | null {
+  if (raw.includes("\\") || raw.includes("\0") || raw.startsWith("/")) return null;
+  const parts = raw.split("/").filter((p) => p !== "" && p !== ".");
+  if (parts.some((p) => p === ".." || p.length > 128)) return null;
+  return parts.join("/");
+}
+
+function existsAs(p: string): "dir" | "symlink" | null {
+  try {
+    const st = lstatSync(p);
+    return st.isSymbolicLink() ? "symlink" : st.isDirectory() ? "dir" : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The shared core: install every skill found among already-unzipped entries.
+ * Throws InstallError for archive-level problems; per-skill problems land as
+ * skipped outcomes.
+ */
+export function installSkillsFromEntries(
+  deps: InstallDeps,
+  entries: Record<string, Uint8Array>,
+  opts: InstallOptions = {}
+): InstallOutcome[] {
+  // Normalize + guard every entry, enforcing the inflated cap.
+  const files = new Map<string, Uint8Array>();
+  let inflated = 0;
+  for (const [raw, bytes] of Object.entries(entries)) {
+    if (raw.endsWith("/")) continue; // directory marker
+    const path = safeEntryPath(raw);
+    if (path === null) {
+      throw new InstallError(`Archive contains an unsafe path: ${JSON.stringify(raw)}`);
+    }
+    if (bytes.length > MAX_FILE_BYTES) {
+      throw new InstallError(`${path} exceeds ${MAX_FILE_BYTES / 1024 / 1024}MB.`);
+    }
+    inflated += bytes.length;
+    if (inflated > MAX_INFLATED_BYTES) {
+      throw new InstallError("Archive inflates past the 50MB cap.");
+    }
+    files.set(path, bytes);
+  }
+
+  // Candidate skill roots: every directory (or the root) holding a SKILL.md,
+  // optionally filtered to a subpath.
+  const prefix = opts.subpath ? opts.subpath.replace(/^\/+|\/+$/g, "") + "/" : "";
+  const roots = [...files.keys()]
+    .filter((p) => p === "SKILL.md" || p.endsWith("/SKILL.md"))
+    .map((p) => (p === "SKILL.md" ? "" : p.slice(0, -"/SKILL.md".length)))
+    .filter((root) => (prefix ? (root + "/").startsWith(prefix) : true))
+    .sort();
+  if (roots.length === 0) {
+    throw new InstallError(
+      "No skill found: no directory containing a SKILL.md" +
+        (opts.subpath ? ` under "${opts.subpath}"` : "") +
+        "."
+    );
+  }
+
+  const enabledDir = join(deps.brainPath, ".agents", "skills");
+  const disabledDir = join(deps.brainPath, ".agents", "skills-disabled");
+  mkdirSync(enabledDir, { recursive: true });
+
+  const outcomes: InstallOutcome[] = [];
+  for (const root of roots) {
+    const rootPrefix = root === "" ? "" : root + "/";
+    const label = root || "(archive root)";
+    // Each file belongs to its DEEPEST skill root, so nested skills never
+    // double-install into their parent.
+    const deeper = roots.filter((r) => r !== root && r.startsWith(rootPrefix));
+    const skillFiles = new Map<string, Uint8Array>();
+    for (const [path, bytes] of files) {
+      if (!path.startsWith(rootPrefix)) continue;
+      if (deeper.some((d) => path.startsWith(d + "/"))) continue;
+      skillFiles.set(path.slice(rootPrefix.length), bytes);
+    }
+
+    outcomes.push(installOne(label, skillFiles, enabledDir, disabledDir, opts));
+  }
+  return outcomes;
+}
+
+function installOne(
+  label: string,
+  skillFiles: Map<string, Uint8Array>,
+  enabledDir: string,
+  disabledDir: string,
+  opts: InstallOptions
+): InstallOutcome {
+  const skillMd = skillFiles.get("SKILL.md");
+  if (!skillMd) return { name: label, status: "skipped", reason: "SKILL.md unreadable" };
+
+  let data: Record<string, unknown>;
+  try {
+    data = matter(Buffer.from(skillMd).toString("utf-8")).data as Record<string, unknown>;
+  } catch (e) {
+    return {
+      name: label,
+      status: "skipped",
+      reason: `frontmatter does not parse: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+  const name = typeof data.name === "string" ? data.name : "";
+  if (!NAME_PATTERN.test(name)) {
+    return {
+      name: label,
+      status: "skipped",
+      reason: "frontmatter `name` missing or not lowercase kebab-case",
+    };
+  }
+  if (typeof data.description !== "string" || !data.description.trim()) {
+    return { name, status: "skipped", reason: "frontmatter has no `description`" };
+  }
+  if (skillFiles.size > MAX_FILES_PER_SKILL) {
+    return { name, status: "skipped", reason: `more than ${MAX_FILES_PER_SKILL} files` };
+  }
+
+  const target = join(enabledDir, name);
+  const disabledTarget = join(disabledDir, name);
+  if (existsAs(target) === "symlink") {
+    return {
+      name,
+      status: "skipped",
+      reason: "a built-in (package) skill has this name; rename yours in the frontmatter",
+    };
+  }
+  const existing = existsAs(target) === "dir" || existsAs(disabledTarget) === "dir";
+  if (existing && !opts.overwrite) {
+    return { name, status: "skipped", reason: "already installed (enable overwrite to replace)" };
+  }
+
+  // Stage into a temp sibling, then swap — a half-written skill dir must
+  // never be what an agent discovers.
+  const staging = join(enabledDir, `.install-${name}-${process.pid}`);
+  rmSync(staging, { recursive: true, force: true });
+  try {
+    for (const [rel, bytes] of skillFiles) {
+      const dest = join(staging, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, bytes);
+    }
+    rmSync(target, { recursive: true, force: true });
+    if (existsSync(disabledTarget)) rmSync(disabledTarget, { recursive: true, force: true });
+    renameSync(staging, target);
+    return { name, status: existing ? "replaced" : "installed", files: skillFiles.size };
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true });
+    return {
+      name,
+      status: "skipped",
+      reason: `write failed: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}
+
+/** Install every skill found in an uploaded ZIP archive. */
+export function installSkillsFromZip(
+  deps: InstallDeps,
+  archive: Uint8Array,
+  opts: InstallOptions = {}
+): InstallOutcome[] {
+  if (archive.length > MAX_ARCHIVE_BYTES) {
+    throw new InstallError(`Archive exceeds ${MAX_ARCHIVE_BYTES / 1024 / 1024}MB.`);
+  }
+  let entries: Record<string, Uint8Array>;
+  try {
+    entries = unzipSync(archive);
+  } catch (e) {
+    throw new InstallError(
+      `Not a readable ZIP archive: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  return installSkillsFromEntries(deps, entries, opts);
+}
+
+// ---------------------------------------------------------------------------
+// GitHub
+// ---------------------------------------------------------------------------
+
+export interface GitHubSource {
+  owner: string;
+  repo: string;
+  ref?: string;
+  /** Repo subpath to search for skills (from a /tree/<ref>/<path> URL). */
+  subpath?: string;
+}
+
+/**
+ * Parse "owner/repo", a github.com URL, or a /tree/<ref>/<subpath> URL.
+ * The ref/subpath split is heuristic for URLs (a ref containing "/" cannot
+ * be told apart from a path); pass an explicit ref for those.
+ */
+export function parseGitHubSource(input: string): GitHubSource | null {
+  const trimmed = input.trim();
+  const bare = /^([\w.-]+)\/([\w.-]+)$/.exec(trimmed);
+  if (bare) return { owner: bare[1]!, repo: bare[2]!.replace(/\.git$/, "") };
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (url.hostname !== "github.com" && url.hostname !== "www.github.com") return null;
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length < 2) return null;
+  const owner = parts[0]!;
+  const repo = parts[1]!.replace(/\.git$/, "");
+  if (parts.length >= 4 && (parts[2] === "tree" || parts[2] === "blob")) {
+    const ref = parts[3]!;
+    const subpath = parts.slice(4).join("/") || undefined;
+    return { owner, repo, ref, ...(subpath ? { subpath } : {}) };
+  }
+  return { owner, repo };
+}
+
+/** Injectable for tests; production passes globalThis.fetch. */
+export type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Download a repo zipball (the API endpoint — works for private repos with a
+ * token, follows the codeload redirect) and install through the shared
+ * pipeline. GitHub zipballs prefix every entry with `owner-repo-sha/`; that
+ * wrapper folder is stripped before candidate discovery so subpaths from
+ * /tree/ URLs match repo-relative paths.
+ */
+export async function installSkillsFromGitHub(
+  deps: InstallDeps,
+  source: GitHubSource,
+  opts: { overwrite?: boolean; token?: string; fetcher?: Fetcher } = {}
+): Promise<InstallOutcome[]> {
+  const fetcher = opts.fetcher ?? fetch;
+  const ref = source.ref ? `/${encodeURIComponent(source.ref)}` : "";
+  const url = `https://api.github.com/repos/${encodeURIComponent(source.owner)}/${encodeURIComponent(source.repo)}/zipball${ref}`;
+  const res = await fetcher(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "brain-kit-ui",
+      ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+    },
+    redirect: "follow",
+  });
+  if (res.status === 404) {
+    throw new InstallError(
+      `GitHub says 404 for ${source.owner}/${source.repo}` +
+        (opts.token
+          ? "."
+          : " — if the repository is private, set GITHUB_TOKEN on the server.")
+    );
+  }
+  if (!res.ok) {
+    throw new InstallError(`GitHub zipball fetch failed: HTTP ${res.status}`);
+  }
+  const buf = new Uint8Array(await res.arrayBuffer());
+  if (buf.length > MAX_ARCHIVE_BYTES) {
+    throw new InstallError(`Repository archive exceeds ${MAX_ARCHIVE_BYTES / 1024 / 1024}MB.`);
+  }
+
+  let entries: Record<string, Uint8Array>;
+  try {
+    entries = unzipSync(buf);
+  } catch (e) {
+    throw new InstallError(
+      `GitHub returned an unreadable archive: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  const stripped: Record<string, Uint8Array> = {};
+  for (const [key, bytes] of Object.entries(entries)) {
+    const slash = key.indexOf("/");
+    if (slash === -1) continue; // nothing lives outside the wrapper dir
+    stripped[key.slice(slash + 1)] = bytes;
+  }
+  return installSkillsFromEntries(deps, stripped, {
+    ...(opts.overwrite !== undefined ? { overwrite: opts.overwrite } : {}),
+    ...(source.subpath ? { subpath: source.subpath } : {}),
+  });
+}