@comment-io/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Every
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# Comment Docs
+
+Collaborative markdown editor with provenance tracking, comments, suggestions, and an agent API. Powers [Comment.io](https://comment.io).
+
+## Stack
+
+- **Backend** (`cf/`) — Cloudflare Workers + Durable Objects + Yjs
+- **Frontend** (`src/`) — React 19, Zustand, Milkdown, Tailwind CSS v4, Vite
+
+## Local Development
+
+```bash
+make dev          # CF Worker (:8787) + Vite editor (:3100) — background
+make dev-stop     # Stop dev servers
+make logs         # Tail structured logs (jq)
+```
+
+## Tests
+
+```bash
+cd cf && npx vitest run    # Backend test suite
+npx vite build             # Verify frontend builds
+```
+
+## Agent API
+
+The canonical reference for the agent-facing REST API is served at `/llms.txt` (and `/docs/api` for the interactive spec). Starting points:
+
+- `POST /docs` — create a document
+- `GET /docs/:id` — read (markdown + marks)
+- `PATCH /docs/:id` — edit via `{ old_string, new_string }` patches
+- `POST /docs/:id/comments` — comment / suggest / reply
+
+## CommentFS Local Sync
+
+CommentFS can project selected Comment.io docs into read-only local markdown
+files under `~/Comment Docs`.
+
+Install the CLI:
+
+```bash
+npm install -g @comment-io/cli
+```
+
+```bash
+comment sync login --api-key <usk_...>
+comment sync
+comment sync watch
+```
+
+Enable **Sync locally** on a document first. Local files are not an edit path;
+edit through the UI or API. See `docs/COMMENTFS-SYNC-USAGE.md`.
+
+## Local Notification Daemon
+
+Registered agents can receive @mention notifications through the local daemon:
+
+```bash
+comment daemon install
+comment daemon health
+comment notifications wait --profile <handle> --timeout 30m
+```
+
+The notification wait command leases work locally. Ack the delivered claim after
+handling it, or release it so another worker can retry:
+
+```bash
+comment notifications ack <claim-id>
+comment notifications release <claim-id>
+```
+
+## Docs
+
+- `CLAUDE.md` — repo-level agent/developer instructions
+- `docs/LOGGING.md` — structured logging guide
+- `docs/ARCHITECTURE.md` — architecture notes

package/bin/comment.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(binDir, '..');
+const tsxCli = resolve(packageRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+const syncCli = resolve(packageRoot, 'scripts', 'commentfs-sync.ts');
+
+const child = spawnSync(process.execPath, [tsxCli, syncCli, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+if (child.error) {
+  console.error(child.error.message);
+  process.exit(1);
+}
+
+if (child.signal) {
+  process.kill(process.pid, child.signal);
+} else {
+  process.exit(child.status ?? 0);
+}

package/docs/COMMENTFS-SYNC-USAGE.md

@@ -0,0 +1,88 @@
+# CommentFS Read-Only Local Sync
+
+CommentFS projects selected Comment.io documents into local markdown files. The
+online Comment.io document is canonical. Local markdown files are read-only
+snapshots for search, context, indexing, and agent inspection.
+
+Do not edit synced markdown files directly. Humans should edit through the
+Comment.io UI. Agents should edit through the Comment.io API.
+
+## Setup
+
+The CommentFS UI is currently gated behind `VITE_ENABLE_COMMENTFS_UI=true` so it
+can be enabled on staging without exposing the flow in production.
+
+1. Open Comment.io settings and generate a CommentFS key.
+2. Configure the local CLI:
+
+```bash
+comment sync login --api-key <usk_...>
+```
+
+For staging or another deployment, include the base URL:
+
+```bash
+comment sync login --api-key <usk_...> --base-url https://staging.example.com
+```
+
+3. Open a document's access panel and enable **Sync locally**.
+4. Run one sync:
+
+```bash
+comment sync
+```
+
+5. Keep projections updated:
+
+```bash
+comment sync watch
+```
+
+By default files are written under `~/Comment Docs`.
+
+## Useful Commands
+
+```bash
+comment sync status
+comment sync repair
+comment sync explain <path>
+comment sync recover <path>
+comment sync watch --interval 10s --full-interval 5m
+```
+
+`comment sync repair` restores read-only permissions on existing projections.
+`comment sync explain` points a markdown or sidecar path back to its source
+document and API docs. `comment sync recover` explains a preserved local edit
+artifact.
+
+## Sidecars
+
+Each sync root has a `.comment/` folder. Important files include:
+
+- `.comment/manifest.json`: local projection manifest.
+- `.comment/docs/<slug>/status.json`: sync health, source URL, revision, sidecar
+  paths, and recovery metadata.
+- `.comment/docs/<slug>/edit.md`: short edit instructions and API doc links.
+- `.comment/docs/<slug>/authorship.json`: authorship/provenance metadata.
+- `.comment/docs/<slug>/comments.json`: comment and suggestion metadata.
+- `.comment/docs/<slug>/participants.json`: participant metadata.
+- `.comment/recovery/*.local.md`: preserved local text from unsupported local
+  edits.
+
+## Local Edits
+
+If a local tool changes a synced markdown file, the next sync preserves that
+local text under `.comment/recovery/` and restores the canonical Comment.io
+version. It does not upload local markdown edits.
+
+To apply an intended change, open the document in Comment.io or use the API docs
+linked from the sidecar `api_docs_url`.
+
+## Auth Notes
+
+`COMMENT_IO_USER_API_KEY` and `usk_` keys are only for read-only projection sync.
+They can poll selected docs and fetch projections. They cannot write documents.
+
+Agent edits need an edit-capable Comment.io credential such as
+`COMMENT_IO_AGENT_SECRET`, a registered agent credential, or an edit-capable
+per-document token.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@comment-io/cli",
+  "version": "0.1.0",
+  "description": "Comment.io CLI and local notification daemon",
+  "private": false,
+  "type": "module",
+  "homepage": "https://comment.io",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/comment-io/comment.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comment-io/comment/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "comment": "bin/comment.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/commentfs-sync.ts",
+    "scripts/commentd.ts",
+    "shared/commentfs-sync.ts",
+    "shared/comment-notifications.ts",
+    "docs/COMMENTFS-SYNC-USAGE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/prepare-cli-package.mjs"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/commentd.ts

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { rm, readFile } from 'node:fs/promises';
+import { hostname, homedir, platform } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import net from 'node:net';
+import {
+  DEFAULT_COMMENTFS_BASE_URL,
+  DEFAULT_SYNC_ROOT,
+  readCommentFsConfig,
+  syncConfiguredCommentDocsSettled,
+  syncRemoteSelectedCommentDocsSettled,
+} from '../shared/commentfs-sync.js';
+import {
+  appendLog,
+  buildQueueEnvelope,
+  daemonLogPath,
+  daemonPidPath,
+  daemonRequest,
+  daemonSocketPath,
+  ensurePrivateDir,
+  findClaimFile,
+  isProcessAlive,
+  loadAgentProfiles,
+  readPid,
+  removeClaimFile,
+  republishClaimFile,
+  sweepExpiredLocalClaims,
+  writePid,
+  writeQueueEnvelope,
+  type CommentAgentProfile,
+  type DaemonRequest,
+  type DaemonResponse,
+  type NotificationLeaseEnvelope,
+  type NotificationPayload,
+} from '../shared/comment-notifications.js';
+
+interface DaemonOptions {
+  rootDir?: string;
+  homeDir?: string;
+  intervalMs?: number;
+  fullIntervalMs?: number;
+  maxBackoffMs?: number;
+}
+
+interface NotificationProfileHealth {
+  handle: string;
+  connected: boolean;
+  lastConnectedAt: string | null;
+  lastMessageAt: string | null;
+  lastLeaseAt: string | null;
+  lastError: string | null;
+  reconnects: number;
+}
+
+interface DaemonHealth {
+  pid: number;
+  started_at: string;
+  socket_path: string;
+  sync: {
+    enabled: boolean;
+    last_attempt_at: string | null;
+    last_success_at: string | null;
+    last_error_at: string | null;
+    last_error: string | null;
+    consecutive_failures: number;
+  };
+  notifications: Record<string, NotificationProfileHealth>;
+}
+
+const defaultOptions: Required<DaemonOptions> = {
+  rootDir: DEFAULT_SYNC_ROOT,
+  homeDir: homedir(),
+  intervalMs: 10_000,
+  fullIntervalMs: 5 * 60_000,
+  maxBackoffMs: 60_000,
+};
+
+export async function runCommentDaemon(options: DaemonOptions = {}): Promise<void> {
+  const opts = { ...defaultOptions, ...options };
+  const socketPath = daemonSocketPath(opts.homeDir);
+  const pidPath = daemonPidPath(opts.homeDir);
+  const logPath = daemonLogPath(new Date(), opts.homeDir);
+  const abort = new AbortController();
+  const startedAt = new Date().toISOString();
+  const profileHealth = new Map<string, NotificationProfileHealth>();
+  const health: DaemonHealth = {
+    pid: process.pid,
+    started_at: startedAt,
+    socket_path: socketPath,
+    sync: {
+      enabled: false,
+      last_attempt_at: null,
+      last_success_at: null,
+      last_error_at: null,
+      last_error: null,
+      consecutive_failures: 0,
+    },
+    notifications: {},
+  };
+
+  async function log(level: 'info' | 'warn' | 'error', msg: string, data: Record<string, unknown> = {}): Promise<void> {
+    await appendLog(logPath, JSON.stringify({ ts: new Date().toISOString(), level, component: 'commentd', msg, data }));
+  }
+
+  await ensurePrivateDir(dirname(pidPath));
+  const existingPid = await readPid(pidPath);
+  if (existingPid && await isProcessAlive(existingPid)) {
+    throw new Error(`comment daemon already running with pid ${existingPid}`);
+  }
+  await writePid(pidPath);
+
+  if (platform() !== 'win32' && existsSync(socketPath)) {
+    const resp = await daemonRequest({ op: 'health' }, opts.homeDir, 500);
+    if (resp.ok) throw new Error(`comment daemon already listening at ${socketPath}`);
+    await rm(socketPath, { force: true });
+  }
+
+  const server = net.createServer((socket) => {
+    let buffer = '';
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf-8');
+      const idx = buffer.indexOf('\n');
+      if (idx < 0) return;
+      const raw = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      handleSocketRequest(raw)
+        .then((response) => socket.end(`${JSON.stringify(response)}\n`))
+        .catch((err) => socket.end(`${JSON.stringify({ ok: false, error: String(err), code: 'INTERNAL' })}\n`));
+    });
+  });
+
+  async function handleSocketRequest(raw: string): Promise<DaemonResponse> {
+    let request: DaemonRequest;
+    try {
+      request = JSON.parse(raw) as DaemonRequest;
+    } catch {
+      return { ok: false, error: 'Invalid JSON', code: 'BAD_REQUEST' };
+    }
+
+    if (request.op === 'health') {
+      health.notifications = Object.fromEntries(profileHealth);
+      return { ok: true, op: 'health', health };
+    }
+    if (request.op === 'stop') {
+      abort.abort();
+      return { ok: true, op: 'stop' };
+    }
+    if (request.op === 'reload-profiles') {
+      await log('info', 'daemon.reload_profiles_requested');
+      return { ok: true, op: 'reload-profiles' };
+    }
+    if (request.op === 'ack' || request.op === 'release') {
+      if (!request.claim_id) return { ok: false, error: 'Missing claim_id', code: 'VALIDATION_ERROR' };
+      return proxyClaim(request.op, request.claim_id);
+    }
+    return { ok: false, error: `Unknown op: ${(request as { op?: string }).op}`, code: 'UNKNOWN_OP' };
+  }
+
+  async function proxyClaim(op: 'ack' | 'release', claimId: string): Promise<DaemonResponse> {
+    const found = await findClaimFile(claimId, opts.homeDir);
+    if (!found) return { ok: false, error: `Unknown local claim ${claimId}`, code: 'CLAIM_NOT_FOUND' };
+    const envelope = JSON.parse(await readFile(found.path, 'utf-8')) as NotificationLeaseEnvelope;
+    const profiles = await loadAgentProfiles({ homeDir: opts.homeDir, defaultBaseUrl: envelope.base_url });
+    const profile = profiles.find((item) => item.handle === envelope.profile);
+    if (!profile) return { ok: false, error: `Profile not configured: ${envelope.profile}`, code: 'PROFILE_NOT_FOUND' };
+
+    const url = `${profile.baseUrl}/agents/me/notifications/claim/${encodeURIComponent(claimId)}/${op}`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${profile.agentSecret}` },
+    });
+    const body = await resp.text();
+    if (!resp.ok) {
+      await log('warn', `notification.${op}_failed`, { claim_id: claimId, status: resp.status, body });
+      return { ok: false, error: body || `${op} failed`, code: `SERVER_${resp.status}` };
+    }
+
+    if (op === 'ack') await removeClaimFile(claimId, opts.homeDir);
+    else await republishClaimFile(claimId, opts.homeDir);
+    await log('info', `notification.${op}`, { claim_id: claimId, profile: envelope.profile });
+    return { ok: true, op, claim_id: claimId };
+  }
+
+  await new Promise<void>((resolvePromise, reject) => {
+    server.once('error', reject);
+    server.listen(socketPath, () => resolvePromise());
+  });
+  if (platform() !== 'win32') {
+    await import('node:fs/promises').then(({ chmod }) => chmod(socketPath, 0o600)).catch(() => {});
+  }
+
+  await log('info', 'daemon.started', { pid: process.pid, socket_path: socketPath });
+
+  const loops = [
+    runSyncLoop(opts, health, abort.signal, log),
+    runNotificationLoops(opts, profileHealth, abort.signal, log),
+    runLocalSweepLoop(opts.homeDir, abort.signal, log),
+  ];
+
+  const stop = async () => {
+    abort.abort();
+    server.close();
+    if (platform() !== 'win32') await rm(socketPath, { force: true });
+    await rm(pidPath, { force: true });
+    await log('info', 'daemon.stopped');
+  };
+
+  process.once('SIGTERM', () => { void stop(); });
+  process.once('SIGINT', () => { void stop(); });
+
+  await Promise.race([
+    Promise.allSettled(loops),
+    new Promise<void>((resolvePromise) => abort.signal.addEventListener('abort', () => resolvePromise(), { once: true })),
+  ]);
+  await stop();
+}
+
+async function runSyncLoop(
+  opts: Required<DaemonOptions>,
+  health: DaemonHealth,
+  signal: AbortSignal,
+  log: (level: 'info' | 'warn' | 'error', msg: string, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  let lastFullSyncAt = 0;
+  while (!signal.aborted) {
+    const attemptedAt = new Date().toISOString();
+    health.sync.last_attempt_at = attemptedAt;
+    try {
+      const configured = await readCommentFsConfig(opts.homeDir).catch(() => null);
+      const userApiKey = process.env.COMMENT_IO_USER_API_KEY ?? configured?.userApiKey;
+      const baseUrl = (configured?.baseUrl ?? DEFAULT_COMMENTFS_BASE_URL).replace(/\/$/, '');
+      health.sync.enabled = Boolean(userApiKey);
+      const full = Boolean(userApiKey && (lastFullSyncAt === 0 || Date.now() - lastFullSyncAt >= opts.fullIntervalMs));
+      const results = userApiKey
+        ? await syncRemoteSelectedCommentDocsSettled({ rootDir: resolve(opts.rootDir), baseUrl, userApiKey, full, homeDir: opts.homeDir })
+        : await syncConfiguredCommentDocsSettled({ rootDir: resolve(opts.rootDir), homeDir: opts.homeDir });
+      if (full) lastFullSyncAt = Date.now();
+      const failures = results.filter((result) => !result.ok).length;
+      if (failures > 0) throw new Error(`${failures} CommentFS sync item(s) failed`);
+      health.sync.last_success_at = new Date().toISOString();
+      health.sync.last_error = null;
+      health.sync.last_error_at = null;
+      health.sync.consecutive_failures = 0;
+      await log('info', 'sync.poll_ok', { count: results.length, full });
+      await delay(opts.intervalMs, signal);
+    } catch (err) {
+      health.sync.consecutive_failures += 1;
+      health.sync.last_error_at = new Date().toISOString();
+      health.sync.last_error = err instanceof Error ? err.message : String(err);
+      const backoff = Math.min(opts.maxBackoffMs, Math.max(opts.intervalMs, opts.intervalMs * 2 ** Math.min(health.sync.consecutive_failures - 1, 6)));
+      await log('warn', 'sync.poll_failed', { error: health.sync.last_error, retry_ms: backoff });
+      await delay(backoff, signal);
+    }
+  }
+}
+
+async function runNotificationLoops(
+  opts: Required<DaemonOptions>,
+  profileHealth: Map<string, NotificationProfileHealth>,
+  signal: AbortSignal,
+  log: (level: 'info' | 'warn' | 'error', msg: string, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  const profiles = await loadAgentProfiles({ homeDir: opts.homeDir });
+  if (profiles.length === 0) {
+    await log('info', 'notifications.no_profiles');
+    return;
+  }
+  await Promise.allSettled(profiles.map((profile) => runNotificationProfile(profile, opts.homeDir, profileHealth, signal, log)));
+}
+
+async function runNotificationProfile(
+  profile: CommentAgentProfile,
+  homeDir: string,
+  profileHealth: Map<string, NotificationProfileHealth>,
+  signal: AbortSignal,
+  log: (level: 'info' | 'warn' | 'error', msg: string, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  let reconnects = 0;
+  const health: NotificationProfileHealth = {
+    handle: profile.handle,
+    connected: false,
+    lastConnectedAt: null,
+    lastMessageAt: null,
+    lastLeaseAt: null,
+    lastError: null,
+    reconnects,
+  };
+  profileHealth.set(profile.handle, health);
+
+  while (!signal.aborted) {
+    try {
+      health.connected = true;
+      health.lastConnectedAt = new Date().toISOString();
+      health.lastError = null;
+      const lease = await waitForServerNotification(profile, signal);
+      health.lastMessageAt = new Date().toISOString();
+      if (lease) {
+        const envelope = buildQueueEnvelope({
+          profile: profile.handle,
+          baseUrl: profile.baseUrl,
+          claimId: lease.claim_id,
+          claimedAt: lease.claimed_at,
+          leaseExpiresAt: lease.lease_expires_at,
+          notification: lease.notification,
+        });
+        await writeQueueEnvelope(envelope, homeDir);
+        health.lastLeaseAt = new Date().toISOString();
+        await log('info', 'notifications.queued', { profile: profile.handle, claim_id: lease.claim_id, notification_id: lease.notification.id });
+      }
+      reconnects = 0;
+      health.reconnects = reconnects;
+    } catch (err) {
+      health.lastError = err instanceof Error ? err.message : String(err);
+      await log('warn', 'notifications.wait_failed', { profile: profile.handle, error: health.lastError });
+      reconnects += 1;
+      health.reconnects = reconnects;
+      await delay(Math.min(60_000, 1000 * 2 ** Math.min(reconnects, 6)), signal);
+    }
+  }
+  health.connected = false;
+}
+
+async function waitForServerNotification(
+  profile: CommentAgentProfile,
+  signal: AbortSignal,
+): Promise<{
+  claim_id: string;
+  claimed_at: string;
+  lease_expires_at: string;
+  notification: NotificationPayload;
+} | null> {
+  const resp = await fetch(`${profile.baseUrl}/agents/me/notifications/wait?timeout=55&lease=600`, {
+    method: 'POST',
+    signal,
+    headers: {
+      Authorization: `Bearer ${profile.agentSecret}`,
+      'Content-Type': 'application/json',
+    },
+  });
+  if (resp.status === 204) return null;
+  if (!resp.ok) throw new Error(`wait failed with ${resp.status}`);
+  return resp.json() as Promise<{
+    claim_id: string;
+    claimed_at: string;
+    lease_expires_at: string;
+    notification: NotificationPayload;
+  }>;
+}
+
+async function runLocalSweepLoop(
+  homeDir: string,
+  signal: AbortSignal,
+  log: (level: 'info' | 'warn' | 'error', msg: string, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  while (!signal.aborted) {
+    const swept = await sweepExpiredLocalClaims(homeDir).catch(() => 0);
+    if (swept > 0) await log('info', 'notifications.local_claims_swept', { swept });
+    await delay(30_000, signal);
+  }
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolvePromise) => {
+    if (signal.aborted) {
+      resolvePromise();
+      return;
+    }
+    const timer = setTimeout(resolvePromise, ms);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolvePromise();
+    }, { once: true });
+  });
+}
+
+export async function startDetachedDaemon(args: string[] = []): Promise<{ pid: number | undefined }> {
+  const script = fileURLToPath(import.meta.url);
+  const packageRoot = resolve(dirname(script), '..');
+  const tsxCli = resolve(packageRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+  const child = spawn(process.execPath, [tsxCli, script, 'run', ...args], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return { pid: child.pid };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv[2] === 'run') {
+    runCommentDaemon().catch((err) => {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+  }
+}