@nyte-ai/host 0.0.0-stage → 0.0.19

package/src/local/worktrees.ts

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, realpath, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { SdkError } from "@nyte-ai/schema";
+import type { WorkspaceTarget } from "@nyte-ai/schema";
+import type { WorktreeProvider } from "@nyte-ai/core";
+import { sha256 } from "../hash.ts";
+import { run } from "./command.ts";
+
+const ENV: Readonly<Record<string, string>> = { GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" };
+
+/** One checkout of a repository: its folder and the branch it has out, null when HEAD is detached. */
+export interface ListedWorktree {
+  readonly path: string;
+  readonly branch: string | null;
+}
+
+type Git = (
+  cwd: string,
+  args: readonly string[],
+  env?: Readonly<Record<string, string>>,
+) => Promise<string>;
+
+type Repository = { readonly root: string; readonly gitDir: string; readonly prefix: string };
+
+function gitCommand(binary = "git"): Git {
+  return async (cwd, args, env) => {
+    const ran = await run(binary, ["-c", "core.quotepath=off", ...args], {
+      cwd,
+      env: { ...ENV, ...env },
+    });
+
+    if (ran.code !== 0)
+      throw new SdkError("unavailable", ran.stderr.trim() || `git ${args[0] ?? ""} failed.`);
+
+    return ran.stdout.toString("utf8");
+  };
+}
+
+/** Lists every worktree of the repository holding `cwd` (`git worktree list --porcelain -z`), the main checkout first. */
+export async function listWorktrees(
+  cwd: string,
+  options?: { readonly git?: string },
+): Promise<readonly ListedWorktree[]> {
+  const out = await gitCommand(options?.git)(cwd, ["worktree", "list", "--porcelain", "-z"]);
+
+  return out.split("\0\0").flatMap((record) => {
+    const fields = record.split("\0");
+    const path = fields.find((field) => field.startsWith("worktree "))?.slice(9);
+    const branch = fields.find((field) => field.startsWith("branch refs/heads/"))?.slice(18);
+
+    return path === undefined ? [] : [{ path: resolve(path), branch: branch ?? null }];
+  });
+}
+
+/** Checks `branch` out in a new worktree at `path` (`git worktree add`), creating the branch at `from` when given. */
+export async function addWorktree(
+  cwd: string,
+  input: { readonly path: string; readonly branch: string; readonly from?: string },
+  options?: { readonly git?: string },
+): Promise<void> {
+  await gitCommand(options?.git)(
+    cwd,
+    input.from === undefined
+      ? ["worktree", "add", input.path, input.branch]
+      : ["worktree", "add", "-b", input.branch, input.path, input.from],
+  );
+}
+
+/** Whether `name` is a local branch of the repository holding `cwd`. */
+export async function hasBranch(
+  cwd: string,
+  name: string,
+  options?: { readonly git?: string },
+): Promise<boolean> {
+  return gitCommand(options?.git)(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${name}`])
+    .then(() => true)
+    .catch(() => false);
+}
+
+/**
+ * Returns git worktrees for local workspaces (`git`, default `git` on the
+ * PATH), each under `<home>/.nyte/worktrees/<repository>/<slug>` on the branch
+ * `nyte/<slug>`, the slug the title's words and a hash of the name.
+ *
+ * `create` refuses a folder outside a repository or one without a commit, then
+ * answers the worktree already on that branch, or adds one from HEAD and
+ * copies the workspace's uncommitted changes in: the worktree's tracked and
+ * untracked files, ignored ones aside, are written to a tree through a
+ * temporary index seeded from the real one (which is never touched), and the
+ * new checkout moves to that tree with its index left at HEAD, so the changes
+ * show as uncommitted there too. A workspace below the repository's root gets
+ * the same folder below the worktree's.
+ *
+ * `remove` keeps a worktree, folder and branch, while it holds uncommitted
+ * changes or ignored files, since none were copied in and one may be a
+ * `.env` or a local database (a wholly ignored folder such as `node_modules`
+ * or a build's output aside); otherwise it removes the folder
+ * (`git worktree remove`) and deletes the branch unless it moved past `base`.
+ */
+export function localWorktrees(options?: {
+  readonly home?: string;
+  readonly git?: string;
+}): WorktreeProvider {
+  const git = gitCommand(options?.git);
+  const folders = join(options?.home ?? homedir(), ".nyte", "worktrees");
+
+  const commitAt = (cwd: string, revision: string): Promise<string | null> =>
+    git(cwd, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`]).then(
+      (out) => out.trim(),
+      () => null,
+    );
+
+  const workingTree = async (repo: Repository): Promise<string> => {
+    const index = join(tmpdir(), `nyte-worktree-index-${randomUUID()}`);
+    const indexEnv = { GIT_INDEX_FILE: index };
+
+    try {
+      await copyFile(join(repo.gitDir, "index"), index).catch(() => undefined);
+      await git(repo.root, ["add", "-A", "--", "."], indexEnv);
+
+      return (await git(repo.root, ["write-tree"], indexEnv)).trim();
+    } finally {
+      await rm(index, { force: true });
+    }
+  };
+
+  return {
+    async create(env, input) {
+      const repo = await readRepository(git, env.cwd);
+
+      if (repo === null)
+        throw new SdkError(
+          "unavailable",
+          `${env.cwd} is not in a git repository, so it cannot have a worktree.`,
+        );
+      const head = await commitAt(repo.root, "HEAD");
+
+      if (head === null)
+        throw new SdkError(
+          "unavailable",
+          `${repo.root} has no commits yet, so a worktree has nothing to branch from.`,
+        );
+
+      const slug = worktreeSlug(input.name, input.title);
+      const branch = `nyte/${slug}`;
+      const below = (root: string): WorkspaceTarget => ({
+        kind: "local",
+        path: resolve(root, repo.prefix),
+      });
+
+      const listed = (await listWorktrees(repo.root, options)).find(
+        (worktree) => worktree.branch === branch,
+      );
+
+      if (listed !== undefined)
+        return {
+          target: below(listed.path),
+          branch,
+          base: (await commitAt(repo.root, `refs/heads/${branch}`)) ?? head,
+        };
+
+      const folder = join(folders, basename(repo.root), slug);
+      const branched = await hasBranch(repo.root, branch, options);
+      const base = branched ? ((await commitAt(repo.root, `refs/heads/${branch}`)) ?? head) : head;
+      const tree = await workingTree(repo);
+
+      await mkdir(dirname(folder), { recursive: true });
+      await addWorktree(
+        repo.root,
+        branched ? { path: folder, branch } : { path: folder, branch, from: head },
+        options,
+      );
+
+      if (tree !== (await git(folder, ["rev-parse", "HEAD^{tree}"])).trim()) {
+        await git(folder, ["read-tree", "-m", "-u", "HEAD", tree]);
+        await git(folder, ["reset", "-q"]);
+      }
+
+      return { target: below(await realpath(folder)), branch, base };
+    },
+    async remove(worktree) {
+      const path = "path" in worktree.target ? worktree.target.path : null;
+
+      if (path === null || (await stat(path).catch(() => null)) === null)
+        return { folder: "removed", branch: "kept" };
+      const [root = path, common = ""] = (
+        await git(path, [
+          "rev-parse",
+          "--show-toplevel",
+          "--path-format=absolute",
+          "--git-common-dir",
+        ])
+      ).split("\n");
+
+      const status = await git(root, ["status", "--porcelain", "--ignored", "-z"]);
+
+      if (
+        status
+          .split("\0")
+          .some((entry) => entry !== "" && !(entry.startsWith("!! ") && entry.endsWith("/")))
+      )
+        return { folder: "kept", branch: "kept" };
+      await git(common, ["worktree", "remove", root]);
+
+      if ((await commitAt(common, `refs/heads/${worktree.branch}`)) !== worktree.base)
+        return { folder: "removed", branch: "kept" };
+      await git(common, ["branch", "-D", worktree.branch]);
+
+      return { folder: "removed", branch: "deleted" };
+    },
+  };
+}
+
+async function readRepository(git: Git, cwd: string): Promise<Repository | null> {
+  const out = await git(cwd, [
+    "rev-parse",
+    "--show-toplevel",
+    "--absolute-git-dir",
+    "--show-prefix",
+  ]).catch(() => null);
+  const [root, gitDir, prefix = ""] = out?.split("\n") ?? [];
+
+  return root === undefined || gitDir === undefined || root === ""
+    ? null
+    : { root: resolve(root), gitDir: resolve(gitDir), prefix };
+}
+
+function worktreeSlug(name: string, title: string | null): string {
+  const words = (title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .slice(0, 40)
+    .replace(/^-+|-+$/gu, "");
+  const key = sha256(name).slice(0, 8);
+
+  return words === "" ? key : `${words}-${key}`;
+}

package/src/mcp/config.ts

@@ -0,0 +1,330 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { isJsonObject, McpExposureNameType, McpOAuthConfigType } from "@nyte-ai/schema";
+import { isJson } from "@nyte-ai/schema";
+import type {
+  Json,
+  McpChange,
+  McpExposure,
+  McpOAuthConfig,
+  McpScope,
+  ValidationIssue,
+} from "@nyte-ai/schema";
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import { Value } from "typebox/value";
+
+const ExposureName = McpExposureNameType;
+
+const Entry = Type.Object({
+  type: Type.Optional(Type.Enum(["stdio", "http", "streamable-http", "sse"])),
+  command: Type.Optional(Type.String({ minLength: 1 })),
+  args: Type.Optional(Type.Array(Type.String())),
+  env: Type.Optional(Type.Record(Type.String(), Type.String())),
+  cwd: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String({ minLength: 1 })),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+  oauth: Type.Optional(McpOAuthConfigType),
+  enabled: Type.Optional(Type.Boolean()),
+  timeout: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+  description: Type.Optional(Type.String()),
+  exposure: Type.Optional(ExposureName),
+  toolExposure: Type.Optional(Type.Record(Type.String(), ExposureName)),
+});
+
+const ConfigFile = Type.Object({
+  mcpServers: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+});
+
+const OVERRIDE_KEYS = new Set(["enabled", "exposure", "toolExposure"]);
+
+const EXPOSURE: Readonly<Record<Static<typeof ExposureName>, McpExposure>> = {
+  direct: "model",
+  deferred: "deferred",
+  codemode: "code",
+  "codemode-deferred": "code",
+  hidden: "hidden",
+};
+
+type McpTransportConfig =
+  | {
+      readonly kind: "stdio";
+      readonly command: string;
+      readonly args: readonly string[];
+      readonly env: Readonly<Record<string, string>>;
+      readonly cwd: string | null;
+    }
+  | {
+      readonly kind: "http";
+      readonly url: string;
+      readonly headers: Readonly<Record<string, string>>;
+      readonly oauth: McpOAuthConfig;
+    };
+
+export type McpServerEntry = {
+  readonly name: string;
+  readonly scope: McpScope;
+  readonly path: string;
+  readonly override: string | null;
+  readonly transport: McpTransportConfig;
+  readonly enabled: boolean;
+  readonly timeoutMs: number;
+  readonly description: string | null;
+  readonly exposure: McpExposure;
+  /** Patterns in file order; `*` matches any characters. */
+  readonly toolExposure: readonly (readonly [pattern: string, exposure: McpExposure])[];
+};
+
+export type McpFileContents =
+  | { readonly kind: "missing" }
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "unreadable"; readonly message: string };
+
+export type McpFile = {
+  readonly path: string;
+  readonly scope: McpScope;
+  readonly contents: McpFileContents;
+};
+
+export type McpConfig = {
+  readonly servers: ReadonlyMap<string, McpServerEntry>;
+  readonly issues: readonly ValidationIssue[];
+};
+
+/** Reads one `mcp.json`; a file that cannot be read is `unreadable`, not missing. */
+export async function readMcpFile(path: string): Promise<McpFileContents> {
+  try {
+    return { kind: "text", text: await readFile(path, "utf8") };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return { kind: "missing" };
+
+    return { kind: "unreadable", message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Merges the user file and then the project file into one server list. A
+ * project entry replaces the user entry of the same name; one with only
+ * `enabled`, `exposure` or `toolExposure` overrides those fields instead.
+ * An invalid entry becomes an issue and is left out.
+ */
+export function parseMcpConfig(files: readonly McpFile[]): McpConfig {
+  const servers = new Map<string, McpServerEntry>();
+  const canonical = new Map<string, string>();
+  const issues: ValidationIssue[] = [];
+
+  for (const file of files) {
+    if (file.contents.kind === "missing") continue;
+
+    const fail = (path: readonly string[], message: string): void => {
+      issues.push({
+        severity: "error",
+        path: ["mcpServers", ...path],
+        message,
+        source: { plugin: "mcp", file: file.path },
+      });
+    };
+
+    if (file.contents.kind === "unreadable") {
+      fail([], `The file cannot be read: ${file.contents.message}`);
+
+      continue;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(file.contents.text);
+    } catch (error) {
+      fail([], `The file is not valid JSON: ${error instanceof Error ? error.message : ""}`);
+
+      continue;
+    }
+
+    if (!Value.Check(ConfigFile, parsed)) {
+      fail([], 'The file must be an object with an "mcpServers" object.');
+
+      continue;
+    }
+
+    for (const [name, raw] of Object.entries(parsed.mcpServers ?? {})) {
+      if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+        fail([name], `Server names may contain only letters, digits, "_" and "-": ${name}.`);
+
+        continue;
+      }
+
+      const key = name.replaceAll("-", "_");
+      const taken = canonical.get(key);
+
+      if (taken !== undefined && taken !== name) {
+        fail([name], `${name} and ${taken} name the same server.`);
+
+        continue;
+      }
+
+      if (!Value.Check(Entry, raw)) {
+        const [first] = Value.Errors(Entry, raw);
+        fail([name], `${name}${first?.instancePath ?? ""} ${first?.message ?? "is invalid"}.`);
+
+        continue;
+      }
+
+      const base = servers.get(name);
+
+      if (raw.command === undefined && raw.url === undefined && raw.type === undefined) {
+        const extra = Object.keys(raw).filter((field) => !OVERRIDE_KEYS.has(field));
+
+        if (file.scope !== "project" || base === undefined)
+          fail([name], `${name} needs "command" or "url".`);
+        else if (extra.length > 0)
+          fail([name], `An override of ${name} can only set enabled, exposure and toolExposure.`);
+        else servers.set(name, { ...base, ...settings(raw, base), override: file.path });
+
+        continue;
+      }
+
+      const transport = readTransport(raw);
+
+      if (typeof transport === "string") {
+        fail([name], `${name}: ${transport}`);
+
+        continue;
+      }
+
+      canonical.set(key, name);
+      servers.set(name, {
+        name,
+        scope: file.scope,
+        path: file.path,
+        override: null,
+        transport,
+        timeoutMs: (raw.timeout ?? 60) * 1000,
+        description: raw.description ?? null,
+        ...settings(raw, null),
+      });
+    }
+  }
+
+  return { servers, issues };
+}
+
+function readTransport(raw: Static<typeof Entry>): McpTransportConfig | string {
+  if (raw.type === "sse")
+    return 'the SSE transport is not supported; use the server\'s streamable HTTP url, often ending in "/mcp".';
+
+  if (raw.command !== undefined && raw.url !== undefined)
+    return 'set "command" or "url", not both.';
+
+  if (raw.command !== undefined && raw.type !== undefined && raw.type !== "stdio")
+    return `type ${raw.type} needs "url", not "command".`;
+
+  if (raw.command !== undefined)
+    return {
+      kind: "stdio",
+      command: raw.command,
+      args: raw.args ?? [],
+      env: raw.env ?? {},
+      cwd: raw.cwd ?? null,
+    };
+
+  if (raw.url === undefined) return `type ${raw.type ?? "stdio"} needs "command" or "url".`;
+
+  if (raw.type === "stdio") return 'type stdio needs "command", not "url".';
+
+  const url = URL.parse(raw.url);
+
+  if (url === null || (url.protocol !== "https:" && url.protocol !== "http:"))
+    return `${raw.url} is not an http or https URL.`;
+
+  if (raw.command === undefined && raw.oauth?.callbackUrl !== undefined) {
+    const callback = URL.parse(raw.oauth.callbackUrl);
+
+    if (
+      callback === null ||
+      callback.protocol !== "http:" ||
+      !["localhost", "127.0.0.1", "[::1]"].includes(callback.hostname)
+    )
+      return "oauth.callbackUrl must be an http URL on localhost, 127.0.0.1 or [::1].";
+  }
+
+  if (raw.oauth?.authServerMetadataUrl !== undefined) {
+    const metadata = URL.parse(raw.oauth.authServerMetadataUrl);
+
+    if (
+      metadata === null ||
+      (metadata.protocol !== "https:" &&
+        !["localhost", "127.0.0.1", "[::1]"].includes(metadata.hostname))
+    )
+      return "oauth.authServerMetadataUrl must use https, except on localhost.";
+  }
+
+  return { kind: "http", url: raw.url, headers: raw.headers ?? {}, oauth: raw.oauth ?? {} };
+}
+
+function settings(
+  raw: Static<typeof Entry>,
+  base: McpServerEntry | null,
+): Pick<McpServerEntry, "enabled" | "exposure" | "toolExposure"> {
+  return {
+    enabled: raw.enabled ?? base?.enabled ?? true,
+    exposure: raw.exposure === undefined ? (base?.exposure ?? "code") : EXPOSURE[raw.exposure],
+    toolExposure:
+      raw.toolExposure === undefined
+        ? (base?.toolExposure ?? [])
+        : Object.entries(raw.toolExposure).map(([pattern, name]) => [pattern, EXPOSURE[name]]),
+  };
+}
+
+/**
+ * Plans a change to the `mcpServers` of one `mcp.json`, keeping the rest of
+ * the file: `change` returns the new servers, or `null` when it has nothing
+ * to change. A missing file starts empty; one that is not a JSON object is
+ * refused. Nothing is written; pass the text to {@link writeMcpFile}.
+ */
+export async function planMcpEdit(
+  path: string,
+  change: (servers: { readonly [name: string]: Json }) => { readonly [name: string]: Json } | null,
+): Promise<
+  { readonly kind: "planned"; readonly text: string } | Exclude<McpChange, { kind: "updated" }>
+> {
+  const contents = await readMcpFile(path);
+
+  if (contents.kind === "unreadable")
+    return { kind: "invalid", message: `${path} cannot be read: ${contents.message}` };
+  let parsed: unknown = {};
+
+  if (contents.kind === "text") {
+    try {
+      parsed = JSON.parse(contents.text);
+    } catch {
+      return { kind: "invalid", message: `${path} is not valid JSON; fix it first.` };
+    }
+  }
+
+  if (!isJson(parsed) || !isJsonObject(parsed))
+    return { kind: "invalid", message: `${path} is not a JSON object.` };
+  const servers = parsed.mcpServers ?? {};
+
+  if (!isJsonObject(servers))
+    return { kind: "invalid", message: `${path} has an "mcpServers" that is not an object.` };
+  const next = change(servers);
+
+  if (next === null) return { kind: "missing" };
+
+  return { kind: "planned", text: `${JSON.stringify({ ...parsed, mcpServers: next }, null, 2)}\n` };
+}
+
+/**
+ * Replaces one `mcp.json` whole, readable only by the user as it may hold
+ * secrets. A symlinked file is written through the link.
+ */
+export async function writeMcpFile(path: string, text: string): Promise<void> {
+  const target = await realpath(path).catch(() => path);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(temporary, text, { mode: 0o600 });
+  await rename(temporary, target);
+}

package/src/mcp/connect.ts

@@ -0,0 +1,92 @@
+import { isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { StdioTransport, StreamableHttpTransport } from "@earendil-works/pi-mcp";
+import type { McpTransport } from "@earendil-works/pi-mcp";
+import type { OAuthChallenge } from "@earendil-works/pi-mcp/oauth";
+import type { PluginStorage } from "@nyte-ai/core";
+import type { McpWorkspace } from "@nyte-ai/core/server";
+import type { McpOAuthConfig } from "@nyte-ai/schema";
+import type { McpServerEntry } from "./config.ts";
+import { createAuthProvider, oauthKey, oauthStore } from "./oauth.ts";
+import type { McpOAuthSettings } from "./oauth.ts";
+
+export type McpConnector = (
+  entry: McpServerEntry,
+  context: {
+    readonly workspace: McpWorkspace;
+    readonly home: string;
+    readonly secrets: PluginStorage["secrets"];
+    readonly challenged: (challenge: OAuthChallenge) => void;
+  },
+) => McpTransport;
+
+export const connectServer: McpConnector = (entry, context) => {
+  const { transport } = entry;
+
+  if (transport.kind === "stdio") {
+    const base = context.workspace.root ?? context.home;
+    const cwd = transport.cwd === null ? base : home(transport.cwd, context.home);
+
+    return new StdioTransport({
+      command: home(transport.command, context.home),
+      args: transport.args.map((arg) => home(arg, context.home)),
+      env: expand(transport.env, entry.name),
+      cwd: isAbsolute(cwd) ? cwd : resolve(base, cwd),
+      stderr: "pipe",
+    });
+  }
+
+  const headers = expand(transport.headers, entry.name);
+
+  if (Object.keys(headers).some((name) => name.toLowerCase() === "authorization"))
+    return new StreamableHttpTransport({ url: transport.url, headers });
+
+  return new StreamableHttpTransport({
+    url: transport.url,
+    headers,
+    authProvider: createAuthProvider({
+      serverUrl: transport.url,
+      store: oauthStore(context.secrets, oauthKey(entry.name, transport.url)),
+      settings: () => oauthSettings(transport.oauth, entry.name),
+      onChallenge: context.challenged,
+    }),
+  });
+};
+
+export function oauthSettings(config: McpOAuthConfig, server: string): McpOAuthSettings {
+  const { clientSecret, authServerMetadataUrl, ...rest } = config;
+
+  return {
+    ...rest,
+    ...(clientSecret === undefined
+      ? {}
+      : { clientSecret: expand({ clientSecret }, server).clientSecret }),
+    ...(authServerMetadataUrl === undefined
+      ? {}
+      : { authServerMetadataUrl: new URL(authServerMetadataUrl) }),
+  };
+}
+
+function home(path: string, directory: string): string {
+  if (path === "~") return directory;
+
+  return path.startsWith("~/") ? join(directory, path.slice(2)) : path;
+}
+
+function expand(values: Readonly<Record<string, string>>, server: string): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [
+      key,
+      value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name: string) => {
+        const found = process.env[name];
+
+        if (found === undefined)
+          throw new Error(
+            `${server} needs the environment variable ${name}. Set it where Nyte runs, then restart Nyte.`,
+          );
+
+        return found;
+      }),
+    ]),
+  );
+}