syndai 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to the `syndai` npm package. Versions follow semver.
 
+## 0.7.0
+
+Land your own branch, and keep a folder in a project's Knowledge.
+
+- `land [branch] [--app A] [--no-wait]` lands your pushed `people/<you>/<name>` branch on a project
+  Syndai hosts: the same checks, review and landing slot as Syndai's own changes, then it watches
+  the landing. It prints any live work on the same files first. A `people/<you>/t12` branch
+  delivers task t12 when it goes live.
+- `sync <dir> [--app A] [--watch]` keeps a folder (an Obsidian vault, any folder of notes) in
+  the project's Knowledge, where its runs and chat search it. Each sync sends every file's
+  sha256 and pushes only the new or changed ones: text files (`.md`, `.txt`, `.csv`, `.json`,
+  `.yaml` and the like) as their text, any other file by name only. A file deleted here is
+  removed there. Hidden files and folders (`.obsidian/`, `.trash/`, `.git/`), `node_modules/`,
+  symlinks, files over 10 MB and the patterns in `<dir>/.syndaiignore` stay out.
+- `--watch` syncs again a second after the last change, one sync at a time, until Ctrl-C; an
+  edit is searchable within seconds. Only changed files are read again.
+- A paused folder, or a folder of the same name someone else syncs, is refused (exit 1) with the
+  server's sentence. It needs `coding:knowledge:sync` (owners and admins); on a terminal the
+  first sync asks for it in the browser.
+- Picking the project from the git remote now matches `github.com/<owner>/<repo>` built from the
+  project's name. The API no longer sends repo URLs. Versions up to 0.6.0 read those URLs, so
+  they skip this rule and fall through to the only project or the picker.
+
 ## 0.6.0
 
 The steps that stay in the browser are one command away, and an agent can sign up.

package/README.md

@@ -44,9 +44,11 @@ README is for whoever works on the package.
 | `answer <run> [--input FILE\|-]` | answer an open question (`--input`: `{"entries":[...]}` from a file or stdin) |
 | `review <run> [--retry \| --close]` | see why a change is held, then approve it in the browser |
 | `go-live`, `revert`, `cancel <run>` | land actions |
+| `land [branch] [--app A] [--no-wait]` | on a project Syndai hosts, check, review and land your pushed `people/<you>/<name>` branch (default: the current one) |
 | `publish [--app A]` | publish (or redeploy) the project as a hosted app and print its live URL (`coding:apps:publish`) |
 | `connect <provider>` | print, and open on a terminal, the workspace page that connects it: `github` -> `settings#repositories`, `sentry` -> `sentry`, the plan logins, OpenRouter, Slack and social accounts -> `connections?connect=<provider>`. Finish in the browser; no key reads connection status |
 | `billing [--open]`, `packs`, `buy <pack>`, `plan <tier> [--interval month\|year] [--country CC]`, `card`, `cancel` | plan, balance (packs + included left - holds, as the portal shows it) and the billing page; `buy`/`plan` print and open a checkout a person pays (nothing is charged until then; `--country` else the locale's region else US prices it); `card`/`cancel` and an existing plan go to the billing page |
+| `sync <dir> [--app A] [--watch]` | keep a folder (an Obsidian vault) in the project's Knowledge (`coding:knowledge:sync`): see [Folder sync](#folder-sync) |
 | `status [--app A]` | what is running, and everything that needs you |
 | `settings [--app A] [get \| set k=v...]` | `autonomy`, `feature_requests`, `bug_scan`, `protected_paths` (`+=` adds) |
 | `mcp install claude\|cursor\|codex` | add the Syndai MCP server to that tool's user config, with its own key |
@@ -79,6 +81,30 @@ Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs
 4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
 unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 
+## Folder sync
+
+`syndai sync <dir>` (`src/sync.js`, SPEC-knowledge-sources K6) walks `<dir>`, hashes every
+file and sends the manifest (`compareKnowledgeFolder`, at most 20,000 `{path, sha256}`). The
+server deletes the files missing from it and answers `need`, the paths new or changed; those go
+up through `pushKnowledgeFolderFiles` in batches of at most 500 files and 8 MB, each read again
+so the hash sent matches the bytes. Text suffixes (the server's `TEXT_SUFFIXES`) carry their
+UTF-8 `content`; any other file goes with `content: null` (recorded by name). The folder's name
+is the basename of `<dir>`; paths are `/`-separated and relative to it. Both calls are
+idempotent (a manifest is a compare, a push upserts by path), so they retry like a GET.
+
+Skipped: names starting with `.` (so `.obsidian/`, `.trash/`, `.git/`, `.syndaiignore` itself),
+`node_modules/`, symlinks (never followed), files over 10 MB (left out of the manifest, listed
+as skipped) and `<dir>/.syndaiignore` patterns: one a line, `#` comments, `dir/` for folders,
+a pattern with a `/` anchored at the root, `*`, `?` and `**`; no `!`. A 409 (paused, or another
+person's folder of that name) prints the detail and exits 1; per-file `failed` rows are printed
+and do not change the exit code.
+
+`--watch` keeps `{size, mtimeMs, sha256}` per file, so a re-sync re-reads only what moved (a
+hash taken within 2 s of the mtime is redone, for coarse clocks). `io.watchDir` (`fs.watch`,
+recursive) is the trigger, debounced 1 s, one sync at a time; a stat-only check every 10 s
+catches missed events, and a watcher error falls back to it. An unreachable API is retried
+after 30 s; any other error ends the watch. Ctrl-C exits 130.
+
 ## Layout
 
 - `bin/syndai.js`: the entrypoint; wires SIGINT to an AbortSignal.
@@ -95,6 +121,7 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 - `src/secrets.js`: `env`, `secrets` and `run` (environment choice, the production step-up retry).
 - `src/dotenv.js`: the `.env` reader (`import`) and writer (`download`); errors name lines, never values.
 - `src/portal.js`: `connect` and `billing`, the hand-offs to a workspace page.
+- `src/sync.js`: `sync` (the walk, `.syndaiignore`, manifest and batched push, `--watch`).
 - `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndai",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {

package/src/changes.js

@@ -2,6 +2,7 @@
 // edit-text. Each command is a thin call to one route plus, where there is an outcome to
 // wait for, `watchChange`.
 
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -175,6 +176,37 @@ async function uploadImage(ctx, file) {
   return { object_key: stored.object_key, content_type: contentType };
 }
 
+/** `syndai land [branch]`: validate, review and land your pushed people/<you>/<name> branch. */
+export async function land(ctx, [branch]) {
+  const { flags, ui } = ctx;
+  const name = branch ?? currentBranch();
+  if (!name) throw new CliError("Which branch? syndai land people/<you>/<name>", EXIT.USAGE);
+  const project = await resolveProject(ctx, { app: flags.app });
+  const landing = await ctx.client.call("landBranch", {
+    params: { coding_repository_id: project.id },
+    body: { branch: name },
+    retry: true, // one landing per pushed head: a retry answers the same run
+  });
+  ui.progress(ui.dim(`Landing ${name} at ${landing.head_sha.slice(0, 12)}: change ${landing.run_id}`));
+  for (const warning of landing.overlap ?? []) ui.progress(`Heads up: ${warning}`);
+  if (flags["no-wait"]) {
+    return finish(ctx, await getChange(ctx, landing.run_id), {
+      exitCode: EXIT.OK,
+      next: `syndai watch ${landing.run_id}`,
+    });
+  }
+  return watchChange(ctx, landing.run_id, { timeoutMs: timeoutOf(flags) });
+}
+
+function currentBranch() {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).trim();
+    return out && out !== "HEAD" ? out : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function watch(ctx, runId) {
   return watchChange(ctx, needRun(runId, "watch"), {
     timeoutMs: timeoutOf(ctx.flags),

package/src/main.js

@@ -2,10 +2,11 @@
 // process I/O as `io`, so tests drive it in-process with a fake server and fake clocks.
 
 import { spawn } from "node:child_process";
+import { watch as watchFs } from "node:fs";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { createContext, login, logout, signup, whoami } from "./auth.js";
-import { answer, cancel, change, editText, goLive, newProject, review, revert, status, watch } from "./changes.js";
+import { answer, cancel, change, editText, goLive, land, newProject, review, revert, status, watch } from "./changes.js";
 import { ApiError, CliError, EXIT, explain, PORTAL_PAGES } from "./errors.js";
 import { VERSION } from "./http.js";
 import { mcp } from "./mcp.js";
@@ -15,6 +16,7 @@ import { api } from "./api.js";
 import { repeat, schedule } from "./schedules.js";
 import { env, run, secrets } from "./secrets.js";
 import { settings } from "./settings.js";
+import { sync } from "./sync.js";
 import { closeInput, openBrowser, openPage, page } from "./ui.js";
 
 const str = { type: "string" };
@@ -49,6 +51,15 @@ const COMMANDS = {
     run: (ctx, args) => newProject(ctx, args),
     stepUp: false,
   },
+  land: {
+    usage: "land [branch] [--app A] [--no-wait] [--timeout D]",
+    summary:
+      "On a project Syndai hosts: check, review and land your pushed branch (default: the current one, people/<you>/<name>).\n" +
+      "      A branch named for a task (people/<you>/t12) delivers it when the landing goes live.",
+    options: { app: str, "no-wait": bool, timeout: str },
+    run: (ctx, args) => land(ctx, args),
+    stepUp: false,
+  },
   watch: {
     usage: "watch <run> [--timeout D] [--logs]",
     summary: "Follow a change to its outcome (Ctrl-C detaches; the change keeps going).",
@@ -182,6 +193,14 @@ const COMMANDS = {
     options: { app: str },
     run: (ctx, args) => settings(ctx, args),
   },
+  sync: {
+    usage: "sync <dir> [--app A] [--watch]",
+    summary:
+      "Sync a folder (an Obsidian vault) into a project's Knowledge: new and changed files go up, deleted ones are removed;\n" +
+      "      hidden files, node_modules/ and <dir>/.syndaiignore patterns stay out. --watch: keep syncing as files change (Ctrl-C stops).",
+    options: { app: str, watch: bool },
+    run: (ctx, args) => sync(ctx, args),
+  },
   mcp: {
     usage: "mcp install claude|cursor|codex",
     summary: "Add Syndai to an AI coding tool, with its own key.",
@@ -249,6 +268,12 @@ export function processIo(signal) {
     sleep: (ms, abortSignal) => sleep(ms, undefined, { signal: abortSignal }),
     openUrl: openBrowser,
     page: (text) => page(process, text),
+    /** `syndai sync --watch`: `onChange(file)` for a change anywhere under `dir` (`file` relative, or null); returns `{close}`. */
+    watchDir: (dir, onChange, onError) => {
+      const watcher = watchFs(dir, { recursive: true }, (_event, file) => onChange(file ? String(file) : null));
+      watcher.on("error", onError);
+      return watcher;
+    },
     /**
      * `syndai run`: the child shares the terminal; resolves `{code, signal}` (ENOENT rejects).
      * While it runs the parent never exits first (that would orphan a child holding the

package/src/projects.js

@@ -28,7 +28,8 @@ export async function listProjects(ctx) {
       full_name: repo.full_name,
       live_url: app?.url ?? null,
       slug: app?.publication?.slug ?? null,
-      repo_urls: [repo.repo_url, repo.clone_url, repo.html_url].filter(Boolean),
+      // A local clone can only be of a GitHub repo (Syndai-hosted ones are never cloned).
+      remote: repo.provider === "github" ? normalizeRemote(`github.com/${repo.full_name}`) : null,
       protected_paths: repo.protected_paths ?? [],
       customer_id: customerId,
     };
@@ -84,7 +85,7 @@ export async function resolveProject(ctx, { app, required = true, picker = true,
     }
   }
   const remotes = gitRemotes(io.cwd);
-  const byRemote = projects.filter((p) => p.repo_urls.some((u) => remotes.has(normalizeRemote(u))));
+  const byRemote = projects.filter((p) => p.remote && remotes.has(p.remote));
   if (byRemote.length === 1) return byRemote[0];
   if (projects.length === 1) return projects[0];
   if (picker && ui.interactive && projects.length > 1) return pickInteractively(ctx, projects);

package/src/routes.js

@@ -28,8 +28,9 @@ export const ROUTES = Object.freeze({
   packs: ["GET", `${EXT}/purchases/packs`],
   packCheckout: ["POST", `${EXT}/purchases/pack-checkout`],
   planCheckout: ["POST", `${EXT}/purchases/subscription-checkout`],
-  getBugScan: ["GET", `${EXT}/repositories/{repository_id}/bug-scan`],
-  setBugScan: ["PUT", `${EXT}/repositories/{repository_id}/bug-scan`],
+  listScans: ["GET", `${EXT}/repositories/{repository_id}/scans`],
+  setScanRoutine: ["PUT", `${EXT}/repositories/{repository_id}/scans`],
+  runScanNow: ["POST", `${EXT}/repositories/{repository_id}/scans/{kind}/run`],
   getPolicy: ["GET", `${EXT}/policy/defaults`],
   putPolicy: ["PUT", `${EXT}/policy/defaults`],
   imageIngest: ["POST", `${EXT}/runs/image-ingest`],
@@ -44,7 +45,10 @@ export const ROUTES = Object.freeze({
   landRetry: ["POST", `${EXT}/runs/{run_id}/land/retry`],
   landClose: ["POST", `${EXT}/runs/{run_id}/land/close`],
   goLive: ["POST", `${EXT}/runs/{run_id}/land/go-live`],
+  landBranch: ["POST", `${EXT}/repos/{coding_repository_id}/land`],
   heldDiff: ["GET", `${EXT}/runs/{run_id}/land/held-diff`],
+  compareKnowledgeFolder: ["POST", `${EXT}/repos/{coding_repository_id}/knowledge/folders/{name}/manifest`],
+  pushKnowledgeFolderFiles: ["POST", `${EXT}/repos/{coding_repository_id}/knowledge/folders/{name}/files`],
   listSchedules: ["GET", `${EXT}/schedules`],
   createSchedule: ["POST", `${EXT}/schedules`],
   getSchedule: ["GET", `${EXT}/schedules/{schedule_id}`],

package/src/settings.js

@@ -3,7 +3,7 @@
 // Settings live in four places server-side:
 //   autonomy          repo-scoped policy default       GET/PUT policy/defaults
 //   feature_requests  the app's publication            GET/PATCH .../publication
-//   bug_scan          the repo's Bug Finder schedule   GET/PUT repositories/{id}/bug-scan
+//   bug_scan          the repo's weekly Code bugs check GET/PUT repositories/{id}/scans
 //   protected_paths   the repo row                     PATCH repos/{id} (a key may only tighten)
 
 import { ApiError, CliError, EXIT, explain } from "./errors.js";
@@ -66,9 +66,9 @@ async function apply(ctx, project, { key, op, value }) {
       body: { feature_requests: value },
     });
   } else if (key === "bug_scan") {
-    await client.call("setBugScan", {
+    await client.call("setScanRoutine", {
       params: { repository_id: project.id },
-      body: { enabled: value === "on" },
+      body: { kind: "code", cadence: value === "on" ? "weekly" : "off" },
     });
   } else {
     const added = value
@@ -91,7 +91,7 @@ async function read(ctx, project) {
   const [policy, publication, bugScan] = await Promise.all([
     settle(client.call("getPolicy", { query: { coding_repository_id: project.id } })),
     settle(client.call("getPublication", { params: ids })),
-    settle(client.call("getBugScan", { params: { repository_id: project.id } })),
+    settle(client.call("listScans", { params: { repository_id: project.id } })),
   ]);
   const unavailable = {};
   for (const [key, got] of [
@@ -104,7 +104,7 @@ async function read(ctx, project) {
   return {
     autonomy: policy.value?.config?.autonomy ?? null,
     feature_requests: publication.value?.feature_requests ?? null,
-    bug_scan: bugScan.value ? (bugScan.value.enabled ? "on" : "off") : null,
+    bug_scan: bugScan.value ? codeScan(bugScan.value) : null,
     protected_paths: project.protected_paths,
     unavailable,
   };
@@ -128,3 +128,9 @@ async function orNull(promise) {
     throw err;
   }
 }
+
+// The Code bugs routine is "on" while it runs on a cadence with its spend agreed.
+function codeScan(scans) {
+  const code = (scans.kinds ?? []).find((k) => k.kind === "code");
+  return code && code.cadence !== "off" && !code.needs_consent ? "on" : "off";
+}

package/src/sync.js

@@ -0,0 +1,389 @@
+// `syndai sync <dir> [--app A] [--watch]`: keep a local folder (an Obsidian vault, any folder of
+// notes) in a project's Knowledge (SPEC-knowledge-sources K6; docs: syndai.ai/docs/cli, "Sync a
+// folder into Knowledge").
+//
+// One sync: walk the folder, hash every file, send the manifest. The server deletes the files no
+// longer here and answers the paths that are new or changed; those are pushed in batches of at
+// most 500 files and 8 MB. A text file goes as its UTF-8 text, any other file by name only. The
+// folder's name in Knowledge is the directory's basename.
+//
+// Skipped: hidden files and folders (a name starting with `.`, so `.obsidian/`, `.trash/` and
+// `.git/`), `node_modules/`, symlinks (never followed: one may point out of the folder, or
+// loop), files over 10 MB, and the patterns in `<dir>/.syndaiignore`.
+//
+// `--watch` re-runs the whole sync once the folder has been quiet for a second, one sync at a
+// time; Ctrl-C stops it. A file is hashed again only when its size or mtime moved (or it was
+// hashed within 2 s of its mtime, which a coarse clock could hide), so a re-sync costs the
+// changed files, not the vault. File events (`fs.watch`) are the trigger; a stat-only
+// check every 10 s catches what they miss (a network drive, a dropped event), so an edit is in
+// Knowledge within seconds either way.
+//
+// File I/O is synchronous: one file at a time through promises is ~20x slower on a big vault,
+// and nothing else runs meanwhile.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { CliError, EXIT, UnavailableError, explain } from "./errors.js";
+import { interrupted } from "./http.js";
+import { projectLabel, resolveProject } from "./projects.js";
+
+/** Sent as text; the server's `TEXT_SUFFIXES` (backend/src/features/project_sources/ingest.py). */
+export const TEXT_SUFFIXES = new Set([
+  ".md",
+  ".markdown",
+  ".mdx",
+  ".txt",
+  ".text",
+  ".csv",
+  ".tsv",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".org",
+  ".rst",
+  ".log",
+]);
+export const FILE_MAX_BYTES = 10 * 1024 * 1024;
+export const MANIFEST_MAX = 20_000;
+export const BATCH_FILES = 500;
+export const BATCH_BYTES = 8 * 1024 * 1024;
+export const DEBOUNCE_MS = 1000;
+const POLL_MS = 10_000;
+const RETRY_MS = 30_000;
+const RACY_MS = 2000; // the coarsest common mtime clock (FAT, exFAT)
+const TOO_BIG = "over 10 MB";
+const IGNORE_FILE = ".syndaiignore";
+const DEFAULT_IGNORES = "node_modules/\n";
+
+export async function sync(ctx, args) {
+  const [dir, ...extra] = args;
+  if (!dir || extra.length) throw new CliError(EXIT.USAGE, "Usage: syndai sync <dir> [--app A] [--watch]");
+  const root = path.resolve(ctx.io.cwd, dir);
+  if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new CliError(EXIT.USAGE, `${dir} is not a folder.`);
+  }
+  const name = path.basename(root);
+  if (!name) throw new CliError(EXIT.USAGE, "Sync a folder with a name, not the filesystem root.");
+  const project = await resolveProject(ctx, { app: ctx.flags.app });
+  // `known`: path -> {size, mtimeMs, hashedAt, sha256 (null: skipped)} as of the last scan.
+  const target = { root, name, project, rules: [], known: new Map() };
+  show(ctx, target, await syncOnce(ctx, target));
+  return ctx.flags.watch ? watchFolder(ctx, target) : EXIT.OK;
+}
+
+// --- one sync ----------------------------------------------------------------------------
+
+async function syncOnce(ctx, target) {
+  const { client } = ctx;
+  const params = { coding_repository_id: target.project.id, name: target.name };
+  scan(target);
+  const files = [...target.known].filter(([, f]) => f.sha256).map(([rel, f]) => ({ path: rel, sha256: f.sha256 }));
+  if (files.length > MANIFEST_MAX) {
+    throw new CliError(
+      EXIT.USAGE,
+      `${target.name} has ${files.length} files; a synced folder holds up to ${MANIFEST_MAX}.`,
+      { next: `list what to leave out in ${path.join(target.root, IGNORE_FILE)}` },
+    );
+  }
+  const manifest = await client.call("compareKnowledgeFolder", {
+    params,
+    body: { files },
+    retry: true, // the same manifest twice is the same answer
+    timeoutMs: 120_000,
+  });
+  const need = manifest.need.filter((rel) => target.known.get(rel)?.sha256);
+  const totals = { indexed: 0, linked: 0, failed: [] };
+  const progress = ctx.io.stderr.isTTY && need.length > BATCH_FILES;
+  let sent = 0;
+  let batch = [];
+  let size = 0;
+  const flush = async () => {
+    const pushed = await client.call("pushKnowledgeFolderFiles", {
+      params,
+      body: { files: batch },
+      retry: true, // a push upserts by path
+      timeoutMs: 120_000,
+    });
+    totals.indexed += pushed.indexed;
+    totals.linked += pushed.linked;
+    totals.failed.push(...pushed.failed);
+    sent += batch.length;
+    if (progress) ctx.ui.progress(ctx.ui.dim(`indexed ${sent} of ${need.length}`));
+    batch = [];
+    size = 0;
+  };
+  for (const rel of need) {
+    // Read again: a file edited since the scan goes with its new hash, so the next manifest
+    // matches it. One gone since is left to the next manifest, which removes it.
+    const file = readFile(target, rel);
+    if (!file?.sha256) continue;
+    const entry = {
+      path: rel,
+      sha256: file.sha256,
+      bytes: file.bytes.length,
+      modified_at: new Date(file.mtimeMs).toISOString(),
+      content: TEXT_SUFFIXES.has(path.extname(rel).toLowerCase()) ? file.bytes.toString("utf8") : null,
+    };
+    const bytes = Buffer.byteLength(JSON.stringify(entry)) + 1;
+    if (batch.length && (batch.length >= BATCH_FILES || size + bytes > BATCH_BYTES)) await flush();
+    batch.push(entry);
+    size += bytes;
+  }
+  if (batch.length) await flush();
+  return {
+    source_id: manifest.source_id,
+    files: files.length,
+    unchanged: files.length - need.length,
+    removed: manifest.removed,
+    ...totals,
+    skipped: [...target.known].filter(([, f]) => !f.sha256).map(([rel]) => ({ path: rel, reason: TOO_BIG })),
+  };
+}
+
+/** Walk the folder into `target.known`, hashing only a file whose size or mtime moved. */
+function scan(target) {
+  target.rules = loadRules(target.root);
+  const before = target.known;
+  target.known = new Map();
+  for (const rel of walk(target.root, target.rules)) {
+    const stat = statFile(target, rel);
+    const last = before.get(rel);
+    if (stat && same(last, stat) && trusted(last)) target.known.set(rel, last);
+    else if (stat) readFile(target, rel);
+  }
+}
+
+const same = (last, stat) => Boolean(last) && last.size === stat.size && last.mtimeMs === stat.mtimeMs;
+
+/** A hash taken soon after the mtime may predate a same-size edit in that clock tick: redo it. */
+const trusted = (last) => !last.sha256 || last.mtimeMs < last.hashedAt - RACY_MS;
+
+/** Whether a stat-only walk differs from the last scan (a file added, removed or touched). */
+function changedOnDisk(target) {
+  const rels = walk(target.root, loadRules(target.root));
+  if (rels.length !== target.known.size) return true;
+  return rels.some((rel) => {
+    const stat = statFile(target, rel);
+    const last = target.known.get(rel);
+    if (!stat || !same(last, stat)) return true;
+    return !trusted(last) && readFile(target, rel)?.sha256 !== last.sha256;
+  });
+}
+
+function statFile(target, rel) {
+  try {
+    const stat = fs.lstatSync(path.join(target.root, ...rel.split("/")));
+    return stat.isFile() ? stat : null;
+  } catch (err) {
+    if (["ENOENT", "EACCES", "EPERM", "ENOTDIR"].includes(err.code)) return null;
+    throw err;
+  }
+}
+
+/**
+ * Read and hash one file into `target.known` and return it with its `bytes`; one over 10 MB is
+ * recorded with `sha256: null` (skipped) and never read. Null when it is gone or unreadable.
+ */
+function readFile(target, rel) {
+  const full = path.join(target.root, ...rel.split("/"));
+  let stat;
+  let bytes;
+  try {
+    stat = fs.lstatSync(full);
+    if (!stat.isFile()) return null;
+    if (stat.size <= FILE_MAX_BYTES) bytes = fs.readFileSync(full);
+  } catch (err) {
+    if (["ENOENT", "EACCES", "EPERM", "EISDIR", "ENOTDIR"].includes(err.code)) {
+      target.known.delete(rel);
+      return null;
+    }
+    throw err;
+  }
+  const small = bytes && bytes.length <= FILE_MAX_BYTES;
+  const file = {
+    size: small ? bytes.length : stat.size,
+    mtimeMs: stat.mtimeMs,
+    hashedAt: Date.now(),
+    sha256: small ? createHash("sha256").update(bytes).digest("hex") : null,
+  };
+  target.known.set(rel, file);
+  return { ...file, bytes };
+}
+
+function show(ctx, target, s) {
+  const lines = [
+    `Synced ${target.name} to ${projectLabel(target.project)}: ` +
+      `${s.indexed} indexed, ${s.linked} linked, ${s.failed.length} failed`,
+  ];
+  if (s.removed) lines.push(`  removed ${s.removed} deleted here`);
+  for (const f of s.failed) lines.push(`  failed ${f.path}: ${f.error}`);
+  for (const f of s.skipped) lines.push(`  skipped ${f.path}: ${f.reason}`);
+  ctx.ui.result({ folder: target.name, dir: target.root, project_id: target.project.id, ...s }, lines.join("\n"));
+}
+
+// --- what is skipped ---------------------------------------------------------------------
+
+function loadRules(root) {
+  let own = "";
+  try {
+    own = fs.readFileSync(path.join(root, IGNORE_FILE), "utf8");
+  } catch {
+    // No .syndaiignore: the defaults alone.
+  }
+  return parseIgnore(DEFAULT_IGNORES + own);
+}
+
+/**
+ * `.syndaiignore`, gitignore-like and kept simple: one pattern a line, `#` comments, `dir/` for
+ * folders only, a pattern with a `/` (or a leading one) anchored at the folder's root and any
+ * other matched against a name at any depth, `*` and `?` within a name, `**` across folders.
+ * No `!` negation.
+ */
+export function parseIgnore(text) {
+  const rules = [];
+  for (const raw of text.split(/\r?\n/)) {
+    let line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("!")) continue;
+    const dirOnly = line.endsWith("/");
+    line = line.replace(/\/+$/, "");
+    const anchored = line.includes("/");
+    line = line.replace(/^\/+/, "");
+    if (line) rules.push({ dirOnly, anchored, regex: globRegex(line) });
+  }
+  return rules;
+}
+
+function globRegex(glob) {
+  let source = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*" && glob[i + 1] === "*") {
+      const slash = glob[i + 2] === "/";
+      source += slash ? "(?:.*/)?" : ".*";
+      i += slash ? 2 : 1;
+    } else if (ch === "*") source += "[^/]*";
+    else if (ch === "?") source += "[^/]";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/** Whether the entry at `rel` (`/`-separated; `isDir` for a folder) is skipped. */
+export function ignored(rules, rel, isDir) {
+  const name = rel.slice(rel.lastIndexOf("/") + 1);
+  if (name.startsWith(".")) return true;
+  return rules.some((r) => (!r.dirOnly || isDir) && r.regex.test(r.anchored ? rel : name));
+}
+
+/** The files to sync, sorted; a skipped folder is never entered. */
+function walk(root, rules) {
+  const files = [];
+  const visit = (dir, prefix) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      if (prefix && ["ENOENT", "EACCES", "EPERM", "ENOTDIR"].includes(err.code)) return;
+      throw err;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      // A Dirent describes the link itself: a symlink is neither, so it is never followed.
+      if (entry.isDirectory()) {
+        if (!ignored(rules, rel, true)) visit(path.join(dir, entry.name), rel);
+      } else if (entry.isFile() && !ignored(rules, rel, false)) {
+        files.push(rel);
+      }
+    }
+  };
+  visit(root, "");
+  return files;
+}
+
+/** A change event for `rel` matters unless it is in a skipped folder or is a skipped file. */
+function relevant(rules, rel) {
+  if (rel === IGNORE_FILE) return true;
+  const parts = rel.split("/");
+  for (let i = 1; i < parts.length; i++) {
+    if (ignored(rules, parts.slice(0, i).join("/"), true)) return false;
+  }
+  return !ignored(rules, rel, false);
+}
+
+// --- --watch -----------------------------------------------------------------------------
+
+async function watchFolder(ctx, target) {
+  const { io, ui } = ctx;
+  const state = { changed: false, wake: null };
+  let watcher = null;
+  const eventsLost = (err) => {
+    watcher?.close();
+    watcher = null;
+    ui.progress(`${ui.yellow("warning:")} file events stopped (${err.code ?? err.message}); checking every 10 s instead.`);
+  };
+  try {
+    watcher = io.watchDir(
+      target.root,
+      (file) => {
+        if (file && !relevant(target.rules, String(file).split(path.sep).join("/"))) return;
+        state.changed = true;
+        state.wake?.();
+      },
+      eventsLost,
+    );
+  } catch (err) {
+    eventsLost(err);
+  }
+  ui.progress(ui.dim(`Watching ${target.root} for changes (Ctrl-C stops).`));
+  try {
+    for (;;) {
+      if (!state.changed && (await nextEvent(io, state)) === "poll" && !changedOnDisk(target)) continue;
+      // Wait until a second passes with no change, so a burst of saves is one sync.
+      do {
+        state.changed = false;
+        await pause(io, DEBOUNCE_MS);
+      } while (state.changed);
+      try {
+        const s = await syncOnce(ctx, target);
+        if (s.indexed || s.linked || s.failed.length || s.removed) show(ctx, target, s);
+      } catch (err) {
+        if (!(err instanceof UnavailableError)) throw err;
+        ui.progress(`${ui.yellow("warning:")} ${explain(err).message} Trying again in 30 s.`);
+        await pause(io, RETRY_MS);
+        state.changed = true;
+      }
+    }
+  } finally {
+    watcher?.close();
+  }
+}
+
+/** "event" on a relevant file event, "poll" after 10 s without one; Ctrl-C interrupts. */
+function nextEvent(io, state) {
+  return new Promise((resolve, reject) => {
+    if (io.signal.aborted) return reject(interrupted());
+    const done = (outcome) => {
+      clearTimeout(timer);
+      io.signal.removeEventListener("abort", onAbort);
+      state.wake = null;
+      if (outcome instanceof Error) reject(outcome);
+      else resolve(outcome);
+    };
+    const onAbort = () => done(interrupted());
+    const timer = setTimeout(() => done("poll"), POLL_MS);
+    io.signal.addEventListener("abort", onAbort, { once: true });
+    state.wake = () => done("event");
+  });
+}
+
+async function pause(io, ms) {
+  if (io.signal.aborted) throw interrupted();
+  try {
+    await io.sleep(ms, io.signal);
+  } catch (err) {
+    if (io.signal.aborted) throw interrupted();
+    throw err;
+  }
+}