@jive-sh/skill-sync 0.2.2-latest-linux-x64 → 0.2.2

package/src/daemons/skill-sync-daemon.ts

@@ -0,0 +1,276 @@
+import { mkdirSync, watch, type FSWatcher } from "node:fs";
+import { exitWhenUninstalled } from "jive-abstract-library";
+import { detectFolders, loadConfig, loadStates, saveStates, stateFor } from "../internal/config";
+import { authHeaders, describe, logReconciliations, register } from "../internal/folders";
+import { notify } from "../internal/notify";
+import { reconcile } from "../internal/reconcile";
+import { isQuiet, syncOnce, type Report } from "../internal/sync";
+import type { DaemonMessage, FolderPrefs, FolderState, HubToDaemon } from "../internal/wire";
+
+/**
+ * Keeps every enabled skills folder on this machine identical to every other machine's.
+ *
+ * Folders are detected (`~/.claude*` homes); which of them sync, and which skills in each, are
+ * preferences held by the server and changed from the dashboard, so they survive a reinstall and apply
+ * the moment they change. A skill not opted in stays local to its folder.
+ *
+ * The daemon holds a WebSocket to the service's hub. That connection is how the dashboard knows this
+ * machine is running, how a preference change arrives, and how a write from another machine triggers a
+ * cycle here at once. Polling stays as the fallback: every 5 minutes while connected, every 30 seconds
+ * while not, so a dropped connection costs latency and never correctness.
+ */
+
+const POLL_CONNECTED_MS = 5 * 60_000;
+const POLL_DISCONNECTED_MS = 30_000;
+/** Long enough that an editor's write-rename-write lands as one cycle, short enough to feel immediate. */
+const SETTLE_MS = 1_000;
+const PING_MS = 30_000;
+/** No pong for this long means the connection is dead even if the socket has not noticed. */
+const PONG_TIMEOUT_MS = 75_000;
+const RECONNECT_MIN_MS = 5_000;
+const RECONNECT_MAX_MS = 5 * 60_000;
+
+exitWhenUninstalled();
+
+const loaded = loadConfig();
+if (!loaded.ok) {
+  console.error(`skill-sync is not configured: ${loaded.reason}`);
+  // Zero, not one: the service manager restarts a daemon that fails, and retrying every few seconds
+  // against a config nobody has filled in yet would just fill the log.
+  process.exit(0);
+}
+const config = loaded.config;
+const states = loadStates();
+
+/** What was last registered, so registration is repeated only when a folder or skill appears or goes. */
+let registered = "";
+/** The folders to sync, each with the skills that sync there. */
+let prefs = new Map<string, ReadonlySet<string>>();
+const watchers = new Map<string, FSWatcher>();
+
+// ── Folders ─────────────────────────────────────────────────────────────────────────────────────────
+
+/** Reports this machine's folders and skills, and adopts the server's answer for what syncs. */
+async function registerFolders(): Promise<void> {
+  const request = describe(config, states);
+  applyPrefs(await register(config, request));
+  registered = JSON.stringify(request);
+}
+
+/** True when a folder or a skill has appeared or gone since the last registration. */
+const registrationStale = (): boolean => JSON.stringify(describe(config, states)) !== registered;
+
+function applyPrefs(folders: ReadonlyArray<FolderPrefs>): void {
+  // Only folders this machine still has. The hub can hold a stale list — it answers a reconnect before
+  // the next registration — and creating a listed folder whose Claude home is gone would bring it back.
+  const present = new Set(detectFolders());
+  const next = new Map(folders.filter((folder) => present.has(folder.path))
+    .map((folder) => [folder.path, new Set(folder.skills)] as const));
+  for (const [folder, watcher] of watchers) {
+    if (!next.has(folder)) {
+      watcher.close();
+      watchers.delete(folder);
+    }
+  }
+  // An unticked folder leaves no trace of syncing: its state goes, so the state file lists only folders
+  // that sync, and ticking it again starts it fresh — any copy that differs is merged, not overwritten.
+  // Covers folders with state from an earlier run too, not only ones this run was syncing.
+  const stopped = [...new Set([...prefs.keys(), ...Object.keys(states)])].filter((folder) => !next.has(folder));
+  for (const folder of stopped) {
+    delete states[folder];
+    console.log(`stopped syncing ${folder}`);
+  }
+  if (stopped.length > 0) saveStates(states);
+  for (const folder of next.keys()) {
+    if (watchers.has(folder)) continue;
+    mkdirSync(folder, { recursive: true });
+    let settle: ReturnType<typeof setTimeout> | undefined;
+    watchers.set(folder, watch(folder, { recursive: true }, () => {
+      if (settle !== undefined) clearTimeout(settle);
+      settle = setTimeout(runCycle, SETTLE_MS);
+    }));
+  }
+  const changed = JSON.stringify([...next].map(([path, skills]) => [path, [...skills].sort()]))
+    !== JSON.stringify([...prefs].map(([path, skills]) => [path, [...skills].sort()]));
+  prefs = next;
+  if (!changed) return;
+  for (const [folder, skills] of prefs) console.log(`syncing ${folder}: ${[...skills].sort().join(", ") || "no skills"}`);
+  if (prefs.size === 0) console.log("syncing no folders");
+  void runCycle();
+}
+
+// ── Hub connection ──────────────────────────────────────────────────────────────────────────────────
+
+let socket: WebSocket | undefined;
+let lastPong = 0;
+let reconnectDelay = RECONNECT_MIN_MS;
+/** What the hub was last told about each folder (state and detail), so only changes are sent. */
+const reported = new Map<string, string>();
+
+function connect(): void {
+  const url = `${config.endpoint.replace(/^http/, "ws")}/daemon`;
+  // Bun's WebSocket takes headers; the browser's does not, which is why the token can travel this way.
+  const ws = new WebSocket(url, { headers: authHeaders(config, {}) } as unknown as string[]);
+  ws.onopen = () => {
+    socket = ws;
+    lastPong = Date.now();
+    reconnectDelay = RECONNECT_MIN_MS;
+    console.log("connected to the hub");
+    // A previous run may have died mid-merge; whatever the hub last heard is stale until re-sent.
+    reported.clear();
+    for (const folder of prefs.keys()) report(folder, "idle");
+  };
+  ws.onmessage = (event) => {
+    const data = String(event.data);
+    if (data === "pong") {
+      lastPong = Date.now();
+      return;
+    }
+    const message = JSON.parse(data) as HubToDaemon;
+    if (message.type === "prefs") applyPrefs(message.folders);
+    if (message.type === "changed") void runCycle();
+  };
+  ws.onclose = () => {
+    if (socket === ws) socket = undefined;
+    setTimeout(connect, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+  };
+  ws.onerror = () => {
+    // `onclose` follows and schedules the reconnect.
+  };
+}
+
+setInterval(() => {
+  if (socket === undefined) return;
+  if (Date.now() - lastPong > PONG_TIMEOUT_MS) {
+    console.error("hub connection went quiet; reconnecting");
+    socket.close();
+    return;
+  }
+  socket.send("ping");
+}, PING_MS);
+
+function report(folder: string, state: FolderState, detail?: string, activity?: string): void {
+  const key = `${state}|${detail ?? ""}`;
+  if (reported.get(folder) === key && activity === undefined) return;
+  if (socket === undefined) return;
+  const message: DaemonMessage = { type: "status", folder, state, detail, activity };
+  socket.send(JSON.stringify(message));
+  reported.set(folder, key);
+}
+
+// ── Sync cycles ─────────────────────────────────────────────────────────────────────────────────────
+
+let running = false;
+let cycleQueued = false;
+
+/**
+ * Conflicts already reported to the desktop.
+ *
+ * A conflict persists until a human resolves it, so every cycle keeps finding it — notifying each time
+ * would put a popup on screen every cycle until they gave up and turned notifications off, which costs
+ * them the one notification that mattered. Only newly-conflicting paths are announced, and a path drops
+ * out of the set once it stops conflicting so a later recurrence is announced again.
+ */
+const announced = new Set<string>();
+
+function announceConflicts(conflicts: ReadonlyArray<string>): void {
+  for (const path of [...announced]) {
+    if (!conflicts.includes(path)) announced.delete(path);
+  }
+  const fresh = conflicts.filter((path) => !announced.has(path));
+  if (fresh.length === 0) return;
+  for (const path of fresh) announced.add(path);
+  notify(
+    "Skill sync conflict",
+    fresh.length === 1
+      ? `${fresh[0]} changed on two machines and could not be merged. Your version is saved as ${fresh[0]}.local`
+      : `${fresh.length} skills changed on two machines and could not be merged. Your versions are saved as .local`,
+  );
+}
+
+function summarise(result: Report): string {
+  const parts = [
+    result.pulled.length > 0 ? `pulled ${result.pulled.join(", ")}` : "",
+    result.pushed.length > 0 ? `pushed ${result.pushed.join(", ")}` : "",
+    result.deletedLocally.length > 0 ? `deleted ${result.deletedLocally.join(", ")}` : "",
+    result.merged.length > 0 ? `merged ${result.merged.join(", ")}` : "",
+  ];
+  return parts.filter(Boolean).join("; ");
+}
+
+async function runCycle(): Promise<void> {
+  if (running) {
+    cycleQueued = true;
+    return;
+  }
+  running = true;
+  const conflicts: string[] = [];
+  try {
+    // Folders sync one after another against the same server, so a change pushed from one folder is
+    // pulled into the others on the follow-up pass this triggers.
+    for (const [folder, skills] of [...prefs]) {
+      try {
+        const result = await syncOnce(config, folder, stateFor(states, folder), skills, {
+          merge: reconcile,
+          onMerging: (path) => {
+            console.log(`${folder}: merging ${path} with Claude`);
+            report(folder, "reconciling", path);
+          },
+        });
+        saveStates(states);
+        log(folder, result);
+        if (result.reconciliations.length > 0) {
+          await logReconciliations(config, result.reconciliations.map((entry) => ({ ...entry, folder })))
+            .catch((cause) => console.error(`could not log a merge: ${cause instanceof Error ? cause.message : String(cause)}`));
+        }
+        conflicts.push(...result.conflicts.map((path) => `${folder}/${path}`));
+
+        const problems = [...result.mergeFailures, ...result.conflicts.map((path) => `${path} kept as .local`), ...result.rejected];
+        if (problems.length > 0) report(folder, "attention", problems.join("; "), summarise(result) || undefined);
+        else report(folder, "idle", undefined, isQuiet(result) ? undefined : summarise(result));
+
+        if (result.pushed.length > 0 || result.merged.length > 0 || result.retry) cycleQueued = true;
+      } catch (cause) {
+        // One failed folder must not end the daemon or the other folders: the usual cause is the network.
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        console.error(`${folder}: sync failed: ${reason}`);
+        report(folder, "attention", `sync failed: ${reason}`);
+      }
+    }
+    announceConflicts(conflicts);
+    // A skill created or removed locally changes what the dashboard should list.
+    if (registrationStale()) await registerFolders().catch(() => undefined);
+  } finally {
+    running = false;
+    if (cycleQueued) {
+      cycleQueued = false;
+      setTimeout(runCycle, SETTLE_MS);
+    }
+  }
+}
+
+function log(folder: string, result: Report): void {
+  for (const path of result.pulled) console.log(`${folder}: pulled ${path}`);
+  for (const path of result.pushed) console.log(`${folder}: pushed ${path}`);
+  for (const path of result.deletedLocally) console.log(`${folder}: deleted ${path}`);
+  for (const path of result.merged) console.log(`${folder}: merged ${path}`);
+  for (const failure of result.mergeFailures) console.error(`${folder}: merge failed for ${failure}`);
+  for (const path of result.conflicts) console.error(`${folder}: conflict on ${path}; your copy is at ${path}.local`);
+  for (const path of result.rejected) console.error(`${folder}: refused a path the server sent: ${path}`);
+}
+
+/** Re-detects folders each poll: a Claude home created since the last one should join without a restart. */
+async function poll(): Promise<void> {
+  try {
+    if (registered === "" || registrationStale()) await registerFolders();
+  } catch (cause) {
+    console.error(`could not register folders: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+  await runCycle();
+  setTimeout(poll, socket === undefined ? POLL_DISCONNECTED_MS : POLL_CONNECTED_MS);
+}
+
+console.log(`skill-sync daemon for ${config.machine}, syncing with ${config.endpoint}`);
+connect();
+await poll();

package/src/entrypoints/skill-sync.ts

@@ -0,0 +1,109 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { rmSync, writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { Effect } from "effect";
+import { upgrade } from "jive-abstract-library";
+import { name } from "../../package.json";
+import { CONFIG_PATH, TOKEN_PATH, loadConfig, loadSettings } from "../internal/config";
+
+/**
+ * The CLI that accompanies the daemon.
+ *
+ * The daemon never authenticates anyone — it reads a token the CLI left behind and nothing more. Signing
+ * in needs a browser and a person, which a process started at login has neither of, and a daemon that
+ * could prompt for credentials would be a daemon that prompts you at every login.
+ */
+
+const program = new Command("skill-sync")
+  .description("keep the skills you choose identical across every Claude folder on every machine; choose them at https://skill-sync.jive.sh/");
+
+program
+  .command("login")
+  .description("verify with your passkey in the browser and store this machine's sync token")
+  .action(async () => {
+    // A missing token is exactly what we are here to fix, so only the settings have to be usable.
+    const settings = loadSettings();
+    if (settings === undefined) {
+      console.error(`Fill in ${CONFIG_PATH} with an endpoint and a machine name first.`);
+      process.exit(1);
+    }
+
+    const token = await captureToken(settings.endpoint, settings.machine);
+    writeFileSync(TOKEN_PATH, `${JSON.stringify({ token }, null, 2)}\n`, { mode: 0o600 });
+    console.log(`Signed in. Token saved to ${TOKEN_PATH}`);
+    console.log(`Choose which folders sync at ${settings.endpoint}/`);
+  });
+
+program
+  .command("logout")
+  .description("forget this machine's sync token")
+  .action(async () => {
+    const loaded = loadConfig();
+    if (loaded.ok) {
+      // Revoke first: if this fails, the token is still on disk and you can try again. Deleting it first
+      // would leave a live token on the server that nobody can revoke any more.
+      const response = await fetch(`${loaded.config.endpoint}/cli/token`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${loaded.config.token}` },
+      });
+      console.log(response.ok ? "Revoked on the server." : `Server revoke failed (${response.status}).`);
+    }
+    rmSync(TOKEN_PATH, { force: true });
+    console.log(`Removed ${TOKEN_PATH}`);
+  });
+
+program
+  .command("upgrade")
+  .description("upgrade skill-sync to the latest version with the package manager that installed it")
+  .action(async () => {
+    await Effect.runPromise(upgrade({ packageName: name })).catch((cause: unknown) => {
+      console.error(`Upgrade failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+      process.exit(1);
+    });
+  });
+
+program.parse();
+if (process.argv.length <= 2) program.help();
+
+/**
+ * Opens the browser at the service's login endpoint and waits for it to come back with a token.
+ *
+ * The browser does the authenticating, with a passkey for the service's domain; this only has to be
+ * listening when it finishes. The listener is bound to 127.0.0.1 so nothing off this machine can receive
+ * the redirect, and the port is whatever the OS hands out so two machines — or two attempts — never
+ * contend for one.
+ */
+async function captureToken(endpoint: string, machine: string): Promise<string> {
+  return await new Promise<string>((resolve, reject) => {
+    const server = createServer((request, response) => {
+      const token = new URL(request.url ?? "/", "http://127.0.0.1").searchParams.get("token");
+      response.writeHead(200, { "content-type": "text/html" });
+      response.end(token
+        ? "<p>Signed in. You can close this tab.</p>"
+        : "<p>No token in the redirect. Check the service logs.</p>");
+      server.close();
+      token ? resolve(token) : reject(new Error("the redirect carried no token"));
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const port = (server.address() as { port: number }).port;
+      const url = `${endpoint}/cli/login?port=${port}&machine=${encodeURIComponent(machine)}`;
+      console.log(`Opening ${url}`);
+      openBrowser(url);
+    });
+
+    setTimeout(() => {
+      server.close();
+      reject(new Error("timed out waiting for the browser"));
+    }, 180_000).unref();
+  });
+}
+
+function openBrowser(url: string): void {
+  const command = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "cmd"
+    : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  spawn(command, args, { stdio: "ignore", detached: true }).unref();
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * What the service needs from this package.
+ *
+ * The daemon and CLI are the product; this entrypoint exists so the service can share the path rules
+ * and wire types rather than restate them. A rule restated is a rule that drifts, and these two are
+ * exactly the pair that must not: one validates what the other writes to disk.
+ */
+
+export { invalidPathReason, isValidPath } from "./internal/path";
+export { skillOf } from "./internal/wire";
+export type {
+  DaemonMessage, DashboardMessage, FileHash, FolderPrefs, FolderState, FolderView, FoldersRequest, FoldersResponse,
+  HubToDaemon, ListFilesResponse, LocalSkill, MachineView, PutFileRequest, ReconciliationRequest,
+  ReconciliationView, RemoteFile, SkillView, Snapshot, SyncedSkill,
+} from "./internal/wire";

package/src/internal/config.ts

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Per-machine settings and sync state, both under `~/.jive/`.
+ *
+ * A file rather than environment variables: the endpoint and which machine this is differ per computer
+ * and have to survive a login, which is exactly what a config file is for and exactly what an environment
+ * variable is not. Which folders to sync is not in here: they are detected, and the choice to leave one
+ * out is kept on the server so the dashboard can change it and a reinstalled daemon still remembers it.
+ */
+
+const JIVE_HOME = join(homedir(), ".jive");
+export const CONFIG_PATH = join(JIVE_HOME, "skill-sync.json");
+/**
+ * The token lives on its own, outside `~/.jive/`, because it is the one part that must not travel with
+ * the rest. Endpoint and machine name are settings you could paste into a gist; this
+ * is a credential, and keeping it in a separate file makes "do not copy this one" a property of the
+ * filesystem rather than a thing you have to remember.
+ */
+export const TOKEN_PATH = join(homedir(), ".skill-sync-token.json");
+const STATE_PATH = join(JIVE_HOME, "skill-sync-state.json");
+
+/** Managed by Claude's own cloud sync; see `Config.exclude`. */
+const DEFAULT_EXCLUDE = ["synced"] as const;
+
+export interface Config {
+  readonly endpoint: string;
+  /**
+   * Top-level directory names under each synced folder to leave alone.
+   *
+   * `synced` holds the skills Claude already pulls from the cloud itself. Syncing them here would mean
+   * two systems writing the same files, each undoing the other, and none of them are yours to edit.
+   */
+  readonly exclude: ReadonlyArray<string>;
+  readonly token: string;
+  /** Names this machine in conflict messages, so "who overwrote this" has an answer. */
+  readonly machine: string;
+}
+
+/** Either the settings, or the one sentence telling the user what to go and fill in. */
+export type ConfigResult =
+  | { readonly ok: true; readonly config: Config }
+  | { readonly ok: false; readonly reason: string };
+
+/** Sync progress for one folder. Each folder syncs with the server on its own, so each has its own. */
+export interface State {
+  /** Highest server sequence number already applied. */
+  cursor: number;
+  /** Last hash this machine agreed with the server on, per relative path. Absent means never synced. */
+  known: Record<string, string>;
+  /** The skills this folder synced last cycle, to notice one being opted in. */
+  skills?: string[];
+}
+
+/** Every folder's `State`, keyed by the folder's absolute path. */
+export type States = Record<string, State>;
+
+/**
+ * The settings alone, with no token required.
+ *
+ * `login` needs these precisely when the token is missing, so it cannot go through `loadConfig` — that
+ * reports "not configured" for a missing token and would refuse to run the command that supplies one.
+ */
+export function loadSettings(): { endpoint: string; machine: string } | undefined {
+  loadConfig();
+  const settings = readJson<Partial<Config>>(CONFIG_PATH);
+  if (!settings.endpoint || !settings.machine) return undefined;
+  return { endpoint: settings.endpoint, machine: settings.machine };
+}
+
+/** Reads both files, writing a template for whichever is missing, and says what is still needed. */
+export function loadConfig(): ConfigResult {
+  if (!existsSync(CONFIG_PATH)) {
+    mkdirSync(JIVE_HOME, { recursive: true });
+    writeFileSync(CONFIG_PATH, `${JSON.stringify({
+      endpoint: "https://skill-sync.jive.sh",
+      machine: machineName(),
+      exclude: DEFAULT_EXCLUDE,
+    }, null, 2)}\n`);
+  }
+
+  if (!existsSync(TOKEN_PATH)) {
+    // 0600 from the moment it exists, rather than written open and tightened afterwards — there is no
+    // window in between for anything else on the machine to read it.
+    writeFileSync(TOKEN_PATH, `${JSON.stringify({ token: "" }, null, 2)}\n`, { mode: 0o600 });
+  }
+
+  const settings = readJson<Partial<Config>>(CONFIG_PATH);
+  const token = readJson<{ token?: string }>(TOKEN_PATH).token;
+
+  if (!settings.endpoint || !settings.machine) {
+    return { ok: false, reason: `${CONFIG_PATH} needs an endpoint and a machine name` };
+  }
+  if (!token) {
+    return { ok: false, reason: `${TOKEN_PATH} needs the sync token` };
+  }
+  return {
+    ok: true,
+    config: { endpoint: settings.endpoint, machine: settings.machine, exclude: settings.exclude ?? DEFAULT_EXCLUDE, token },
+  };
+}
+
+function readJson<T>(path: string): T {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return {} as T;
+  }
+}
+
+/**
+ * Every folder's sync state.
+ *
+ * Before folders were detected the file held one folder's `{ cursor, known }`, for the folder then named
+ * by `skillsDir` in the settings. That state is carried over to that folder: dropping it would make the
+ * folder look never-synced, and every file in it that differs from the server would become a conflict.
+ */
+export function loadStates(): States {
+  const stored = readJson<Partial<State> & { folders?: States }>(STATE_PATH);
+  if (stored.folders !== undefined) return stored.folders;
+  const legacyFolder = readJson<{ skillsDir?: string }>(CONFIG_PATH).skillsDir;
+  if (legacyFolder !== undefined && stored.cursor !== undefined && stored.known !== undefined) {
+    return { [legacyFolder]: { cursor: stored.cursor, known: stored.known } };
+  }
+  return {};
+}
+
+export function stateFor(states: States, folder: string): State {
+  states[folder] ??= { cursor: 0, known: {} };
+  return states[folder];
+}
+
+export function saveStates(states: States): void {
+  mkdirSync(JIVE_HOME, { recursive: true });
+  writeFileSync(STATE_PATH, `${JSON.stringify({ folders: states }, null, 2)}\n`);
+}
+
+/** `HOSTNAME` is not set on macOS, so the template was writing "unknown" on exactly this machine. */
+function machineName(): string {
+  return hostname().replace(/\.local$/, "").replace(/[^A-Za-z0-9-]+/g, "-") || "unknown";
+}
+
+/**
+ * The `skills` folder of every Claude home on this machine: `~/.claude` and each `~/.claude-<name>`.
+ *
+ * Every home is a candidate, whether or not it has a `skills` folder yet, so a Claude account added
+ * later joins without anyone listing it. Which of them actually sync is the user's choice on the
+ * dashboard; a folder that is synced and missing is created.
+ */
+export function detectFolders(): string[] {
+  return readdirSync(homedir())
+    .filter((entry) => entry === ".claude" || entry.startsWith(".claude-"))
+    .filter((entry) => statSync(join(homedir(), entry)).isDirectory())
+    .map((entry) => join(homedir(), entry, "skills"))
+    .sort();
+}
+
+export function hashBytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Suffix for the copy kept when an incoming change would have overwritten a local edit. */
+export const CONFLICT_SUFFIX = ".local";
+
+/**
+ * Every file under a synced folder, as paths relative to it with forward slashes.
+ *
+ * Normalised because the same skill synced from Windows and macOS must be one row, not two.
+ *
+ * Conflict copies are skipped. They are this machine's evidence of a collision, not content anyone else
+ * asked for, and syncing them spreads one machine's mess to every other machine.
+ */
+export function listLocalFiles(folder: string, exclude: ReadonlyArray<string> = DEFAULT_EXCLUDE): string[] {
+  if (!existsSync(folder)) return [];
+
+  const found: string[] = [];
+  const walk = (dir: string, top: boolean): void => {
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith(".")) continue;
+      if (top && exclude.includes(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full, false);
+      else if (!entry.endsWith(CONFLICT_SUFFIX)) found.push(relative(folder, full).split(sep).join("/"));
+    }
+  };
+  walk(folder, true);
+  return found.sort();
+}

package/src/internal/folders.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectFolders, hashBytes, listLocalFiles, type Config, type States } from "./config";
+import {
+  skillOf, type FileHash, type FolderPrefs, type FoldersRequest, type FoldersResponse, type LocalSkill, type ReconciliationRequest,
+} from "./wire";
+
+/**
+ * What this machine tells the service about its folders, and what it hears back.
+ *
+ * The daemon and the CLI both register, so this lives in one place: they must describe a folder the same
+ * way, or the dashboard would show whichever of them spoke last.
+ */
+
+/**
+ * The skills on disk in one folder, with each file's hash. Hashing every file on each check is cheap at
+ * skills' size, and it is what lets the dashboard show whether this folder's copy is the synced one.
+ */
+export function localSkills(folder: string, config: Config, states: States): LocalSkill[] {
+  const known = Object.keys(states[folder]?.known ?? {});
+  const byName = new Map<string, FileHash[]>();
+  for (const path of listLocalFiles(folder, config.exclude)) {
+    const name = skillOf(path);
+    let hash: string;
+    try {
+      hash = hashBytes(readFileSync(join(folder, path)));
+    } catch {
+      continue; // Deleted between listing and reading; the next check reports the folder as it is.
+    }
+    byName.set(name, [...(byName.get(name) ?? []), { path, hash }]);
+  }
+  return [...byName].map(([name, files]) => ({
+    name,
+    files,
+    tracked: known.some((path) => skillOf(path) === name),
+  }));
+}
+
+/** Everything registration sends, so a caller can tell when it has changed and is worth re-sending. */
+export function describe(config: Config, states: States): FoldersRequest {
+  return { folders: detectFolders().map((path) => ({ path, skills: localSkills(path, config, states) })) };
+}
+
+/** Registers this machine's folders and skills; returns the folders to sync and the skills in each. */
+export async function register(config: Config, request: FoldersRequest): Promise<ReadonlyArray<FolderPrefs>> {
+  const response = await fetch(`${config.endpoint}/folders`, {
+    method: "POST",
+    headers: authHeaders(config, { "content-type": "application/json" }),
+    body: JSON.stringify(request),
+  });
+  if (!response.ok) throw new Error(`POST /folders: ${response.status} ${await response.text()}`);
+  return (await response.json() as FoldersResponse).folders;
+}
+
+/** Sends merges to the audit log. A failure here is logged by the caller, never fatal to a sync. */
+export async function logReconciliations(config: Config, entries: ReadonlyArray<ReconciliationRequest>): Promise<void> {
+  for (const entry of entries) {
+    const response = await fetch(`${config.endpoint}/reconciliations`, {
+      method: "POST",
+      headers: authHeaders(config, { "content-type": "application/json" }),
+      body: JSON.stringify(entry),
+    });
+    if (!response.ok) throw new Error(`POST /reconciliations: ${response.status} ${await response.text()}`);
+  }
+}
+
+export function authHeaders(config: Config, extra: Record<string, string>): Record<string, string> {
+  return { authorization: `Bearer ${config.token}`, "x-skill-sync-machine": config.machine, ...extra };
+}