@comment-io/cli 0.1.0

package/scripts/commentfs-sync.ts

@@ -0,0 +1,586 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { resolve } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_COMMENTFS_BASE_URL,
+  DEFAULT_SYNC_ROOT,
+  readCommentFsConfig,
+  explainCommentFsPath,
+  getCommentFsStatus,
+  recoverCommentFsPath,
+  repairCommentFsPermissions,
+  saveCommentFsUserApiKey,
+  syncConfiguredCommentDocs,
+  syncConfiguredCommentDocsSettled,
+  syncOneCommentDoc,
+  syncRemoteSelectedCommentDocsSettled,
+} from '../shared/commentfs-sync.js';
+import {
+  daemonPidPath,
+  daemonRequest,
+  isProcessAlive,
+  loadAgentProfiles,
+  readPid,
+  waitForLocalNotification,
+} from '../shared/comment-notifications.js';
+import { runCommentDaemon, startDetachedDaemon } from './commentd.js';
+
+interface ParsedArgs {
+  command: string[];
+  options: Record<string, string | true>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const command: string[] = [];
+  const options: Record<string, string | true> = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        options[key] = next;
+        i += 1;
+      } else {
+        options[key] = true;
+      }
+    } else {
+      command.push(arg);
+    }
+  }
+  return { command, options };
+}
+
+function optionString(options: Record<string, string | true>, key: string): string | undefined {
+  const value = options[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function usage(): string {
+  return [
+    'Usage:',
+    '  comment sync add <doc-url-or-slug> [--root <folder>] [--token <token>] [--base-url <url>] [--agent <handle>] [--filename <name.md>]',
+    '  comment sync login --api-key <user-api-key> [--base-url <url>]',
+    '  comment sync [--root <folder>] [--api-key <user-api-key>]',
+    '  comment sync status [--root <folder>]',
+    '  comment sync repair [--root <folder>]',
+    '  comment sync recover <path>',
+    '  comment sync watch [--root <folder>] [--interval <seconds>] [--full-interval <seconds>] [--max-backoff <seconds>] [--once] [--api-key <user-api-key>] [--base-url <url>]',
+    '  comment sync explain <path>',
+    '  comment daemon run|start|stop|status|health|install|uninstall [--root <folder>]',
+    '  comment notifications wait --profile <handle> [--timeout 30m] [--poll 250ms]',
+    '  comment notifications ack <claim-id>',
+    '  comment notifications release <claim-id>',
+    '',
+    'Local markdown files are read-only projections. Edit through Comment.io UI or API.',
+    `Default root: ${DEFAULT_SYNC_ROOT}`,
+  ].join('\n');
+}
+
+async function main(): Promise<void> {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (options.help || command[0] === 'help') {
+    console.log(usage());
+    return;
+  }
+
+  if (command[0] === 'daemon') {
+    await runDaemonCommand(command.slice(1), options);
+    return;
+  }
+
+  if (command[0] === 'notifications') {
+    await runNotificationsCommand(command.slice(1), options);
+    return;
+  }
+
+  if (command[0] !== 'sync') {
+    throw new Error(`Unknown command.\n\n${usage()}`);
+  }
+
+  const rootDir = optionString(options, 'root');
+
+  if (command[1] === 'login') {
+    const apiKey = optionString(options, 'api-key');
+    if (!apiKey) throw new Error(`Missing --api-key.\n\n${usage()}`);
+    const saved = await saveCommentFsUserApiKey({
+      userApiKey: apiKey,
+      baseUrl: optionString(options, 'base-url'),
+    });
+    console.log(`saved: ${saved.path}`);
+    console.log(`base_url: ${saved.config.baseUrl}`);
+    if (options['no-daemon'] !== true) {
+      await maybeOfferDaemonInstall();
+    }
+    return;
+  }
+
+  if (command[1] === 'add') {
+    const input = command[2];
+    if (!input) throw new Error(`Missing doc URL or slug.\n\n${usage()}`);
+    const result = await syncOneCommentDoc({
+      rootDir,
+      input,
+      token: optionString(options, 'token'),
+      baseUrl: optionString(options, 'base-url'),
+      agentHandle: optionString(options, 'agent'),
+      filename: optionString(options, 'filename'),
+    });
+    printResult(result);
+    return;
+  }
+
+  if (command[1] === 'explain') {
+    const inputPath = command[2];
+    if (!inputPath) throw new Error(`Missing path.\n\n${usage()}`);
+    const result = await explainCommentFsPath(inputPath);
+    console.log(result.explanation);
+    return;
+  }
+
+  if (command[1] === 'recover') {
+    const inputPath = command[2];
+    if (!inputPath) throw new Error(`Missing path.\n\n${usage()}`);
+    const result = await recoverCommentFsPath(inputPath);
+    console.log(result.instructions);
+    console.log(`markdown: ${result.markdownPath}`);
+    console.log(`status:   ${result.statusPath}`);
+    console.log(`edit:     ${result.editPath}`);
+    return;
+  }
+
+  if (command[1] === 'watch') {
+    await runWatch({
+      rootDir,
+      baseUrl: optionString(options, 'base-url'),
+      apiKey: optionString(options, 'api-key'),
+      intervalMs: parseIntervalMs(optionString(options, 'interval') ?? '10s'),
+      fullIntervalMs: parseIntervalMs(optionString(options, 'full-interval') ?? '5m'),
+      maxBackoffMs: parseIntervalMs(optionString(options, 'max-backoff') ?? '1m'),
+      once: options.once === true,
+    });
+    return;
+  }
+
+  if (command[1] === 'status') {
+    const status = await getCommentFsStatus(rootDir);
+    console.log(`root: ${status.rootDir}`);
+    console.log(`manifest: ${status.manifestPath}`);
+    if (status.docs.length === 0) {
+      console.log('No Comment.io docs configured.');
+      return;
+    }
+    for (const doc of status.docs) {
+      const health = doc.syncHealth?.status ?? 'unknown';
+      const revision = doc.revision === null ? 'unknown' : String(doc.revision);
+      const mode = doc.readOnly ? 'read-only' : 'writable-or-missing';
+      console.log(`${health}: ${doc.title} (${doc.slug}) revision ${revision} ${mode}`);
+      console.log(`  markdown: ${doc.markdownPath}`);
+      console.log(`  status:   ${doc.statusPath}`);
+      if (doc.localChange) console.log(`  recovery: ${doc.localChange.recoveryFile}`);
+      if (doc.syncHealth?.lastError) console.log(`  error:    ${doc.syncHealth.lastError}`);
+    }
+    return;
+  }
+
+  if (command[1] === 'repair') {
+    const results = await repairCommentFsPermissions(rootDir);
+    if (results.length === 0) {
+      console.log('No Comment.io docs configured.');
+      return;
+    }
+    for (const result of results) {
+      if (!result.existed) console.log(`missing: ${result.title} (${result.markdownPath})`);
+      else if (result.repaired) console.log(`repaired: ${result.title} (${result.markdownPath})`);
+      else console.log(`ok: ${result.title} (${result.markdownPath})`);
+    }
+    return;
+  }
+
+  if (command.length === 1) {
+    const apiKey = optionString(options, 'api-key');
+    const results = await syncConfiguredCommentDocs({ rootDir, userApiKey: apiKey });
+    if (results.length === 0) {
+      console.log('No Comment.io docs configured. Run `comment sync add <doc-url-or-slug>` first.');
+      return;
+    }
+    for (const result of results) printResult(result);
+    return;
+  }
+
+  throw new Error(`Unknown sync subcommand.\n\n${usage()}`);
+}
+
+async function runDaemonCommand(command: string[], options: Record<string, string | true>): Promise<void> {
+  const sub = command[0] ?? 'status';
+  if (sub === 'run') {
+    await runCommentDaemon({
+      rootDir: optionString(options, 'root'),
+      intervalMs: parseIntervalMs(optionString(options, 'interval') ?? '10s'),
+      fullIntervalMs: parseIntervalMs(optionString(options, 'full-interval') ?? '5m'),
+      maxBackoffMs: parseIntervalMs(optionString(options, 'max-backoff') ?? '1m'),
+    });
+    return;
+  }
+
+  if (sub === 'start') {
+    const health = await daemonRequest({ op: 'health' });
+    if (health.ok) {
+      console.log('daemon: already running');
+      return;
+    }
+    const started = await startDetachedDaemon([]);
+    console.log(`daemon: starting${started.pid ? ` pid ${started.pid}` : ''}`);
+    for (let i = 0; i < 20; i++) {
+      await sleep(250);
+      const resp = await daemonRequest({ op: 'health' }, homedir(), 500);
+      if (resp.ok) {
+        console.log('daemon: running');
+        return;
+      }
+    }
+    throw new Error('Daemon did not become healthy within 5s.');
+  }
+
+  if (sub === 'stop') {
+    const resp = await daemonRequest({ op: 'stop' });
+    if (resp.ok) {
+      console.log('daemon: stopping');
+      return;
+    }
+    const pid = await readPid(daemonPidPath());
+    if (pid && await isProcessAlive(pid)) {
+      process.kill(pid, 'SIGTERM');
+      console.log(`daemon: sent SIGTERM to ${pid}`);
+      return;
+    }
+    console.log('daemon: not running');
+    return;
+  }
+
+  if (sub === 'health') {
+    const resp = await daemonRequest({ op: 'health' });
+    console.log(JSON.stringify(resp, null, 2));
+    if (!resp.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (sub === 'status') {
+    const pid = await readPid(daemonPidPath());
+    const alive = pid ? await isProcessAlive(pid) : false;
+    const resp = await daemonRequest({ op: 'health' }, homedir(), 500);
+    console.log(`pid: ${pid ?? 'none'}`);
+    console.log(`process: ${alive ? 'running' : 'not-running'}`);
+    console.log(`socket: ${resp.ok ? 'healthy' : 'unavailable'}`);
+    if (resp.ok) console.log(JSON.stringify((resp as { health?: unknown }).health, null, 2));
+    return;
+  }
+
+  if (sub === 'install') {
+    await installDaemonService();
+    console.log('daemon: installed');
+    return;
+  }
+
+  if (sub === 'uninstall') {
+    await uninstallDaemonService();
+    console.log('daemon: uninstalled');
+    return;
+  }
+
+  throw new Error(`Unknown daemon subcommand.\n\n${usage()}`);
+}
+
+async function runNotificationsCommand(command: string[], options: Record<string, string | true>): Promise<void> {
+  const sub = command[0];
+  if (sub === 'wait') {
+    let profile = optionString(options, 'profile');
+    if (!profile) {
+      const profiles = await loadAgentProfiles();
+      profile = profiles[0]?.handle;
+    }
+    if (!profile) throw new Error('Missing --profile and no configured Comment.io agent profile found.');
+
+    const health = await daemonRequest({ op: 'health' }, homedir(), 500);
+    if (!health.ok) {
+      console.log(JSON.stringify({ timeout: true, error: 'comment daemon is not running', code: 'DAEMON_UNAVAILABLE' }));
+      return;
+    }
+
+    const timeoutMs = parseIntervalMs(optionString(options, 'timeout') ?? '30m');
+    const pollMs = parseIntervalMs(optionString(options, 'poll') ?? '250ms');
+    const envelope = await waitForLocalNotification({ profile, timeoutMs, pollMs });
+    if (!envelope) {
+      console.log(JSON.stringify({ timeout: true, profile }));
+      return;
+    }
+    console.log(JSON.stringify(envelope, null, 2));
+    return;
+  }
+
+  if (sub === 'ack' || sub === 'release') {
+    const claimId = command[1];
+    if (!claimId) throw new Error(`Missing claim id.\n\n${usage()}`);
+    const resp = await daemonRequest({ op: sub, claim_id: claimId });
+    console.log(JSON.stringify(resp, null, 2));
+    if (!resp.ok) process.exitCode = 1;
+    return;
+  }
+
+  throw new Error(`Unknown notifications subcommand.\n\n${usage()}`);
+}
+
+async function maybeOfferDaemonInstall(): Promise<void> {
+  const health = await daemonRequest({ op: 'health' }, homedir(), 500);
+  if (health.ok) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log('daemon: not running; run `comment daemon install` or `comment daemon start` to enable background sync and notifications.');
+    return;
+  }
+  process.stdout.write('Install and start the Comment.io daemon for background sync and notifications? [y/N] ');
+  const answer = await new Promise<string>((resolvePromise) => {
+    process.stdin.once('data', (chunk) => resolvePromise(chunk.toString('utf-8').trim().toLowerCase()));
+  });
+  if (answer === 'y' || answer === 'yes') {
+    await installDaemonService();
+  } else {
+    console.log('daemon: skipped');
+  }
+}
+
+function commandPaths(): { tsxCli: string; cliScript: string } {
+  const script = fileURLToPath(import.meta.url);
+  const packageRoot = resolve(dirname(script), '..');
+  return {
+    tsxCli: resolve(packageRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+    cliScript: script,
+  };
+}
+
+async function installDaemonService(): Promise<void> {
+  const { tsxCli, cliScript } = commandPaths();
+  if (platform() === 'darwin') {
+    const plistPath = resolve(homedir(), 'Library', 'LaunchAgents', 'io.comment.daemon.plist');
+    await mkdir(dirname(plistPath), { recursive: true, mode: 0o755 });
+    const plist = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      '<dict>',
+      '  <key>Label</key><string>io.comment.daemon</string>',
+      '  <key>ProgramArguments</key>',
+      '  <array>',
+      `    <string>${escapeXml(process.execPath)}</string>`,
+      `    <string>${escapeXml(tsxCli)}</string>`,
+      `    <string>${escapeXml(cliScript)}</string>`,
+      '    <string>daemon</string>',
+      '    <string>run</string>',
+      '  </array>',
+      '  <key>RunAtLoad</key><true/>',
+      '  <key>KeepAlive</key><true/>',
+      '</dict>',
+      '</plist>',
+      '',
+    ].join('\n');
+    await writeFile(plistPath, plist, { mode: 0o644 });
+    spawnSync('launchctl', ['unload', plistPath], { stdio: 'ignore' });
+    spawnSync('launchctl', ['load', '-w', plistPath], { stdio: 'inherit' });
+    return;
+  }
+
+  if (platform() === 'linux') {
+    const unitDir = resolve(homedir(), '.config', 'systemd', 'user');
+    const unitPath = resolve(unitDir, 'comment-io.service');
+    await mkdir(unitDir, { recursive: true, mode: 0o755 });
+    const unit = [
+      '[Unit]',
+      'Description=Comment.io local daemon',
+      '',
+      '[Service]',
+      `ExecStart=${process.execPath} ${tsxCli} ${cliScript} daemon run`,
+      'Restart=always',
+      'RestartSec=5',
+      '',
+      '[Install]',
+      'WantedBy=default.target',
+      '',
+    ].join('\n');
+    await writeFile(unitPath, unit, { mode: 0o644 });
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+    spawnSync('systemctl', ['--user', 'enable', '--now', 'comment-io.service'], { stdio: 'inherit' });
+    return;
+  }
+
+  await runDaemonCommand(['start'], {});
+}
+
+async function uninstallDaemonService(): Promise<void> {
+  if (platform() === 'darwin') {
+    const plistPath = resolve(homedir(), 'Library', 'LaunchAgents', 'io.comment.daemon.plist');
+    spawnSync('launchctl', ['unload', plistPath], { stdio: 'ignore' });
+    await rm(plistPath, { force: true });
+    return;
+  }
+  if (platform() === 'linux') {
+    spawnSync('systemctl', ['--user', 'disable', '--now', 'comment-io.service'], { stdio: 'ignore' });
+    await rm(resolve(homedir(), '.config', 'systemd', 'user', 'comment-io.service'), { force: true });
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+  }
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function printResult(result: {
+  ok: boolean;
+  title: string;
+  revision?: number;
+  changed?: boolean;
+  localChangeDetected?: boolean;
+  recoveryPath?: string;
+  disabled?: boolean;
+  markdownPath: string;
+  statusPath: string;
+  error?: string;
+}): void {
+  if (!result.ok) {
+    console.log(`error: ${result.title}`);
+    console.log(`markdown: ${result.markdownPath}`);
+    console.log(`status:   ${result.statusPath}`);
+    console.log(`message:  ${result.error ?? 'unknown error'}`);
+    return;
+  }
+  if (result.disabled) {
+    console.log(`unselected: ${result.title}`);
+    console.log(`removed:  ${result.markdownPath}`);
+    console.log(`status:   ${result.statusPath}`);
+    if (result.recoveryPath) console.log(`recovery: ${result.recoveryPath}`);
+    return;
+  }
+  const state = result.localChangeDetected ? 'recovered-local-change' : result.changed ? 'updated' : 'unchanged';
+  console.log(`${state}: ${result.title} (revision ${result.revision})`);
+  console.log(`markdown: ${result.markdownPath}`);
+  console.log(`status:   ${result.statusPath}`);
+  if (result.recoveryPath) console.log(`recovery: ${result.recoveryPath}`);
+}
+
+async function runWatch(options: {
+  rootDir?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  intervalMs: number;
+  fullIntervalMs: number;
+  maxBackoffMs: number;
+  once: boolean;
+}): Promise<void> {
+  const configured = await readCommentFsConfig().catch(() => null);
+  const apiKey = options.apiKey ?? process.env.COMMENT_IO_USER_API_KEY ?? configured?.userApiKey;
+  const baseUrl = (options.baseUrl ?? configured?.baseUrl ?? DEFAULT_COMMENTFS_BASE_URL).replace(/\/$/, '');
+  const rootDir = resolve(options.rootDir ?? DEFAULT_SYNC_ROOT);
+  const authMode = apiKey ? 'user_api_key' : 'configured_doc_credentials';
+  const maxBackoffMs = Math.max(options.maxBackoffMs, options.intervalMs);
+  let lastFullSyncAt = 0;
+  let consecutiveFailures = 0;
+  let emptyPolls = 0;
+
+  console.log('watch: starting CommentFS read-only projection sync');
+  console.log(`root: ${rootDir}`);
+  console.log(`base_url: ${apiKey ? baseUrl : 'per-doc manifest URLs'}`);
+  console.log(`auth_mode: ${authMode}`);
+  console.log(`interval: ${formatDuration(options.intervalMs)}`);
+  console.log(`full_reconcile_interval: ${apiKey ? formatDuration(options.fullIntervalMs) : 'not used without a user API key'}`);
+  console.log(`max_backoff: ${formatDuration(maxBackoffMs)}`);
+
+  do {
+    try {
+      const full = Boolean(apiKey && (lastFullSyncAt === 0 || Date.now() - lastFullSyncAt >= options.fullIntervalMs));
+      const results = apiKey
+        ? await syncRemoteSelectedCommentDocsSettled({
+            rootDir,
+            baseUrl,
+            userApiKey: apiKey,
+            full,
+          })
+        : await syncConfiguredCommentDocsSettled({ rootDir });
+      if (full) lastFullSyncAt = Date.now();
+
+      const failures = results.filter((result) => !result.ok).length;
+      if (failures === 0) consecutiveFailures = 0;
+      else consecutiveFailures += 1;
+
+      if (results.length === 0) {
+        emptyPolls += 1;
+        if (emptyPolls === 1 || emptyPolls % 6 === 0 || options.once) {
+          console.log(`${watchStamp()} ${apiKey
+            ? 'No remote Comment.io sync changes.'
+            : 'No Comment.io docs configured. Run `comment sync add <doc-url-or-slug>` first.'}`);
+        }
+      } else {
+        emptyPolls = 0;
+        console.log(`${watchStamp()} ${full ? 'full reconcile' : 'poll'} returned ${results.length} result${results.length === 1 ? '' : 's'}.`);
+        for (const result of results) printResult(result);
+      }
+
+      if (options.once) {
+        if (failures > 0) process.exitCode = 1;
+        return;
+      }
+      await sleep(nextWatchDelay(options.intervalMs, maxBackoffMs, consecutiveFailures));
+    } catch (error) {
+      consecutiveFailures += 1;
+      const delayMs = nextWatchDelay(options.intervalMs, maxBackoffMs, consecutiveFailures);
+      console.error(`${watchStamp()} sync poll failed: ${error instanceof Error ? error.message : String(error)}`);
+      if (options.once) {
+        process.exitCode = 1;
+        return;
+      }
+      console.error(`${watchStamp()} retrying in ${formatDuration(delayMs)}.`);
+      await sleep(delayMs);
+    }
+  } while (true);
+}
+
+function parseIntervalMs(value: string): number {
+  const trimmed = value.trim().toLowerCase();
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(trimmed);
+  if (!match) throw new Error(`Invalid interval: ${value}`);
+  const amount = Number(match[1]);
+  const unit = match[2] ?? 's';
+  const ms = unit === 'm' ? amount * 60_000 : unit === 's' ? amount * 1000 : amount;
+  if (!Number.isFinite(ms) || ms < 100) throw new Error('Interval must be at least 100ms.');
+  return Math.round(ms);
+}
+
+function nextWatchDelay(intervalMs: number, maxBackoffMs: number, consecutiveFailures: number): number {
+  if (consecutiveFailures <= 0) return intervalMs;
+  const multiplier = 2 ** Math.min(consecutiveFailures - 1, 6);
+  return Math.min(maxBackoffMs, Math.max(intervalMs, intervalMs * multiplier));
+}
+
+function formatDuration(ms: number): string {
+  if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+  if (ms % 1000 === 0) return `${ms / 1000}s`;
+  return `${ms}ms`;
+}
+
+function watchStamp(): string {
+  return `[${new Date().toISOString()}]`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});