Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

15.4 KB
Raw Blame
/**
 * The Trail workspace this machine is connected to, and the calls that talk
 * to it (trail-cloud's `/api/cli/…`).
 *
 * One connection per machine, not per repo: a person signs in once, through
 * the link their agent offers, and picks which of their repos the workspace
 * gets. It lives in `~/.trail/cloud.json` next to their notes, never in a
 * repo. Learnings themselves travel through git (`.trail/` is committed);
 * the workspace adds what one clone can't see: who is learning what across
 * the team's repos, how often a learning is reused, and the team page.
 *
 * Every call is bounded and never throws: a failure comes back as
 * `{ error }`, so a command still answers when Trail is unreachable.
 */
import { existsSync, rmSync } from "node:fs";
import { join } from "node:path";
import { trailHome } from "../notes/home.js";
import { ensurePrivateDir, PRIVATE_FILE_MODE } from "../util/private-file.js";
import { readJson, writeJsonAtomic } from "../util/state.js";

/** Trail's own front end and API: Trail cloud, which serves the CLI routes at team.trailhq.com. */
export const DEFAULT_TRAIL_URL = "https://team.trailhq.com";

/**
 * TEST ONLY. Points sign-in at a stand-in Trail, for tests and local demos.
 * Taken only for a host on this machine (localhost, 127.0.0.1, [::1]) or a
 * `.test` one, which nothing on the internet answers, so an export left in a
 * shell can't send a sign-in, and the learnings uploaded after it, anywhere
 * else. Never documented for users: a self-hosted Trail is `trail login
 * --server <url>`, which the link itself carries.
 */
export const TEST_SERVER_ENV = "TRAIL_TEST_SERVER";

/** `url` as a server address (http or https, no trailing slash), or null when it isn't one. */
export function serverUrl(url: string | undefined): string | null {
  const t = url?.trim().replace(/\/+$/, "");
  if (!t || !/^https?:\/\//i.test(t)) return null;
  try {
    new URL(t);
    return t;
  } catch {
    return null;
  }
}

function testServer(env: NodeJS.ProcessEnv): string | null {
  const url = serverUrl(env[TEST_SERVER_ENV]);
  if (!url) return null;
  const host = new URL(url).hostname.toLowerCase();
  const local = host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost") || host.endsWith(".test");
  return local ? url : null;
}

/** The Trail `init --connect` or `--pair` was told with `--server`, for the rest of this process. */
let runServer: string | null = null;

/**
 * Where a sign-in goes when nothing chose otherwise: Trail cloud. The
 * connection then keeps the address it signed in at in cloud.json, and every
 * later call goes there. No variable a shell might still export moves it
 * (TRAIL_URL, or GRAFT_BRAIN_URL for the old brain API): a self-hosted Trail
 * comes from `trail login --server`, saved on the link, or from `--server`
 * on `init --connect` and `--pair` for that run (`useServer`); tests use
 * TEST_SERVER_ENV.
 */
export function trailUrl(env: NodeJS.ProcessEnv = process.env): string {
  return runServer ?? testServer(env) ?? DEFAULT_TRAIL_URL;
}

/**
 * `--server <url>` on `init --connect` and `--pair` (and the `_trail-pair`
 * child they start): the Trail that gave the code, for every call this
 * process makes. Set by the command line, never read from the environment;
 * null puts it back to Trail cloud.
 */
export function useServer(url: string | null): void {
  runServer = url;
}

export interface WorkspaceInfo {
  id: string;
  name: string;
  slug: string;
  url: string;
  invite_url: string;
}

export interface Cloud {
  /** The Trail it's connected to. */
  url: string;
  /** `trl_…`: this machine's token for the workspace. */
  token: string;
  user: { name: string; email: string };
  workspace: WorkspaceInfo;
  /** Repo keys in the workspace (`github.com/owner/name`), as of the last look. */
  repos: string[];
  linkedAt: number;
  /**
   * `connect`: connected by `trail init --connect <code>` from the onboarding
   * on the web. Such a machine sends a repo summary (titles, counts, names)
   * and never the full learnings sync, so it's never asked to add repos.
   */
  via?: "connect";
}

function cloudPath(env: NodeJS.ProcessEnv = process.env): string {
  return join(trailHome(env), "cloud.json");
}

/** The connection, or null when this machine hasn't connected a workspace. */
export function readCloud(env: NodeJS.ProcessEnv = process.env): Cloud | null {
  const c = readJson<Cloud>(cloudPath(env));
  return c?.token && c.workspace?.slug ? c : null;
}

/**
 * Whether the workspace side of trail is on: the sign-in link at the end of a
 * reply, and `login`, `logout` and `workspace`. Committing `.trail/` already
 * shares learnings with a team, so it stays off until signing in gives more
 * than that. TRAIL_CLOUD=1 turns it on; a machine already connected keeps it.
 */
export function cloudEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
  return env.TRAIL_CLOUD === "1" || readCloud(env) !== null;
}

/** Owner-only: the file holds the workspace token. */
export const SECRET_FILE_MODE = PRIVATE_FILE_MODE;

/** Owner-only, in an owner-only folder: the file holds the workspace token. */
export function writeCloud(c: Cloud, env: NodeJS.ProcessEnv = process.env): void {
  ensurePrivateDir(trailHome(env));
  writeJsonAtomic(cloudPath(env), c, false, SECRET_FILE_MODE);
}

export function clearCloud(env: NodeJS.ProcessEnv = process.env): boolean {
  const p = cloudPath(env);
  if (!existsSync(p)) return false;
  rmSync(p, { force: true });
  return true;
}

/* -------------------------------------------------------------------------- */
/* calls                                                                      */
/* -------------------------------------------------------------------------- */

type Fetch = typeof fetch;

export interface ApiError {
  error: string;
  /** HTTP status, when Trail answered at all. */
  status?: number;
}

export function isError(x: unknown): x is ApiError {
  return typeof x === "object" && x !== null && typeof (x as ApiError).error === "string";
}

async function call<T>(
  base: string,
  method: "GET" | "POST" | "PUT",
  path: string,
  body: unknown,
  opts: { token?: string; timeoutMs?: number; fetchImpl?: Fetch } = {},
): Promise<{ status: number; body: T } | ApiError> {
  const f = opts.fetchImpl ?? fetch;
  try {
    const headers: Record<string, string> = { "content-type": "application/json", accept: "application/json" };
    if (opts.token) headers.authorization = `Bearer ${opts.token}`;
    const res = await f(`${base}${path}`, {
      method,
      headers,
      body: method === "GET" ? undefined : JSON.stringify(body),
      signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
    });
    const text = await res.text();
    let json: unknown = null;
    try {
      json = text ? JSON.parse(text) : null;
    } catch {
      /* not JSON */
    }
    if (!res.ok) {
      const msg = (json as { error?: unknown } | null)?.error;
      return { error: typeof msg === "string" ? msg : `Trail answered ${res.status}`, status: res.status };
    }
    return { status: res.status, body: json as T };
  } catch (err) {
    const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
    return { error: timedOut ? "Trail didn't answer in time" : "couldn't reach Trail" };
  }
}

async function authed<T>(c: Cloud, method: "GET" | "POST" | "PUT", path: string, body: unknown, opts: { timeoutMs?: number; fetchImpl?: Fetch } = {}): Promise<T | ApiError> {
  const r = await call<T>(c.url, method, path, body, { ...opts, token: c.token });
  return isError(r) ? r : r.body;
}

/* sign-in handoff ----------------------------------------------------------- */

export interface HandoffRepo {
  key: string;
  name: string;
  learnings: number;
}

/**
 * Tell Trail about a sign-in link before anyone opens it: the repo the agent
 * was in, which is what the workspace's repo picker lists. Its name and
 * learning count only; no learning, no other repo and no person's name travels.
 */
export async function registerHandoff(
  base: string,
  req: { state: string; repo: { key: string; name: string } | null; repos: HandoffRepo[]; author: string; pair?: string },
  fetchImpl?: Fetch,
): Promise<{ url: string } | ApiError> {
  const r = await call<{ url: string }>(base, "POST", "/api/cli/handoffs", req, { fetchImpl });
  return isError(r) ? r : r.body;
}

/**
 * Report how a `trail init --pair` run is going, for the onboarding page that
 * shows it live. "reviewed" once the person has kept or dropped what it found
 * (Trail takes no more), "gone" when the link expired or Trail doesn't know it.
 */
export async function postHandoffProgress(base: string, body: { state: string } & Record<string, unknown>, fetchImpl?: Fetch): Promise<"ok" | "reviewed" | "gone" | "error"> {
  const r = await call(base, "POST", "/api/cli/handoffs/progress", body, { fetchImpl, timeoutMs: 15_000 });
  if (!isError(r)) return "ok";
  if (r.status === 409) return "reviewed";
  if (r.status === 404 || r.status === 410) return "gone";
  return "error";
}

export type ClaimResult =
  | { cloud: Omit<Cloud, "url" | "linkedAt"> }
  | { pending: true }
  | { error: string; reason: "expired" | "unsupported" };

/** Ask once whether the person finished in the browser. A network or server error counts as "not yet". */
export async function claimHandoff(base: string, state: string, fetchImpl?: Fetch): Promise<ClaimResult> {
  const r = await call<{ token?: string; user?: Cloud["user"]; workspace?: WorkspaceInfo; repos?: string[]; pending?: boolean }>(
    base,
    "POST",
    "/api/cli/handoffs/claim",
    { state },
    { fetchImpl, timeoutMs: 10_000 },
  );
  if (isError(r)) {
    if (r.status === 410) return { error: "that sign-in link was already used or has expired", reason: "expired" };
    if (r.status === 404 || r.status === 405) return { error: "this Trail doesn't take sign-ins from the CLI yet", reason: "unsupported" };
    return { pending: true };
  }
  const b = r.body;
  if (r.status === 200 && b?.token && b.workspace?.slug) {
    return { cloud: { token: b.token, user: b.user ?? { name: "", email: "" }, workspace: b.workspace, repos: b.repos ?? [] } };
  }
  return { pending: true };
}

/* the workspace ------------------------------------------------------------- */

export interface WorkspaceRepo {
  key: string;
  name: string;
  learnings: number;
  added_by: string;
}

export interface Me {
  user: Cloud["user"];
  workspace: WorkspaceInfo;
  repos: WorkspaceRepo[];
}

export function fetchMe(c: Cloud, fetchImpl?: Fetch): Promise<Me | ApiError> {
  return authed<Me>(c, "GET", "/api/cli/me", undefined, { fetchImpl });
}

export function addRepo(c: Cloud, repo: { key: string; name: string }, fetchImpl?: Fetch): Promise<{ repos: WorkspaceRepo[] } | ApiError> {
  return authed<{ repos: WorkspaceRepo[] }>(c, "POST", "/api/cli/repos", repo, { fetchImpl });
}

/** The laptop's other repos, by name only, for the onboarding page to offer. */
export function sendMachineRepos(c: Cloud, state: string, repos: { key: string; name: string; last_used?: string; sessions: number }[], fetchImpl?: Fetch): Promise<object | ApiError> {
  return authed<object>(c, "POST", "/api/cli/handoffs/repos", { state, repos }, { fetchImpl });
}

/** Which of them the person picked: null until they choose. */
export function fetchMachinePicks(c: Cloud, state: string, fetchImpl?: Fetch): Promise<{ picks: string[] | null } | ApiError> {
  return authed<{ picks: string[] | null }>(c, "POST", "/api/cli/handoffs/picks", { state }, { fetchImpl });
}

/** How setting up one picked repo is going, for the page. */
export function postRepoSetup(c: Cloud, state: string, key: string, status: "setting_up" | "done" | "failed", learnings = 0, fetchImpl?: Fetch): Promise<object | ApiError> {
  return authed<object>(c, "POST", "/api/cli/handoffs/repos/status", { state, key, status, learnings }, { fetchImpl });
}

export interface UploadedLearning {
  /** `.trail/learnings/<name>`, or `.claude/skills/<name>/SKILL.md` for a skill. */
  path: string;
  /** "skill" for a skill of the repo; a plain learning leaves it out. */
  kind?: "skill";
  /** "" when committed at HEAD, or the pushed branch it was found on (`origin/kumar/x`). */
  ref: string;
  branch?: string;
  title: string;
  author: string;
  date: string;
  minutes?: number;
  tokens?: number;
  touches: string[];
  body: string;
  hash: string;
  /** A skill's description: what it does and when to use it. */
  why?: string;
  /** A skill's other files: everything git tracks in its folder besides SKILL.md. */
  files?: SkillFileUpload[];
}

export interface SkillFileUpload {
  /** Relative to the skill's folder: `references/forms.md`, `scripts/fill.py`. */
  path: string;
  /** The file as text, or base64 when `encoding` says so. */
  content: string;
  encoding?: "base64";
  executable?: boolean;
}

/** Most of one upload request: skills bring their folders, so a big set goes up in parts. */
export const UPLOAD_PART_BYTES = 12 * 1024 * 1024;

export async function uploadLearnings(
  c: Cloud,
  req: { repo: { key: string; name: string }; learnings: UploadedLearning[] },
  fetchImpl?: Fetch,
): Promise<{ repo: string; learnings: number; added: number } | ApiError> {
  const parts: UploadedLearning[][] = [[]];
  let bytes = 0;
  for (const l of req.learnings) {
    const size = JSON.stringify(l).length;
    if (bytes + size > UPLOAD_PART_BYTES && parts.at(-1)!.length) {
      parts.push([]);
      bytes = 0;
    }
    parts.at(-1)!.push(l);
    bytes += size;
  }
  let added = 0;
  let last: { repo: string; learnings: number; added: number } | ApiError | null = null;
  for (const learnings of parts) {
    last = await authed<{ repo: string; learnings: number; added: number }>(c, "PUT", "/api/cli/learnings", { ...req, learnings }, { timeoutMs: 60_000, fetchImpl });
    if (isError(last)) return last;
    added += last.added;
  }
  return { ...last!, added };
}

/**
 * One use of the learnings: a search that showed some, a check against them,
 * or a coding agent using one of the repo's skills. Counts and which
 * learnings, never content: no query (for the prompt hook that is the
 * person's prompt), no file paths and no task.
 */
export interface ActivityEvent {
  repo: string;
  kind: "search" | "check" | "skill";
  /** For a skill use: the skill's folder name under `.claude/skills/`. */
  skill?: string;
  asker: string;
  session: string;
  /** How many files the answer pointed into, or the check covered. */
  file_count: number;
  /** File names of the learnings it showed: the name is what the workspace knows a learning by. */
  shown_paths: string[];
  shown_authors: string[];
  /** Tokens the map saved on this lookup (what `ask` prints as "tokens saved"); absent when unknown. */
  saved_tokens?: number;
  at: string;
}

export function postActivity(c: Cloud, events: ActivityEvent[], fetchImpl?: Fetch): Promise<{ stored: number } | ApiError> {
  return authed(c, "POST", "/api/cli/activity", { events }, { fetchImpl });
}

export interface TeamView {
  workspace: string;
  repo: string;
  days: number;
  people: number;
  sessions: number;
  new_learnings: number;
  reused: number;
  members: Array<{ name: string; topics: string[]; learnings: number; reused: number }>;
  overlaps: Array<{ kind: string; text: string }>;
  url?: string;
}

export function fetchTeam(c: Cloud, opts: { repo?: string; days?: number } = {}, fetchImpl?: Fetch): Promise<TeamView | ApiError> {
  const q = new URLSearchParams({ days: String(opts.days ?? 7) });
  if (opts.repo) q.set("repo", opts.repo);
  return authed<TeamView>(c, "GET", `/api/cli/team?${q.toString()}`, undefined, { fetchImpl });
}