syndes 0.1.0 → 0.2.0

package/sync/transport.mjs

@@ -0,0 +1,203 @@
+/**
+ * How the pool is reached: a git remote, or a folder something else syncs.
+ *
+ * Both transports rest on one rule that makes the whole scheme work without a
+ * server, a lock or a merge strategy:
+ *
+ *   A device writes ONLY inside devices/<its own id>/ and reads everyone's.
+ *
+ * Because no two devices ever touch the same path, a concurrent push is a
+ * rebase over disjoint files, which always applies cleanly, and a Dropbox-style
+ * folder has nothing to conflict over. The distributed-writer problem is not
+ * solved here; it is removed.
+ *
+ * git is reached through execFile with an argv array and a hard timeout, never
+ * a shell string — a repository path with a space in it must not become a
+ * command injection, and a network hang must not wedge the dashboard.
+ *
+ * Credentials are deliberately NOT handled. The user's own git already knows how
+ * to authenticate to their remote; re-implementing that would mean holding a
+ * token we have no business holding. A push that fails for auth reports the
+ * failure verbatim, which is what makes it fixable.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { which } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const NET_TIMEOUT_MS = 25_000;
+const LOCAL_TIMEOUT_MS = 8_000;
+
+/** @returns {{ok: boolean, out: string, error: string|null}} */
+function git(cwd, args, timeout = LOCAL_TIMEOUT_MS) {
+  const binary = which('git');
+  if (!binary) return { ok: false, out: '', error: 'git is not installed or not on PATH' };
+
+  try {
+    const out = execFileSync(binary, args, {
+      cwd,
+      encoding: 'utf8',
+      timeout,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      // A prompt inside a detached poll would hang forever with nobody to answer.
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo' },
+    });
+    return { ok: true, out: out.trim(), error: null };
+  } catch (error) {
+    const stderr = String(error.stderr ?? '').trim();
+    debug('git failed', args.join(' '), stderr || error.message);
+    return { ok: false, out: '', error: (stderr || error.message).split('\n').slice(-3).join(' ').slice(0, 300) };
+  }
+}
+
+// ── git transport ───────────────────────────────────────────────────────────
+
+export const gitTransport = {
+  id: 'git',
+
+  /**
+   * Clone, or adopt an existing working copy.
+   *
+   * An empty remote has no branch to check out, so a fresh `main` is created
+   * rather than reporting a clone that "failed" on a repository the user just
+   * made and has every right to expect to work.
+   */
+  init(root, { repo }) {
+    if (!repo) return { ok: false, error: 'no repository url' };
+
+    if (existsSync(join(root, '.git'))) {
+      const set = git(root, ['remote', 'set-url', 'origin', repo]);
+      if (!set.ok) git(root, ['remote', 'add', 'origin', repo]);
+      return identify(root);
+    }
+
+    mkdirSync(root, { recursive: true });
+    const cloned = git(root, ['clone', '--depth', '50', repo, '.'], NET_TIMEOUT_MS);
+    if (!cloned.ok) {
+      // A brand-new empty repository clones with a warning and no HEAD.
+      const fresh = git(root, ['init']);
+      if (!fresh.ok) return { ok: false, error: cloned.error };
+      git(root, ['remote', 'add', 'origin', repo]);
+    }
+    if (!git(root, ['rev-parse', '--abbrev-ref', 'HEAD']).ok) git(root, ['checkout', '-b', 'main']);
+    return identify(root);
+  },
+
+  pull(root) {
+    if (!existsSync(join(root, '.git'))) return { ok: false, error: 'not initialised' };
+    // --autostash so a half-written publish never blocks the incoming update.
+    const pulled = git(root, ['pull', '--rebase', '--autostash', 'origin', branchOf(root)], NET_TIMEOUT_MS);
+    if (pulled.ok) return { ok: true, error: null };
+    // An empty remote has nothing to pull, which is not an error worth surfacing.
+    if (/couldn't find remote ref|does not appear to be a git repository|no such ref/i.test(pulled.error ?? '')) {
+      return { ok: true, error: null };
+    }
+    return { ok: false, error: pulled.error };
+  },
+
+  /** Commit and push our shelf. Silent when nothing under it changed. */
+  push(root, { deviceId, message }) {
+    const shelf = join('devices', deviceId);
+    const added = git(root, ['add', '--', shelf]);
+    if (!added.ok) return { ok: false, error: added.error, pushed: false };
+
+    const dirty = git(root, ['diff', '--cached', '--quiet', '--', shelf]);
+    if (dirty.ok) return { ok: true, error: null, pushed: false }; // exit 0 = no change
+
+    const committed = git(root, ['commit', '-m', message, '--', shelf]);
+    if (!committed.ok) return { ok: false, error: committed.error, pushed: false };
+
+    let pushed = git(root, ['push', 'origin', `HEAD:${branchOf(root)}`], NET_TIMEOUT_MS);
+    if (!pushed.ok) {
+      // Somebody else pushed between our pull and our push. Files are disjoint,
+      // so a rebase resolves it with no possibility of a content conflict.
+      this.pull(root);
+      pushed = git(root, ['push', 'origin', `HEAD:${branchOf(root)}`], NET_TIMEOUT_MS);
+    }
+    return { ok: pushed.ok, error: pushed.error, pushed: pushed.ok };
+  },
+
+  describe(root) {
+    const remote = git(root, ['remote', 'get-url', 'origin']);
+    return remote.ok ? remote.out : null;
+  },
+};
+
+function branchOf(root) {
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  return head.ok && head.out && head.out !== 'HEAD' ? head.out : 'main';
+}
+
+/** git refuses to commit without an identity, and a global one may not exist. */
+function identify(root) {
+  if (!git(root, ['config', 'user.email']).ok) {
+    git(root, ['config', 'user.email', 'syndes@localhost']);
+    git(root, ['config', 'user.name', 'syndes']);
+  }
+  return { ok: true, error: null };
+}
+
+// ── folder transport ────────────────────────────────────────────────────────
+
+/**
+ * A directory something else keeps in sync — Dropbox, iCloud, a network share.
+ *
+ * Nothing to do on pull or push: the files are already where everyone can see
+ * them. This exists because it is the correct answer for two people who do not
+ * want to run anything, and because having a second transport is what proves the
+ * pool logic does not secretly depend on git.
+ */
+export const folderTransport = {
+  id: 'folder',
+  init(root) {
+    try {
+      mkdirSync(root, { recursive: true });
+      return { ok: true, error: null };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  },
+  pull() { return { ok: true, error: null }; },
+  push() { return { ok: true, error: null, pushed: true }; },
+  describe(root) { return root; },
+};
+
+export function transportFor(kind) {
+  if (kind === 'git') return gitTransport;
+  if (kind === 'folder') return folderTransport;
+  return null;
+}
+
+// ── shelf io, shared by both transports ─────────────────────────────────────
+
+export function listDevices(root) {
+  try {
+    return readdirSync(join(root, 'devices'), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export function readJsonFile(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeJsonFile(file, data) {
+  writeFileSync(file, `${JSON.stringify(data)}\n`);
+}
+
+export function removeFile(file) {
+  try { rmSync(file, { force: true }); } catch { /* already gone */ }
+}
+
+export { git };