@comment-io/cli 0.1.0 → 0.1.1-alpha.5

package/README.md

@@ -6,15 +6,31 @@ Collaborative markdown editor with provenance tracking, comments, suggestions, a
 
 - **Backend** (`cf/`) — Cloudflare Workers + Durable Objects + Yjs
 - **Frontend** (`src/`) — React 19, Zustand, Milkdown, Tailwind CSS v4, Vite
+- **Shared packages** (`packages/`) — document client/core/surface and shared protocol utilities
+- **Plugins** (`plugins/`) — public Claude Code/OpenClaw plugin artifacts synced to standalone repos
 
 ## Local Development
 
 ```bash
-make dev          # CF Worker (:8787) + Vite editor (:3100) — background
+make setup        # Fresh-machine bootstrap (idempotent — safe to re-run)
+make dev          # Per-worktree Caddy host + Worker + Vite — background
 make dev-stop     # Stop dev servers
+make dev-status   # Show this worktree's dev URL and ports
 make logs         # Tail structured logs (jq)
 ```
 
+`make setup` checks the toolchain, installs `simple-worktree` globally,
+initializes its git hooks, creates `.env.local` from `.env.example`, stamps
+`cf/.dev.vars` with dev secrets, and runs `npm install`.
+
+For browser/OAuth/local-server work, create a worktree with `swt create <name>`
+and run `make dev` there. The app is served at
+`https://<worktree-name>.toofs.us` behind Caddy with isolated cookies,
+localStorage, Vite HMR, Worker ports, and local Durable Object persistence.
+Google login uses the singleton `https://auth.toofs.us` broker, so every
+worktree can log in without adding a new Google redirect URI. See
+[`docs/LOCAL-WORKTREE-DEV.md`](docs/LOCAL-WORKTREE-DEV.md).
+
 ## Tests
 
 ```bash
@@ -22,6 +38,19 @@ cd cf && npx vitest run    # Backend test suite
 npx vite build             # Verify frontend builds
 ```
 
+## Monorepo and DocumentSurface
+
+This repo is an npm-workspaces monorepo. The root install owns `cf` and
+`packages/*`; do not run separate nested installs for routine development.
+
+Comment.io and Botspring share the same document experience through
+`@comment-io/document-surface`. Product shells create a Comment.io client,
+provide a slug/token and storage namespace, and render the shared editor,
+comments, suggestions, provenance, and sync UI. The current Botspring staging
+smoke host lives at `https://botspring.dev` and renders one configurable
+DocumentSurface against the staging Worker. See
+[`docs/DOCUMENT-SURFACE.md`](docs/DOCUMENT-SURFACE.md).
+
 ## 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:
@@ -39,13 +68,14 @@ files under `~/Comment Docs`.
 Install the CLI:
 
 ```bash
-npm install -g @comment-io/cli
+npm install -g '@comment-io/cli@^0.1.1'
 ```
 
 ```bash
 comment sync login --api-key <usk_...>
 comment sync
 comment sync watch
+comment sync logout
 ```
 
 Enable **Sync locally** on a document first. Local files are not an edit path;
@@ -56,21 +86,46 @@ edit through the UI or API. See `docs/COMMENTFS-SYNC-USAGE.md`.
 Registered agents can receive @mention notifications through the local daemon:
 
 ```bash
-comment daemon install
-comment daemon health
-comment notifications wait --profile <handle> --timeout 30m
+comment bus install  # macOS launchd or Linux systemd --user
+comment bus status
+comment run --runtime claude --profile <handle>
+```
+
+On macOS, `comment bus install` installs the Go bus daemon as a launchd user
+service. On Linux, it installs a `systemd --user` service when systemd is
+available. In both cases notifications keep working after restart.
+If persistent service install is unavailable, run `comment bus run` under your
+own user service manager.
+
+For a one-shot manual check outside `comment run`, use
+`comment messages wait --profile <handle> --timeout 10s`, then receive and
+ack/release the returned local `message_id`.
+
+The message wait command returns a local `message_id`. Receive it before
+handling the work, renew it during long work, then ack it after handling or
+release it so another worker can retry:
+
+```bash
+comment messages receive --profile <handle> <message-id>
+comment messages renew --profile <handle> <message-id>
+comment messages ack --profile <handle> <message-id>
+comment messages release --profile <handle> <message-id>
 ```
 
-The notification wait command leases work locally. Ack the delivered claim after
-handling it, or release it so another worker can retry:
+For a live local runtime, launch the CLI through the daemon bridge so
+notifications can wake that tmux session:
 
 ```bash
-comment notifications ack <claim-id>
-comment notifications release <claim-id>
+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.
+
 ## Docs
 
 - `CLAUDE.md` — repo-level agent/developer instructions
+- `docs/DOCUMENT-SURFACE.md` — shared Comment.io/Botspring document surface contract
 - `docs/LOGGING.md` — structured logging guide
 - `docs/ARCHITECTURE.md` — architecture notes

package/bin/comment.js

@@ -1,24 +1,65 @@
 #!/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 tsxCli = resolve(packageRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+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);
 
-const child = spawnSync(process.execPath, [tsxCli, syncCli, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-});
+function run(command, commandArgs, options = {}) {
+  const child = spawnSync(command, commandArgs, {
+    stdio: 'inherit',
+    ...options,
+  });
+  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);
+  }
+}
+
+function goTarget() {
+  const platform = {
+    darwin: 'darwin',
+    linux: 'linux',
+  }[process.platform];
+  const arch = {
+    arm64: 'arm64',
+    x64: 'amd64',
+  }[process.arch];
+  if (!platform || !arch) return null;
+  return `${platform}-${arch}`;
+}
 
-if (child.error) {
-  console.error(child.error.message);
-  process.exit(1);
+if (args[0] === 'sync') {
+  run(process.execPath, [tsxCli, syncCli, ...args]);
 }
 
-if (child.signal) {
-  process.kill(process.pid, child.signal);
-} else {
-  process.exit(child.status ?? 0);
+const target = goTarget();
+const exe = process.platform === 'win32' ? '.exe' : '';
+const bundledBinary = target ? resolve(packageRoot, 'dist', `comment-${target}${exe}`) : '';
+
+if (bundledBinary && existsSync(bundledBinary)) {
+  run(bundledBinary, args);
 }
+
+const repoGoMain = resolve(packageRoot, 'packages', 'comment-go', 'cmd', 'comment');
+if (target && existsSync(repoGoMain)) {
+  run('go', ['run', './cmd/comment', ...args], {
+    cwd: resolve(packageRoot, 'packages', 'comment-go'),
+  });
+}
+
+console.error(`Unsupported platform or missing bundled Comment.io binary: ${process.platform}/${process.arch}`);
+console.error('Install a release of @comment-io/cli that includes your platform, or build the Go CLI from source.');
+process.exit(1);

package/docs/COMMENTFS-SYNC-USAGE.md

@@ -25,6 +25,12 @@ For staging or another deployment, include the base URL:
 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:
 
@@ -44,6 +50,7 @@ By default files are written under `~/Comment Docs`.
 
 ```bash
 comment sync status
+comment sync logout
 comment sync repair
 comment sync explain <path>
 comment sync recover <path>
@@ -82,6 +89,8 @@ linked from the sidecar `api_docs_url`.
 
 `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

package/package.json

@@ -1,29 +1,36 @@
 {
   "name": "@comment-io/cli",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.5",
   "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"
+    "url": "git+https://github.com/botspring-ai/monorepo.git"
   },
   "bugs": {
-    "url": "https://github.com/comment-io/comment/issues"
+    "url": "https://github.com/botspring-ai/monorepo/issues"
   },
   "publishConfig": {
     "access": "public"
   },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
   "bin": {
     "comment": "bin/comment.js"
   },
   "files": [
     "bin/",
+    "dist/",
     "scripts/commentfs-sync.ts",
-    "scripts/commentd.ts",
     "shared/commentfs-sync.ts",
-    "shared/comment-notifications.ts",
     "docs/COMMENTFS-SYNC-USAGE.md",
     "README.md",
     "LICENSE"

package/scripts/commentfs-sync.ts

@@ -1,13 +1,10 @@
 #!/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 { homedir } 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,
+  deleteCommentFsUserApiKey,
   readCommentFsConfig,
   explainCommentFsPath,
   getCommentFsStatus,
@@ -19,15 +16,6 @@ import {
   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[];
@@ -65,16 +53,13 @@ function usage(): string {
     '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>',
-    '  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}`,
@@ -88,16 +73,6 @@ async function main(): Promise<void> {
     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()}`);
   }
@@ -113,9 +88,15 @@ async function main(): Promise<void> {
     });
     console.log(`saved: ${saved.path}`);
     console.log(`base_url: ${saved.config.baseUrl}`);
-    if (options['no-daemon'] !== true) {
-      await maybeOfferDaemonInstall();
-    }
+    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;
   }
 
@@ -215,231 +196,6 @@ async function main(): Promise<void> {
   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;

package/shared/commentfs-sync.ts

@@ -422,6 +422,13 @@ export async function saveCommentFsUserApiKey(options: {
   return { path, config };
 }
 
+export async function deleteCommentFsUserApiKey(homeDir = homedir()): Promise<{ path: string; removed: boolean }> {
+  const path = commentFsConfigPath(homeDir);
+  const removed = existsSync(path);
+  await rm(path, { force: true });
+  return { path, removed };
+}
+
 export async function syncOneCommentDoc(options: SyncDocOptions): Promise<SyncDocResult> {
   const rootDir = resolve(options.rootDir ?? DEFAULT_SYNC_ROOT);
   const now = options.now ?? (() => new Date());