@abraca/cli 1.5.0

package/src/commands/documents.ts

@@ -0,0 +1,419 @@
+/**
+ * Document CRUD commands: read, create, rename, move, delete, type, doc.
+ */
+import * as Y from 'yjs'
+import { registerCommand } from '../command.ts'
+import type { CLIConnection } from '../connection.ts'
+import type { ParsedArgs } from '../parser.ts'
+import { readEntries, childrenOf, normalizeRootId, resolveDocument, descendantsOf } from '../resolve.ts'
+import { printJson, relativeTime } from '../output.ts'
+import { yjsToMarkdown } from '../converters/yjsToMarkdown.ts'
+import { populateYDocFromMarkdown, parseFrontmatter } from '../converters/markdownToYjs.ts'
+
+/** Safely read a tree map value, converting Y.Map to plain object if needed. */
+function toPlain(val: any): any {
+  return val instanceof Y.Map ? val.toJSON() : val
+}
+
+registerCommand({
+  name: 'doc',
+  aliases: ['info:doc'],
+  description: 'Show document metadata (label, type, meta, dates).',
+  usage: 'doc id=<docId> | name=<label> | path=<a/b/c>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found. Specify id=, name=, or path= to identify the document.'
+
+    const treeMap = conn.getTreeMap()
+    if (!treeMap) return 'Not connected'
+
+    const raw = treeMap.get(docId)
+    if (!raw) return `Document ${docId} not found in tree.`
+
+    const entry = toPlain(raw)
+
+    const lines = [
+      `id:        ${docId}`,
+      `label:     ${entry.label || 'Untitled'}`,
+      `type:      ${entry.type ?? '—'}`,
+      `parent:    ${entry.parentId ?? '(root)'}`,
+      `order:     ${entry.order ?? 0}`,
+      `created:   ${entry.createdAt ? new Date(entry.createdAt).toISOString() : '—'}`,
+      `updated:   ${entry.updatedAt ? new Date(entry.updatedAt).toISOString() : '—'} (${relativeTime(entry.updatedAt)})`,
+    ]
+
+    if (entry.meta && Object.keys(entry.meta).length > 0) {
+      lines.push(`meta:`)
+      for (const [k, v] of Object.entries(entry.meta)) {
+        lines.push(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`)
+      }
+    }
+
+    // Count children
+    const entries = readEntries(treeMap)
+    const children = childrenOf(entries, docId)
+    lines.push(`children:  ${children.length}`)
+
+    return lines.join('\n')
+  },
+})
+
+registerCommand({
+  name: 'read',
+  aliases: ['cat', 'r'],
+  description: 'Read document content as markdown.',
+  usage: 'read id=<docId> | name=<label> | path=<a/b/c> [--format=json|md]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found. Specify id=, name=, or path= to identify the document.'
+
+    try {
+      const provider = await conn.getChildProvider(docId)
+      const fragment = provider.document.getXmlFragment('default')
+      const { title, markdown } = yjsToMarkdown(fragment)
+
+      if (args.flags.has('json') || args.params['format'] === 'json') {
+        // Include tree metadata + children
+        const treeMap = conn.getTreeMap()
+        let label = title
+        let type: string | undefined
+        let meta: Record<string, unknown> | undefined
+        let children: Array<{ id: string; label: string; type?: string }> = []
+        if (treeMap) {
+          const entry = treeMap.get(docId)
+          if (entry) {
+            label = entry.label || title
+            type = entry.type
+            meta = entry.meta
+          }
+          treeMap.forEach((value: any, id: string) => {
+            const v = toPlain(value)
+            if (v.parentId === docId) {
+              children.push({ id, label: v.label || 'Untitled', type: v.type })
+            }
+          })
+          children.sort((a: any, b: any) => {
+            const va = treeMap.get(a.id)
+            const vb = treeMap.get(b.id)
+            return ((va?.order ?? 0) - (vb?.order ?? 0))
+          })
+        }
+        return printJson({ label, type, meta, markdown, children })
+      }
+
+      return markdown || '(empty document)'
+    } catch (error: any) {
+      return `Error reading document: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'create',
+  aliases: ['new'],
+  description: 'Create a new document in the tree.',
+  usage: 'create label=<name> [parent=<docId>] [type=<pageType>] [content=<markdown>] [--format=json]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const label = args.params['label'] || args.params['name'] || args.positional[0]
+    if (!label) return 'Missing required parameter: label=<name>'
+
+    const treeMap = conn.getTreeMap()
+    const rootDoc = conn.rootDoc
+    if (!treeMap || !rootDoc) return 'Not connected'
+
+    // Resolve parent
+    let parentId: string | null = null
+    if (args.params['parent']) {
+      parentId = resolveDocument(conn, { id: args.params['parent'], name: args.params['parent'] }, [])
+      if (!parentId) parentId = args.params['parent'] // Use raw value as ID
+    }
+
+    const normalizedParent = normalizeRootId(parentId || conn.rootDocId, conn)
+    const type = args.params['type']
+
+    const id = crypto.randomUUID()
+    const now = Date.now()
+
+    // Parse optional meta from params
+    const meta: Record<string, unknown> = {}
+    if (args.params['icon']) meta['icon'] = args.params['icon']
+    if (args.params['color']) meta['color'] = args.params['color']
+
+    rootDoc.transact(() => {
+      treeMap.set(id, {
+        label,
+        parentId: normalizedParent,
+        order: now,
+        type,
+        meta: Object.keys(meta).length > 0 ? meta : undefined,
+        createdAt: now,
+        updatedAt: now,
+      })
+    })
+
+    // Write content if provided
+    const content = args.params['content']
+    if (content) {
+      try {
+        const provider = await conn.getChildProvider(id)
+        const fragment = provider.document.getXmlFragment('default')
+        const contentToWrite = content.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+        populateYDocFromMarkdown(fragment, contentToWrite, label)
+      } catch (error: any) {
+        return `Created ${id} "${label}" but failed to write content: ${error.message}`
+      }
+    }
+
+    if (args.params['format'] === 'json') {
+      return printJson({ id, label, parentId: normalizedParent, type })
+    }
+
+    return `Created: ${id.slice(0, 8)}… "${label}"${type ? ` (${type})` : ''}`
+  },
+})
+
+registerCommand({
+  name: 'rename',
+  description: 'Rename a document.',
+  usage: 'rename id=<docId> | name=<oldLabel> label=<newLabel>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const newLabel = args.params['label'] || args.params['to']
+    if (!newLabel) return 'Missing required parameter: label=<newLabel>'
+
+    const treeMap = conn.getTreeMap()
+    if (!treeMap) return 'Not connected'
+
+    const raw = treeMap.get(docId)
+    if (!raw) return `Document ${docId} not found.`
+
+    const entry = toPlain(raw)
+    treeMap.set(docId, { ...entry, label: newLabel, updatedAt: Date.now() })
+
+    return `Renamed to "${newLabel}"`
+  },
+})
+
+registerCommand({
+  name: 'move',
+  aliases: ['mv'],
+  description: 'Move a document to a new parent.',
+  usage: 'move id=<docId> | name=<label> to=<parentId> [order=<n>]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const newParentId = args.params['to'] || args.params['parent']
+    if (!newParentId) return 'Missing required parameter: to=<parentId>'
+
+    const treeMap = conn.getTreeMap()
+    if (!treeMap) return 'Not connected'
+
+    const raw = treeMap.get(docId)
+    if (!raw) return `Document ${docId} not found.`
+
+    const entry = toPlain(raw)
+    const order = args.params['order'] ? parseInt(args.params['order'], 10) : Date.now()
+    treeMap.set(docId, {
+      ...entry,
+      parentId: normalizeRootId(newParentId, conn),
+      order,
+      updatedAt: Date.now(),
+    })
+
+    return `Moved ${docId.slice(0, 8)}… to parent ${newParentId.slice(0, 8)}…`
+  },
+})
+
+registerCommand({
+  name: 'delete',
+  aliases: ['rm', 'del'],
+  description: 'Soft-delete a document (moves to trash).',
+  usage: 'delete id=<docId> | name=<label>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const treeMap = conn.getTreeMap()
+    const trashMap = conn.getTrashMap()
+    const rootDoc = conn.rootDoc
+    if (!treeMap || !trashMap || !rootDoc) return 'Not connected'
+
+    const entries = readEntries(treeMap)
+    const toDelete = [docId, ...descendantsOf(entries, docId).map(e => e.id)]
+
+    const now = Date.now()
+    rootDoc.transact(() => {
+      for (const nid of toDelete) {
+        const raw = treeMap.get(nid)
+        if (!raw) continue
+        const entry = toPlain(raw)
+        trashMap.set(nid, {
+          label: entry.label || 'Untitled',
+          parentId: entry.parentId ?? null,
+          order: entry.order ?? 0,
+          type: entry.type,
+          meta: entry.meta,
+          deletedAt: now,
+        })
+        treeMap.delete(nid)
+      }
+    })
+
+    return `Deleted ${toDelete.length} document(s)`
+  },
+})
+
+registerCommand({
+  name: 'type',
+  description: 'Change the page type view of a document.',
+  usage: 'type id=<docId> | name=<label> type=<pageType>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const newType = args.params['type'] || args.positional[1]
+    if (!newType) return 'Missing required parameter: type=<pageType>'
+
+    const treeMap = conn.getTreeMap()
+    if (!treeMap) return 'Not connected'
+
+    const raw = treeMap.get(docId)
+    if (!raw) return `Document ${docId} not found.`
+
+    const entry = toPlain(raw)
+    treeMap.set(docId, { ...entry, type: newType, updatedAt: Date.now() })
+
+    return `Changed type to "${newType}"`
+  },
+})
+
+registerCommand({
+  name: 'write',
+  description: 'Write markdown content to a document (replace or append).',
+  usage: 'write id=<docId> | name=<label> content=<markdown> [mode=replace|append]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    // Content from param, or read from stdin if piped
+    let content = args.params['content']
+
+    if (!content) {
+      // Check if stdin is piped (not a TTY)
+      if (!process.stdin.isTTY) {
+        content = await readStdin()
+      }
+    }
+
+    if (!content) return 'Missing required parameter: content=<markdown> (or pipe via stdin)'
+
+    // Unescape \n and \t
+    content = content.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+
+    try {
+      const writeMode = args.params['mode'] ?? 'replace'
+      const provider = await conn.getChildProvider(docId)
+      const doc = provider.document
+      const fragment = doc.getXmlFragment('default')
+
+      // Parse optional frontmatter
+      const { title, meta, body } = parseFrontmatter(content)
+
+      // Update tree metadata if frontmatter provided
+      if (title || Object.keys(meta).length > 0) {
+        const treeMap = conn.getTreeMap()
+        const rootDoc = conn.rootDoc
+        if (treeMap && rootDoc) {
+          const entry = treeMap.get(docId)
+          if (entry) {
+            const e = toPlain(entry)
+            rootDoc.transact(() => {
+              const updates: Record<string, unknown> = { ...e, updatedAt: Date.now() }
+              if (title) updates.label = title
+              if (Object.keys(meta).length > 0) {
+                updates.meta = { ...(e.meta ?? {}), ...meta }
+              }
+              treeMap.set(docId, updates)
+            })
+          }
+        }
+      }
+
+      if (writeMode === 'replace') {
+        doc.transact(() => {
+          while (fragment.length > 0) {
+            fragment.delete(0)
+          }
+        })
+      }
+
+      const contentToWrite = body || content
+      populateYDocFromMarkdown(fragment, contentToWrite, title || 'Untitled')
+
+      return `Document ${docId.slice(0, 8)}… updated (${writeMode} mode)`
+    } catch (error: any) {
+      return `Error writing document: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'duplicate',
+  aliases: ['dup'],
+  description: 'Shallow-clone a document.',
+  usage: 'duplicate id=<docId> | name=<label>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const treeMap = conn.getTreeMap()
+    if (!treeMap) return 'Not connected'
+
+    const raw = treeMap.get(docId)
+    if (!raw) return `Document ${docId} not found.`
+
+    const entry = toPlain(raw)
+    const newId = crypto.randomUUID()
+    treeMap.set(newId, {
+      ...entry,
+      label: (entry.label || 'Untitled') + ' (copy)',
+      order: Date.now(),
+    })
+
+    return `Duplicated: ${newId.slice(0, 8)}… "${entry.label} (copy)"`
+  },
+})
+
+/** Helper to read all of stdin as a string. */
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    process.stdin.setEncoding('utf-8')
+    process.stdin.on('data', (chunk: string) => { data += chunk })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', reject)
+    // Safety timeout — don't hang forever
+    setTimeout(() => resolve(data), 5000)
+  })
+}

package/src/commands/files.ts

@@ -0,0 +1,117 @@
+/**
+ * File attachment commands: upload, uploads.
+ */
+import * as fs from 'node:fs'
+import * as nodePath from 'node:path'
+import { registerCommand } from '../command.ts'
+import type { CLIConnection } from '../connection.ts'
+import type { ParsedArgs } from '../parser.ts'
+import { resolveDocument } from '../resolve.ts'
+import { printJson, printTable, getFormat } from '../output.ts'
+
+registerCommand({
+  name: 'uploads',
+  aliases: ['attachments'],
+  description: 'List file attachments for a document.',
+  usage: 'uploads id=<docId> | name=<label> [--format=json|tsv] [--total]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    try {
+      const uploads = await conn.client.listUploads(docId)
+
+      if (args.flags.has('total')) {
+        return String(uploads.length)
+      }
+
+      const format = getFormat(args, 'text')
+
+      if (format === 'json') {
+        return printJson(uploads)
+      }
+
+      if (uploads.length === 0) {
+        return 'No attachments.'
+      }
+
+      const rows = uploads.map(u => [
+        u.id.slice(0, 8) + '…',
+        u.filename,
+        u.mime_type ?? '—',
+        u.size ? formatBytes(u.size) : '—',
+      ])
+
+      return printTable(rows, ['ID', 'FILENAME', 'TYPE', 'SIZE'])
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'upload',
+  description: 'Upload a local file to a document.',
+  usage: 'upload id=<docId> | name=<label> file=<localPath> [filename=<override>]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const filePath = args.params['file'] || args.params['path']
+    if (!filePath) return 'Missing required parameter: file=<localPath>'
+
+    try {
+      const resolvedPath = nodePath.resolve(filePath)
+      if (!fs.existsSync(resolvedPath)) {
+        return `File not found: ${resolvedPath}`
+      }
+      const data = fs.readFileSync(resolvedPath)
+      const filename = args.params['filename'] ?? nodePath.basename(resolvedPath)
+      const blob = new Blob([data])
+      const result = await conn.client.upload(docId, blob, filename)
+
+      return `Uploaded: ${filename} (${formatBytes(data.length)}) → ${result.id}`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'download',
+  description: 'Download a file attachment from a document.',
+  usage: 'download id=<docId> | name=<label> upload=<uploadId> output=<localPath>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const docId = resolveDocument(conn, args.params, args.positional)
+    if (!docId) return 'Document not found.'
+
+    const uploadId = args.params['upload'] || args.params['uploadId']
+    if (!uploadId) return 'Missing required parameter: upload=<uploadId>'
+
+    const outputPath = args.params['output'] || args.params['to']
+    if (!outputPath) return 'Missing required parameter: output=<localPath>'
+
+    try {
+      const blob = await conn.client.getUpload(docId, uploadId)
+      const buffer = Buffer.from(await blob.arrayBuffer())
+      const resolvedPath = nodePath.resolve(outputPath)
+      fs.writeFileSync(resolvedPath, buffer)
+
+      return `Downloaded to ${resolvedPath} (${formatBytes(buffer.length)})`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}

package/src/commands/help.ts

@@ -0,0 +1,72 @@
+/**
+ * help + version commands.
+ */
+import { registerCommand, getAllCommands } from '../command.ts'
+import type { CLIConnection } from '../connection.ts'
+import type { ParsedArgs } from '../parser.ts'
+import { pad } from '../output.ts'
+
+registerCommand({
+  name: 'help',
+  aliases: ['h', '?'],
+  description: 'Show list of all available commands.',
+  usage: 'help [<command>]',
+  async run(_conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    const target = args.positional[0]
+
+    if (target) {
+      const cmd = getAllCommands().find(c =>
+        c.name === target || c.aliases?.includes(target)
+      )
+      if (!cmd) {
+        return `Unknown command: ${target}\n\nRun 'abracadabra help' to see all commands.`
+      }
+      const aliasStr = cmd.aliases?.length ? ` (aliases: ${cmd.aliases.join(', ')})` : ''
+      let text = `${cmd.name}${aliasStr}\n  ${cmd.description}`
+      if (cmd.usage) text += `\n\n  Usage: abracadabra ${cmd.usage}`
+      return text
+    }
+
+    const cmds = getAllCommands()
+    const maxLen = Math.max(...cmds.map(c => c.name.length))
+
+    const lines = [
+      'Abracadabra CLI — interact with CRDT document workspaces from the terminal.',
+      '',
+      'Usage: abracadabra <command> [key=value ...] [--flags]',
+      '',
+      'Commands:',
+      ...cmds.map(c => {
+        const aliasStr = c.aliases?.length ? ` (${c.aliases.join(', ')})` : ''
+        return `  ${pad(c.name, maxLen + 2)}${c.description}${aliasStr}`
+      }),
+      '',
+      'Environment:',
+      '  ABRA_URL          Server URL (required)',
+      '  ABRA_KEY_FILE     Path to Ed25519 key file',
+      '  ABRA_INVITE_CODE  Invite code for first-run registration',
+      '  ABRA_NAME         Display name',
+      '  ABRA_COLOR        Presence color',
+      '',
+      'Run "abracadabra help <command>" for command-specific help.',
+    ]
+    return lines.join('\n')
+  },
+})
+
+registerCommand({
+  name: 'version',
+  aliases: ['v'],
+  description: 'Show CLI and server version.',
+  async run(conn: CLIConnection | null): Promise<string> {
+    const cliVersion = '1.0.0'
+    const lines = [`Abracadabra CLI  v${cliVersion}`]
+    if (conn?.serverInfo) {
+      const si = conn.serverInfo
+      if (si.version) lines.push(`Server           v${si.version}`)
+      if (si.name) lines.push(`Server name      ${si.name}`)
+      if (si.protocol_version) lines.push(`Protocol         ${si.protocol_version}`)
+    }
+    return lines.join('\n')
+  },
+})