@abraca/cli 1.5.0

package/src/connection.ts

@@ -0,0 +1,321 @@
+/**
+ * CLIConnection — manages the CRDT connection lifecycle for the CLI.
+ *
+ * Handles: Ed25519 auth → space discovery → Y.Doc sync → awareness.
+ * Reuses the same patterns as AbracadabraMCPServer but without MCP SDK dependency.
+ */
+import * as Y from 'yjs'
+import { AbracadabraProvider, AbracadabraClient } from '@abraca/dabra'
+import type { ServerInfo, DocumentMeta, SpaceMeta } from '@abraca/dabra'
+import { loadOrCreateKeypair, signChallenge } from './crypto.ts'
+
+export interface CLIConnectionConfig {
+  url: string
+  name?: string
+  color?: string
+  inviteCode?: string
+  keyFile?: string
+  /** If true, suppress all stderr logging */
+  quiet?: boolean
+}
+
+interface CachedProvider {
+  provider: AbracadabraProvider
+  lastAccessed: number
+}
+
+function waitForSync(
+  provider: { on(event: string, cb: () => void): void; off(event: string, cb: () => void): void },
+  timeoutMs = 15000
+): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      provider.off('synced', handler)
+      reject(new Error(`Sync timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    function handler() {
+      clearTimeout(timer)
+      resolve()
+    }
+
+    provider.on('synced', handler)
+  })
+}
+
+/** Map a DocumentMeta to SpaceMeta shape for display compatibility. */
+function docToSpaceMeta(doc: DocumentMeta): SpaceMeta {
+  const publicAccess = doc.public_access
+  let visibility: SpaceMeta['visibility'] = 'private'
+  if (publicAccess && publicAccess !== 'none') visibility = 'public'
+
+  return {
+    id: doc.id,
+    doc_id: doc.id,
+    name: doc.label ?? doc.id,
+    description: doc.description ?? null,
+    visibility,
+    is_hub: doc.is_hub ?? false,
+    owner_id: doc.owner_id ?? null,
+    created_at: 0,
+    updated_at: doc.updated_at ?? 0,
+    public_access: publicAccess ?? null,
+  }
+}
+
+export class CLIConnection {
+  readonly config: CLIConnectionConfig
+  readonly client: AbracadabraClient
+
+  private _serverInfo: ServerInfo | null = null
+  private _rootDocId: string | null = null
+  private _spaces: SpaceMeta[] = []
+  private _rootDoc: Y.Doc | null = null
+  private _rootProvider: AbracadabraProvider | null = null
+  private _userId: string | null = null
+  private _signFn: ((challenge: string) => Promise<string>) | null = null
+  private childCache = new Map<string, CachedProvider>()
+
+  constructor(config: CLIConnectionConfig) {
+    this.config = config
+    this.client = new AbracadabraClient({
+      url: config.url,
+      persistAuth: false,
+    })
+  }
+
+  get displayName(): string {
+    return this.config.name || 'CLI User'
+  }
+
+  get displayColor(): string {
+    return this.config.color || 'hsl(45, 90%, 55%)'
+  }
+
+  get serverInfo(): ServerInfo | null {
+    return this._serverInfo
+  }
+
+  get rootDocId(): string | null {
+    return this._rootDocId
+  }
+
+  get spaces(): SpaceMeta[] {
+    return this._spaces
+  }
+
+  get rootDoc(): Y.Doc | null {
+    return this._rootDoc
+  }
+
+  get rootProvider(): AbracadabraProvider | null {
+    return this._rootProvider
+  }
+
+  get userId(): string | null {
+    return this._userId
+  }
+
+  private log(msg: string): void {
+    if (!this.config.quiet) {
+      console.error(`[abracadabra] ${msg}`)
+    }
+  }
+
+  /** Connect to the server: authenticate, discover spaces, sync root doc. */
+  async connect(): Promise<void> {
+    // Step 1: Load or generate Ed25519 keypair
+    const keypair = await loadOrCreateKeypair(this.config.keyFile)
+    this._userId = keypair.publicKeyB64
+    const signFn = (challenge: string) => Promise.resolve(signChallenge(challenge, keypair.privateKey))
+    this._signFn = signFn
+
+    // Step 2: Authenticate via challenge-response (register on first run)
+    try {
+      await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+    } catch (err: any) {
+      const status = err?.status ?? err?.response?.status
+      if (status === 404 || status === 422) {
+        this.log('Key not registered, creating new account...')
+        await this.client.registerWithKey({
+          publicKey: keypair.publicKeyB64,
+          username: this.displayName.replace(/\s+/g, '-').toLowerCase(),
+          displayName: this.displayName,
+          deviceName: 'CLI',
+          inviteCode: this.config.inviteCode,
+        })
+        await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+      } else {
+        throw err
+      }
+    }
+    this.log(`Authenticated as ${this.displayName} (${keypair.publicKeyB64.slice(0, 12)}...)`)
+
+    // Step 3: Discover server info
+    this._serverInfo = await this.client.serverInfo()
+
+    // Step 4: Discover root documents
+    let initialDocId: string | null = this._serverInfo.index_doc_id ?? null
+    try {
+      const roots = await this.client.listRootDocuments()
+      this._spaces = roots.map(docToSpaceMeta)
+      const hub = roots.find((d: any) => d.is_hub)
+      if (hub) {
+        initialDocId = hub.id
+        this.log(`Hub document: ${hub.label ?? hub.id} (${hub.id})`)
+      } else if (roots.length > 0) {
+        initialDocId = roots[0].id
+        this.log(`No hub, using first root doc: ${roots[0].label ?? roots[0].id}`)
+      }
+    } catch {
+      try {
+        this._spaces = await this.client.listSpaces()
+        const hub = this._spaces.find(s => s.is_hub)
+        if (hub) {
+          initialDocId = hub.doc_id
+        } else if (this._spaces.length > 0) {
+          initialDocId = this._spaces[0].doc_id
+        }
+      } catch {
+        this.log('Neither /docs?root=true nor /spaces available, using index_doc_id')
+      }
+    }
+
+    if (!initialDocId) {
+      throw new Error('No entry point found: server has neither spaces nor index_doc_id configured.')
+    }
+
+    this._rootDocId = initialDocId
+
+    // Step 5: Connect provider and sync
+    const doc = new Y.Doc({ guid: initialDocId })
+    const provider = new AbracadabraProvider({
+      name: initialDocId,
+      document: doc,
+      client: this.client,
+      disableOfflineStore: true,
+      subdocLoading: 'lazy',
+    })
+
+    await waitForSync(provider)
+
+    provider.awareness.setLocalStateField('user', {
+      name: this.displayName,
+      color: this.displayColor,
+      publicKey: this._userId,
+      isAgent: false,
+    })
+    provider.awareness.setLocalStateField('status', null)
+
+    this._rootDoc = doc
+    this._rootProvider = provider
+    this.log('Connected and synced')
+  }
+
+  /** Switch active space to a different root document. */
+  async switchSpace(docId: string): Promise<void> {
+    // Destroy existing child providers
+    for (const [, cached] of this.childCache) {
+      cached.provider.destroy()
+    }
+    this.childCache.clear()
+
+    // Destroy current root provider
+    if (this._rootProvider) {
+      this._rootProvider.destroy()
+      this._rootProvider = null
+    }
+    this._rootDoc = null
+
+    // Re-authenticate if JWT has expired
+    if (!this.client.isTokenValid() && this._signFn && this._userId) {
+      await this.client.loginWithKey(this._userId, this._signFn)
+    }
+
+    // Connect to new space
+    const doc = new Y.Doc({ guid: docId })
+    const provider = new AbracadabraProvider({
+      name: docId,
+      document: doc,
+      client: this.client,
+      disableOfflineStore: true,
+      subdocLoading: 'lazy',
+    })
+
+    await waitForSync(provider)
+
+    provider.awareness.setLocalStateField('user', {
+      name: this.displayName,
+      color: this.displayColor,
+      publicKey: this._userId,
+      isAgent: false,
+    })
+
+    this._rootDoc = doc
+    this._rootProvider = provider
+    this._rootDocId = docId
+    this.log(`Switched to space ${docId}`)
+  }
+
+  /** Get the root doc-tree Y.Map. */
+  getTreeMap(): Y.Map<any> | null {
+    return this._rootDoc?.getMap('doc-tree') ?? null
+  }
+
+  /** Get the root doc-trash Y.Map. */
+  getTrashMap(): Y.Map<any> | null {
+    return this._rootDoc?.getMap('doc-trash') ?? null
+  }
+
+  /** Get or create a child provider for a document. */
+  async getChildProvider(docId: string): Promise<AbracadabraProvider> {
+    const cached = this.childCache.get(docId)
+    if (cached) {
+      cached.lastAccessed = Date.now()
+      return cached.provider
+    }
+
+    if (!this._rootProvider) {
+      throw new Error('Not connected. Call connect() first.')
+    }
+
+    // Re-authenticate if JWT has expired
+    if (!this.client.isTokenValid() && this._signFn && this._userId) {
+      await this.client.loginWithKey(this._userId, this._signFn)
+    }
+
+    const childProvider = await this._rootProvider.loadChild(docId)
+    await waitForSync(childProvider)
+
+    childProvider.awareness.setLocalStateField('user', {
+      name: this.displayName,
+      color: this.displayColor,
+      publicKey: this._userId,
+      isAgent: false,
+    })
+
+    this.childCache.set(docId, {
+      provider: childProvider,
+      lastAccessed: Date.now(),
+    })
+
+    return childProvider
+  }
+
+  /** Graceful shutdown. */
+  async destroy(): Promise<void> {
+    for (const [, cached] of this.childCache) {
+      cached.provider.destroy()
+    }
+    this.childCache.clear()
+
+    if (this._rootProvider) {
+      this._rootProvider.awareness.setLocalStateField('status', null)
+      this._rootProvider.destroy()
+      this._rootProvider = null
+    }
+    this._rootDoc = null
+
+    this.log('Disconnected')
+  }
+}

package/src/converters/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Re-export converters from @abraca/mcp for markdown ↔ Y.js conversion.
+ *
+ * These modules only depend on yjs (a peer dep of this package),
+ * not on the MCP SDK, so importing via the source export condition is safe.
+ */
+// @ts-ignore — resolve via monorepo source condition
+export { yjsToMarkdown } from '../../mcp/src/converters/yjsToMarkdown.ts'
+// @ts-ignore — resolve via monorepo source condition
+export { populateYDocFromMarkdown, parseFrontmatter } from '../../mcp/src/converters/markdownToYjs.ts'

package/src/converters/markdownToYjs.ts

@@ -0,0 +1,3 @@
+// Re-export from @abraca/mcp converters (only depends on yjs, not MCP SDK)
+// @ts-ignore — resolve via monorepo relative path
+export { populateYDocFromMarkdown, parseFrontmatter } from '../../../mcp/src/converters/markdownToYjs.ts'

package/src/converters/types.ts

@@ -0,0 +1,3 @@
+// Re-export converter types from @abraca/mcp
+// @ts-ignore — resolve via monorepo relative path
+export type { PageMeta, TreeEntry, UserMetaField } from '../../../mcp/src/converters/types.ts'

package/src/converters/yjsToMarkdown.ts

@@ -0,0 +1,3 @@
+// Re-export from @abraca/mcp converters (only depends on yjs, not MCP SDK)
+// @ts-ignore — resolve via monorepo relative path
+export { yjsToMarkdown } from '../../../mcp/src/converters/yjsToMarkdown.ts'

package/src/crypto.ts

@@ -0,0 +1,69 @@
+/**
+ * Ed25519 key generation, persistence, and challenge signing for CLI auth.
+ * Mirrors @abraca/mcp/src/crypto.ts — standalone to avoid MCP SDK dependency.
+ */
+import * as ed from '@noble/ed25519'
+import { sha512 } from '@noble/hashes/sha2'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+
+// @noble/ed25519 v2+ requires explicit hash configuration
+ed.etc.sha512Sync = (...msgs: Uint8Array[]) => sha512(ed.etc.concatBytes(...msgs))
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+
+const DEFAULT_KEY_PATH = join(homedir(), '.abracadabra', 'cli.key')
+
+function toBase64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+function fromBase64url(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64url'))
+}
+
+export interface CLIKeypair {
+  privateKey: Uint8Array
+  publicKeyB64: string
+}
+
+/**
+ * Load an existing Ed25519 keypair from disk, or generate and persist a new one.
+ * The file stores the raw 32-byte private key seed.
+ */
+export async function loadOrCreateKeypair(keyPath?: string): Promise<CLIKeypair> {
+  const path = keyPath || DEFAULT_KEY_PATH
+
+  if (existsSync(path)) {
+    const seed = await readFile(path)
+    if (seed.length !== 32) {
+      throw new Error(`Invalid key file at ${path}: expected 32 bytes, got ${seed.length}`)
+    }
+    const privateKey = new Uint8Array(seed)
+    const publicKey = ed.getPublicKey(privateKey)
+    return { privateKey, publicKeyB64: toBase64url(publicKey) }
+  }
+
+  // Generate new keypair
+  const privateKey = ed.utils.randomPrivateKey()
+  const publicKey = ed.getPublicKey(privateKey)
+
+  // Ensure directory exists and write seed with restricted permissions
+  const dir = dirname(path)
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+  }
+  await writeFile(path, Buffer.from(privateKey), { mode: 0o600 })
+
+  console.error(`[abracadabra] Generated new keypair at ${path}`)
+  console.error(`[abracadabra] Public key: ${toBase64url(publicKey)}`)
+
+  return { privateKey, publicKeyB64: toBase64url(publicKey) }
+}
+
+/** Sign a base64url challenge with the private key; returns base64url signature. */
+export function signChallenge(challengeB64: string, privateKey: Uint8Array): string {
+  const challenge = fromBase64url(challengeB64)
+  const sig = ed.sign(challenge, privateKey)
+  return toBase64url(sig)
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Abracadabra CLI — interact with CRDT document workspaces from the terminal.
+ *
+ * Usage:
+ *   abracadabra <command> [key=value ...] [--flags]
+ *
+ * Environment:
+ *   ABRA_URL          Server URL (required)
+ *   ABRA_KEY_FILE     Path to Ed25519 key file (~/.abracadabra/cli.key)
+ *   ABRA_INVITE_CODE  Invite code for first-run registration
+ *   ABRA_NAME         Display name (default: CLI User)
+ *   ABRA_COLOR        Presence color (default: hsl(45, 90%, 55%))
+ */
+import { parseArgs } from './parser.ts'
+import { CLIConnection } from './connection.ts'
+import { getCommand } from './command.ts'
+
+// ── Register all commands ────────────────────────────────────────────────────
+// Side-effect imports: each module calls registerCommand() at module scope.
+import './commands/help.ts'
+import './commands/spaces.ts'
+import './commands/tree.ts'
+import './commands/documents.ts'
+import './commands/content.ts'
+import './commands/meta.ts'
+import './commands/awareness.ts'
+import './commands/files.ts'
+import './commands/permissions.ts'
+
+// ── Commands that don't require a connection ─────────────────────────────────
+const NO_CONNECT_COMMANDS = new Set(['help', 'h', '?', 'version', 'v'])
+
+async function main() {
+  const args = parseArgs(process.argv)
+
+  // Resolve command
+  const cmd = getCommand(args.command)
+  if (!cmd) {
+    console.error(`Unknown command: "${args.command}"`)
+    console.error('Run "abracadabra help" to see all commands.')
+    process.exit(1)
+  }
+
+  // Commands that don't need a server connection
+  if (NO_CONNECT_COMMANDS.has(args.command)) {
+    // Try to connect for extra info (version), but don't fail
+    let conn: CLIConnection | null = null
+    const url = process.env['ABRA_URL']
+    if (url && args.command === 'version') {
+      try {
+        conn = new CLIConnection({
+          url,
+          name: process.env['ABRA_NAME'],
+          color: process.env['ABRA_COLOR'],
+          inviteCode: process.env['ABRA_INVITE_CODE'],
+          keyFile: process.env['ABRA_KEY_FILE'],
+          quiet: true,
+        })
+        await conn.connect()
+      } catch {
+        // Silently fall back to local-only version info
+      }
+    }
+
+    try {
+      const output = await cmd.run(conn, args)
+      if (output) console.log(output)
+    } finally {
+      if (conn) await conn.destroy().catch(() => {})
+    }
+    return
+  }
+
+  // All other commands require ABRA_URL
+  const url = process.env['ABRA_URL']
+  if (!url) {
+    console.error('Error: ABRA_URL environment variable is required.')
+    console.error('')
+    console.error('Set it to your Abracadabra server URL:')
+    console.error('  export ABRA_URL=https://your-server.example.com')
+    console.error('')
+    console.error('Run "abracadabra help" for more info.')
+    process.exit(1)
+  }
+
+  const conn = new CLIConnection({
+    url,
+    name: process.env['ABRA_NAME'],
+    color: process.env['ABRA_COLOR'],
+    inviteCode: process.env['ABRA_INVITE_CODE'],
+    keyFile: process.env['ABRA_KEY_FILE'],
+    quiet: args.flags.has('quiet') || args.flags.has('q'),
+  })
+
+  try {
+    await conn.connect()
+    const output = await cmd.run(conn, args)
+    if (output) console.log(output)
+  } catch (error: any) {
+    console.error(`Error: ${error.message}`)
+    if (args.flags.has('verbose')) {
+      console.error(error.stack)
+    }
+    process.exit(1)
+  } finally {
+    await conn.destroy().catch(() => {})
+  }
+}
+
+main().catch((err) => {
+  console.error(`Fatal: ${err.message ?? err}`)
+  process.exit(1)
+})

package/src/output.ts

@@ -0,0 +1,109 @@
+/**
+ * Output formatting utilities for Abracadabra CLI.
+ *
+ * Supports JSON, TSV, tree, and compact text output.
+ */
+
+import type { ParsedArgs } from './parser.ts'
+
+export type OutputFormat = 'json' | 'tsv' | 'tree' | 'text' | 'md'
+
+export function getFormat(args: ParsedArgs, defaultFormat: OutputFormat = 'text'): OutputFormat {
+  const f = args.params['format']
+  if (f && ['json', 'tsv', 'tree', 'text', 'md'].includes(f)) {
+    return f as OutputFormat
+  }
+  return defaultFormat
+}
+
+/** Print a JSON-serializable value. */
+export function printJson(data: unknown): string {
+  return JSON.stringify(data, null, 2)
+}
+
+/** Print a list of objects as TSV. */
+export function printTsv(rows: Record<string, unknown>[], columns?: string[]): string {
+  if (rows.length === 0) return ''
+  const cols = columns ?? Object.keys(rows[0])
+  const header = cols.map(c => c.toUpperCase()).join('\t')
+  const body = rows.map(row =>
+    cols.map(c => {
+      const val = row[c]
+      if (val == null) return '—'
+      if (typeof val === 'object') return JSON.stringify(val)
+      return String(val)
+    }).join('\t')
+  ).join('\n')
+  return header + '\n' + body
+}
+
+/** Format a tree of nested items with box-drawing characters. */
+export function printTree(
+  items: TreeNode[],
+  opts: { indent?: string, isLast?: boolean[] } = {}
+): string {
+  const lines: string[] = []
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    const isLast = i === items.length - 1
+    const prefix = (opts.isLast ?? [])
+      .map(last => last ? '    ' : '│   ')
+      .join('')
+    const connector = isLast ? '└── ' : '├── '
+    const typeSuffix = item.type ? ` (${item.type})` : ''
+    lines.push(`${prefix}${connector}${item.label}${typeSuffix}`)
+    if (item.children && item.children.length > 0) {
+      lines.push(printTree(item.children, {
+        isLast: [...(opts.isLast ?? []), isLast],
+      }))
+    }
+  }
+  return lines.join('\n')
+}
+
+export interface TreeNode {
+  label: string
+  type?: string
+  children?: TreeNode[]
+}
+
+/** Format relative time (e.g. "2m ago", "1h ago"). */
+export function relativeTime(timestamp: number | undefined | null): string {
+  if (!timestamp) return '—'
+  const diff = Date.now() - timestamp
+  if (diff < 0) return 'just now'
+  if (diff < 60_000) return `${Math.floor(diff / 1000)}s ago`
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`
+  return `${Math.floor(diff / 86_400_000)}d ago`
+}
+
+/** Truncate a string to a max length, appending '…' if truncated. */
+export function truncate(str: string, max: number): string {
+  if (str.length <= max) return str
+  return str.slice(0, max - 1) + '…'
+}
+
+/** Pad a string to a fixed width. */
+export function pad(str: string, width: number): string {
+  if (str.length >= width) return str.slice(0, width)
+  return str + ' '.repeat(width - str.length)
+}
+
+/** Format a table with auto-column widths. */
+export function printTable(rows: string[][], headers?: string[]): string {
+  const allRows = headers ? [headers, ...rows] : rows
+  if (allRows.length === 0) return ''
+
+  const colCount = Math.max(...allRows.map(r => r.length))
+  const widths: number[] = []
+  for (let c = 0; c < colCount; c++) {
+    widths[c] = Math.max(...allRows.map(r => (r[c] ?? '').length))
+  }
+
+  const formatted = allRows.map(row =>
+    row.map((cell, i) => pad(cell, widths[i])).join('  ')
+  )
+
+  return formatted.join('\n')
+}