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

package/src/internal/notify.ts

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+
+/**
+ * A desktop notification, best effort.
+ *
+ * Best effort is the whole contract: a daemon that cannot tell you about a conflict is worse than one
+ * that cannot sync, but a daemon that *dies* because a notification helper is missing is worse than
+ * both. Every failure here is swallowed.
+ *
+ * This works because these daemons are registered per-user and run inside the logged-in session — a
+ * LaunchAgent, a `systemctl --user` unit, a scheduled task. A system-wide service would have no desktop
+ * to post to.
+ */
+
+/** No shell anywhere below: the arguments carry file paths, and a path is not a safe thing to interpolate. */
+function run(command: string, args: ReadonlyArray<string>): void {
+  try {
+    spawn(command, [...args], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Swallowed on purpose; see above.
+  }
+}
+
+export function notify(title: string, body: string): void {
+  switch (process.platform) {
+    case "darwin":
+      // AppleScript string literals take double quotes and backslashes as escapes, and nothing else.
+      return run("osascript", [
+        "-e",
+        `display notification "${escapeAppleScript(body)}" with title "${escapeAppleScript(title)}"`,
+      ]);
+    case "linux":
+      return run("notify-send", [title, body]);
+    case "win32":
+      return run("powershell", [
+        "-NoProfile", "-NonInteractive", "-Command",
+        "[reflection.assembly]::LoadWithPartialName('System.Windows.Forms') > $null;"
+        + "$n = New-Object System.Windows.Forms.NotifyIcon;"
+        + "$n.Icon = [System.Drawing.SystemIcons]::Warning; $n.Visible = $true;"
+        + `$n.ShowBalloonTip(10000, '${escapeSingleQuotes(title)}', '${escapeSingleQuotes(body)}', 'Warning')`,
+      ]);
+    default:
+      return;
+  }
+}
+
+function escapeAppleScript(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function escapeSingleQuotes(value: string): string {
+  return value.replace(/'/g, "''");
+}

package/src/internal/path.ts

@@ -0,0 +1,32 @@
+/**
+ * Validation for the one piece of untrusted input that becomes a filesystem path.
+ *
+ * Shared by the Worker and the daemon on purpose, and deliberately free of any Node import so the Worker
+ * can bundle it. Both ends check: the server so one compromised client cannot poison what every machine
+ * pulls, and the daemon because a server it does not control is not a thing to take paths from either.
+ *
+ * Without this, a pushed path of `../../.ssh/authorized_keys` is joined to the skills directory and
+ * written wherever the daemon's user can write.
+ */
+
+/** Long enough for any real nesting, short enough that nothing can be used to exhaust anything. */
+const MAX_LENGTH = 512;
+
+export function invalidPathReason(path: string): string | undefined {
+  if (path.length === 0 || path.length > MAX_LENGTH) return "path is empty or too long";
+  if (path.includes("\0")) return "path contains a null byte";
+  if (path.includes("\\")) return "path must use forward slashes";
+  if (path.startsWith("/")) return "path must be relative";
+  // A Windows drive letter is absolute on the machine that matters even though it has no leading slash.
+  if (/^[A-Za-z]:/.test(path)) return "path must be relative";
+
+  for (const segment of path.split("/")) {
+    if (segment === "") return "path has an empty segment";
+    if (segment === "." || segment === "..") return "path must not contain . or .. segments";
+  }
+  return undefined;
+}
+
+export function isValidPath(path: string): boolean {
+  return invalidPathReason(path) === undefined;
+}

package/src/internal/reconcile.ts

@@ -0,0 +1,166 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join } from "node:path";
+
+/**
+ * Merges two versions of one skill file with Claude, on this machine.
+ *
+ * A conflict used to mean "the server's copy wins and yours is set aside as `.local`", which left the
+ * merge to a person who might not notice for days, while every machine ran the losing half. Skills are
+ * prose that Claude reads, so Claude is the right one to merge them: it keeps every rule either side
+ * added and resolves the ones that disagree.
+ *
+ * Claude runs with no tools, no MCP servers and no settings: it receives the versions on stdin and
+ * answers with the merged file, so it cannot touch anything else. It runs as the Claude account whose
+ * folder is being merged (`CLAUDE_CONFIG_DIR` set to that folder's home), so it never creates or writes
+ * `~/.claude` — a home the user may have deleted on purpose.
+ */
+
+export interface Version {
+  readonly content: string;
+  /** Where this version came from, for the prompt: "this machine, edited …" or "MacBookPro, uploaded …". */
+  readonly label: string;
+}
+
+/** The merged file, and Claude's account of it for the audit log. */
+export interface Resolution {
+  readonly merged: string;
+  /** What differed between the two versions. */
+  readonly conflict: string;
+  /** What the merge kept, dropped or reworded. */
+  readonly resolution: string;
+}
+
+export interface Conflict {
+  readonly folder: string;
+  readonly path: string;
+  readonly local: Version;
+  readonly remote: Version;
+  /** The last version both sides agreed on, when there is one; it lets Claude see what each side changed. */
+  readonly base: string | null;
+}
+
+const BACKUP_ROOT = join(homedir(), ".jive", "skill-sync", "reconciled");
+/** A long skill is tens of thousands of tokens to write back out. */
+const TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * A merge shorter than this fraction of the longer input is refused as probably truncated: a model that
+ * stops early produces a file that looks fine and silently drops half the rules.
+ */
+const MIN_LENGTH_RATIO = 0.6;
+
+const SYSTEM_PROMPT = `You merge two versions of one file from a user's Claude skills folder into one.
+Answer in exactly this form and nothing else:
+<conflict>One or two plain sentences: what differs between the versions.</conflict>
+<resolution>One or two plain sentences: what the merge kept from each, and anything dropped or reworded.</resolution>
+<merged>
+The complete merged file, exactly as it should be saved. No code fences.
+</merged>
+Rules for the merge:
+- Keep every rule, example and fact that either version has, unless the other version clearly replaces it.
+- Where the two disagree, prefer the newer version's wording, and keep anything only the older one has.
+- If a base version is given, it is what both started from: use it to tell additions from deletions, and
+  honour a deletion made on one side when the other side did not edit that part.
+- Keep the file's frontmatter and structure.
+In <conflict> and <resolution>, call the two versions by the names they are given (for example "the copy in
+~/.claude-chaine/skills on MacBookPro" and "the synced copy"), never "Version A" or "Version B": these are
+read later by a person auditing the merge, who never saw this prompt.`;
+
+/**
+ * Both versions are copied out of the synced folder before anything is written, so a bad merge costs a
+ * file copy, not the user's work. Outside the folder so the copies are never synced or read as skills.
+ */
+export function backUp(conflict: Conflict): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dir = join(BACKUP_ROOT, stamp, basename(dirname(conflict.folder)), conflict.path);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "local"), conflict.local.content);
+  writeFileSync(join(dir, "remote"), conflict.remote.content);
+  if (conflict.base !== null) writeFileSync(join(dir, "base"), conflict.base);
+  return dir;
+}
+
+export async function reconcile(conflict: Conflict): Promise<Resolution> {
+  const sections = [
+    `File: ${conflict.path}`,
+    conflict.base === null ? "No base version: these two have never been in sync." : `=== the base version both started from:\n${conflict.base}`,
+    `=== ${conflict.local.label}:\n${conflict.local.content}`,
+    `=== ${conflict.remote.label}:\n${conflict.remote.content}`,
+    "Write the merged file now.",
+  ];
+  const answer = await runClaude(sections.join("\n\n-----\n\n"), dirname(conflict.folder));
+  const start = answer.indexOf("<merged>");
+  const end = answer.lastIndexOf("</merged>");
+  if (start === -1 || end <= start) throw new Error("Claude's answer had no <merged> section");
+  // The file is everything between the tags, minus the newline that follows the opening one.
+  const merged = answer.slice(start + "<merged>".length, end).replace(/^\r?\n/, "");
+  const conflictText = /<conflict>([\s\S]*?)<\/conflict>/.exec(answer)?.[1]?.trim() ?? "";
+  const resolutionText = /<resolution>([\s\S]*?)<\/resolution>/.exec(answer)?.[1]?.trim() ?? "";
+
+  const longest = Math.max(conflict.local.content.length, conflict.remote.content.length);
+  if (merged.trim().length === 0) throw new Error("Claude returned an empty merge");
+  if (merged.length < longest * MIN_LENGTH_RATIO) {
+    throw new Error(`the merge is ${merged.length} characters against ${longest}; refusing it as probably truncated`);
+  }
+  return {
+    merged: merged.endsWith("\n") ? merged : `${merged}\n`,
+    conflict: conflictText || "Claude did not describe the conflict.",
+    resolution: resolutionText || "Claude did not describe the resolution.",
+  };
+}
+
+/** `configDir` is the Claude home that owns the folder, e.g. `~/.claude-chaine` for `~/.claude-chaine/skills`. */
+function runClaude(input: string, configDir: string): Promise<string> {
+  const claude = findClaude();
+  if (claude === undefined) return Promise.reject(new Error("the claude CLI is not installed"));
+
+  // Always set, never inherited or left unset: unset, `claude` falls back to `~/.claude` and writes its
+  // session files, backups and caches there, recreating that home every time it is deleted.
+  const env = { ...process.env, CLAUDE_CONFIG_DIR: configDir };
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(claude, [
+      "-p", "--output-format", "json", "--tools", "", "--strict-mcp-config", "--setting-sources", "",
+      "--no-session-persistence", "--system-prompt", SYSTEM_PROMPT,
+    ], { env, cwd: homedir(), stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+    const timer = setTimeout(() => child.kill("SIGTERM"), TIMEOUT_MS);
+
+    child.on("error", (cause) => { clearTimeout(timer); reject(cause); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      try {
+        const result = JSON.parse(stdout) as { is_error?: boolean; result?: string };
+        if (code !== 0 || result.is_error || typeof result.result !== "string") {
+          reject(new Error(`claude failed (exit ${code}): ${result.result ?? stderr.trim()}`));
+        } else {
+          resolve(result.result);
+        }
+      } catch {
+        reject(new Error(`claude failed (exit ${code}): ${stderr.trim() || stdout.slice(0, 300)}`));
+      }
+    });
+    child.stdin.end(input);
+  });
+}
+
+/**
+ * The daemon starts at login with the service manager's minimal PATH, which rarely includes where the
+ * Claude installer puts `claude`, so the usual install locations are checked too.
+ */
+function findClaude(): string | undefined {
+  const name = process.platform === "win32" ? "claude.exe" : "claude";
+  const fromPath = (process.env["PATH"] ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, name));
+  const known = [
+    join(homedir(), ".local", "bin", name),
+    join(homedir(), ".claude", "local", "claude"),
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+  ];
+  return [...fromPath, ...known].find((candidate) => existsSync(candidate));
+}

package/src/internal/sync.ts

@@ -0,0 +1,304 @@
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONFLICT_SUFFIX, hashBytes, listLocalFiles, type Config, type State } from "./config";
+import { invalidPathReason } from "./path";
+import { backUp, type Conflict, type Resolution } from "./reconcile";
+import { skillOf, type ReconciliationRequest } from "./wire";
+
+/**
+ * One sync cycle: take everything the server has that we do not, then offer everything we have that it
+ * does not.
+ *
+ * Pull before push, deliberately. Pushing first would send a file the server already changed, get it
+ * refused, and report a conflict that pulling would have resolved on its own.
+ */
+
+interface RemoteFile {
+  readonly path: string;
+  readonly hash: string | null;
+  readonly deleted: boolean;
+  readonly updatedAt: number;
+  readonly updatedBy: string;
+}
+
+/**
+ * How a cycle resolves a file changed both here and on the server. Without a `merge`, the server's copy
+ * wins and this machine's is kept beside it as `.local`; with one, the two are merged and the result
+ * is pushed. `onMerging` fires before a merge starts, since one can take minutes.
+ */
+export interface Reconciler {
+  readonly merge: (conflict: Conflict) => Promise<Resolution>;
+  readonly onMerging?: (path: string) => void;
+}
+
+export interface Report {
+  readonly pulled: string[];
+  readonly pushed: string[];
+  readonly deletedLocally: string[];
+  readonly conflicts: string[];
+  /** Paths changed on both sides and merged; the merge is pushed in the same cycle. */
+  readonly merged: string[];
+  /** Merges that failed, with the reason; those paths fell back to `.local`. */
+  readonly mergeFailures: string[];
+  /** Every merge attempted this cycle, for the audit log. */
+  readonly reconciliations: Omit<ReconciliationRequest, "folder">[];
+  /** Paths the server offered that this machine refused to write. */
+  readonly rejected: string[];
+  /** A push lost a race to another machine; the next cycle pulls and reconciles it. */
+  retry: boolean;
+}
+
+/** True when a report has nothing in it worth telling anyone. */
+export function isQuiet(report: Report): boolean {
+  return [report.pulled, report.pushed, report.deletedLocally, report.conflicts, report.merged,
+    report.mergeFailures, report.rejected].every((list) => list.length === 0);
+}
+
+/**
+ * `skills` are the skills this folder has opted into. Everything else in the folder is local to it: never
+ * pushed, never overwritten, never deleted by a sync.
+ */
+export async function syncOnce(
+  config: Config, folder: string, state: State, skills: ReadonlySet<string>, reconciler?: Reconciler,
+): Promise<Report> {
+  const report: Report = {
+    pulled: [], pushed: [], deletedLocally: [], conflicts: [], merged: [], mergeFailures: [], reconciliations: [],
+    rejected: [], retry: false,
+  };
+  mkdirSync(folder, { recursive: true });
+
+  // A skill opted in since last cycle may have server files older than the cursor; re-read from the start.
+  if ([...skills].some((skill) => !(state.skills ?? []).includes(skill))) state.cursor = 0;
+  state.skills = [...skills].sort();
+  // A skill opted out stops being tracked here. Left in `known`, its files would look deleted from this
+  // folder and the push would tombstone them on every machine.
+  for (const path of Object.keys(state.known)) {
+    if (!skills.has(skillOf(path))) delete state.known[path];
+  }
+
+  const present = new Set(listLocalFiles(folder, config.exclude).filter((path) => skills.has(skillOf(path))));
+  const ctx: Cycle = { config, folder, state, report, reconciler, skills };
+
+  /**
+   * Files deleted here since the last cycle, worked out before anything is fetched.
+   *
+   * A push does not advance this machine's cursor, so the next pull sees its own earlier write as news.
+   * With the file now gone from disk that looked like "remote has it, we do not" and the pull put it
+   * straight back, undoing the delete every time. Deciding what was deleted up front, and refusing to
+   * recreate those paths, is what lets the push below turn them into tombstones.
+   */
+  const pendingDeletes = new Set(Object.keys(state.known).filter((path) => !present.has(path)));
+
+  // `present` is passed through both passes and kept current: the pull removes tombstoned files and adds
+  // new ones, and a push that read a stale snapshot would try to open a file the pull had just deleted.
+  await pull(ctx, pendingDeletes, present);
+  await push(ctx, present);
+  return report;
+}
+
+interface Cycle {
+  readonly config: Config;
+  readonly folder: string;
+  readonly state: State;
+  readonly report: Report;
+  readonly reconciler: Reconciler | undefined;
+  readonly skills: ReadonlySet<string>;
+}
+
+async function pull(ctx: Cycle, pendingDeletes: Set<string>, present: Set<string>): Promise<void> {
+  const { config, folder, state, report } = ctx;
+  const response = await call(config, `/files?since=${state.cursor}`);
+  const body = await response.json() as { cursor: number; files: RemoteFile[] };
+
+  for (const file of body.files) {
+    // The server is not trusted to supply a path either: one bad row would otherwise write outside the
+    // skills directory on every machine that syncs.
+    const badPath = invalidPathReason(file.path);
+    if (badPath) {
+      report.rejected.push(`${file.path} (${badPath})`);
+      continue;
+    }
+    // Local to this folder: the server's version is not wanted here.
+    if (!ctx.skills.has(skillOf(file.path))) continue;
+    const local = join(folder, file.path);
+    // Deleted here and not yet reported; the push pass owns this path for the rest of the cycle.
+    if (pendingDeletes.has(file.path)) continue;
+
+    if (file.deleted) {
+      if (existsSync(local)) {
+        // Never destroy content this machine never agreed with the server on. A file written here that
+        // the server happens to have tombstoned — a fresh machine, or one that was offline through the
+        // delete — is not the same file, and deleting it silently would lose work nobody could recover.
+        const localHash = hashBytes(readFileSync(local));
+        if (localHash !== state.known[file.path]) {
+          writeFileSync(`${local}${CONFLICT_SUFFIX}`, readFileSync(local));
+          report.conflicts.push(file.path);
+        }
+        rmSync(local, { force: true });
+        report.deletedLocally.push(file.path);
+      }
+      present.delete(file.path);
+      delete state.known[file.path];
+      continue;
+    }
+
+    const localHash = existsSync(local) ? hashBytes(readFileSync(local)) : undefined;
+    if (localHash === file.hash) {
+      // Already identical — record agreement so the push pass does not treat it as a local edit.
+      state.known[file.path] = file.hash!;
+      continue;
+    }
+
+    const content = new Uint8Array(await (await call(config, `/content/${file.hash}`)).arrayBuffer());
+
+    // Changed here and on the server. Merge the two when possible: the merge is written here, recorded as
+    // based on the server's copy, and so goes out in this cycle's push.
+    if (localHash !== undefined && localHash !== state.known[file.path]) {
+      if (await mergeInto(ctx, file, local, content)) {
+        present.add(file.path);
+        continue;
+      }
+      // No merge: a local edit we have not pushed yet would be destroyed by overwriting, so it is kept
+      // beside the incoming copy.
+      writeFileSync(`${local}${CONFLICT_SUFFIX}`, readFileSync(local));
+      report.conflicts.push(file.path);
+    }
+
+    mkdirSync(dirname(local), { recursive: true });
+    writeFileSync(local, content);
+    state.known[file.path] = file.hash!;
+    present.add(file.path);
+    report.pulled.push(file.path);
+  }
+
+  state.cursor = body.cursor;
+}
+
+/**
+ * Merges this machine's copy with the server's and writes the result over the local file. False when
+ * there is no merger, either side is not text, or the merge failed — the caller then keeps `.local`.
+ */
+async function mergeInto(ctx: Cycle, file: RemoteFile, local: string, remote: Uint8Array): Promise<boolean> {
+  const { config, folder, state, report, reconciler } = ctx;
+  if (reconciler === undefined) return false;
+
+  const mine = readFileSync(local);
+  const localText = asText(mine);
+  const remoteText = asText(remote);
+  if (localText === undefined || remoteText === undefined) return false;
+
+  const known = state.known[file.path];
+  const base = known === undefined ? null : await fetchText(config, known);
+  const conflict: Conflict = {
+    folder,
+    path: file.path,
+    local: {
+      content: localText,
+      label: `the copy in ${folder} on ${config.machine}, last edited ${statSync(local).mtime.toISOString()}`,
+    },
+    remote: {
+      content: remoteText,
+      label: `the synced copy, last uploaded by ${file.updatedBy} at ${new Date(file.updatedAt).toISOString()}`,
+    },
+    base,
+  };
+
+  backUp(conflict);
+  reconciler.onMerging?.(file.path);
+  let resolution: Resolution;
+  try {
+    resolution = await reconciler.merge(conflict);
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    report.mergeFailures.push(`${file.path}: ${reason}`);
+    report.reconciliations.push({
+      path: file.path, outcome: "failed",
+      conflict: "This machine's copy and the server's differ.",
+      resolution: `Not merged: ${reason}. The server's version was kept and this machine's saved as ${file.path}${CONFLICT_SUFFIX}.`,
+    });
+    return false;
+  }
+  writeFileSync(local, resolution.merged);
+  state.known[file.path] = file.hash!;
+  report.merged.push(file.path);
+  report.reconciliations.push({
+    path: file.path, outcome: "merged", conflict: resolution.conflict, resolution: resolution.resolution,
+  });
+  return true;
+}
+
+/** Text only: a merge by a language model is meaningless for an image or a binary, and harmful. */
+function asText(bytes: Uint8Array): string | undefined {
+  if (bytes.length > 512 * 1024 || bytes.includes(0)) return undefined;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The base is a nicety for the merge; if the server no longer has it, merge without one. */
+async function fetchText(config: Config, hash: string): Promise<string | null> {
+  try {
+    return asText(new Uint8Array(await (await call(config, `/content/${hash}`)).arrayBuffer())) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function push(ctx: Cycle, present: Set<string>): Promise<void> {
+  const { config, folder, state, report } = ctx;
+  for (const path of present) {
+    const bytes = readFileSync(join(folder, path));
+    const hash = hashBytes(bytes);
+    if (state.known[path] === hash) continue;
+
+    const accepted = await put(config, {
+      path,
+      baseHash: state.known[path] ?? null,
+      hash,
+      content: Buffer.from(bytes).toString("base64"),
+    });
+    if (accepted) {
+      state.known[path] = hash;
+      report.pushed.push(path);
+    } else {
+      // Another machine wrote first. Not a conflict yet: the next cycle pulls its version and merges.
+      report.retry = true;
+    }
+  }
+
+  // A path we previously agreed on that is no longer on disk was deleted here, and the server needs the
+  // tombstone or the next machine to sync will upload it back.
+  for (const path of Object.keys(state.known)) {
+    if (present.has(path)) continue;
+    if (await put(config, { path, baseHash: state.known[path]!, hash: null, content: null })) {
+      delete state.known[path];
+      report.pushed.push(`${path} (deleted)`);
+    } else {
+      report.conflicts.push(path);
+    }
+  }
+}
+
+/** True when the server accepted the write; false means another machine got there first. */
+async function put(config: Config, body: {
+  path: string; baseHash: string | null; hash: string | null; content: string | null;
+}): Promise<boolean> {
+  const response = await fetch(`${config.endpoint}/files`, {
+    method: "PUT",
+    headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
+    body: JSON.stringify({ ...body, machine: config.machine }),
+  });
+  if (response.status === 409) return false;
+  if (!response.ok) throw new Error(`PUT /files ${body.path}: ${response.status} ${await response.text()}`);
+  return true;
+}
+
+async function call(config: Config, path: string): Promise<Response> {
+  const response = await fetch(`${config.endpoint}${path}`, {
+    headers: { authorization: `Bearer ${config.token}` },
+  });
+  if (!response.ok) throw new Error(`GET ${path}: ${response.status} ${await response.text()}`);
+  return response;
+}