@creativeintelligence/abbie 0.1.0

package/src/lib/content-sync/index.ts

@@ -0,0 +1,882 @@
+/**
+ * ContentSyncRunner — orchestrates Convex ↔ local sync for rules, skills, hooks.
+ *
+ * Pull (Convex → local):
+ *   fetch snapshot → compare hash → write files → update manifest
+ *
+ * Push (local → Convex):
+ *   scan local files → compare hashes → upsert to Convex
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  chmodSync,
+  unlinkSync,
+  rmSync,
+} from "node:fs";
+import { join, basename, extname } from "node:path";
+import { homedir } from "node:os";
+import { writeConfigAtomic, getSyncDir } from "../config-sync/writer.js";
+import type {
+  ContentSnapshot,
+  ContentSyncState,
+  ContentManifest,
+  ContentSyncTickResult,
+  ContentPushResult,
+  ContentType,
+  SyncRule,
+  SyncSkill,
+  SyncHook,
+} from "./types.js";
+
+/** Default backoff interval (ms) */
+const DEFAULT_INTERVAL_MS = 60_000;
+const MAX_BACKOFF_MS = 5 * 60_000;
+const CIRCUIT_BREAKER_FAILURES = 10;
+const CIRCUIT_BREAKER_WINDOW_MS = 10 * 60_000;
+
+/** Base directories */
+const ABBIE_DIR = join(homedir(), ".abbie");
+const RULES_DIR = join(ABBIE_DIR, "rules");
+const SKILLS_DIR = join(ABBIE_DIR, "skills");
+const HOOKS_DIR = join(ABBIE_DIR, "hooks");
+
+/** Simple djb2 hash (same as backend) */
+function djb2Hash(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+type FetchSnapshotFn = () => Promise<ContentSnapshot>;
+
+type UpsertRuleFn = (rule: {
+  clerkId: string;
+  name: string;
+  content: string;
+  isEnabled: boolean;
+  category?: string;
+  triggers?: string[];
+  summary?: string;
+}) => Promise<unknown>;
+
+type UpsertSkillFn = (skill: {
+  clerkId: string;
+  name: string;
+  content: string;
+  isEnabled: boolean;
+  description?: string;
+  triggers?: string[];
+  hasScripts: boolean;
+  hasRefs: boolean;
+  files?: Record<string, string>;
+}) => Promise<unknown>;
+
+type UpsertHookFn = (hook: {
+  clerkId: string;
+  name: string;
+  content: string;
+  event: string;
+  platform?: string;
+  isEnabled: boolean;
+  isExecutable: boolean;
+}) => Promise<unknown>;
+
+export type ContentSyncRunnerOptions = {
+  fetchSnapshot: FetchSnapshotFn;
+  upsertRule?: UpsertRuleFn;
+  upsertSkill?: UpsertSkillFn;
+  upsertHook?: UpsertHookFn;
+  /** Filter to specific content types */
+  types?: ContentType[];
+};
+
+export class ContentSyncRunner {
+  private fetchSnapshot: FetchSnapshotFn;
+  private upsertRule?: UpsertRuleFn;
+  private upsertSkill?: UpsertSkillFn;
+  private upsertHook?: UpsertHookFn;
+  private typeFilter?: ContentType[];
+  private state: ContentSyncState;
+  private manifest: ContentManifest;
+
+  constructor(opts: ContentSyncRunnerOptions) {
+    this.fetchSnapshot = opts.fetchSnapshot;
+    this.upsertRule = opts.upsertRule;
+    this.upsertSkill = opts.upsertSkill;
+    this.upsertHook = opts.upsertHook;
+    this.typeFilter = opts.types;
+    this.state = this.loadState();
+    this.manifest = this.loadManifest();
+  }
+
+  /**
+   * Pull tick — sync Convex → local.
+   *
+   * @param opts.snapshot - Pre-fetched snapshot (from subscription). Skips fetch if provided.
+   */
+  async tick(opts?: {
+    force?: boolean;
+    dryRun?: boolean;
+    snapshot?: ContentSnapshot;
+  }): Promise<ContentSyncTickResult> {
+    const force = opts?.force ?? false;
+    const dryRun = opts?.dryRun ?? false;
+
+    if (this.isCircuitOpen()) {
+      return { ok: false, reason: "circuit-breaker-open", dryRun, changes: [] };
+    }
+
+    let snapshot: ContentSnapshot;
+    if (opts?.snapshot) {
+      snapshot = opts.snapshot;
+    } else {
+      try {
+        snapshot = await this.fetchSnapshot();
+      } catch (err) {
+        this.recordFailure();
+        return {
+          ok: false,
+          reason: `fetch-failed: ${err instanceof Error ? err.message : String(err)}`,
+          dryRun,
+          changes: [],
+        };
+      }
+    }
+
+    // Skip if hash unchanged
+    if (!force && snapshot.hash === this.state.lastHash) {
+      return { ok: true, reason: "unchanged", dryRun, changes: [] };
+    }
+
+    const changes: ContentSyncTickResult["changes"] = [];
+    const shouldSync = (t: ContentType) =>
+      !this.typeFilter || this.typeFilter.includes(t);
+
+    // Sync rules
+    if (shouldSync("rules")) {
+      const ruleChanges = this.syncRules(snapshot.rules, dryRun);
+      changes.push(...ruleChanges);
+    }
+
+    // Sync skills
+    if (shouldSync("skills")) {
+      const skillChanges = this.syncSkills(snapshot.skills, dryRun);
+      changes.push(...skillChanges);
+    }
+
+    // Sync hooks
+    if (shouldSync("hooks")) {
+      const hookChanges = this.syncHooks(snapshot.hooks, dryRun);
+      changes.push(...hookChanges);
+    }
+
+    // Persist state (unless dry-run)
+    if (!dryRun) {
+      this.state.lastHash = snapshot.hash;
+      this.state.lastSuccessAt = Date.now();
+      this.state.consecutiveFailures = 0;
+      this.saveState();
+      this.saveManifest();
+    }
+
+    const hasErrors = changes.some((c) => c.action === "error");
+    return {
+      ok: !hasErrors,
+      reason: hasErrors ? "partial-failure" : "synced",
+      dryRun,
+      changes,
+    };
+  }
+
+  /**
+   * Push — scan local files and upsert to Convex.
+   */
+  async push(
+    clerkId: string,
+    opts?: { types?: ContentType[]; dryRun?: boolean },
+  ): Promise<ContentPushResult> {
+    const dryRun = opts?.dryRun ?? false;
+    const types = opts?.types ?? ["rules", "skills", "hooks"];
+    const pushed: ContentPushResult["pushed"] = [];
+    const errors: ContentPushResult["errors"] = [];
+
+    if (types.includes("rules") && this.upsertRule) {
+      const localRules = this.scanLocalRules();
+      for (const rule of localRules) {
+        try {
+          if (!dryRun) {
+            await this.upsertRule({
+              clerkId,
+              name: rule.name,
+              content: rule.content,
+              isEnabled: true,
+              category: rule.category,
+              triggers: rule.triggers,
+              summary: rule.summary,
+            });
+          }
+          pushed.push({ type: "rules", name: rule.name, action: "updated" });
+        } catch (err) {
+          errors.push({
+            type: "rules",
+            name: rule.name,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    if (types.includes("skills") && this.upsertSkill) {
+      const localSkills = this.scanLocalSkills();
+      for (const skill of localSkills) {
+        try {
+          if (!dryRun) {
+            await this.upsertSkill({
+              clerkId,
+              name: skill.name,
+              content: skill.content,
+              isEnabled: true,
+              description: skill.description,
+              triggers: skill.triggers,
+              hasScripts: skill.hasScripts,
+              hasRefs: skill.hasRefs,
+              files: skill.files,
+            });
+          }
+          pushed.push({ type: "skills", name: skill.name, action: "updated" });
+        } catch (err) {
+          errors.push({
+            type: "skills",
+            name: skill.name,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    if (types.includes("hooks") && this.upsertHook) {
+      const localHooks = this.scanLocalHooks();
+      for (const hook of localHooks) {
+        try {
+          if (!dryRun) {
+            await this.upsertHook({
+              clerkId,
+              name: hook.name,
+              content: hook.content,
+              event: hook.event,
+              platform: hook.platform,
+              isEnabled: true,
+              isExecutable: hook.isExecutable,
+            });
+          }
+          pushed.push({ type: "hooks", name: hook.name, action: "updated" });
+        } catch (err) {
+          errors.push({
+            type: "hooks",
+            name: hook.name,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { ok: errors.length === 0, pushed, errors };
+  }
+
+  getState(): ContentSyncState {
+    return { ...this.state };
+  }
+
+  getManifest(): ContentManifest {
+    return { ...this.manifest };
+  }
+
+  // ─── Pull: sync rules ──────────────────────────────────────────────────
+
+  private syncRules(
+    rules: SyncRule[],
+    dryRun: boolean,
+  ): ContentSyncTickResult["changes"] {
+    const changes: ContentSyncTickResult["changes"] = [];
+    const previousFiles = new Set(this.manifest.rules?.managedFiles ?? []);
+    const currentFiles = new Set<string>();
+
+    if (!dryRun) ensureDir(RULES_DIR);
+
+    for (const rule of rules) {
+      const fileName = `${rule.name}.md`;
+      const filePath = join(RULES_DIR, fileName);
+      currentFiles.add(fileName);
+
+      try {
+        // Check if file exists and content matches
+        if (existsSync(filePath)) {
+          const existing = readFileSync(filePath, "utf-8");
+          const existingHash = djb2Hash(existing);
+          if (existingHash === rule.hash) {
+            changes.push({
+              type: "rules",
+              name: rule.name,
+              action: "unchanged",
+            });
+            continue;
+          }
+        }
+
+        if (!dryRun) {
+          writeConfigAtomic(filePath, rule.content);
+        }
+        changes.push({
+          type: "rules",
+          name: rule.name,
+          action: existsSync(filePath) ? "updated" : "created",
+        });
+      } catch (err) {
+        changes.push({
+          type: "rules",
+          name: rule.name,
+          action: "error",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Remove files that were managed but are no longer in snapshot
+    for (const oldFile of previousFiles) {
+      if (!currentFiles.has(oldFile)) {
+        const filePath = join(RULES_DIR, oldFile);
+        if (existsSync(filePath)) {
+          if (!dryRun) {
+            try {
+              unlinkSync(filePath);
+            } catch {
+              /* ignore */
+            }
+          }
+          changes.push({
+            type: "rules",
+            name: oldFile.replace(".md", ""),
+            action: "removed",
+          });
+        }
+      }
+    }
+
+    if (!dryRun) {
+      this.manifest.rules = {
+        managedFiles: [...currentFiles],
+        lastSyncHash: this.state.lastHash,
+        lastSyncAt: Date.now(),
+      };
+    }
+
+    return changes;
+  }
+
+  // ─── Pull: sync skills ─────────────────────────────────────────────────
+
+  private syncSkills(
+    skills: SyncSkill[],
+    dryRun: boolean,
+  ): ContentSyncTickResult["changes"] {
+    const changes: ContentSyncTickResult["changes"] = [];
+    const previousDirs = new Set(this.manifest.skills?.managedDirs ?? []);
+    const currentDirs = new Set<string>();
+
+    if (!dryRun) ensureDir(SKILLS_DIR);
+
+    for (const skill of skills) {
+      const dirName = skill.name;
+      const dirPath = join(SKILLS_DIR, dirName);
+      const skillMdPath = join(dirPath, "SKILL.md");
+      currentDirs.add(dirName);
+
+      try {
+        // Check if SKILL.md exists and content matches
+        if (existsSync(skillMdPath)) {
+          const existing = readFileSync(skillMdPath, "utf-8");
+          // Hash must match the same way as backend: content + "|" + filesStr (always includes pipe)
+          const filesStr = skill.files ? JSON.stringify(skill.files) : "";
+          const existingHash = djb2Hash(existing + "|" + filesStr);
+          if (existingHash === skill.hash) {
+            changes.push({
+              type: "skills",
+              name: skill.name,
+              action: "unchanged",
+            });
+            continue;
+          }
+        }
+
+        if (!dryRun) {
+          ensureDir(dirPath);
+          writeConfigAtomic(skillMdPath, skill.content);
+
+          // Write additional files (scripts/, references/)
+          if (skill.files) {
+            for (const [relPath, fileContent] of Object.entries(skill.files)) {
+              const fullPath = join(dirPath, relPath);
+              ensureDir(join(fullPath, ".."));
+              writeConfigAtomic(fullPath, fileContent);
+              // Make scripts executable
+              if (relPath.startsWith("scripts/")) {
+                try {
+                  chmodSync(fullPath, 0o755);
+                } catch {
+                  /* ignore */
+                }
+              }
+            }
+          }
+        }
+
+        changes.push({
+          type: "skills",
+          name: skill.name,
+          action: existsSync(skillMdPath) ? "updated" : "created",
+        });
+      } catch (err) {
+        changes.push({
+          type: "skills",
+          name: skill.name,
+          action: "error",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Remove dirs that were managed but no longer in snapshot
+    for (const oldDir of previousDirs) {
+      if (!currentDirs.has(oldDir)) {
+        const dirPath = join(SKILLS_DIR, oldDir);
+        if (existsSync(dirPath)) {
+          if (!dryRun) {
+            try {
+              rmSync(dirPath, { recursive: true, force: true });
+            } catch {
+              /* ignore */
+            }
+          }
+          changes.push({
+            type: "skills",
+            name: oldDir,
+            action: "removed",
+          });
+        }
+      }
+    }
+
+    if (!dryRun) {
+      this.manifest.skills = {
+        managedDirs: [...currentDirs],
+        lastSyncHash: this.state.lastHash,
+        lastSyncAt: Date.now(),
+      };
+    }
+
+    return changes;
+  }
+
+  // ─── Pull: sync hooks ──────────────────────────────────────────────────
+
+  private syncHooks(
+    hooks: SyncHook[],
+    dryRun: boolean,
+  ): ContentSyncTickResult["changes"] {
+    const changes: ContentSyncTickResult["changes"] = [];
+    const previousFiles = new Set(this.manifest.hooks?.managedFiles ?? []);
+    const currentFiles = new Set<string>();
+
+    if (!dryRun) ensureDir(HOOKS_DIR);
+
+    for (const hook of hooks) {
+      // Determine file extension from content (shebang detection)
+      const ext = hook.content.startsWith("#!/usr/bin/env python")
+        ? ".py"
+        : ".sh";
+      const fileName = hook.name.endsWith(ext) ? hook.name : `${hook.name}${ext}`;
+      const filePath = join(HOOKS_DIR, fileName);
+      currentFiles.add(fileName);
+
+      try {
+        if (existsSync(filePath)) {
+          const existing = readFileSync(filePath, "utf-8");
+          const existingHash = djb2Hash(existing);
+          if (existingHash === hook.hash) {
+            changes.push({
+              type: "hooks",
+              name: hook.name,
+              action: "unchanged",
+            });
+            continue;
+          }
+        }
+
+        if (!dryRun) {
+          writeConfigAtomic(filePath, hook.content);
+          if (hook.isExecutable) {
+            try {
+              chmodSync(filePath, 0o755);
+            } catch {
+              /* ignore */
+            }
+          }
+        }
+        changes.push({
+          type: "hooks",
+          name: hook.name,
+          action: existsSync(filePath) ? "updated" : "created",
+        });
+      } catch (err) {
+        changes.push({
+          type: "hooks",
+          name: hook.name,
+          action: "error",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Remove managed files no longer in snapshot
+    for (const oldFile of previousFiles) {
+      if (!currentFiles.has(oldFile)) {
+        const filePath = join(HOOKS_DIR, oldFile);
+        if (existsSync(filePath)) {
+          if (!dryRun) {
+            try {
+              unlinkSync(filePath);
+            } catch {
+              /* ignore */
+            }
+          }
+          changes.push({
+            type: "hooks",
+            name: oldFile.replace(/\.(sh|py)$/, ""),
+            action: "removed",
+          });
+        }
+      }
+    }
+
+    if (!dryRun) {
+      this.manifest.hooks = {
+        managedFiles: [...currentFiles],
+        lastSyncHash: this.state.lastHash,
+        lastSyncAt: Date.now(),
+      };
+    }
+
+    return changes;
+  }
+
+  // ─── Local scanners (for push) ─────────────────────────────────────────
+
+  /** Scan ~/.abbie/rules/ for markdown files */
+  scanLocalRules(): SyncRule[] {
+    if (!existsSync(RULES_DIR)) return [];
+
+    return readdirSync(RULES_DIR)
+      .filter((f) => f.endsWith(".md") && f !== "README.md")
+      .map((f) => {
+        const content = readFileSync(join(RULES_DIR, f), "utf-8");
+        const name = f.replace(".md", "");
+
+        // Parse basic metadata from content
+        const triggers = this.extractTriggers(content);
+        const summary = this.extractFirstLine(content);
+        const category = this.guessCategory(name);
+
+        return {
+          name,
+          content,
+          isEnabled: true,
+          category,
+          triggers,
+          summary,
+          lineCount: content.split("\n").length,
+          hash: djb2Hash(content),
+        };
+      });
+  }
+
+  /** Scan ~/.abbie/skills/ for skill directories */
+  scanLocalSkills(): SyncSkill[] {
+    if (!existsSync(SKILLS_DIR)) return [];
+
+    return readdirSync(SKILLS_DIR)
+      .filter((d) => {
+        const p = join(SKILLS_DIR, d);
+        return (
+          statSync(p).isDirectory() &&
+          existsSync(join(p, "SKILL.md"))
+        );
+      })
+      .map((d) => {
+        const dirPath = join(SKILLS_DIR, d);
+        const content = readFileSync(join(dirPath, "SKILL.md"), "utf-8");
+        const hasScripts = existsSync(join(dirPath, "scripts"));
+        const hasRefs = existsSync(join(dirPath, "references"));
+
+        // Parse frontmatter
+        const { description, triggers } = this.parseFrontmatter(content);
+
+        // Bundle additional files
+        const files: Record<string, string> = {};
+        this.bundleDir(dirPath, "scripts", files);
+        this.bundleDir(dirPath, "references", files);
+
+        const filesStr = Object.keys(files).length > 0 ? JSON.stringify(files) : "";
+
+        return {
+          name: d,
+          content,
+          isEnabled: true,
+          description,
+          triggers,
+          hasScripts,
+          hasRefs,
+          files: Object.keys(files).length > 0 ? files : undefined,
+          lineCount: content.split("\n").length,
+          hash: djb2Hash(content + "|" + filesStr),
+        };
+      });
+  }
+
+  /** Scan ~/.abbie/hooks/ for script files */
+  scanLocalHooks(): SyncHook[] {
+    if (!existsSync(HOOKS_DIR)) return [];
+
+    return readdirSync(HOOKS_DIR)
+      .filter((f) => {
+        if (f === "README.md" || f.startsWith(".")) return false;
+        const ext = extname(f);
+        return [".sh", ".py", ".toml"].includes(ext);
+      })
+      .map((f) => {
+        const filePath = join(HOOKS_DIR, f);
+        const content = readFileSync(filePath, "utf-8");
+        const name = f.replace(/\.(sh|py|toml)$/, "");
+        const stat = statSync(filePath);
+        const isExecutable = !!(stat.mode & 0o111);
+
+        // Guess event from name
+        const event = this.guessHookEvent(name);
+        const platform = this.guessHookPlatform(name);
+
+        return {
+          name,
+          content,
+          event,
+          platform,
+          isEnabled: true,
+          isExecutable,
+          hash: djb2Hash(content),
+        };
+      });
+  }
+
+  // ─── Helpers ───────────────────────────────────────────────────────────
+
+  private extractTriggers(content: string): string[] {
+    // Extract from first heading or table entries
+    const triggers: string[] = [];
+    const lines = content.split("\n").slice(0, 20);
+    for (const line of lines) {
+      if (line.startsWith("# ")) {
+        // Use heading words as triggers
+        const words = line
+          .replace("# ", "")
+          .toLowerCase()
+          .split(/\s+/)
+          .filter((w) => w.length > 2);
+        triggers.push(...words);
+        break;
+      }
+    }
+    return triggers;
+  }
+
+  private extractFirstLine(content: string): string {
+    const lines = content.split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("---")) {
+        return trimmed.slice(0, 200);
+      }
+    }
+    return "";
+  }
+
+  private guessCategory(name: string): string {
+    const categories: Record<string, string> = {
+      core: "core",
+      stack: "technical",
+      "cli-tools": "technical",
+      "agent-orchestration": "workflow",
+      observability: "workflow",
+      linear: "workflow",
+      browser: "technical",
+      messaging: "workflow",
+      prompts: "technical",
+      roles: "workflow",
+      "swift-ui-decisions": "technical",
+      e2e: "technical",
+      taste: "core",
+      glossary: "reference",
+      sprites: "technical",
+    };
+    return categories[name] ?? "other";
+  }
+
+  private parseFrontmatter(content: string): {
+    description?: string;
+    triggers?: string[];
+  } {
+    if (!content.startsWith("---")) return {};
+    const end = content.indexOf("---", 3);
+    if (end === -1) return {};
+    const fm = content.slice(3, end);
+
+    let description: string | undefined;
+    let triggers: string[] | undefined;
+
+    for (const line of fm.split("\n")) {
+      const descMatch = line.match(/^description:\s*(.+)/);
+      if (descMatch) description = descMatch[1].trim();
+
+      const trigMatch = line.match(/^triggers:\s*\[(.+)\]/);
+      if (trigMatch) {
+        triggers = trigMatch[1].split(",").map((t) => t.trim().replace(/['"]/g, ""));
+      }
+    }
+
+    return { description, triggers };
+  }
+
+  private bundleDir(
+    baseDir: string,
+    subDir: string,
+    files: Record<string, string>,
+  ): void {
+    const dir = join(baseDir, subDir);
+    if (!existsSync(dir)) return;
+
+    for (const f of readdirSync(dir)) {
+      const fullPath = join(dir, f);
+      if (statSync(fullPath).isFile()) {
+        try {
+          const content = readFileSync(fullPath, "utf-8");
+          files[`${subDir}/${f}`] = content;
+        } catch {
+          /* skip binary files */
+        }
+      }
+    }
+  }
+
+  private guessHookEvent(name: string): string {
+    if (name.includes("stop") || name.includes("end")) return "stop";
+    if (name.includes("start")) return "start";
+    if (name.includes("error")) return "error";
+    if (name.includes("notify") || name.includes("notification")) return "notification";
+    if (name.includes("checkpoint") || name.includes("tool")) return "tool-call";
+    if (name.includes("summary") || name.includes("context")) return "custom";
+    return "custom";
+  }
+
+  private guessHookPlatform(name: string): string | undefined {
+    if (name.includes("codex")) return "codex";
+    if (name.includes("claude")) return "claude";
+    if (name.includes("copilot")) return "copilot";
+    return undefined;
+  }
+
+  // ─── State persistence ─────────────────────────────────────────────────
+
+  private get statePath(): string {
+    return join(getSyncDir(), "content-sync-state.json");
+  }
+
+  private get manifestPath(): string {
+    return join(getSyncDir(), "content-manifest.json");
+  }
+
+  private loadState(): ContentSyncState {
+    try {
+      if (existsSync(this.statePath)) {
+        return JSON.parse(readFileSync(this.statePath, "utf-8"));
+      }
+    } catch {
+      /* fresh start */
+    }
+    return { lastHash: "", lastSuccessAt: 0, consecutiveFailures: 0, nextRetryAt: 0 };
+  }
+
+  private saveState(): void {
+    const dir = getSyncDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.statePath, JSON.stringify(this.state, null, 2) + "\n");
+  }
+
+  private loadManifest(): ContentManifest {
+    try {
+      if (existsSync(this.manifestPath)) {
+        return JSON.parse(readFileSync(this.manifestPath, "utf-8"));
+      }
+    } catch {
+      /* fresh start */
+    }
+    return {};
+  }
+
+  private saveManifest(): void {
+    const dir = getSyncDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      this.manifestPath,
+      JSON.stringify(this.manifest, null, 2) + "\n",
+    );
+  }
+
+  private recordFailure(): void {
+    this.state.consecutiveFailures++;
+    const backoffMs = Math.min(
+      DEFAULT_INTERVAL_MS * 2 ** this.state.consecutiveFailures,
+      MAX_BACKOFF_MS,
+    );
+    this.state.nextRetryAt = Date.now() + backoffMs;
+    this.saveState();
+  }
+
+  private isCircuitOpen(): boolean {
+    if (this.state.consecutiveFailures < CIRCUIT_BREAKER_FAILURES) return false;
+    const windowStart = Date.now() - CIRCUIT_BREAKER_WINDOW_MS;
+    return this.state.nextRetryAt > windowStart;
+  }
+}
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export type {
+  ContentSnapshot,
+  ContentSyncState,
+  ContentManifest,
+  ContentSyncTickResult,
+  ContentPushResult,
+  ContentType,
+  SyncRule,
+  SyncSkill,
+  SyncHook,
+} from "./types.js";