@jive-sh/skill-sync 0.4.4-latest-darwin-arm64 → 0.4.4

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

@@ -0,0 +1,418 @@
+import { mkdirSync, watch, type FSWatcher } from "node:fs";
+import { createServer } from "node:http";
+import { exitWhenUninstalled } from "jive-abstract-library";
+import {
+  TOKEN_PATH, deleteToken, detectFolders, loadSettings, loadStates, loadToken, saveStates, saveToken, stateFor,
+  type Config,
+} from "../internal/config";
+import { serve, type ControlRequest, type Reply } from "../internal/control";
+import { describe, register } from "../internal/folders";
+import { authHeaders, fetchServer, TokenRejected } from "../internal/server";
+import { isQuiet, syncOnce, type Report } from "../internal/sync";
+import type { DaemonMessage, FolderPrefs, FolderState, HubToDaemon, ListSkillsResponse } from "../internal/wire";
+
+/**
+ * Keeps every enabled skills folder on this machine identical to every other machine's.
+ *
+ * Folders are detected: the `skills` folder in each `~/.claude*` home and Codex's `~/.agents/skills`
+ * (see `detectFolders`). Which of them sync, and the one list of skills that syncs in all of them, are
+ * held by the server and changed from the dashboard, so they survive a reinstall and apply the moment
+ * they change. A skill not on the list is never pushed or pulled.
+ *
+ * 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.
+ *
+ * `skill-sync login` asks the daemon, over the control socket, to sign in; the token arrives from the
+ * browser straight to this process, which keeps it in `~/.jive/skill-sync-token.json` (`TOKEN_PATH`). A
+ * daemon that starts and finds that file is signed in, so a restart, a reboot or an upgrade needs no
+ * sign-in. Signing out, or the server rejecting the token, deletes the file.
+ */
+
+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;
+/** How long a sign-in waits for the browser before giving up. */
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+exitWhenUninstalled();
+
+const settings = loadSettings();
+if (settings === undefined) {
+  console.error("~/.jive/skill-sync.json needs an endpoint and a machine name");
+  // Zero, not one: the service manager restarts a daemon that fails, and a file nobody has fixed would
+  // only fill the log.
+  process.exit(0);
+}
+const states = loadStates();
+
+/** Set while signed in. Everything that talks to the server reads it; signing out clears it. */
+let session: Config | undefined;
+/** The signed-in config, for code that only runs during a session. */
+function current(): Config {
+  if (session === undefined) throw new Error("not signed in");
+  return session;
+}
+
+/** What was last registered, so registration is repeated only when a folder or skill appears or goes. */
+let registered = "";
+/** The enabled folders, each with the synced list. */
+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(current());
+  applyPrefs(await register(current(), 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(current())) !== 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 agent 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.
+  // 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 {
+  if (session === undefined) return;
+  const config = session;
+  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");
+    // Whatever the hub last heard from a previous connection 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;
+    // Only the session that opened it reconnects: after a sign-out, or a sign-in with a new token, this
+    // socket belongs to nobody.
+    if (session !== config) return;
+    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;
+
+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(", ")}` : "",
+  ];
+  return parts.filter(Boolean).join("; ");
+}
+
+async function runCycle(): Promise<void> {
+  if (session === undefined) return;
+  if (running) {
+    cycleQueued = true;
+    return;
+  }
+  running = true;
+  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(current(), folder, stateFor(states, folder), skills);
+        saveStates(states);
+        log(folder, result);
+        if (result.rejected.length > 0) report(folder, "attention", result.rejected.join("; "), summarise(result) || undefined);
+        else report(folder, "idle", undefined, isQuiet(result) ? undefined : summarise(result));
+        // What this folder pushed is pulled into the machine's other folders on the follow-up pass.
+        if (result.pushed.length > 0) cycleQueued = true;
+      } catch (cause) {
+        if (cause instanceof TokenRejected) {
+          dropRejectedToken(cause);
+          return;
+        }
+        // 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}`);
+      }
+    }
+    // A skill created or removed locally changes what the dashboard should list.
+    if (registrationStale()) {
+      await registerFolders().catch((cause: unknown) => {
+        if (cause instanceof TokenRejected) dropRejectedToken(cause);
+      });
+    }
+  } 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.rejected) console.error(`${folder}: refused a path the server sent: ${path}`);
+}
+
+let pollTimer: ReturnType<typeof setTimeout> | undefined;
+
+/** Re-detects folders each poll: an agent home created since the last one should join without a restart. */
+async function poll(): Promise<void> {
+  if (session === undefined) return;
+  try {
+    if (registered === "" || registrationStale()) await registerFolders();
+  } catch (cause) {
+    if (cause instanceof TokenRejected) {
+      dropRejectedToken(cause);
+      return;
+    }
+    console.error(`could not register folders: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+  await runCycle();
+  if (session !== undefined) pollTimer = setTimeout(poll, socket === undefined ? POLL_DISCONNECTED_MS : POLL_CONNECTED_MS);
+}
+
+// ── Signing in and out ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Starts a session with a token from the browser. Registering this machine's folders is the first call
+ * that needs the token, so it doubles as the check that the token works: a failure leaves the daemon
+ * signed out, not half-running, and the token unsaved.
+ */
+async function signIn(token: string): Promise<void> {
+  if (session !== undefined) await signOut();
+  session = { ...settings!, token };
+  try {
+    await registerFolders();
+  } catch (cause) {
+    session = undefined;
+    throw cause;
+  }
+  saveToken(token);
+  console.log(`signed in as ${session.machine}; syncing with ${session.endpoint}`);
+  connect();
+  void poll();
+}
+
+/**
+ * Starts a session with the token saved by an earlier sign-in. Not checked first, unlike `signIn`: at boot
+ * the network may not be up yet, and a failure for that reason must not sign the machine out. The first
+ * poll registers; a rejected token signs out there.
+ */
+function resume(token: string): void {
+  session = { ...settings!, token };
+  console.log(`signed in as ${session.machine} with the token in ${TOKEN_PATH}; syncing with ${session.endpoint}`);
+  connect();
+  void poll();
+}
+
+/** Stops syncing and forgets the token, here and in `TOKEN_PATH`. Returns the session that ended. */
+function endSession(): Config | undefined {
+  const config = session;
+  if (config === undefined) return undefined;
+  session = undefined;
+  deleteToken();
+  if (pollTimer !== undefined) clearTimeout(pollTimer);
+  socket?.close();
+  socket = undefined;
+  for (const watcher of watchers.values()) watcher.close();
+  watchers.clear();
+  prefs = new Map();
+  registered = "";
+  return config;
+}
+
+/**
+ * The server no longer accepts the token, so no request can succeed until someone signs in again. Only
+ * when it is this session's token: a request still in flight from before a new sign-in may be rejected too.
+ */
+function dropRejectedToken(cause: TokenRejected): void {
+  if (session?.token !== cause.token) return;
+  endSession();
+  console.error(`${cause.message}; signed out and deleted ${TOKEN_PATH}. Run \`skill-sync login\` to sign in again.`);
+}
+
+/** Revokes the token on the server, forgets it, and stops syncing. Returns whether the revoke succeeded. */
+async function signOut(): Promise<boolean> {
+  const config = endSession();
+  if (config === undefined) return false;
+  // Revoked, not just forgotten: a token copied while it was live would otherwise keep working.
+  // A token the server already rejects is as revoked as it can be.
+  const revoked = await fetchServer(config, "/cli/token", { method: "DELETE" })
+    .then((response) => response.ok, (cause: unknown) => cause instanceof TokenRejected);
+  console.log(`signed out${revoked ? "" : " (the server could not be reached to revoke the token)"}`);
+  return revoked;
+}
+
+let loginInProgress = false;
+
+/**
+ * One sign-in: listen on 127.0.0.1 for the browser to hand over the token, tell the CLI which URL to
+ * open, and finish when the token arrives. The browser's login page posts to this listener only, never to
+ * an address the request chose, so a page that tricks you into signing in cannot collect the token.
+ */
+function login(reply: Reply): void {
+  if (loginInProgress) {
+    reply.send({ type: "error", message: "a sign-in is already in progress" });
+    return;
+  }
+  loginInProgress = true;
+  const done = (): void => {
+    loginInProgress = false;
+    listener.close();
+    clearTimeout(timer);
+  };
+  const listener = 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.</p>");
+    if (token === null) return;
+    done();
+    signIn(token).then(
+      () => reply.send({ type: "signedIn", machine: settings!.machine }),
+      (cause) => reply.send({ type: "error", message: `the server refused the sign-in: ${cause instanceof Error ? cause.message : String(cause)}` }),
+    );
+  });
+  const timer = setTimeout(() => {
+    done();
+    reply.send({ type: "error", message: "timed out waiting for the browser" });
+  }, LOGIN_TIMEOUT_MS);
+  listener.listen(0, "127.0.0.1", () => {
+    const port = (listener.address() as { port: number }).port;
+    reply.send({ type: "open", url: `${settings!.endpoint}/cli/login?port=${port}&machine=${encodeURIComponent(settings!.machine)}` });
+  });
+}
+
+/** The synced list, from the server: the CLI has no token to ask with, so it asks this daemon. */
+function list(reply: Reply): void {
+  const config = session;
+  if (config === undefined) {
+    reply.send({ type: "error", message: "this machine is signed out; run `skill-sync login` first" });
+    return;
+  }
+  fetchServer(config, "/skills")
+    .then(async (response) => {
+      if (!response.ok) throw new Error(`GET /skills: ${response.status} ${await response.text()}`);
+      reply.send({ type: "list", skills: (await response.json() as ListSkillsResponse).skills });
+    })
+    .catch((cause: unknown) => {
+      if (cause instanceof TokenRejected) {
+        dropRejectedToken(cause);
+        reply.send({ type: "error", message: "the server rejected this machine's token, so it is signed out; run `skill-sync login`" });
+        return;
+      }
+      reply.send({ type: "error", message: `could not reach the server: ${cause instanceof Error ? cause.message : String(cause)}` });
+    });
+}
+
+function handleControl(message: ControlRequest, reply: Reply): void {
+  if (message.type === "login") login(reply);
+  else if (message.type === "logout") void signOut().then((revoked) => reply.send({ type: "signedOut", revoked }));
+  else if (message.type === "list") list(reply);
+  else reply.send({ type: "error", message: `unknown request ${JSON.stringify(message)}` });
+}
+
+if (await serve(handleControl) === false) {
+  console.log("another skill-sync daemon is already running for this user; standing down");
+  // Zero: a second install's daemon is not a failure, and the service manager must not keep retrying it.
+  process.exit(0);
+}
+// Only after taking the control socket: a daemon that stands down must not sync too.
+const savedToken = loadToken();
+if (savedToken !== undefined) resume(savedToken);
+else console.log(`skill-sync daemon for ${settings.machine}; waiting for \`skill-sync login\``);

package/src/entrypoints/skill-sync.ts

@@ -0,0 +1,136 @@
+import { spawn, spawnSync } from "node:child_process";
+import { Command } from "commander";
+import { Effect } from "effect";
+import { daemonStatuses, upgrade } from "jive-abstract-library";
+import { name } from "../../package.json";
+import { DaemonUnreachable, request, type ControlEvent, type ControlRequest } from "../internal/control";
+
+/**
+ * The CLI that accompanies the daemon: `login`, `logout`, `list` and `upgrade`, and nothing else — which
+ * folders and skills sync is chosen on the dashboard.
+ *
+ * The daemon owns the sync token and keeps it in `~/.jive/skill-sync-token.json`. `login`, `logout` and
+ * `list` are requests to it over the control socket; the token goes from the browser straight to the daemon
+ * and never through here.
+ */
+
+const program = new Command("skill-sync")
+  .description("keep the skills you choose identical across every Claude and Codex skills folder on every machine; choose them at https://skill-sync.jive.sh/");
+
+program
+  .command("login")
+  .description("sign this machine in with your passkey in the browser; it stays signed in until you log out")
+  .action(async () => {
+    const result = await withDaemon({ type: "login" }, (event) => {
+      if (event.type !== "open") return;
+      console.log(`Opening ${event.url}`);
+      openBrowser(event.url);
+    });
+    if (result.type === "signedIn") {
+      console.log(`Signed in. ${result.machine} is syncing; choose what syncs at https://skill-sync.jive.sh/`);
+    } else {
+      fail(result);
+    }
+  });
+
+program
+  .command("logout")
+  .description("revoke this machine's token and stop syncing until the next login")
+  .action(async () => {
+    const result = await withDaemon({ type: "logout" }, () => undefined);
+    if (result.type === "signedOut") {
+      console.log(result.revoked ? "Signed out; the token is revoked." : "Signed out locally; the server could not be reached to revoke the token.");
+    } else {
+      fail(result);
+    }
+  });
+
+program
+  .command("list")
+  .description("list the skills that sync, as the server holds them; needs this machine signed in")
+  .action(async () => {
+    const result = await withDaemon({ type: "list" }, () => undefined);
+    if (result.type !== "list") fail(result);
+    if (result.skills.length === 0) {
+      console.log("No skills sync yet; tick them at https://skill-sync.jive.sh/");
+      return;
+    }
+    const width = Math.max(...result.skills.map((skill) => skill.name.length));
+    for (const skill of result.skills) {
+      const detail = skill.editedAt === null
+        ? "no files yet"
+        : `${skill.files} ${skill.files === 1 ? "file" : "files"}, last edited ${new Date(skill.editedAt).toLocaleString()} on ${skill.editedBy}`;
+      console.log(`${skill.name.padEnd(width)}  ${detail}`);
+    }
+  });
+
+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();
+
+/**
+ * Sends a request to the running daemon. If none is listening — stopped, or never started since the
+ * install — this package's registered daemon is started through its service manager and the request is
+ * retried for a few seconds.
+ */
+async function withDaemon(message: ControlRequest, onEvent: (event: ControlEvent) => void): Promise<ControlEvent> {
+  try {
+    return await request(message, onEvent);
+  } catch (cause) {
+    if (!(cause instanceof DaemonUnreachable)) throw cause;
+  }
+  await startDaemons();
+  for (let attempt = 0; ; attempt++) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    try {
+      return await request(message, onEvent);
+    } catch (cause) {
+      if (!(cause instanceof DaemonUnreachable) || attempt >= 20) {
+        console.error(`${cause instanceof Error ? cause.message : String(cause)}. Reinstall skill-sync to register its daemon.`);
+        process.exit(1);
+      }
+    }
+  }
+}
+
+function fail(event: ControlEvent): never {
+  console.error(event.type === "error" ? event.message : `unexpected answer from the daemon: ${JSON.stringify(event)}`);
+  process.exit(1);
+}
+
+/** Starts this package's registered daemons through their service manager. */
+async function startDaemons(): Promise<void> {
+  const statuses = await Effect.runPromise(daemonStatuses).catch(() => []);
+  const ours = statuses.filter((status) => status.registration.packageName === name && status.executableExists);
+  if (ours.length === 0) {
+    return;
+  }
+  for (const { registration } of ours) {
+    const command: string[] = registration.kind === "launchd"
+      ? ["launchctl", "kickstart", "-k", `gui/${process.getuid?.() ?? 0}/${registration.unit}`]
+      : registration.kind === "systemd"
+        ? ["systemctl", "--user", "restart", registration.unit]
+        : ["schtasks", "/Run", "/TN", registration.unit];
+    const result = spawnSync(command[0]!, command.slice(1), { stdio: ["ignore", "ignore", "pipe"] });
+    if (result.status !== 0) {
+      console.error(`Could not start ${registration.unit}: ${String(result.stderr ?? "").trim() || `exit ${result.status}`}`);
+    }
+  }
+}
+
+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, ListedSkill, ListFilesResponse, ListSkillsResponse, LocalSkill, MachineView, PutFileRequest, RemoteFile,
+  SkillView, Snapshot, SyncedSkill,
+} from "./internal/wire";