Skip to content

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

12.9 KB
Raw Blame
/**
 * Connecting a workspace, offered by the agent: once a person has a learning,
 * `trail ask`, `trail note` and `trail check` hand the agent a link to end its
 * reply with, at most once a session and in wording that changes from one
 * session to the next. A background wait registers the link with Trail, picks
 * up the sign-in, uploads the picked repos' learnings, and the next command
 * says so once. Connected, a repo outside the workspace gets one question.
 * All of it is off unless TRAIL_CLOUD=1, or the machine is already connected.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { BRAND_ENV } from "../src/brand.js";
import { rememberRepo } from "../src/notes/home.js";
import { writeNote } from "../src/notes/notes.js";
import { cloudLines, loginLink, NUDGE_WORDS, waitForConnect } from "../src/cloud/nudge.js";
import { readCloud, writeCloud, type Cloud } from "../src/cloud/workspace.js";
import { tmpRepo } from "./helpers.js";

process.env.DO_NOT_TRACK = "1";
process.env[BRAND_ENV] = "trail";
// The test-only stand-in address: real sign-ins only go where `trail login --server` says, or to Trail cloud.
process.env.TRAIL_TEST_SERVER = "http://trail.test";
process.env.TRAIL_NO_FETCH = "1";
process.env.TRAIL_CLOUD = "1";

/** A fresh ~/.trail for each test, so links, sessions and connections never leak between them. */
function freshHome(): NodeJS.ProcessEnv {
  process.env.TRAIL_HOME = mkdtempSync(join(tmpdir(), "nudge-trail-home-"));
  return process.env;
}

function git(d: string, args: string[]) {
  spawnSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: d });
}

let n = 0;
/** A GitHub-backed repo, with a learning in its .trail/ unless `learnings` is false. */
function repo(learnings = true): { dir: string; key: string } {
  const dir = tmpRepo("nudge");
  const name = `acme/extract-${++n}`;
  git(dir, ["init", "-q", "-b", "main"]);
  git(dir, ["config", "user.name", "Priya Raman"]);
  git(dir, ["remote", "add", "origin", `https://github.com/${name}.git`]);
  if (learnings) writeNote(dir, { title: "Retries trip the rate limit", body: "## Decided\nThree retries.", author: "Priya", date: "2026-10-07", touches: [] });
  else rememberRepo(dir);
  return { dir, key: `github.com/${name}` };
}

const noWait = () => {};

function lines(d: string, command: "ask" | "note" | "check", session: string, opts: { agent?: boolean; now?: number } = {}) {
  return cloudLines(d, { command, agent: opts.agent ?? true, env: { ...process.env, CLAUDE_CODE_SESSION_ID: session }, now: opts.now, startWait: noWait });
}

function stateOf(): { pending?: { state: string } } {
  return JSON.parse(readFileSync(join(process.env.TRAIL_HOME!, "cloud-nudge.json"), "utf8"));
}

test("with signing in off, nobody is offered a link, learnings or not", () => {
  freshHome();
  const { dir } = repo();
  const off = cloudLines(dir, { command: "ask", agent: true, env: { ...process.env, TRAIL_CLOUD: undefined, CLAUDE_CODE_SESSION_ID: "s1" }, startWait: noWait });
  assert.deepEqual(off, []);
});

test("no learning yet: nobody is asked to sign in", () => {
  freshHome();
  assert.deepEqual(lines(repo(false).dir, "ask", "s1"), []);
});

test("a repo with no remote is never offered a workspace", () => {
  freshHome();
  const d = tmpRepo("nudge-local");
  git(d, ["init", "-q"]);
  writeNote(d, { title: "x", body: "## Decided\ny", author: "Priya", date: "2026-10-07" });
  assert.deepEqual(lines(d, "ask", "s1"), []);
});

test("once a session, a connect link the agent ends its reply with, in wording that changes per session", () => {
  freshHome();
  const { dir } = repo();
  const first = lines(dir, "ask", "s1");
  assert.match(first[0]!, /^\[trail\] End your reply with this line, word for word: \[Share your learnings with your team\?\]\(http:\/\/trail\.test\/connect\?state=[\w-]{32}\)$/);
  assert.match(first[1]!, /don't run trail login yourself/);
  assert.deepEqual(lines(dir, "note", "s1"), [], "not twice in one session");
  const second = lines(dir, "check", "s2");
  assert.ok(second[0]!.includes(NUDGE_WORDS[1]), "the next session reads differently");
  assert.ok(second[0]!.includes(stateOf().pending!.state), "the same link, while it's good");
});

test("at a terminal it's one plain line", () => {
  freshHome();
  const { dir } = repo();
  const out = lines(dir, "ask", "s1", { agent: false });
  assert.equal(out.length, 1);
  assert.match(out[0]!, /^· Share your learnings with your team\? http:\/\/trail\.test\/connect\?state=/);
});

/** A Trail that answers the handoff routes from memory, and records what it was sent. */
function fakeTrail(opts: { finishAfter?: number; expire?: boolean } = {}) {
  const sent: Array<{ path: string; origin: string; body: any; auth?: string }> = [];
  let claims = 0;
  const fetchImpl = (async (url: string, init: RequestInit) => {
    const { pathname: path, origin } = new URL(url);
    const body = init.body ? JSON.parse(String(init.body)) : undefined;
    sent.push({ path, origin, body, auth: (init.headers as Record<string, string>)?.authorization });
    const json = (status: number, b: unknown) => new Response(JSON.stringify(b), { status, headers: { "content-type": "application/json" } });
    if (path === "/api/cli/handoffs") return json(201, { url: `http://trail.test/connect?state=${body.state}` });
    if (path === "/api/cli/handoffs/claim") {
      if (opts.expire) return json(410, { error: "expired" });
      if (++claims < (opts.finishAfter ?? 1)) return json(202, { pending: true });
      return json(200, {
        token: "trl_test",
        user: { name: "Priya", email: "[email protected]" },
        workspace: { id: "w1", name: "Acme", slug: "acme", url: "http://trail.test/w/acme", invite_url: "http://trail.test/join/abc" },
        repos: sent.find((s) => s.path === "/api/cli/handoffs")!.body.repo ? [sent.find((s) => s.path === "/api/cli/handoffs")!.body.repo.key] : [],
      });
    }
    if (path === "/api/cli/learnings") return json(200, { repo: body.repo.key, learnings: body.learnings.length, added: body.learnings.length });
    if (path === "/api/cli/activity") return json(200, { stored: body.events.length });
    return json(404, { error: "no route" });
  }) as typeof fetch;
  return { fetchImpl, sent };
}

test("the background wait registers the link with only the repo it was offered in, then connects and uploads that repo's learnings", async () => {
  freshHome();
  const { dir, key } = repo();
  // Only what git has goes up: the learning is committed, as it would be to share it.
  git(dir, ["add", "-A"]);
  git(dir, ["-c", "[email protected]", "commit", "-qm", "learning"]);
  const other = repo(false);
  lines(dir, "ask", "s1");
  const trail = fakeTrail({ finishAfter: 2 });
  const got = await waitForConnect({ fetchImpl: trail.fetchImpl, sleep: async () => {} });
  assert.ok(got && "cloud" in got);

  const reg = trail.sent.find((s) => s.path === "/api/cli/handoffs")!.body;
  assert.equal(reg.state, stateOf().pending?.state ?? reg.state);
  assert.deepEqual(reg.repo, { key, name: key.replace("github.com/", "") });
  // Before anyone opens the link: no list of this machine's other repos, and no name.
  assert.deepEqual(reg.repos, [{ key, name: key.replace("github.com/", ""), learnings: 1 }]);
  assert.ok(!JSON.stringify(reg).includes(other.key.replace("github.com/", "")), "another repo on this machine");
  assert.ok(!JSON.stringify(reg).includes("Priya"), "the person's name");

  const cloud = readCloud()!;
  assert.equal(cloud.token, "trl_test");
  assert.equal(cloud.workspace.name, "Acme");
  assert.deepEqual(cloud.repos, [key]);
  const up = trail.sent.find((s) => s.path === "/api/cli/learnings")!;
  assert.equal(up.auth, "Bearer trl_test");
  assert.equal(up.body.repo.key, key);
  assert.equal(up.body.learnings.length, 1);
  assert.match(up.body.learnings[0].path, /^\.trail\/learnings\/2026-10-07-retries-trip-the-rate-limit-priya\.md$/);
  assert.equal(up.body.learnings[0].ref, "");

  // The next command says so, once, and asks the agent to tell the person.
  const told = lines(dir, "ask", "s2");
  assert.equal(told[0], "✓ connected to workspace Acme");
  assert.match(told[1]!, /^✓ shared 1 learning from 1 repo · http:\/\/trail\.test\/w\/acme$/);
  assert.match(told[2]!, /Tell the user once/);
  assert.deepEqual(lines(dir, "ask", "s3"), [], "only once");
});

test("connecting sends nothing queued before it, whatever its timestamp", async () => {
  freshHome();
  const { dir, key } = repo();
  lines(dir, "ask", "s1");
  // What an older trail left: a search from before anyone signed in, in this repo and another.
  const at = new Date(Date.now() + 60_000).toISOString();
  const old = (repo: string) => JSON.stringify({ repo, kind: "search", asker: "Priya", session: "s0", query: "rate limit", files: ["a.go"], shown_paths: ["x.md"], shown_authors: ["Priya"], at });
  const outbox = join(process.env.TRAIL_HOME!, "outbox.jsonl");
  writeFileSync(outbox, `${old(key)}\n${old("github.com/acme/private")}\n`);
  const trail = fakeTrail();
  const got = await waitForConnect({ fetchImpl: trail.fetchImpl, sleep: async () => {} });
  assert.ok(got && "cloud" in got);
  assert.equal(trail.sent.filter((s) => s.path === "/api/cli/activity").length, 0, "no activity sent");
  assert.equal(existsSync(outbox), false, "and none kept to send later");
  rmSync(join(process.env.TRAIL_HOME!, "cloud.json"));
});

test("a spent link stops the wait and is forgotten, so the next session mints a new one", async () => {
  freshHome();
  const { dir } = repo();
  lines(dir, "ask", "s1");
  const before = stateOf().pending!.state;
  const got = await waitForConnect({ fetchImpl: fakeTrail({ expire: true }).fetchImpl, sleep: async () => {} });
  assert.ok(got && "error" in got && got.reason === "expired");
  assert.equal(readCloud(), null);
  const next = lines(dir, "ask", "s2");
  assert.ok(next.length > 0);
  assert.ok(!next[0]!.includes(before), "a new link");
});

test("trail login --server: the link, its sign-in and every later upload go to that Trail, with nothing in the environment", async () => {
  freshHome();
  const { dir } = repo();
  git(dir, ["add", "-A"]);
  git(dir, ["-c", "[email protected]", "commit", "-qm", "learning"]);
  const server = "https://trail.acme.example.com";
  const env = { ...process.env, TRAIL_TEST_SERVER: undefined };
  const url = loginLink(dir, env, Date.now(), server);
  assert.match(url, /^https:\/\/trail\.acme\.example\.com\/connect\?state=[\w-]{32}$/);
  // An agent's later link in the same repo is the same one, for the same Trail.
  const offered = lines(dir, "ask", "s1");
  assert.ok(offered[0]!.includes(url), "the nudge offers the link login made");

  const trail = fakeTrail();
  const got = await waitForConnect({ env, fetchImpl: trail.fetchImpl, sleep: async () => {} });
  assert.ok(got && "cloud" in got);
  assert.deepEqual([...new Set(trail.sent.map((s) => s.origin))], [server], "every call, sign-in and upload");
  assert.equal(readCloud()!.url, server, "and the connection keeps it");
  rmSync(join(process.env.TRAIL_HOME!, "cloud.json"));
});

test("a login link for another Trail is a new link: a state registered with one Trail is never sent to another", () => {
  freshHome();
  const { dir } = repo();
  const env = { ...process.env, TRAIL_TEST_SERVER: undefined };
  const first = loginLink(dir, env);
  assert.match(first, /^https:\/\/team\.trailhq\.com\/connect\?state=/);
  const second = loginLink(dir, env, Date.now(), "https://trail.acme.example.com");
  assert.match(second, /^https:\/\/trail\.acme\.example\.com\/connect\?state=/);
  assert.notEqual(new URL(first).searchParams.get("state"), new URL(second).searchParams.get("state"));
  assert.equal(loginLink(dir, env, Date.now(), "https://trail.acme.example.com"), second, "the same Trail again: the same link");
});

function connect(repos: string[]): void {
  const c: Cloud = {
    url: "http://trail.test",
    token: "trl_test",
    user: { name: "Priya", email: "[email protected]" },
    workspace: { id: "w1", name: "Acme", slug: "acme", url: "http://trail.test/w/acme", invite_url: "http://trail.test/join/abc" },
    repos,
    linkedAt: Date.now(),
  };
  writeCloud(c);
}

test("connected: a repo with learnings outside the workspace gets one question, ever", () => {
  freshHome();
  const inside = repo();
  const outside = repo();
  connect([inside.key]);
  assert.deepEqual(lines(inside.dir, "ask", "s1"), [], "nothing to say about a repo already in it");
  const asked = lines(outside.dir, "ask", "s1");
  assert.equal(asked.length, 1);
  assert.match(asked[0]!, /^\[trail\] Ask the user once, at the end of your reply: add acme\/extract-\d+ to their Trail workspace Acme/);
  assert.match(asked[0]!, /run `trail workspace add`/);
  assert.deepEqual(lines(outside.dir, "ask", "s2"), [], "never again");
  rmSync(join(process.env.TRAIL_HOME!, "cloud.json"));
});