@abraca/cli 1.5.0

package/src/parser.ts

@@ -0,0 +1,80 @@
+/**
+ * Minimal argument parser for Abracadabra CLI.
+ *
+ * Syntax:
+ *   abracadabra [--flag] <command>[:<subcommand>] [key=value ...] [--flag2]
+ *   abracadabra [--flag] <command>[:<subcommand>] [key="value with spaces"] [--format=json]
+ */
+
+export interface ParsedArgs {
+  /** The command name, e.g. "tree", "spaces:switch", "read" */
+  command: string
+  /** Key-value parameters, e.g. { name: "My Doc", type: "doc" } */
+  params: Record<string, string>
+  /** Boolean flags, e.g. { total: true, verbose: true } */
+  flags: Set<string>
+  /** Positional arguments (non-flag, non-key=value, after the command) */
+  positional: string[]
+}
+
+/**
+ * Parse CLI arguments into a structured object.
+ * @param argv Raw process.argv (includes node path and script path)
+ */
+export function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2) // skip node + script
+
+  const result: ParsedArgs = {
+    command: 'help',
+    params: {},
+    flags: new Set(),
+    positional: [],
+  }
+
+  let commandFound = false
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    // --flag or --key=value
+    if (arg.startsWith('--')) {
+      const stripped = arg.slice(2)
+      const eqIdx = stripped.indexOf('=')
+      if (eqIdx !== -1) {
+        // --format=json style
+        const key = stripped.slice(0, eqIdx)
+        const value = stripped.slice(eqIdx + 1)
+        result.params[key] = value
+      } else {
+        result.flags.add(stripped)
+      }
+      continue
+    }
+
+    // key=value pair
+    const eqIdx = arg.indexOf('=')
+    if (eqIdx !== -1 && eqIdx > 0) {
+      const key = arg.slice(0, eqIdx)
+      let value = arg.slice(eqIdx + 1)
+      // Strip surrounding quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      result.params[key] = value
+      continue
+    }
+
+    // First bare word is the command
+    if (!commandFound) {
+      result.command = arg
+      commandFound = true
+      continue
+    }
+
+    // Subsequent bare words are positional
+    result.positional.push(arg)
+  }
+
+  return result
+}

package/src/resolve.ts

@@ -0,0 +1,174 @@
+/**
+ * Document resolution utilities for the CLI.
+ *
+ * Resolves documents by id, name (label), or path (label chain from root).
+ * Similar to Obsidian's file= / path= resolution.
+ */
+import * as Y from 'yjs'
+import type { CLIConnection } from './connection.ts'
+
+export interface TreeEntry {
+  id: string
+  label: string
+  parentId: string | null
+  order: number
+  type?: string
+  meta?: Record<string, unknown>
+  createdAt?: number
+  updatedAt?: number
+}
+
+/** 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
+}
+
+/** Read all tree entries from the Y.Map. */
+export function readEntries(treeMap: Y.Map<any>): TreeEntry[] {
+  const entries: TreeEntry[] = []
+  treeMap.forEach((raw: any, id: string) => {
+    const value = toPlain(raw)
+    if (typeof value !== 'object' || value === null) return
+    entries.push({
+      id,
+      label: value.label || 'Untitled',
+      parentId: value.parentId ?? null,
+      order: value.order ?? 0,
+      type: value.type,
+      meta: value.meta,
+      createdAt: value.createdAt,
+      updatedAt: value.updatedAt,
+    })
+  })
+  return entries
+}
+
+/** Get direct children of a parent, sorted by order. */
+export function childrenOf(entries: TreeEntry[], parentId: string | null): TreeEntry[] {
+  return entries
+    .filter(e => e.parentId === parentId)
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+}
+
+/** Get all descendants of an entry. */
+export function descendantsOf(entries: TreeEntry[], id: string | null): TreeEntry[] {
+  const result: TreeEntry[] = []
+  const visited = new Set<string>()
+  function collect(pid: string) {
+    if (visited.has(pid)) return
+    visited.add(pid)
+    for (const child of childrenOf(entries, pid)) {
+      result.push(child)
+      collect(child.id)
+    }
+  }
+  collect(id!)
+  return result
+}
+
+/** Build a nested tree structure for display. */
+export function buildTree(entries: TreeEntry[], rootId: string | null, maxDepth: number, currentDepth = 0, visited = new Set<string>()): TreeDisplayNode[] {
+  if (maxDepth >= 0 && currentDepth >= maxDepth) return []
+  const children = childrenOf(entries, rootId)
+  return children.filter(e => !visited.has(e.id)).map(entry => {
+    const next = new Set(visited)
+    next.add(entry.id)
+    return {
+      id: entry.id,
+      label: entry.label,
+      type: entry.type,
+      meta: entry.meta,
+      children: buildTree(entries, entry.id, maxDepth, currentDepth + 1, next),
+    }
+  })
+}
+
+export interface TreeDisplayNode {
+  id: string
+  label: string
+  type?: string
+  meta?: Record<string, unknown>
+  children: TreeDisplayNode[]
+}
+
+/**
+ * Normalize a document ID so the hub/root doc ID is treated as the tree root (null).
+ */
+export function normalizeRootId(id: string | null | undefined, conn: CLIConnection): string | null {
+  if (id == null) return null
+  return id === conn.rootDocId ? null : id
+}
+
+/**
+ * Resolve a document from parsed args.
+ *
+ * Resolution order:
+ *   1. id=<uuid> — Direct document ID
+ *   2. name=<label> — Case-insensitive label match (first match wins)
+ *   3. path=<a/b/c> — Resolve by label path from root
+ *   4. First positional argument — tries name resolution
+ *
+ * Returns the document ID or null if not found.
+ */
+export function resolveDocument(
+  conn: CLIConnection,
+  params: Record<string, string>,
+  positional: string[],
+): string | null {
+  const treeMap = conn.getTreeMap()
+  if (!treeMap) return null
+
+  const entries = readEntries(treeMap)
+
+  // 1. Direct ID
+  if (params['id']) {
+    const entry = entries.find(e => e.id === params['id'])
+    return entry ? entry.id : null
+  }
+
+  // 2. Name resolution (case-insensitive label match)
+  const name = params['name'] || params['file'] || positional[0]
+  if (name) {
+    const lower = name.toLowerCase()
+    const match = entries.find(e => e.label.toLowerCase() === lower)
+    if (match) return match.id
+
+    // Substring match as fallback
+    const substring = entries.find(e => e.label.toLowerCase().includes(lower))
+    if (substring) return substring.id
+  }
+
+  // 3. Path resolution (slash-separated label chain)
+  if (params['path']) {
+    const segments = params['path'].split('/').map(s => s.trim()).filter(Boolean)
+    let currentParent: string | null = normalizeRootId(conn.rootDocId, conn)
+
+    for (const segment of segments) {
+      const lower = segment.toLowerCase()
+      const children = childrenOf(entries, currentParent)
+      const match = children.find(c => c.label.toLowerCase() === lower)
+      if (!match) return null
+      currentParent = match.id
+    }
+
+    return currentParent
+  }
+
+  return null
+}
+
+/** Get the ancestor path labels for a document. */
+export function getAncestorPath(entries: TreeEntry[], docId: string): string[] {
+  const byId = new Map(entries.map(e => [e.id, e]))
+  const path: string[] = []
+  let current = byId.get(docId)?.parentId
+  const visited = new Set<string>()
+  while (current && !visited.has(current)) {
+    visited.add(current)
+    const parent = byId.get(current)
+    if (!parent) break
+    path.unshift(parent.label)
+    current = parent.parentId
+  }
+  return path
+}