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

package/src/internal/control.ts

@@ -0,0 +1,123 @@
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { chmodSync, rmSync } from "node:fs";
+import { CONTROL_SOCKET } from "./config";
+
+/**
+ * The channel between the CLI and the running daemon.
+ *
+ * The daemon owns the sync token: it receives it from the browser and keeps it only in memory, so it is
+ * never in a file and never passes through the CLI. The CLI's `login` and `logout` are requests to the
+ * daemon over this channel. Messages are newline-delimited JSON; each request gets events until one that
+ * ends it.
+ */
+
+export type ControlRequest =
+  | { readonly type: "login" }
+  | { readonly type: "logout" };
+
+export type ControlEvent =
+  /** Sign-in has started: the CLI opens this URL in the browser, where the passkey is verified. */
+  | { readonly type: "open"; readonly url: string }
+  | { readonly type: "signedIn"; readonly machine: string }
+  | { readonly type: "signedOut"; readonly revoked: boolean }
+  | { readonly type: "error"; readonly message: string };
+
+const isFinal = (event: ControlEvent): boolean => event.type !== "open";
+
+/** The daemon is not running, as opposed to running and refusing the request. */
+export class DaemonUnreachable extends Error {}
+
+/** Sends one request and calls `onEvent` for each event until the final one, which it resolves with. */
+export function request(message: ControlRequest, onEvent: (event: ControlEvent) => void): Promise<ControlEvent> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const socket = createConnection(CONTROL_SOCKET);
+    socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
+    socket.on("error", (cause: NodeJS.ErrnoException) => {
+      if (settled) return;
+      settled = true;
+      reject(cause.code === "ENOENT" || cause.code === "ECONNREFUSED"
+        ? new DaemonUnreachable(`the skill-sync daemon is not running (${cause.code} on ${CONTROL_SOCKET})`)
+        : cause);
+    });
+    readLines(socket, (line) => {
+      const event = JSON.parse(line) as ControlEvent;
+      onEvent(event);
+      if (isFinal(event) && !settled) {
+        settled = true;
+        socket.end();
+        resolve(event);
+      }
+    });
+    socket.on("close", () => {
+      if (!settled) {
+        settled = true;
+        reject(new Error("the daemon closed the connection without answering"));
+      }
+    });
+  });
+}
+
+/** One request being answered: send events, and end the conversation with a final one. */
+export interface Reply {
+  readonly send: (event: ControlEvent) => void;
+}
+
+/**
+ * Listens on the control socket. Resolves false, without listening, when another live daemon already
+ * holds it: two installs of skill-sync mean two daemons, and the second stands down rather than fight.
+ */
+export async function serve(handle: (message: ControlRequest, reply: Reply) => void): Promise<Server | false> {
+  if (await answers()) return false;
+  // Nothing answered, so a socket file left here is from a daemon that died; it would block the listen.
+  if (process.platform !== "win32") rmSync(CONTROL_SOCKET, { force: true });
+
+  const server = createServer((socket) => {
+    const reply: Reply = {
+      send: (event) => {
+        if (socket.writable) socket.write(`${JSON.stringify(event)}\n`);
+        if (isFinal(event)) socket.end();
+      },
+    };
+    readLines(socket, (line) => {
+      try {
+        handle(JSON.parse(line) as ControlRequest, reply);
+      } catch (cause) {
+        reply.send({ type: "error", message: cause instanceof Error ? cause.message : String(cause) });
+      }
+    });
+    socket.on("error", () => undefined); // A CLI that went away mid-request; nothing to tell it.
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(CONTROL_SOCKET, () => resolve());
+  });
+  // Only this user may talk to the daemon that holds their token.
+  if (process.platform !== "win32") chmodSync(CONTROL_SOCKET, 0o600);
+  return server;
+}
+
+/** Whether a live daemon is listening on the control socket. */
+function answers(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(CONTROL_SOCKET);
+    socket.on("connect", () => {
+      socket.end();
+      resolve(true);
+    });
+    socket.on("error", () => resolve(false));
+  });
+}
+
+function readLines(socket: Socket, onLine: (line: string) => void): void {
+  let buffer = "";
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString();
+    let newline: number;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line !== "") onLine(line);
+    }
+  });
+}

package/src/internal/folders.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectFolders, hashBytes, listLocalFiles, type Config } from "./config";
+import {
+  skillOf, type FileHash, type FolderPrefs, type FoldersRequest, type FoldersResponse, type LocalSkill,
+} 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): LocalSkill[] {
+  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 }));
+}
+
+/** Everything registration sends, so a caller can tell when it has changed and is worth re-sending. */
+export function describe(config: Config): FoldersRequest {
+  return { folders: detectFolders().map((path) => ({ path, skills: localSkills(path, config) })) };
+}
+
+/** 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;
+}
+
+export function authHeaders(config: Config, extra: Record<string, string>): Record<string, string> {
+  return { authorization: `Bearer ${config.token}`, "x-skill-sync-machine": config.machine, ...extra };
+}

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/sync.ts

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { hashBytes, listLocalFiles, type Config, type State } from "./config";
+import { invalidPathReason } from "./path";
+import { skillOf, type ListFilesResponse, type PutFileRequest } from "./wire";
+
+/**
+ * One sync cycle: take every newer edit the server has, then send every newer edit this folder has.
+ *
+ * The latest edit wins, always. Every file carries the time it was last edited: here, the file's
+ * modification time; on the server, the edit time of the version it holds. When this folder and the
+ * server disagree about a file, whichever was edited later is kept, on both sides. Nothing is merged and
+ * nothing is set aside, so every folder converges on the same bytes.
+ *
+ * A pulled file is given the server's edit time as its modification time, so the next cycle does not
+ * mistake the pull for a local edit.
+ */
+
+export interface Report {
+  readonly pulled: string[];
+  readonly pushed: string[];
+  readonly deletedLocally: string[];
+  /** Paths the server offered that this machine refused to write. */
+  readonly rejected: string[];
+}
+
+/** 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.rejected].every((list) => list.length === 0);
+}
+
+/**
+ * `skills` is the synced list. Every other skill 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>): Promise<Report> {
+  const report: Report = { pulled: [], pushed: [], deletedLocally: [], rejected: [] };
+  mkdirSync(folder, { recursive: true });
+
+  // A skill added to the list 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 removed from the list stops being tracked here. Left in `known`, its files would look deleted
+  // from this folder and the push would delete 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))));
+  // Files deleted here since the last cycle. When they were deleted is not recorded anywhere, so the
+  // deletion counts as an edit made now: the pull leaves these paths alone and the push deletes them.
+  const deletedHere = new Set(Object.keys(state.known).filter((path) => !present.has(path)));
+
+  const ctx: Cycle = { config, folder, state, report, skills };
+  await pull(ctx, deletedHere, present);
+  await push(ctx, present);
+  return report;
+}
+
+interface Cycle {
+  readonly config: Config;
+  readonly folder: string;
+  readonly state: State;
+  readonly report: Report;
+  readonly skills: ReadonlySet<string>;
+}
+
+/** When this file was last edited here, to the millisecond the server stores. */
+const editedAt = (file: string): number => Math.floor(statSync(file).mtimeMs);
+
+async function pull(ctx: Cycle, deletedHere: ReadonlySet<string>, present: Set<string>): Promise<void> {
+  const { config, folder, state, report } = ctx;
+  const body = await (await call(config, `/files?since=${state.cursor}`)).json() as ListFilesResponse;
+
+  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;
+    }
+    if (!ctx.skills.has(skillOf(file.path))) continue;
+    // Deleted here, which is newer than anything the server has; the push sends the deletion.
+    if (deletedHere.has(file.path)) continue;
+
+    const local = join(folder, file.path);
+    const exists = existsSync(local);
+    const localHash = exists ? hashBytes(readFileSync(local)) : undefined;
+    if (localHash === (file.hash ?? undefined)) {
+      if (file.hash === null) delete state.known[file.path];
+      else state.known[file.path] = file.hash;
+      continue;
+    }
+    // Edited here since this folder last agreed with the server, and later than the server's version:
+    // this folder's edit wins, and the push sends it.
+    if (exists && localHash !== state.known[file.path] && editedAt(local) > file.editedAt) continue;
+
+    await apply(ctx, file, present);
+  }
+
+  state.cursor = body.cursor;
+}
+
+async function push(ctx: Cycle, present: Set<string>): Promise<void> {
+  const { config, folder, state, report } = ctx;
+  for (const path of [...present]) {
+    const file = join(folder, path);
+    const bytes = readFileSync(file);
+    const hash = hashBytes(bytes);
+    if (state.known[path] === hash) continue;
+    const later = await put(config, { path, hash, content: Buffer.from(bytes).toString("base64"), editedAt: editedAt(file) });
+    if (later === undefined) {
+      state.known[path] = hash;
+      report.pushed.push(path);
+    } else {
+      await apply(ctx, { path, ...later }, present);
+    }
+  }
+
+  // A path this folder agreed on that is no longer on disk was deleted here. The server keeps the
+  // deletion, or the next machine to sync would upload the file again.
+  for (const path of Object.keys(state.known)) {
+    if (present.has(path)) continue;
+    const later = await put(config, { path, hash: null, content: null, editedAt: Date.now() });
+    if (later === undefined) {
+      delete state.known[path];
+      report.pushed.push(`${path} (deleted)`);
+    } else {
+      await apply(ctx, { path, ...later }, present);
+    }
+  }
+}
+
+/** The server's version of a file, as it answers a refused write. */
+interface ServerVersion {
+  readonly hash: string | null;
+  readonly editedAt: number;
+}
+
+/**
+ * Writes the server's version of a file here: its bytes with its edit time, or a deletion. Used by the
+ * pull, and by the push when the server refuses a write because it holds a later edit, so a refused write
+ * settles at once rather than waiting for a pull that may never list the file again.
+ */
+async function apply(ctx: Cycle, file: ServerVersion & { readonly path: string }, present: Set<string>): Promise<void> {
+  const { config, folder, state, report } = ctx;
+  const local = join(folder, file.path);
+  if (file.hash === null) {
+    rmSync(local, { force: true });
+    removeEmptyParents(folder, local);
+    present.delete(file.path);
+    delete state.known[file.path];
+    report.deletedLocally.push(file.path);
+    return;
+  }
+  const content = new Uint8Array(await (await call(config, `/content/${file.hash}`)).arrayBuffer());
+  mkdirSync(dirname(local), { recursive: true });
+  writeFileSync(local, content);
+  utimesSync(local, new Date(), new Date(file.editedAt));
+  state.known[file.path] = file.hash;
+  present.add(file.path);
+  report.pulled.push(file.path);
+}
+
+/** A deleted skill leaves no empty directory behind, which would still show up as a skill. */
+function removeEmptyParents(folder: string, file: string): void {
+  for (let dir = dirname(file); dir !== folder && dir.startsWith(folder); dir = dirname(dir)) {
+    if (readdirSync(dir).length > 0) return;
+    rmdirSync(dir);
+  }
+}
+
+/** Undefined when the server took the write; otherwise the later version it holds instead. */
+async function put(config: Config, body: Omit<PutFileRequest, "machine">): Promise<ServerVersion | undefined> {
+  const request: PutFileRequest = { ...body, machine: config.machine };
+  const response = await fetch(`${config.endpoint}/files`, {
+    method: "PUT",
+    headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
+    body: JSON.stringify(request),
+  });
+  if (response.status === 409) {
+    const current = await response.json() as { currentHash: string | null; currentEditedAt: number };
+    return { hash: current.currentHash, editedAt: current.currentEditedAt };
+  }
+  if (!response.ok) throw new Error(`PUT /files ${body.path}: ${response.status} ${await response.text()}`);
+  return undefined;
+}
+
+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;
+}

package/src/internal/wire.ts

@@ -0,0 +1,141 @@
+/**
+ * The shapes the daemon and the service exchange.
+ *
+ * Declared in the library and imported by the service so there is one definition rather than two that
+ * drift. The service depends on the library; nothing goes the other way.
+ */
+
+export interface RemoteFile {
+  readonly path: string;
+  /** Null when the file is deleted; the row stays, so the deletion reaches every machine. */
+  readonly hash: string | null;
+  /** When this version was edited, in milliseconds since the epoch. The latest edit wins. */
+  readonly editedAt: number;
+  readonly updatedBy: string;
+}
+
+export interface ListFilesResponse {
+  /** Highest sequence number in this page; the caller sends it back as `since`. */
+  readonly cursor: number;
+  readonly files: ReadonlyArray<RemoteFile>;
+}
+
+/** Taken only when `editedAt` is later than the edit the server holds; refused with 409 otherwise. */
+export interface PutFileRequest {
+  readonly path: string;
+  /** When the file was edited: its modification time, or for a deletion, when it was noticed. */
+  readonly editedAt: number;
+  /** Null to delete. */
+  readonly hash: string | null;
+  /** Base64, absent for a delete. */
+  readonly content: string | null;
+  readonly machine: string;
+}
+
+/** Where a folder's sync stands, as the dashboard shows it. `attention` means a cycle failed; `detail` says why. */
+export type FolderState = "idle" | "attention";
+
+/**
+ * A skill is a top-level entry of a skills folder — usually a directory like `jive/` holding `SKILL.md`
+ * and its files — and it is the unit of opting in: all of its files sync, or none do, so a skill never
+ * arrives half-present on another machine.
+ */
+export const skillOf = (path: string): string => path.split("/")[0]!;
+
+/** A file and the SHA-256 of its content — the same hash the server stores, so copies can be compared. */
+export interface FileHash {
+  readonly path: string;
+  readonly hash: string;
+}
+
+/** One skill as a folder holds it. */
+export interface LocalSkill {
+  readonly name: string;
+  readonly files: ReadonlyArray<FileHash>;
+}
+
+/**
+ * `POST /folders`: every folder this machine found, with the skills in each, for the dashboard. Answered
+ * with the enabled folders, each with the synced list: the daemon pushes and pulls exactly those skills,
+ * and never touches any other.
+ */
+export interface FoldersRequest {
+  readonly folders: ReadonlyArray<{ readonly path: string; readonly skills: ReadonlyArray<LocalSkill> }>;
+}
+export interface FolderPrefs {
+  readonly path: string;
+  readonly skills: ReadonlyArray<string>;
+}
+export interface FoldersResponse {
+  readonly folders: ReadonlyArray<FolderPrefs>;
+}
+
+/** Daemon → hub, over the daemon's WebSocket. */
+export type DaemonMessage = {
+  readonly type: "status";
+  readonly folder: string;
+  readonly state: FolderState;
+  readonly detail?: string;
+  /** A one-line summary of what the last cycle changed, when it changed anything. */
+  readonly activity?: string;
+};
+
+/** Hub → daemon. `prefs` replaces what syncs; `changed` means another write landed on the server. */
+export type HubToDaemon =
+  | { readonly type: "prefs"; readonly folders: ReadonlyArray<FolderPrefs> }
+  | { readonly type: "changed" };
+
+export interface SkillView {
+  readonly name: string;
+  /** On the list of synced skills, which every enabled folder sends and receives. */
+  readonly synced: boolean;
+  /** The folder has a copy on disk. */
+  readonly local: boolean;
+  readonly files: ReadonlyArray<FileHash>;
+}
+
+export interface FolderView {
+  readonly path: string;
+  readonly enabled: boolean;
+  readonly state: FolderState;
+  readonly detail: string | null;
+  readonly lastActivityAt: number | null;
+  readonly lastActivity: string | null;
+  readonly skills: ReadonlyArray<SkillView>;
+}
+
+export interface MachineView {
+  /** The name the machine's daemon uses; it identifies the machine and never changes. */
+  readonly machine: string;
+  /** What the dashboard calls it: renamed there, or the machine name until then. */
+  readonly name: string;
+  /** True while this machine's daemon holds a connection to the hub. */
+  readonly online: boolean;
+  readonly lastSeen: number | null;
+  readonly folders: ReadonlyArray<FolderView>;
+}
+
+/** A skill on the synced list, as the server holds it: the version every enabled folder converges on. */
+export interface SyncedSkill {
+  readonly name: string;
+  readonly files: ReadonlyArray<FileHash & { readonly updatedBy: string; readonly editedAt: number }>;
+}
+
+/** Hub → dashboard: the whole picture, resent on every change. It is small, and a diff protocol is not. */
+export interface Snapshot {
+  readonly type: "snapshot";
+  /** The deployed service version. A dashboard built by another version reloads itself. */
+  readonly version: string;
+  /** Display name for every machine name that appears anywhere in the snapshot, including old log entries. */
+  readonly names: Readonly<Record<string, string>>;
+  readonly skills: ReadonlyArray<SyncedSkill>;
+  readonly machines: ReadonlyArray<MachineView>;
+}
+
+/** Dashboard → hub. */
+export type DashboardMessage =
+  | { readonly type: "setFolder"; readonly machine: string; readonly path: string; readonly enabled: boolean }
+  /** Adds a skill to the synced list, or removes it: one list for every machine and folder. */
+  | { readonly type: "setSkill"; readonly skill: string; readonly synced: boolean }
+  /** An empty name restores the machine name. */
+  | { readonly type: "renameMachine"; readonly machine: string; readonly name: string };

package/multi-call-binary

@@ -1,4 +0,0 @@
-[diffend] Oversized file quarantined before diffing.
-name: package/multi-call-binary
-size: 91174370 bytes
-sha256: f59b146b747e2e96e2b1470718fbe038382006a49a67845c55783ef053c6d3e4