Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Keeps the workspace's copy of a repo's learnings, and its record of how
* they're used, in step with this machine.
*
* What goes up for a repo in the workspace is every learning in its `.trail/`
* that git has: the ones committed at HEAD and the ones on teammates' pushed
* branches, after a `git fetch`. Never an uncommitted edit or an untracked
* file. Not just this person's, so one person is enough to cover a repo.
* Personal learnings in ~/.trail never go up.
*
* Uses (a search that showed learnings, a check against them) are appended to
* `~/.trail/outbox.jsonl` as they happen, and sent with the next sync. That's
* how a teammate's reuse of a learning shows on the team page. A use is counts
* and the names of the learnings shown: never what someone typed, never the
* files they're in. And only names the workspace already has: a learning's
* file name carries the first words of its title, so a personal learning, or
* one git doesn't have yet, is left out. Only while the machine is connected,
* and only for a repo in the workspace: nobody agreed to send even that for a
* repo they didn't pick, or from before they signed in.
*
* Commands never wait on any of this: when something changed, a detached
* `_trail-sync` child does it.
*/
import { createHash } from "node:crypto";
import { execFileSync, spawn } from "node:child_process";
import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
import { basename, join, relative, sep } from "node:path";
import { isUtf8 } from "node:buffer";
import { graftCliPath } from "../claude/paths.js";
import { readBranchCache, refreshBranches } from "../notes/branches.js";
import { knownRepos, repoName, repoPlace, trailHome } from "../notes/home.js";
import { LEARNINGS_DIR, learningFiles, readLearningFile } from "../notes/repo-trail.js";
import { parseNote, type Note } from "../notes/notes.js";
import { liveLearnings } from "../notes/learning-fields.js";
import { secretReason } from "../notes/secrets.js";
import { OWN_SKILLS, skillDirs } from "../skills/skills.js";
import { matter } from "../util/front-matter.js";
import { appendPrivateFile, ensurePrivateDir, PRIVATE_FILE_MODE, writePrivateFile } from "../util/private-file.js";
import { cacheDir, readJson, writeJsonAtomic } from "../util/state.js";
import { headLearnings } from "./head-learnings.js";
import { isError, postActivity, readCloud, uploadLearnings, type ActivityEvent, type ApiError, type Cloud, type SkillFileUpload, type UploadedLearning } from "./workspace.js";
/** A failed sync is retried after this long, not on every command. */
const RETRY_MS = 5 * 60 * 1000;
/** The outbox is trimmed to its newest lines past this size. */
const OUTBOX_MAX_BYTES = 1024 * 1024;
const OUTBOX_KEEP_LINES = 2000;
function sha256(text: string): string {
return createHash("sha256").update(text).digest("hex");
}
/** A learning that stays off the workspace, and why, for `trail workspace` to name. */
export interface LeftOut {
/** Its file name in `.trail/learnings/`. */
name: string;
/** "" when committed at HEAD, else the pushed branch it's on. */
ref: string;
/** What `secretReason` saw: "an API key", "a password in a URL". Never the secret. */
why: string;
}
/** A skill folder name safe to send as a path part. */
const SKILL_FOLDER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
function inside(root: string, p: string): boolean {
return p === root || p.startsWith(root + sep);
}
/** A SKILL.md bigger than this is not a skill, and is never sent. */
const SKILL_MAX_BYTES = 256 * 1024;
/** What Trail keeps of a skill's folder besides SKILL.md (the server's limits too). */
const SKILL_FILES_MAX = 100;
const SKILL_FILE_MAX_BYTES = 1024 * 1024;
const SKILL_FOLDER_MAX_BYTES = 4 * 1024 * 1024;
/** Never part of a skill, though a folder may hold them. */
const NOT_SKILL_FILE = /(^|\/)(node_modules|__pycache__|\.git|\.venv)(\/|$)|(^|\/)\.DS_Store$|\.(map|pyc)$/;
/**
* The files git tracks in a skill's folder besides SKILL.md, as they go up:
* text as is, anything else as base64, the executable bit kept. A file that
* resolves outside the checkout, or is too big, stays behind; so do the
* ones past the folder's limits, smallest paths first.
*/
function skillFolderFiles(root: string, folder: string): SkillFileUpload[] {
let rel: string;
try {
rel = relative(root, realpathSync(folder)).split(sep).join("/");
} catch {
return [];
}
const out: SkillFileUpload[] = [];
let total = 0;
for (const path of [...trackedAmong(root, [rel + "/"])].sort()) {
const inner = path.slice(rel.length + 1);
if (!inner || inner === "SKILL.md" || NOT_SKILL_FILE.test(inner) || out.length === SKILL_FILES_MAX) continue;
try {
const file = join(root, ...path.split("/"));
const st = statSync(file);
if (!st.isFile() || st.size > SKILL_FILE_MAX_BYTES || total + st.size > SKILL_FOLDER_MAX_BYTES) continue;
if (!inside(root, realpathSync(file))) continue;
const bytes = readFileSync(file);
const text = !bytes.includes(0) && isUtf8(bytes);
total += bytes.length;
out.push({
path: inner,
content: text ? bytes.toString("utf8") : bytes.toString("base64"),
...(text ? {} : { encoding: "base64" as const }),
...(st.mode & 0o111 ? { executable: true } : {}),
});
} catch {
/* gone, or can't be read */
}
}
return out;
}
/** `cut-a-release` → `Cut a release`: a skill's folder name as a title. */
function skillTitle(name: string): string {
const words = name.replace(/[-_]+/g, " ").trim();
return words ? words[0]!.toUpperCase() + words.slice(1) : name;
}
/**
* Which of `paths` (relative to `root`) git tracks, by what `git ls-files` says,
* so a gitignored or untracked file is not among them. Empty when `root` isn't a
* git checkout or git fails: no skill goes up then.
*/
function trackedAmong(root: string, paths: string[]): Set<string> {
if (paths.length === 0) return new Set();
try {
const out = execFileSync("git", ["--literal-pathspecs", "ls-files", "-z", "--", ...paths], {
cwd: root,
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
timeout: 15_000,
maxBuffer: 16 * 1024 * 1024,
});
return new Set(out.split("\0").filter(Boolean));
} catch {
return new Set();
}
}
/**
* The repo's skills, as the workspace takes them: each `.claude/skills/<name>/SKILL.md`
* in the working tree that git tracks (an untracked or gitignored one isn't the
* team's, so it stays here; no git, no skills). Same item as the one init sends
* for a skill it just found (the server keeps one per repo and path): the body is
* SKILL.md without its frontmatter, the hash is of the whole file. A symlinked
* skill is read only when it resolves inside the checkout, and goes up when the
* file it resolves to is tracked. A SKILL.md that can't be read or parsed, or is
* over 256 KB, is skipped. Skills kept in ~/.trail are never sent.
*/
function skillItems(checkout: string): UploadedLearning[] {
const dir = skillDirs(checkout).repo;
let root: string;
let names: string[];
try {
root = realpathSync(join(dir, "..", ".."));
names = readdirSync(dir).sort();
} catch {
return [];
}
// Each candidate that passes the cheap checks, with where its file really is.
const candidates: Array<{ name: string; file: string; real: string }> = [];
for (const name of names) {
if (!SKILL_FOLDER.test(name) || OWN_SKILLS.has(name)) continue;
try {
const file = join(dir, name, "SKILL.md");
if (!statSync(join(dir, name)).isDirectory()) continue;
const st = statSync(file);
if (!st.isFile() || st.size > SKILL_MAX_BYTES) continue;
const real = realpathSync(file);
if (!inside(root, realpathSync(join(dir, name))) || !inside(root, real)) continue;
candidates.push({ name, file, real: relative(root, real).split(sep).join("/") });
} catch {
/* no SKILL.md here */
}
}
const tracked = trackedAmong(root, [...new Set(candidates.map((c) => c.real))]);
const out: UploadedLearning[] = [];
for (const { name, file, real } of candidates) {
if (!tracked.has(real)) continue;
try {
const text = readFileSync(file, "utf8");
const parsed = matter(text);
const d = parsed.data as Record<string, unknown>;
const description = typeof d.description === "string" ? d.description.trim().replace(/\s+/g, " ") : "";
const files = skillFolderFiles(root, join(dir, name));
out.push({
path: `.claude/skills/${name}/SKILL.md`,
kind: "skill",
ref: "",
title: skillTitle(typeof d.name === "string" && d.name.trim() ? d.name.trim() : name),
why: description,
author: typeof d.author === "string" ? d.author.trim() : "",
date: "",
touches: [],
body: parsed.content.trim(),
// The whole folder: any file changing sends the skill again.
hash: sha256(JSON.stringify(["folder", text, files.map((f) => [f.path, sha256(f.content), !!f.executable])])),
files,
});
} catch {
/* a SKILL.md that can't be read or parsed */
}
}
return out;
}
/**
* Every live learning in the repo's `.trail/`, as the workspace takes them:
* the ones committed at HEAD, then the ones only a pushed branch has (from
* the branch cache), then the repo's skills that git tracks (`skillItems`).
* Never the working tree's learnings: an uncommitted or untracked learning
* stays on this machine. Paths are repo-relative; nothing about this
* machine is sent. Null when git couldn't read HEAD: then nothing may go up,
* since a set without HEAD's learnings would tell the workspace they're gone.
*
* Live means what recall reads (`liveLearnings`): a retired, held or replaced
* learning stays behind, so the team page never shows one nobody is meant to
* follow. A learning on an unmerged branch replaces nothing yet.
*
* A learning or skill whose text holds a secret (`secretReason`) stays behind, every
* copy of it: what a sync sent is what vouches for a learning's name in a
* use, so its name never goes up either. It is listed in `leftOut`, so
* `trail workspace` can say so instead of it going missing in silence.
*
* `tree`: the working tree's learnings in place of HEAD's, for `init --pair`'s
* review page only, which shows the person what init just wrote before any of
* it is committed. A sync never reads them.
*/
export function workspaceLearnings(checkout: string, opts: { tree?: boolean } = {}): { learnings: UploadedLearning[]; leftOut: LeftOut[] } | null {
const head = opts.tree ? treeLearnings(checkout) : headLearnings(checkout);
if (!head) return null;
const read: Array<Note & { text: string }> = [];
const leftOut: LeftOut[] = [];
const seen = new Set<string>();
const add = (name: string, text: string, ref: string) => {
if (seen.has(name)) return;
const why = secretReason(text);
if (why) {
seen.add(name);
leftOut.push({ name, ref, why });
return;
}
const n = parseNote(text, name);
if (!n) return;
seen.add(name);
read.push({ ...n, scope: "repo", ...(ref ? { ref } : {}), text });
};
for (const l of head) add(l.name, l.text, "");
for (const b of readBranchCache(checkout)?.branches ?? []) for (const l of b.learnings) add(l.name, l.text, b.ref);
const learnings: UploadedLearning[] = liveLearnings(read).map((n) => ({
path: `${LEARNINGS_DIR}/${n.path}`,
ref: n.ref ?? "",
branch: n.branch,
title: n.title,
author: n.author,
date: n.date,
minutes: n.cost?.minutes,
tokens: n.cost?.tokens,
touches: n.touches,
body: n.body,
hash: sha256(n.text),
}));
// A skill whose text holds a secret stays behind too, named like a learning is.
for (const skill of skillItems(checkout)) {
const texts = (skill.files ?? []).filter((f) => !f.encoding).map((f) => f.content);
const why = secretReason([skill.title, skill.why ?? "", skill.body, ...texts].join("\n"));
if (why) leftOut.push({ name: skill.path, ref: "", why });
else learnings.push(skill);
}
return { learnings, leftOut };
}
/** The working tree's `.trail/learnings/` files, as `headLearnings` gives HEAD's. */
function treeLearnings(checkout: string): Array<{ name: string; text: string }> {
const out: Array<{ name: string; text: string }> = [];
for (const name of learningFiles(checkout)) {
const text = readLearningFile(checkout, name);
if (text) out.push({ name, text });
}
return out;
}
/**
* What `init --pair` hands its review page: the working tree's live learnings
* (what the person's agents start from, the ones init just wrote among them),
* teammates' pushed ones and the repo's tracked skills, secrets left out.
*/
export function reviewPayload(checkout: string): UploadedLearning[] {
return workspaceLearnings(checkout, { tree: true })?.learnings ?? [];
}
/** The learnings a sync uploads: `workspaceLearnings` without what it left out. Null when git couldn't read HEAD. */
export function learningsPayload(checkout: string): UploadedLearning[] | null {
return workspaceLearnings(checkout)?.learnings ?? null;
}
function fingerprint(learnings: UploadedLearning[]): string {
return sha256(JSON.stringify(learnings.map((l) => [l.path, l.hash]).sort()));
}
interface SyncState {
fingerprint: string;
at: number;
failedAt?: number;
learnings?: number;
}
function statePath(repo: string): string {
return join(cacheDir(repo), "trail-workspace-sync.json");
}
/**
* Whether the repo at `checkout` is one of the workspace's, so its learnings
* and uses go up. Never on a machine connected by `trail init --connect`: that
* one sends a repo summary only (titles and counts, no learning bodies, no
* searches), whatever repos the workspace lists.
*/
export function inWorkspace(checkout: string, cloud: Cloud | null = readCloud()): boolean {
return !!cloud && cloud.via !== "connect" && cloud.repos.includes(repoPlace(checkout).key);
}
/**
* Upload the repo's learnings now, after fetching teammates' branches. Only for
* a repo in the workspace. Remembers what was sent so an unchanged repo isn't
* sent again. When git can't read HEAD nothing is sent and the sync counts as
* failed, so it's tried again later.
*/
export async function syncRepo(
checkout: string,
cloud: Cloud,
opts: { fetch?: boolean; fetchImpl?: typeof fetch } = {},
): Promise<{ repo: string; learnings: number; added: number } | ApiError> {
const place = repoPlace(checkout);
if (!cloud.repos.includes(place.key)) return { error: "this repo isn't in your workspace" };
if (opts.fetch !== false) refreshBranches(place.checkout);
const learnings = learningsPayload(place.checkout);
const res: Awaited<ReturnType<typeof uploadLearnings>> = learnings
? await uploadLearnings(cloud, { repo: { key: place.key, name: repoName(place.key, place.checkout) }, learnings }, opts.fetchImpl)
: { error: "git couldn't read this repo's learnings at HEAD" };
const prior = readJson<SyncState>(statePath(place.checkout));
if (isError(res)) writeJsonAtomic(statePath(place.checkout), { ...(prior ?? { fingerprint: "", at: 0 }), failedAt: Date.now() }, true);
else if (learnings) {
writeJsonAtomic(statePath(place.checkout), { fingerprint: fingerprint(learnings), at: Date.now(), learnings: res.learnings }, true);
rememberSent(place.key, learnings);
}
return res;
}
/* -------------------------------------------------------------------------- */
/* what the workspace has */
/* -------------------------------------------------------------------------- */
/** Per repo key: the learnings its last upload from this machine carried, by file name, with their authors, and its skills by folder name. */
type SentLearnings = Record<string, { at: number; learnings: Record<string, string>; skills?: string[] }>;
/** What the workspace got of each repo: learnings by file name to author, and skill folder names. */
interface Sent {
learnings: Map<string, Map<string, string>>;
skills: Map<string, Set<string>>;
}
/** `.claude/skills/<name>/SKILL.md` → `<name>`; "" for any other path. */
export function repoSkillName(path: string): string {
return /^\.claude\/skills\/([^/]+)\/SKILL\.md$/.exec(path)?.[1] ?? "";
}
function sentPath(env: NodeJS.ProcessEnv = process.env): string {
return join(trailHome(env), "workspace-sent.json");
}
/**
* Note what the workspace now has of a repo, which is what a use may name.
* Two syncs of different repos at once can lose one's entry: its uses then
* name nothing until its next sync, an undercount, never a leak.
*/
function rememberSent(key: string, learnings: UploadedLearning[]): void {
try {
const all = readJson<SentLearnings>(sentPath()) ?? {};
const skills = learnings.filter((l) => l.kind === "skill").map((l) => repoSkillName(l.path)).filter(Boolean);
all[key] = { at: Date.now(), learnings: Object.fromEntries(learnings.filter((l) => l.kind !== "skill").map((l) => [learningName(l.path), l.author])), skills };
ensurePrivateDir(trailHome());
writeJsonAtomic(sentPath(), all, true, PRIVATE_FILE_MODE);
} catch {
/* uses name nothing until the next sync */
}
}
/** What the workspace got of each repo from this machine. Empty when nothing was sent yet. */
function readSent(): Sent {
const out: Sent = { learnings: new Map(), skills: new Map() };
const all = readJson<SentLearnings>(sentPath());
if (typeof all !== "object" || all === null) return out;
for (const [key, v] of Object.entries(all)) {
const ls = v?.learnings;
if (typeof ls === "object" && ls !== null) out.learnings.set(key, new Map(Object.entries(ls).filter((e): e is [string, string] => typeof e[1] === "string")));
out.skills.set(key, new Set(asStrings(v?.skills)));
}
return out;
}
/**
* The use as it may go up: only the learnings the workspace already got of
* its repo, each with the author that upload gave it. A personal learning,
* an uncommitted or untracked one, or one an older trail queued, is dropped
* from it, name and author both. A skill use goes only for a skill the
* workspace got of that repo; any other is dropped whole.
*/
function onlySent(e: ActivityEvent, sent: Sent): ActivityEvent | null {
if (e.kind === "skill") return e.skill && sent.skills.get(e.repo)?.has(e.skill) ? e : null;
const has = sent.learnings.get(e.repo);
const names = [...new Set(e.shown_paths)].filter((n) => has?.has(n));
const authors = names.map((n) => has!.get(n)!);
return { ...e, shown_paths: names, shown_authors: e.kind === "check" ? [...new Set(authors)] : authors };
}
/** Sync every repo of the workspace that's on this machine. Returns what went up. */
export async function syncWorkspaceRepos(cloud: Cloud, fetchImpl?: typeof fetch): Promise<{ repos: number; learnings: number }> {
let repos = 0;
let learnings = 0;
for (const r of knownRepos()) {
if (!cloud.repos.includes(r.key) || !existsSync(r.path)) continue;
const res = await syncRepo(r.path, cloud, { fetchImpl });
if (isError(res)) continue;
repos++;
learnings += res.learnings;
}
await flushActivity(cloud, fetchImpl);
return { repos, learnings };
}
/* -------------------------------------------------------------------------- */
/* the activity outbox */
/* -------------------------------------------------------------------------- */
function outboxPath(env: NodeJS.ProcessEnv = process.env): string {
return join(trailHome(env), "outbox.jsonl");
}
/** Whether a use may go to `cloud`: the repo is the workspace's, and it happened since connecting. */
function sendable(e: ActivityEvent, cloud: Cloud): boolean {
return cloud.repos.includes(e.repo) && Date.parse(e.at) >= (cloud.linkedAt || 0);
}
/** Whether uses of `repo` are recorded at all: connected by `pair`/login (not `connect`) and the repo is the workspace's. */
export function records(cloud: Cloud | null, repo: string): cloud is Cloud {
return !!cloud && cloud.via !== "connect" && cloud.repos.includes(repo);
}
/** A skill's folder name, as Claude Code names skills. */
const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
const asStrings = (x: unknown): string[] => (Array.isArray(x) ? x.filter((s): s is string => typeof s === "string") : []);
const asText = (x: unknown): string => (typeof x === "string" ? x : "");
/**
* A use as it may be queued or sent, built field by field from what was
* handed in. Anything else is left behind: an older trail queued the query
* (for the prompt hook, the person's whole prompt) and the file paths, and
* neither may reach the outbox or Trail. Null when it isn't a use at all.
*/
export function activityEvent(raw: unknown): ActivityEvent | null {
if (typeof raw !== "object" || raw === null) return null;
const r = raw as Record<string, unknown>;
if (r.kind !== "search" && r.kind !== "check" && r.kind !== "skill") return null;
const skill = r.kind === "skill" ? asText(r.skill) : "";
if (r.kind === "skill" && !SKILL_NAME.test(skill)) return null;
const count = typeof r.file_count === "number" && Number.isFinite(r.file_count) ? Math.max(0, Math.floor(r.file_count)) : asStrings(r.files).length;
return {
repo: asText(r.repo),
kind: r.kind,
...(skill ? { skill } : {}),
asker: asText(r.asker),
session: asText(r.session),
file_count: count,
shown_paths: asStrings(r.shown_paths),
shown_authors: asStrings(r.shown_authors),
...(typeof r.saved_tokens === "number" && Number.isFinite(r.saved_tokens) && r.saved_tokens > 0 ? { saved_tokens: Math.floor(r.saved_tokens) } : {}),
at: asText(r.at),
};
}
/**
* Remember one use of the learnings, to send with the next sync: only while
* this machine is connected, and only for a repo in the workspace. Not
* connected, or another repo, and nothing is written. Never throws.
*/
export function recordActivity(use: ActivityEvent, cloud: Cloud | null = readCloud()): void {
const e = activityEvent(use);
if (!e || !records(cloud, e.repo)) return;
try {
const p = outboxPath();
appendPrivateFile(p, `${JSON.stringify(e)}\n`);
if (statSync(p).size > OUTBOX_MAX_BYTES) {
const lines = readFileSync(p, "utf8").split("\n").filter(Boolean).slice(-OUTBOX_KEEP_LINES);
writePrivateFile(p, `${lines.join("\n")}\n`);
}
} catch {
/* a lost event undercounts reuse by one */
}
}
/**
* Forget every use waiting to go, and what an earlier connection was sent.
* Run when a machine connects, so nothing recorded before that is ever sent,
* and only what this connection uploads vouches for a learning's name.
*/
export function dropActivity(env: NodeJS.ProcessEnv = process.env): void {
try {
rmSync(outboxPath(env), { force: true });
rmSync(sentPath(env), { force: true });
} catch {
/* sent-time filtering in flushActivity drops them anyway */
}
}
function outboxHasEvents(): boolean {
try {
return statSync(outboxPath()).size > 0;
} catch {
return false;
}
}
/**
* Send the outbox. It's moved aside first, so events recorded while the
* request is out land in a fresh file; on failure they're put back. A use
* from before this connection, or for a repo the workspace doesn't have
* (left by an older trail), is dropped, never sent; so is the name of any
* learning the workspace didn't get from this machine's last upload of that
* repo, put back or sent.
*/
export async function flushActivity(cloud: Cloud, fetchImpl?: typeof fetch): Promise<number> {
const p = outboxPath();
if (!outboxHasEvents()) return 0;
const sending = `${p}.${process.pid}.sending`;
try {
renameSync(p, sending);
} catch {
return 0;
}
const has = readSent();
const events: ActivityEvent[] = [];
for (const line of readFileSync(sending, "utf8").split("\n")) {
try {
if (!line.trim()) continue;
const e = activityEvent(JSON.parse(line));
const out = e && sendable(e, cloud) ? onlySent(e, has) : null;
if (out) events.push(out);
} catch {
/* a torn line */
}
}
let sent = 0;
for (let i = 0; i < events.length; i += 500) {
const res = await postActivity(cloud, events.slice(i, i + 500), fetchImpl);
if (isError(res)) {
// Put back what didn't go, ahead of anything recorded since.
const rest = events.slice(i).map((e) => JSON.stringify(e)).join("\n");
appendPrivateFile(p, `${rest}\n`);
break;
}
sent += Math.min(500, events.length - i);
}
// Sent, or put back above: either way this copy is done with.
rmSync(sending, { force: true });
return sent;
}
/* -------------------------------------------------------------------------- */
/* in the background */
/* -------------------------------------------------------------------------- */
/** Whether the repo's learnings changed since they last went up, and a retry is due. Never while git can't read HEAD. */
export function syncIsDue(checkout: string, now = Date.now()): boolean {
const state = readJson<SyncState>(statePath(checkout));
if (state?.failedAt && now - state.failedAt < RETRY_MS) return false;
const learnings = learningsPayload(checkout);
return !!learnings && state?.fingerprint !== fingerprint(learnings);
}
/**
* Sync in a detached child when this machine is connected and either the
* repo (one of the workspace's) has learnings the workspace hasn't seen, or
* there are uses waiting to go. Never waits, never throws.
*/
export function maybeSyncInBackground(dir: string, now = Date.now()): boolean {
try {
const cloud = readCloud();
if (!cloud) {
// Whatever an older trail queued here can never go: connecting drops it.
dropActivity();
return false;
}
const checkout = repoPlace(dir).checkout;
const due = (inWorkspace(checkout, cloud) && syncIsDue(checkout, now)) || outboxHasEvents();
if (!due) return false;
// Marked first, so commands run while the child works don't start another.
const prior = readJson<SyncState>(statePath(checkout));
writeJsonAtomic(statePath(checkout), { ...(prior ?? { fingerprint: "", at: 0 }), failedAt: now }, true);
const child = spawn(process.execPath, [graftCliPath(), "_trail-sync", checkout], { detached: true, stdio: "ignore", windowsHide: true });
child.unref();
return true;
} catch {
return false;
}
}
/** `_trail-sync`: what the background child does. */
export async function runSyncChild(dir: string): Promise<void> {
const cloud = readCloud();
if (!cloud) return;
const checkout = repoPlace(dir).checkout;
if (inWorkspace(checkout, cloud)) await syncRepo(checkout, cloud);
await flushActivity(cloud);
}
/** The name a learning's file goes by, from a path or a `ref:path`. */
export function learningName(path: string): string {
return basename(path.slice(path.lastIndexOf(":") + 1));
}