@abraca/cli 1.5.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@abraca/cli",
+  "version": "1.5.0",
+  "description": "CLI for Abracadabra — interact with CRDT document workspaces from the terminal",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/abracadabra-cli.cjs",
+  "module": "dist/abracadabra-cli.esm.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "abracadabra": "./dist/abracadabra-cli.esm.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "source": {
+      "import": "./src/index.ts"
+    },
+    "default": {
+      "import": "./dist/abracadabra-cli.esm.js",
+      "require": "./dist/abracadabra-cli.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "@noble/ed25519": "^2.3.0",
+    "@noble/hashes": "^1.8.0"
+  },
+  "peerDependencies": {
+    "@abraca/dabra": ">=1.0.0",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.8"
+  }
+}

package/src/command.ts

@@ -0,0 +1,29 @@
+/**
+ * Command interface and registry.
+ */
+import type { CLIConnection } from './connection.ts'
+import type { ParsedArgs } from './parser.ts'
+
+export interface Command {
+  name: string
+  aliases?: string[]
+  description: string
+  usage?: string
+  run(conn: CLIConnection | null, args: ParsedArgs): Promise<string>
+}
+
+const commands: Command[] = []
+
+export function registerCommand(cmd: Command): void {
+  commands.push(cmd)
+}
+
+export function getCommand(name: string): Command | null {
+  return commands.find(c =>
+    c.name === name || c.aliases?.includes(name)
+  ) ?? null
+}
+
+export function getAllCommands(): Command[] {
+  return [...commands]
+}

package/src/commands/awareness.ts

@@ -0,0 +1,122 @@
+/**
+ * Awareness commands: who, status, chat.
+ */
+import { registerCommand } from '../command.ts'
+import type { CLIConnection } from '../connection.ts'
+import type { ParsedArgs } from '../parser.ts'
+import { printJson, printTable, getFormat } from '../output.ts'
+
+registerCommand({
+  name: 'who',
+  aliases: ['users', 'online'],
+  description: 'List connected users and their awareness state.',
+  usage: 'who [id=<docId>] [--format=json|tsv]',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    let awareness
+    if (args.params['id']) {
+      try {
+        const provider = await conn.getChildProvider(args.params['id'])
+        awareness = provider.awareness
+      } catch (error: any) {
+        return `Error: ${error.message}`
+      }
+    } else {
+      const rootProvider = conn.rootProvider
+      if (!rootProvider) return 'Not connected'
+      awareness = rootProvider.awareness
+    }
+
+    const states = awareness.getStates()
+    const selfId = awareness.clientID
+    const users: Array<{
+      name: string
+      status: string
+      docId: string
+      isYou: boolean
+      isAgent: boolean
+    }> = []
+
+    for (const [clientId, state] of states) {
+      const user = (state as Record<string, any>)['user']
+      if (!user) continue
+      users.push({
+        name: user.name ?? 'Unknown',
+        status: (state as Record<string, any>)['status'] ?? '—',
+        docId: (state as Record<string, any>)['docId'] ?? '—',
+        isYou: clientId === selfId,
+        isAgent: user.isAgent ?? false,
+      })
+    }
+
+    const format = getFormat(args, 'text')
+
+    if (format === 'json') {
+      return printJson(users)
+    }
+
+    if (users.length === 0) {
+      return 'No users connected.'
+    }
+
+    const rows = users.map(u => [
+      u.name + (u.isYou ? ' (you)' : '') + (u.isAgent ? ' 🤖' : ''),
+      u.status,
+      u.docId === '—' ? '—' : u.docId.slice(0, 8) + '…',
+    ])
+
+    return printTable(rows, ['NAME', 'STATUS', 'DOCUMENT'])
+  },
+})
+
+registerCommand({
+  name: 'status',
+  description: 'Set your presence status.',
+  usage: 'status <text> | status --clear',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const rootProvider = conn.rootProvider
+    if (!rootProvider) return 'Not connected'
+
+    if (args.flags.has('clear')) {
+      rootProvider.awareness.setLocalStateField('status', null)
+      return 'Status cleared.'
+    }
+
+    const status = args.params['text'] || args.positional[0]
+    if (!status) return 'Missing status text. Use: status <text> or status --clear'
+
+    rootProvider.awareness.setLocalStateField('status', status)
+    return `Status set to "${status}"`
+  },
+})
+
+registerCommand({
+  name: 'chat',
+  aliases: ['send'],
+  description: 'Send a chat message to a channel.',
+  usage: 'chat channel=<group:docId> text=<message>',
+  async run(conn: CLIConnection | null, args: ParsedArgs): Promise<string> {
+    if (!conn) return 'Not connected'
+
+    const rootProvider = conn.rootProvider
+    if (!rootProvider) return 'Not connected'
+
+    const channel = args.params['channel']
+    if (!channel) return 'Missing required parameter: channel=<group:docId>'
+
+    const text = args.params['text'] || args.params['content'] || args.positional[0]
+    if (!text) return 'Missing required parameter: text=<message>'
+
+    rootProvider.sendStateless(JSON.stringify({
+      type: 'chat:send',
+      channel,
+      content: text,
+      sender_name: conn.displayName,
+    }))
+
+    return `Sent to ${channel}`
+  },
+})

package/src/commands/content.ts

@@ -0,0 +1,135 @@
+/**
+ * Content commands: append, prepend, wc, export.
+ */
+import * as fs from 'node:fs'
+import * as path 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 { yjsToMarkdown } from '../converters/yjsToMarkdown.ts'
+import { populateYDocFromMarkdown } from '../converters/markdownToYjs.ts'
+
+registerCommand({
+  name: 'append',
+  description: 'Append content to a document.',
+  usage: 'append id=<docId> | name=<label> content=<text> [--inline]',
+  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 content = args.params['content']
+    if (!content) return 'Missing required parameter: content=<text>'
+
+    try {
+      const provider = await conn.getChildProvider(docId)
+      const fragment = provider.document.getXmlFragment('default')
+      const text = args.flags.has('inline')
+        ? content.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+        : '\n' + content.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+      populateYDocFromMarkdown(fragment, text, '')
+
+      return `Appended to ${docId.slice(0, 8)}…`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'prepend',
+  description: 'Prepend content to a document (after frontmatter).',
+  usage: 'prepend id=<docId> | name=<label> content=<text> [--inline]',
+  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 content = args.params['content']
+    if (!content) return 'Missing required parameter: content=<text>'
+
+    try {
+      const provider = await conn.getChildProvider(docId)
+      const doc = provider.document
+      const fragment = doc.getXmlFragment('default')
+
+      // Read existing, prepend, rewrite
+      const { markdown: existing } = yjsToMarkdown(fragment)
+      const text = content.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+      const combined = args.flags.has('inline')
+        ? text + existing
+        : text + '\n' + existing
+
+      doc.transact(() => {
+        while (fragment.length > 0) {
+          fragment.delete(0)
+        }
+      })
+      populateYDocFromMarkdown(fragment, combined, '')
+
+      return `Prepended to ${docId.slice(0, 8)}…`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'wc',
+  aliases: ['wordcount'],
+  description: 'Count words and characters in a document.',
+  usage: 'wc id=<docId> | name=<label> [--words] [--characters]',
+  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 provider = await conn.getChildProvider(docId)
+      const fragment = provider.document.getXmlFragment('default')
+      const { markdown } = yjsToMarkdown(fragment)
+
+      const words = markdown.split(/\s+/).filter(Boolean).length
+      const chars = markdown.length
+
+      if (args.flags.has('words')) return String(words)
+      if (args.flags.has('characters')) return String(chars)
+
+      return `Words:      ${words}\nCharacters: ${chars}`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})
+
+registerCommand({
+  name: 'export',
+  description: 'Export a document as markdown to a local file.',
+  usage: 'export id=<docId> | name=<label> output=<filepath>',
+  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 outputPath = args.params['output'] || args.params['to'] || args.params['path']
+    if (!outputPath) return 'Missing required parameter: output=<filepath>'
+
+    try {
+      const provider = await conn.getChildProvider(docId)
+      const fragment = provider.document.getXmlFragment('default')
+      const { title, markdown } = yjsToMarkdown(fragment)
+
+      const resolvedPath = path.resolve(outputPath)
+      fs.writeFileSync(resolvedPath, markdown, 'utf-8')
+
+      return `Exported "${title || 'document'}" to ${resolvedPath} (${Buffer.byteLength(markdown)} bytes)`
+    } catch (error: any) {
+      return `Error: ${error.message}`
+    }
+  },
+})