@clearlysh/beehaven 0.8.16

package/dist/clearly-sync.js

@@ -0,0 +1,518 @@
+/**
+ * .clearly/ Bidirectional Sync
+ *
+ * Keeps a project-scoped .clearly/ directory in sync with the cloud DO.
+ * This is how Claude Code gets project context (reads CLAUDE.md) and
+ * pushes content back (writes notes, edits tasks, stores memories).
+ *
+ * Directory layout:
+ *   .clearly/
+ *     CLAUDE.md          ← daemon-generated context (read-only for Claude)
+ *     notes/             ← bidirectional: local .md ↔ DO notes
+ *     tasks.yaml         ← bidirectional: local YAML ↔ DO board items
+ *     memories.yaml      ← bidirectional: local YAML ↔ DO agent memory
+ *     .sync.json         ← sync state (hashes, timestamps, versions)
+ *
+ * Sync is PROJECT-SCOPED: only data for the linked project syncs.
+ * Does NOT sync: all notes, compositions, SVG blobs, R2 files, chat, billing.
+ */
+import { EventEmitter } from 'events';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, watch as fsWatch, } from 'fs';
+import { join, basename } from 'path';
+import { createHash } from 'crypto';
+const CLEARLY_DIR = '.clearly';
+const SYNC_FILE = '.sync.json';
+const CONTEXT_FILE = 'CLAUDE.md';
+const TASKS_FILE = 'tasks.yaml';
+const MEMORIES_FILE = 'memories.yaml';
+const NOTES_DIR = 'notes';
+/** How often to pull context from the DO (ms) */
+const PULL_INTERVAL = 60_000; // 1 minute
+/** Debounce for local file changes before pushing (ms) */
+const PUSH_DEBOUNCE = 2_000;
+export class ClearlySync extends EventEmitter {
+    projectPath;
+    projectId;
+    callAction;
+    clearlyDir;
+    state;
+    pullTimer = null;
+    pushTimer = null;
+    watchers = [];
+    pushing = false;
+    pulling = false;
+    /** Suppress push while we're writing from a pull (avoid echo) */
+    suppressPush = false;
+    constructor(opts) {
+        super();
+        this.projectPath = opts.projectPath;
+        this.projectId = opts.projectId;
+        this.callAction = opts.callAction;
+        this.clearlyDir = join(this.projectPath, CLEARLY_DIR);
+        this.state = this.loadState();
+    }
+    /** Initialize directory structure and start sync */
+    async start() {
+        this.ensureDirectories();
+        this.state = this.loadState();
+        // Initial pull — get context from cloud
+        await this.pull();
+        // Watch local .clearly/ for changes
+        this.watchLocal();
+        // Periodic pull
+        this.pullTimer = setInterval(() => this.pull(), PULL_INTERVAL);
+        this.emit('started');
+    }
+    /** Stop sync — clean up watchers and timers */
+    stop() {
+        if (this.pullTimer)
+            clearInterval(this.pullTimer);
+        if (this.pushTimer)
+            clearTimeout(this.pushTimer);
+        for (const w of this.watchers)
+            w.close();
+        this.watchers = [];
+        this.pullTimer = null;
+        this.pushTimer = null;
+        this.emit('stopped');
+    }
+    /** Force a full pull from cloud → local */
+    async pull() {
+        if (this.pulling)
+            return;
+        this.pulling = true;
+        try {
+            const context = (await this.callAction('project-context', {
+                projectId: this.projectId,
+            }));
+            if (!context || !context.project) {
+                this.emit('pull-error', 'No project context returned');
+                return;
+            }
+            this.suppressPush = true;
+            // Write CLAUDE.md
+            this.writeContextFile(context);
+            // Sync tasks
+            this.writeTasksFile(context.tasks || []);
+            // Sync memories
+            this.writeMemoriesFile(context.memories || []);
+            // Sync notes (cloud → local, don't overwrite local-only files)
+            this.syncNotesDown(context.recentNotes || []);
+            this.state.lastPullAt = Date.now();
+            this.saveState();
+            this.suppressPush = false;
+            this.emit('pulled', context);
+        }
+        catch (err) {
+            this.suppressPush = false;
+            this.emit('pull-error', err.message);
+        }
+        finally {
+            this.pulling = false;
+        }
+    }
+    /** Push local changes → cloud */
+    async push() {
+        if (this.pushing || this.suppressPush)
+            return;
+        this.pushing = true;
+        try {
+            await this.pushTasks();
+            await this.pushMemories();
+            await this.pushNotes();
+            this.state.lastPushAt = Date.now();
+            this.saveState();
+            this.emit('pushed');
+        }
+        catch (err) {
+            this.emit('push-error', err.message);
+        }
+        finally {
+            this.pushing = false;
+        }
+    }
+    /** Get the .clearly directory path */
+    get dirPath() {
+        return this.clearlyDir;
+    }
+    // ── Context File Generation ──────────────────────────────────────────
+    writeContextFile(context) {
+        const lines = [];
+        lines.push(`# ${context.project.title}`);
+        if (context.project.description) {
+            lines.push(`${context.project.description}`);
+        }
+        lines.push('');
+        // Active tasks
+        const activeTasks = (context.tasks || []).filter((t) => t.status === 'active');
+        const ideaTasks = (context.tasks || []).filter((t) => t.status === 'idea');
+        const shippedTasks = (context.tasks || []).filter((t) => t.status === 'shipped').slice(0, 5);
+        if (activeTasks.length > 0 || ideaTasks.length > 0) {
+            lines.push('## Tasks');
+            for (const t of activeTasks) {
+                lines.push(`- [ ] ${t.title}${t.description ? ` — ${t.description}` : ''}`);
+            }
+            for (const t of ideaTasks) {
+                lines.push(`- [ ] ${t.title} *(idea)*`);
+            }
+            for (const t of shippedTasks) {
+                lines.push(`- [x] ${t.title}`);
+            }
+            lines.push('');
+        }
+        // Memories
+        if (context.memories && context.memories.length > 0) {
+            lines.push('## Memories');
+            for (const m of context.memories) {
+                lines.push(`- **${m.key}**: ${m.value}`);
+            }
+            lines.push('');
+        }
+        // Recent notes
+        if (context.recentNotes && context.recentNotes.length > 0) {
+            lines.push('## Recent Notes');
+            for (const n of context.recentNotes) {
+                const date = new Date(n.updatedAt).toISOString().slice(0, 10);
+                lines.push(`- ${n.title} *(${date})*${n.preview ? ` — ${n.preview}` : ''}`);
+            }
+            lines.push('');
+        }
+        // Agent
+        if (context.agent) {
+            lines.push('## Agent');
+            lines.push(`State: ${context.agent.state}`);
+            if (context.agent.lastThought) {
+                lines.push(`Last thought: ${context.agent.lastThought}`);
+            }
+            lines.push('');
+        }
+        // Workspace CLI
+        lines.push('## Workspace CLI');
+        lines.push('Access the Clearly workspace via `beehaven` (if the daemon is running):');
+        lines.push('- `beehaven actions` — list available workspace actions');
+        lines.push("- `beehaven call <action> '<json>'` — call any action");
+        lines.push('- `beehaven call ticket-list \'{"projectId":"<id>"}\'` — list a project board\'s cards (a card is a ticket)');
+        lines.push('- `beehaven call note-create \'{"noteData":{"title":"..."}}\' ` — create a note');
+        lines.push('');
+        // Footer
+        lines.push('---');
+        lines.push(`*Synced from Clearly workspace · ${new Date().toISOString().slice(0, 16)}*`);
+        lines.push('*Edit tasks.yaml, memories.yaml, or notes/ — changes sync to cloud.*');
+        lines.push('');
+        const content = lines.join('\n');
+        const filePath = join(this.clearlyDir, CONTEXT_FILE);
+        const hash = md5(content);
+        // Only write if changed
+        if (this.state.fileHashes[CONTEXT_FILE] !== hash) {
+            writeFileSync(filePath, content, 'utf8');
+            this.state.fileHashes[CONTEXT_FILE] = hash;
+        }
+    }
+    // ── Tasks Sync ───────────────────────────────────────────────────────
+    writeTasksFile(tasks) {
+        const lines = ['# Tasks — edit status to sync changes to Clearly', ''];
+        for (const t of tasks) {
+            lines.push(`- id: ${t.id}`);
+            lines.push(`  title: "${escapeYaml(t.title)}"`);
+            lines.push(`  status: ${t.status}`);
+            if (t.description)
+                lines.push(`  description: "${escapeYaml(t.description)}"`);
+            if (t.tags && t.tags.length > 0)
+                lines.push(`  tags: [${t.tags.join(', ')}]`);
+            lines.push('');
+        }
+        const content = lines.join('\n');
+        const filePath = join(this.clearlyDir, TASKS_FILE);
+        const hash = md5(content);
+        if (this.state.fileHashes[TASKS_FILE] !== hash) {
+            writeFileSync(filePath, content, 'utf8');
+            this.state.fileHashes[TASKS_FILE] = hash;
+        }
+        // Store remote version markers
+        for (const t of tasks) {
+            this.state.remoteVersions[`task:${t.id}`] = t.updatedAt || 0;
+        }
+    }
+    async pushTasks() {
+        const filePath = join(this.clearlyDir, TASKS_FILE);
+        if (!existsSync(filePath))
+            return;
+        const content = readFileSync(filePath, 'utf8');
+        const hash = md5(content);
+        if (this.state.fileHashes[TASKS_FILE] === hash)
+            return; // unchanged
+        const tasks = parseTasksYaml(content);
+        for (const task of tasks) {
+            try {
+                if (task.id) {
+                    // Update existing task
+                    await this.callAction('note-update', {
+                        id: task.id,
+                        updates: { title: task.title, status: task.status, description: task.description },
+                    });
+                }
+                else {
+                    // New task (no id) — create it
+                    await this.callAction('note-create', {
+                        title: task.title,
+                        fileType: 'board',
+                        status: task.status || 'idea',
+                        description: task.description,
+                        projectId: this.projectId,
+                    });
+                }
+            }
+            catch (err) {
+                this.emit('push-error', `Task sync failed for "${task.title}": ${err.message}`);
+            }
+        }
+        this.state.fileHashes[TASKS_FILE] = hash;
+    }
+    // ── Memories Sync ────────────────────────────────────────────────────
+    writeMemoriesFile(memories) {
+        const lines = ['# Memories — key-value pairs synced with Clearly agent', ''];
+        for (const m of memories) {
+            lines.push(`${m.key}: "${escapeYaml(m.value)}"`);
+        }
+        lines.push('');
+        const content = lines.join('\n');
+        const filePath = join(this.clearlyDir, MEMORIES_FILE);
+        const hash = md5(content);
+        if (this.state.fileHashes[MEMORIES_FILE] !== hash) {
+            writeFileSync(filePath, content, 'utf8');
+            this.state.fileHashes[MEMORIES_FILE] = hash;
+        }
+    }
+    async pushMemories() {
+        const filePath = join(this.clearlyDir, MEMORIES_FILE);
+        if (!existsSync(filePath))
+            return;
+        const content = readFileSync(filePath, 'utf8');
+        const hash = md5(content);
+        if (this.state.fileHashes[MEMORIES_FILE] === hash)
+            return;
+        const memories = parseMemoriesYaml(content);
+        for (const mem of memories) {
+            try {
+                await this.callAction('remember', { key: mem.key, value: mem.value });
+            }
+            catch (err) {
+                this.emit('push-error', `Memory sync failed for "${mem.key}": ${err.message}`);
+            }
+        }
+        this.state.fileHashes[MEMORIES_FILE] = hash;
+    }
+    // ── Notes Sync ───────────────────────────────────────────────────────
+    syncNotesDown(notes) {
+        const notesDir = join(this.clearlyDir, NOTES_DIR);
+        for (const note of notes) {
+            const slug = slugify(note.title);
+            const filePath = join(notesDir, `${slug}.md`);
+            // Don't overwrite locally-created files that have no remote version
+            const remoteVersion = note.updatedAt || 0;
+            const knownVersion = this.state.remoteVersions[`note:${note.id}`] || 0;
+            if (existsSync(filePath) && remoteVersion <= knownVersion)
+                continue;
+            // Write note stub (title + preview — full content stays in cloud)
+            const content = `# ${note.title}\n\n${note.preview || ''}\n\n---\n*Note ID: ${note.id} · Full content at clearly.sh*\n`;
+            writeFileSync(filePath, content, 'utf8');
+            this.state.remoteVersions[`note:${note.id}`] = remoteVersion;
+            this.state.fileHashes[`notes/${slug}.md`] = md5(content);
+        }
+    }
+    async pushNotes() {
+        const notesDir = join(this.clearlyDir, NOTES_DIR);
+        if (!existsSync(notesDir))
+            return;
+        const files = readdirSync(notesDir).filter((f) => f.endsWith('.md'));
+        for (const file of files) {
+            const filePath = join(notesDir, file);
+            const content = readFileSync(filePath, 'utf8');
+            const hash = md5(content);
+            const key = `notes/${file}`;
+            if (this.state.fileHashes[key] === hash)
+                continue; // unchanged
+            // Extract title from first heading or filename
+            const titleMatch = content.match(/^#\s+(.+)$/m);
+            const title = titleMatch ? titleMatch[1].trim() : file.replace('.md', '');
+            // Check if this is a stub from a cloud note (has Note ID in footer)
+            const idMatch = content.match(/Note ID:\s*(\S+)/);
+            if (idMatch) {
+                // This is a cloud note stub — don't push stubs back up
+                // Only push if user added substantial content
+                const lines = content
+                    .split('\n')
+                    .filter((l) => l.trim() && !l.startsWith('#') && !l.startsWith('*') && !l.startsWith('---'));
+                if (lines.length <= 1) {
+                    this.state.fileHashes[key] = hash;
+                    continue;
+                }
+            }
+            try {
+                await this.callAction('note-create', {
+                    title,
+                    content,
+                    fileType: 'note',
+                    projectId: this.projectId,
+                    source: 'beehaven-sync',
+                });
+                this.state.fileHashes[key] = hash;
+            }
+            catch (err) {
+                this.emit('push-error', `Note sync failed for "${title}": ${err.message}`);
+            }
+        }
+    }
+    // ── File Watching ────────────────────────────────────────────────────
+    watchLocal() {
+        // Watch the .clearly/ directory for changes
+        try {
+            const watcher = fsWatch(this.clearlyDir, { recursive: true }, (_event, filename) => {
+                if (!filename)
+                    return;
+                // Ignore sync state file and CLAUDE.md (we write those)
+                if (filename === SYNC_FILE || filename === CONTEXT_FILE)
+                    return;
+                // Ignore hidden files
+                if (basename(filename).startsWith('.'))
+                    return;
+                this.schedulePush();
+            });
+            this.watchers.push(watcher);
+        }
+        catch {
+            // recursive watch not supported on all platforms — fall back to individual watches
+            this.watchFile(join(this.clearlyDir, TASKS_FILE));
+            this.watchFile(join(this.clearlyDir, MEMORIES_FILE));
+            this.watchDir(join(this.clearlyDir, NOTES_DIR));
+        }
+    }
+    watchFile(filePath) {
+        if (!existsSync(filePath))
+            return;
+        try {
+            const watcher = fsWatch(filePath, () => this.schedulePush());
+            this.watchers.push(watcher);
+        }
+        catch { }
+    }
+    watchDir(dirPath) {
+        if (!existsSync(dirPath))
+            return;
+        try {
+            const watcher = fsWatch(dirPath, (_event, filename) => {
+                if (!filename || basename(filename).startsWith('.'))
+                    return;
+                this.schedulePush();
+            });
+            this.watchers.push(watcher);
+        }
+        catch { }
+    }
+    schedulePush() {
+        if (this.suppressPush)
+            return;
+        if (this.pushTimer)
+            clearTimeout(this.pushTimer);
+        this.pushTimer = setTimeout(() => this.push(), PUSH_DEBOUNCE);
+    }
+    // ── State Persistence ────────────────────────────────────────────────
+    ensureDirectories() {
+        mkdirSync(this.clearlyDir, { recursive: true });
+        mkdirSync(join(this.clearlyDir, NOTES_DIR), { recursive: true });
+    }
+    loadState() {
+        const filePath = join(this.clearlyDir, SYNC_FILE);
+        if (!existsSync(filePath)) {
+            return {
+                lastPullAt: 0,
+                lastPushAt: 0,
+                fileHashes: {},
+                remoteVersions: {},
+                projectId: this.projectId,
+            };
+        }
+        try {
+            return JSON.parse(readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            return {
+                lastPullAt: 0,
+                lastPushAt: 0,
+                fileHashes: {},
+                remoteVersions: {},
+                projectId: this.projectId,
+            };
+        }
+    }
+    saveState() {
+        const filePath = join(this.clearlyDir, SYNC_FILE);
+        writeFileSync(filePath, JSON.stringify(this.state, null, 2), 'utf8');
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+function md5(content) {
+    return createHash('md5').update(content).digest('hex');
+}
+function escapeYaml(str) {
+    return str.replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+}
+/** Parse the simple YAML-ish tasks format */
+export function parseTasksYaml(content) {
+    const tasks = [];
+    let current = null;
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        if (trimmed.startsWith('- id:')) {
+            if (current && current.title)
+                tasks.push(current);
+            current = { id: trimmed.replace('- id:', '').trim() };
+        }
+        else if (current) {
+            const match = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
+            if (match) {
+                const [, key, value] = match;
+                if (key === 'title')
+                    current.title = value;
+                else if (key === 'status')
+                    current.status = value;
+                else if (key === 'description')
+                    current.description = value;
+                else if (key === 'tags') {
+                    current.tags = value
+                        .replace(/[[\]]/g, '')
+                        .split(',')
+                        .map((t) => t.trim())
+                        .filter(Boolean);
+                }
+            }
+        }
+    }
+    if (current && current.title)
+        tasks.push(current);
+    return tasks;
+}
+/** Parse the simple key: "value" memories format */
+export function parseMemoriesYaml(content) {
+    const memories = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const match = trimmed.match(/^([^:]+):\s*"?([^"]*)"?\s*$/);
+        if (match) {
+            const [, key, value] = match;
+            memories.push({ key: key.trim(), value: value.trim() });
+        }
+    }
+    return memories;
+}