@comment-io/cli 0.1.1-alpha.9 → 0.1.2

package/README.md

@@ -60,10 +60,10 @@ The canonical reference for the agent-facing REST API is served at `/llms.txt` (
 - `PATCH /docs/:id` — edit via `{ old_string, new_string }` patches
 - `POST /docs/:id/comments` — comment / suggest / reply
 
-## CommentFS Local Sync
+## Local Sync Files
 
-CommentFS can project selected Comment.io docs into read-only local markdown
-files under `~/Comment Docs`.
+The Go `comment` CLI can mirror read-only markdown projections for the current
+library sync scope, **My Files and Shared With Me**, under `~/Comment Docs`.
 
 Install the CLI:
 
@@ -72,14 +72,21 @@ npm install -g '@comment-io/cli@^0.1.1'
 ```
 
 ```bash
-comment sync login --api-key <usk_...>
-comment sync
+comment sync login
+comment sync once
+comment sync enable
 comment sync watch
-comment sync logout
+comment sync logout [--purge-local]
 ```
 
-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`.
+Approve the device in Settings when `comment sync login` prints the browser
+code. `comment sync enable` lets the Go bus worker run local sync; install or
+run the bus daemon with `comment bus install` or `comment bus run` for
+persistent background sync. Local files are not an edit path; edit through the
+UI or REST API. Local edits are preserved under `~/.comment-io/sync/recovery`
+and the server version is restored on the next sync. Use
+`comment sync logout --purge-local` only when you also want to remove verified
+clean local projections.
 
 ## Local Notification Daemon
 
@@ -120,8 +127,7 @@ comment run --runtime claude --profile <handle>
 comment run --runtime codex --profile <handle>
 ```
 
-The npm package ships the Go bus binary for macOS and Linux while keeping the
-legacy `comment sync ...` commands available through the Node wrapper.
+The npm package ships the Go bus and local sync binary for macOS and Linux.
 
 ## Docs
 

package/bin/comment.js

@@ -1,15 +1,11 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const binDir = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(binDir, '..');
-const require = createRequire(import.meta.url);
-const tsxCli = require.resolve('tsx/cli');
-const syncCli = resolve(packageRoot, 'scripts', 'commentfs-sync.ts');
 const args = process.argv.slice(2);
 
 function run(command, commandArgs, options = {}) {
@@ -41,10 +37,6 @@ function goTarget() {
   return `${platform}-${arch}`;
 }
 
-if (args[0] === 'sync') {
-  run(process.execPath, [tsxCli, syncCli, ...args]);
-}
-
 const target = goTarget();
 const exe = process.platform === 'win32' ? '.exe' : '';
 const bundledBinary = target ? resolve(packageRoot, 'dist', `comment-${target}${exe}`) : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comment-io/cli",
-  "version": "0.1.1-alpha.9",
+  "version": "0.1.2",
   "description": "Comment.io CLI and local notification daemon",
   "private": false,
   "type": "module",
@@ -29,18 +29,12 @@
   "files": [
     "bin/",
     "dist/",
-    "scripts/commentfs-sync.ts",
-    "shared/commentfs-sync.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/docs/COMMENTFS-SYNC-USAGE.md

@@ -1,97 +0,0 @@
-# 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
-```
-
-To remove the stored sync key from this computer:
-
-```bash
-comment sync logout
-```
-
-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 logout
-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.
-`comment sync logout` removes the stored `usk_` key from this computer; revoke
-the key in Comment.io to invalidate it everywhere.
-
-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/scripts/commentfs-sync.ts

@@ -1,342 +0,0 @@
-#!/usr/bin/env node
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import {
-  DEFAULT_COMMENTFS_BASE_URL,
-  DEFAULT_SYNC_ROOT,
-  deleteCommentFsUserApiKey,
-  readCommentFsConfig,
-  explainCommentFsPath,
-  getCommentFsStatus,
-  recoverCommentFsPath,
-  repairCommentFsPermissions,
-  saveCommentFsUserApiKey,
-  syncConfiguredCommentDocs,
-  syncConfiguredCommentDocsSettled,
-  syncOneCommentDoc,
-  syncRemoteSelectedCommentDocsSettled,
-} from '../shared/commentfs-sync.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 logout',
-    '  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>',
-    '',
-    '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] !== '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}`);
-    return;
-  }
-
-  if (command[1] === 'logout') {
-    const result = await deleteCommentFsUserApiKey();
-    console.log(`${result.removed ? 'removed' : 'not logged in'}: ${result.path}`);
-    console.log(result.removed
-      ? 'CommentFS user API key removed from this computer.'
-      : 'No CommentFS user API key was stored on this computer.');
-    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()}`);
-}
-
-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);
-});