parawatch 0.2.1 → 0.3.1

package/README.md

@@ -267,12 +267,43 @@ parawatch watch --from 120       # starting after event 120
 
 ## Storage
 
-Everything lives in one append-only file, `~/.local/state/parawatch/events.jsonl` (`$PARAWATCH_HOME`, or `$XDG_STATE_HOME/parawatch`). Writers take a short lock, so several agents can write at once. Next to it: cursors in `cursors/`, running waits in `listeners/`, the last GitHub reading in `github.json`, the last update check in `update.json`, the version each copy (CLI, app) last ran in `clients/`, and the optional `config.json`. Delete the folder to start over.
+Everything lives in one append-only file, `~/.local/state/parawatch/events.jsonl` (`$PARAWATCH_HOME`, or `$XDG_STATE_HOME/parawatch`). Writers take a short lock, so several agents can write at once. Next to it: cursors in `cursors/`, running waits in `listeners/`, the last GitHub reading in `github.json`, the last update check in `update.json`, the version each copy (CLI, app) last ran in `clients/`, and the optional `config.json`. Delete the folder to start over. A shared log lives in the shared folder instead; see [More than one machine](#more-than-one-machine).
 
 Every event carries a format number. A copy of parawatch reads a log that a newer copy wrote, skipping what it does not know, but refuses to write to it and says to update. The desktop app's own log is in `~/Library/Logs/Parawatch/main.log` (Help > Show Log File).
 
 Desktop notifications for new cards use `osascript` on macOS and `notify-send` on Linux. `PARAWATCH_NOTIFY=0` turns them off. While the desktop app runs it notifies instead, and the CLI stays quiet. To-dos never notify.
 
+## More than one machine
+
+Agents on a second machine (a desktop PC, a build box) can ask and be answered like the ones on your laptop. Parawatch does not move files between machines itself: point it at a folder that something else keeps in step, and each machine writes only its own log there.
+
+```sh
+# on each machine, once, with its own name
+parawatch sync setup ~/agent-sync/parawatch --device mac --adapter syncthing
+parawatch sync setup ~/agent-sync/parawatch --device pc  --adapter syncthing
+parawatch sync            # this machine, the others, how the sync tool is doing
+```
+
+- **Nothing moves until you run `sync setup`.** A machine on its own keeps today's single file and format.
+- **`sync setup` moves this machine's log into the folder.** It becomes `events/<device>.jsonl` with every event, id and seq as it was, so cursors and open cards carry on. The old file is kept beside it as `events.jsonl.before-sync`. A copy of parawatch older than 0.3 on that machine stops writing until it is updated.
+- **Each machine reads every log and writes only its own.** The logs merge in time order. Two machines never write one file, so a sync tool has nothing to merge.
+- **Ids carry the machine once a log is shared:** `pc-c3`, `mac-r2`. Commands take the short form (`parawatch close c3`) while only one machine has that number. Cards from before the move keep their ids.
+- **When two machines answer one card before either has seen the other's answer, the earlier answer stands.** The other one stays on the card, marked as not used, and does not wake the agent. An answer given after seeing the first one counts as usual.
+- **Paths follow the machine.** Attachments, things to open and project folders written on another machine are read as the same place here, under its home folder or the shared folder. Name other folders that sit in different places on each machine (a cloud drive, say): `parawatch sync root gdrive "G:\My Drive"` on one machine and `parawatch sync root gdrive ~/Library/CloudStorage/…/My\ Drive` on the other. Pasted pictures are saved in the shared folder, so every machine can open them.
+- **Waits are seen everywhere.** A card on your laptop says whether an agent on the PC is waiting for it.
+- **Every machine reads GitHub for itself.** The same news is delivered once.
+
+The shared folder holds `events/`, `devices/` (each machine's paths, version and last sign of life), `listeners/` and `attachments/`. Cursors, the lock, the GitHub reading and settings stay on each machine.
+
+**Sync adapters** are how parawatch asks the sync tool how it is doing, for `parawatch sync`, `doctor` and the app's settings. Pick one with `--adapter` (or `"sync": { "adapter": … }` in `config.json`):
+
+| Adapter | Reports |
+|---|---|
+| `syncthing` | Asks the local Syncthing through its REST API (address and API key from its `config.xml`; `PARAWATCH_SYNCTHING_KEY` or `"sync": { "syncthing": { "url", "home" } }` override): connected devices, when the folder was last in step, files on the way, errors. |
+| `folder` | Anything else that keeps a folder in step (a cloud drive, a network share): the other machines' last writes and conflict copies. |
+
+An adapter is one object with a `status()` method (`src/core/sync.ts`, `registerAdapter`). Another tool, such as a git checkout or a small server, fits the same shape.
+
 ## Not goals
 
 - Starting or steering agents. Use whatever you already use; parawatch only watches and carries answers back.

package/dist/bin/cli.js

@@ -2,12 +2,13 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { Command } from "commander";
-import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, consumerName, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, readInbox, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
+import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, consumerName, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
 import { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../core/github.js";
 import { digest, digestText, localDate } from "../core/digest.js";
-import { readEvents } from "../core/store.js";
+import { everywhere, readEvents } from "../core/store.js";
 import { followEvents } from "../core/follow.js";
-import { fold } from "../core/state.js";
+import { adapterNames, setRoot, setupSync, syncAdapter, syncStatus, touchDevice } from "../core/sync.js";
+import { syncText } from "../core/format.js";
 import { collectRuns } from "../core/runs.js";
 import { askRows, cardDetail, cardLine, cardRows, inboxLine, prRows, runsTree, view } from "../core/format.js";
 import { hookContext, notify, removeInstructions, writeInstructions } from "../core/integrate.js";
@@ -42,6 +43,7 @@ function binPath() {
     }
 }
 recordClient({ name: "cli", version: VERSION, path: binPath() });
+touchDevice(VERSION);
 const program = new Command();
 program
     .name("parawatch")
@@ -50,7 +52,7 @@ program
 /** Read GitHub when the last reading is old; never fails the command. */
 async function refreshGithub(force = false) {
     try {
-        await syncGithub({ state: fold(readEvents()), force });
+        await syncGithub({ state: readState(), force });
     }
     catch (err) {
         if (force)
@@ -129,7 +131,7 @@ program
     .option("--copy", "also put a line about the card on the clipboard, to paste into that session")
     .option("--print", "print the link instead of opening it")
     .action((target, o) => {
-    const g = resolveGoto(target, fold(readEvents()));
+    const g = resolveGoto(target, readState());
     if (o.copy && g.card) {
         const line = cardContextLine(g.card);
         try {
@@ -171,7 +173,7 @@ program
     .description("show one card with its answers")
     .option("--json", "JSON output")
     .action((id, o) => {
-    const card = fold(readEvents()).cards.get(id);
+    const card = findCard(readState(), id);
     if (!card)
         throw new UserError(`no card "${id}"`);
     if (o.json) {
@@ -193,7 +195,7 @@ program
     .option("-a, --all", "include closed cards")
     .option("--json", "JSON output")
     .action((o) => {
-    const cards = [...fold(readEvents()).cards.values()].filter((c) => (o.all || c.status !== "closed") && (!o.project || c.project === o.project));
+    const cards = [...readState().cards.values()].filter((c) => (o.all || c.status !== "closed") && (!o.project || c.project === o.project));
     if (o.json)
         print({ v: SCHEMA_VERSION, cards });
     else
@@ -239,9 +241,9 @@ inboxOptions(program.command("inbox").description("print unhandled answers witho
 program
     .command("watch")
     .description("stream every new event as one JSON line (for plugins and monitors)")
-    .option("--from <seq>", "replay events after this sequence number first", int)
+    .option("--from <seq>", "replay events after this sequence number first (in every machine's log)", int)
     .action(async (o) => {
-    followEvents(print, o.from);
+    followEvents(print, o.from === undefined ? undefined : everywhere(o.from, readEvents()));
     await new Promise(() => { });
 });
 // ------------------------------------------------------------------ runs
@@ -256,7 +258,7 @@ program
     .option("-w, --wide", "show runtime and ids")
     .option("--json", "JSON output")
     .action((o) => {
-    const runs = collectRuns(fold(readEvents()), { sinceHours: o.since, project: o.project, includeEnded: o.all, runtimes: o.runtime, keepRepeats: o.every });
+    const runs = collectRuns(readState(), { sinceHours: o.since, project: o.project, includeEnded: o.all, runtimes: o.runtime, keepRepeats: o.every });
     if (o.json)
         print({ v: SCHEMA_VERSION, runs });
     else
@@ -322,7 +324,7 @@ pr.command("list")
     .action(async (o) => {
     if (!o.offline)
         await refreshGithub();
-    const state = fold(readEvents());
+    const state = readState();
     const runs = collectRuns(state, { sinceHours: 72 });
     let prs = prViews(readCache(), state, runs);
     if (o.project)
@@ -335,7 +337,7 @@ pr.command("list")
 pr.command("sync")
     .description("read GitHub now")
     .action(async () => {
-    const c = await syncGithub({ state: fold(readEvents()), force: true });
+    const c = await syncGithub({ state: readState(), force: true });
     if (c.error)
         process.stderr.write(`parawatch: ${c.error}\n`);
     process.stdout.write(`${c.prs.filter((p) => p.state === "open").length} open pull requests on ${(c.hosts ?? []).join(", ") || "no host"}\n`);
@@ -480,7 +482,7 @@ project
     .command("list")
     .option("--json", "JSON output")
     .action((o) => {
-    const ps = [...fold(readEvents()).projects.values()];
+    const ps = [...readState().projects.values()];
     if (o.json)
         print({ v: SCHEMA_VERSION, projects: ps });
     else
@@ -513,6 +515,41 @@ program
     else
         process.stdout.write(`${doctorText(checks, view({}).color)}\n`);
 });
+// ------------------------------------------------------------------ sharing between machines
+const sync = program.command("sync").description("share cards and answers with your other machines through a synced folder");
+sync
+    .command("status", { isDefault: true })
+    .description("how sharing is doing: this machine, the others, the sync tool")
+    .option("--json", "JSON output")
+    .action(async (o) => {
+    const st = await syncStatus();
+    if (o.json)
+        print({ v: SCHEMA_VERSION, sync: st ?? null });
+    else
+        process.stdout.write(syncText(st, view({}).color) + "\n");
+});
+sync
+    .command("setup <folder>")
+    .description("start writing to a shared folder; this machine's log moves there, nothing is lost")
+    .option("-d, --device <name>", "this machine's name in the folder (a-z, 0-9, -); defaults to the host name")
+    .option("-a, --adapter <name>", `the tool that carries the folder: ${adapterNames().join(", ")}`)
+    .action((folder, o) => {
+    const r = setupSync({ dir: folder, device: o.device, adapter: o.adapter, version: VERSION });
+    const lines = [
+        `This machine writes to ${r.dir} as "${r.device}" (adapter: ${r.adapter}, ${syncAdapter(r.adapter).about}).`,
+        r.moved ? `Moved ${r.moved} events from this machine's log; the old file is kept at ${r.backup}.` : "",
+        r.others.length ? `Other machines already here: ${r.others.join(", ")}.` : "No other machine has written here yet. Run the same command on the next one with its own --device.",
+        "Older parawatch copies (before 0.3) on this machine stop writing until they are updated.",
+    ];
+    process.stdout.write(lines.filter(Boolean).join("\n") + "\n");
+});
+sync
+    .command("root <name> [folder]")
+    .description("name a folder on this machine (a cloud drive, say) so paths under it open on the others; no folder removes it")
+    .action((name, folder) => {
+    const d = setRoot(name, folder, VERSION);
+    process.stdout.write(Object.entries(d.roots ?? {}).map(([k, v]) => `${k}  ${v}`).join("\n") + (d.roots ? "\n" : "No named folders.\n"));
+});
 program
     .command("hook <runtime>")
     .description("hook entry point; 'claude-code' reads the hook JSON on stdin")

package/dist/core/doctor.js

@@ -10,9 +10,10 @@ import { ghHosts, githubConfig, readCache, runGh } from "./github.js";
 import { instructionState } from "./integrate.js";
 import { listeners } from "./ops.js";
 import { fold } from "./state.js";
-import { eventsPath, homeDir, readEvents, storeFormat } from "./store.js";
+import { deviceName, eventFiles, homeDir, readEvents, sharedDir, storeFormat } from "./store.js";
+import { readDevice, syncStatus } from "./sync.js";
 import { skillState, skillTargets } from "./skill.js";
-import { SCHEMA_VERSION } from "./types.js";
+import { STORE_FORMAT } from "./types.js";
 import { updateChecksOn } from "./update.js";
 function claudeSettingsFiles() {
     const dir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
@@ -38,17 +39,39 @@ export async function doctor(input) {
     // the store
     const events = readEvents();
     let size = 0;
-    try {
-        size = fs.statSync(eventsPath()).size;
-    }
-    catch {
-        // no events yet
+    for (const f of eventFiles()) {
+        try {
+            size += fs.statSync(f.file).size;
+        }
+        catch {
+            // no events yet
+        }
     }
     const format = storeFormat(events);
-    if (format > SCHEMA_VERSION)
-        add("store", "warn", `${eventsPath()} has format ${format}, newer than this copy reads (${SCHEMA_VERSION})`, CLI_UPDATE);
+    const shared = sharedDir();
+    const where = shared ? `${shared} (shared) · this machine ${homeDir()}` : homeDir();
+    if (format > STORE_FORMAT)
+        add("store", "warn", `${where} has format ${format}, newer than this copy reads (${STORE_FORMAT})`, CLI_UPDATE);
     else
-        add("store", "ok", `${homeDir()} · ${events.length} events, ${bytes(size)}`);
+        add("store", "ok", `${where} · ${events.length} events, ${bytes(size)}`);
+    // other machines
+    const st = input.sync === undefined ? await syncStatus().catch(() => undefined) : input.sync ?? undefined;
+    if (!shared)
+        add("sync", "off", "this machine only", "to share with another machine: parawatch sync setup <folder> --device <name>");
+    else {
+        const me = deviceName();
+        const mine = readDevice(me);
+        if (mine && mine.host !== `${os.hostname()}:${os.homedir()}`)
+            add("sync", "warn", `another machine (${mine.host}) also writes as "${me}"`, "give each machine its own name: parawatch sync setup <folder> --device <name>");
+        if (!st)
+            add("sync", "info", `${me} · ${shared}`);
+        else {
+            const peers = st.peers.map((p) => `${p.name} ${p.connected === true ? "connected" : p.connected === false ? "not connected" : "seen"}`).join(", ");
+            add("sync", st.error || !st.ok ? "warn" : "ok", `${me} · ${st.adapter} · ${peers || "no other machine yet"}${st.error ? ` · ${st.error}` : ""}`);
+            if (st.conflicts.length)
+                add("sync", "warn", `${st.conflicts.length} conflict copy(ies): ${st.conflicts.slice(0, 3).join(", ")}`, "each machine writes only its own file; look for two machines using one device name");
+        }
+    }
     const state = fold(events);
     add("projects", state.projects.size ? "ok" : "info", state.projects.size ? [...state.projects.keys()].join(", ") : "none registered (claims still work)");
     // the desktop app

package/dist/core/follow.js

@@ -1,62 +1,49 @@
 import fs from "node:fs";
-import { eventsPath, homeDir, parseEventLines } from "./store.js";
+import { endOf, eventFiles, eventsDir, isAfter, parseEventLines, readEvents } from "./store.js";
 /**
- * Call `onEvent` for every event appended after `afterSeq` (or after the current end when it is
- * undefined). Watches the store folder and also checks once a second. Returns a stop function.
+ * Call `onEvent` for every event appended after `after` (or after the current end when it is
+ * undefined), in any machine's log. Watches the log folder and also checks once a second, so a
+ * log a sync tool brings in from another machine shows up too. Returns a stop function.
  */
-export function followEvents(onEvent, afterSeq) {
-    const file = eventsPath();
-    let offset = 0;
-    let lastSeq = afterSeq ?? Infinity;
-    try {
-        const text = fs.readFileSync(file, "utf8");
-        offset = Buffer.byteLength(text);
-        const events = parseEventLines(text);
-        const end = events[events.length - 1]?.seq ?? 0;
-        if (afterSeq === undefined)
-            lastSeq = end;
-        else {
-            for (const ev of events)
-                if (ev.seq > afterSeq)
-                    onEvent(ev);
-            lastSeq = Math.max(afterSeq, end);
-        }
-    }
-    catch {
-        lastSeq = afterSeq ?? 0;
-    }
+export function followEvents(onEvent, after) {
+    const offsets = new Map();
+    let pos = after ?? endOf(readEvents());
     const pump = () => {
-        let size = 0;
-        try {
-            size = fs.statSync(file).size;
-        }
-        catch {
-            return;
-        }
-        if (size < offset)
-            offset = 0; // file replaced
-        if (size === offset)
-            return;
-        const fd = fs.openSync(file, "r");
-        const buf = Buffer.alloc(size - offset);
-        fs.readSync(fd, buf, 0, buf.length, offset);
-        fs.closeSync(fd);
-        const text = buf.toString("utf8");
-        const cut = text.lastIndexOf("\n");
-        if (cut < 0)
-            return;
-        offset += Buffer.byteLength(text.slice(0, cut + 1));
-        for (const ev of parseEventLines(text.slice(0, cut + 1))) {
-            if (ev.seq > lastSeq) {
+        for (const f of eventFiles()) {
+            let size = 0;
+            try {
+                size = fs.statSync(f.file).size;
+            }
+            catch {
+                continue;
+            }
+            let offset = offsets.get(f.file) ?? 0;
+            if (size < offset)
+                offset = 0; // file replaced
+            if (size === offset)
+                continue;
+            const fd = fs.openSync(f.file, "r");
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            fs.closeSync(fd);
+            const text = buf.toString("utf8");
+            const cut = text.lastIndexOf("\n");
+            if (cut < 0)
+                continue;
+            offsets.set(f.file, offset + Buffer.byteLength(text.slice(0, cut + 1)));
+            for (const ev of parseEventLines(text.slice(0, cut + 1), f.device)) {
+                if (!isAfter(ev, pos))
+                    continue;
+                pos = { ...pos, [f.device]: ev.seq };
                 onEvent(ev);
-                lastSeq = ev.seq;
             }
         }
     };
+    pump();
     let watcher;
     try {
-        fs.mkdirSync(homeDir(), { recursive: true });
-        watcher = fs.watch(homeDir(), () => pump());
+        fs.mkdirSync(eventsDir(), { recursive: true });
+        watcher = fs.watch(eventsDir(), () => pump());
     }
     catch {
         watcher = undefined; // the timer alone still works

package/dist/core/format.js

@@ -138,9 +138,13 @@ export function cardDetail(c) {
     if (c.from || c.session)
         out.push(`From: ${[c.from, c.session ? `session ${c.session.slice(0, 8)}` : ""].filter(Boolean).join(", ")}`);
     out.push(`Opened: ${new Date(c.openedAt).toLocaleString()}${c.since ? `, first came up ${new Date(c.since).toLocaleDateString()}` : ""}`);
+    if (c.dev)
+        out.push(`Machine: ${c.dev}`);
     for (const a of c.answers) {
         const choice = a.choice !== undefined ? ` chose ${a.choice}${c.options?.[a.choice - 1] ? ` (${c.options[a.choice - 1]})` : ""}` : "";
-        out.push("", `${a.by}${choice}${a.comment ? `: ${a.comment}` : ""}`);
+        const where = a.dev ? ` on ${a.dev}` : "";
+        const late = a.late ? "  (not used: given at the same time as the answer before it, which stands)" : "";
+        out.push("", `${a.by}${where}${choice}${a.comment ? `: ${a.comment}` : ""}${late}`);
         for (const f of a.attach ?? [])
             out.push(`  attached ${f}`);
     }
@@ -348,4 +352,26 @@ export function runsTree(runs, v = PLAIN, now = Date.now(), indent = "") {
     }
     return out.join("\n");
 }
+// ------------------------------------------------------------------ sharing
+/** `parawatch sync status` as text. */
+export function syncText(st, color = false, now = Date.now()) {
+    const v = { ...PLAIN, color };
+    if (!st)
+        return "This machine keeps its log to itself. To share it with another machine: parawatch sync setup <folder> --device <name>";
+    const lines = [
+        `${paint(v, st.device, "bold")} writes to ${st.dir}`,
+        `adapter  ${st.adapter}${st.ok ? "" : paint(v, " (not reachable)", "yellow")}${st.lastSync ? ` · last in step ${ago(st.lastSync, now)} ago` : ""}${st.pending ? ` · ${st.pending} file(s) on the way` : ""}`,
+    ];
+    if (!st.peers.length)
+        lines.push("peers    none yet");
+    for (const p of st.peers) {
+        const state = p.connected === true ? paint(v, "connected", "green") : p.connected === false ? paint(v, "not connected", "yellow") : "seen";
+        lines.push(`peer     ${p.name}  ${state}${p.lastSeen && p.connected !== true ? ` · last ${ago(p.lastSeen, now)} ago` : ""}${p.address ? ` · ${p.address}` : ""}${p.version ? ` · parawatch ${p.version}` : ""}`);
+    }
+    if (st.conflicts.length)
+        lines.push(paint(v, `conflicts ${st.conflicts.length}:`, "yellow"), ...st.conflicts.map((c) => `  ${c}`));
+    if (st.error)
+        lines.push(paint(v, st.error, "yellow"));
+    return lines.join("\n");
+}
 //# sourceMappingURL=format.js.map

package/dist/core/integrate.js

@@ -1,9 +1,8 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { readInbox, inboxFrom } from "./ops.js";
+import { readInbox, inboxFrom, readState } from "./ops.js";
 import { homeDir, readCursor, readEvents } from "./store.js";
-import { fold } from "./state.js";
 import { inboxLine } from "./format.js";
 export const BEGIN = "<!-- parawatch:begin -->";
 export const END = "<!-- parawatch:end -->";
@@ -97,7 +96,7 @@ export function instructionState(file) {
  */
 export function hookContext(input, project) {
     const events = readEvents();
-    const state = fold(events);
+    const state = readState(events);
     let name = project;
     if (!name && input.session_id)
         name = state.claims.find((c) => input.session_id.startsWith(c.session))?.project;
@@ -108,7 +107,7 @@ export function hookContext(input, project) {
     }
     if (!name)
         return undefined;
-    const items = inboxFrom(events, readCursor(name), { project: name });
+    const items = inboxFrom(events, readCursor(name), { project: name }, state);
     if (!items.length)
         return undefined;
     const cards = items.filter((i) => i.kind !== "pr").length;