@sinoia/hubdoc-tools 1.11.0 → 1.13.0

package/docs/llm-usage.md

@@ -408,6 +408,110 @@ without going through a workspace-scoped ACL. Example:
 `hubdoc permissions grant --to <user-id> --to-type user --on <project-id>
 --on-type project --level admin`.
 
+### Concurrent markdown editing (`hubdoc md`, corex#594)
+
+`hubdoc md` exposes the corex `Tools::Documents::MarkdownEditor` (the
+same tool internal Ruby agents use) through a single HTTP endpoint
+(`POST /api/v1/documents/files/:id/markdown_editor`). Eleven surgical
+actions, one HTTP round-trip each:
+
+- **Discovery** : `structure` (outline + line numbers), `stats` (word
+  counts, section sizes, TODOs), `search --pattern <regex> [--context N]`.
+- **Read** : `read [--from-line N --to-line M | --offset N --limit M]`,
+  `read-section --heading "…" [--level N] [--index N]`.
+- **Write** : `write-section --heading "…" (--content <text> |
+  --content-file <path>)`, `append`, `insert (--at-line N | --at-offset
+  N)`, `delete (--from-line/--to-line | --from-offset/--to-offset)`,
+  `replace --find "…" (--replace-with "…" | --replace-with-file <path>)
+  [--all]`.
+- **Save** : `save [--create-version] [--version-comment "…"]` — the
+  content is auto-saved by every write; `save` is just for the explicit
+  version snapshot.
+
+**Concurrency & merge — handled server-side, no client state** :
+
+Each write action executes on the server as a single load-blob → mutate
+→ save-blob → `publish Documents::FileContentUpdated` cycle. Two agents
+running `hubdoc md insert` in parallel serialise at the Rails +
+ActiveStorage level; the second one loads the first one's result before
+applying its own. No client-side coordination or CRDT to maintain.
+
+Cross-modal coordination (agent + human on the web UI): every write
+broadcasts `content_refresh` over `DocumentEditingChannel`, which the
+frontend's Y.js session reloads from server content. Cf. the corex
+design `.claude/context/designs/y-rb-implementation.md`.
+
+**Inter-agent coordination via events** :
+
+```bash
+# Agent B watches for edits on the file, reacts.
+hubdoc events watch \
+    --type Documents::FileContentUpdated \
+    --timeout 900 --json \
+    | jq -r '.items[-1].data.file_id'
+# → returns as soon as another agent (or the human) touches the file.
+```
+
+**Typical agent workflow — build a section incrementally without racing** :
+
+```bash
+# 1. Discover current structure (10 KB, no side effects).
+hubdoc md structure "$FID" --json
+
+# 2. Read just the section we care about.
+hubdoc md read-section "$FID" --heading "Analyse" --json > current.md
+
+# 3. Regenerate its body locally, push atomically.
+llm-generate-analysis > new-analysis.md
+hubdoc md write-section "$FID" --heading "Analyse" \
+    --content-file new-analysis.md --json
+
+# 4. Snapshot when done.
+hubdoc md save "$FID" --create-version --version-comment "Analyse v2" --json
+```
+
+### Events — react to what's happening (corex#593)
+
+`hubdoc events ls` and `hubdoc events watch` sit on top of the Rails
+Event Store stream. Every mutation done by `projects/sprints/tickets/
+tasks` (create, update, status_changed, moved, deliverable_attached,
+channel_message_posted, …) is published as a typed event; the CLI lets
+an agent either **poll** the stream once (`ls`) or **block** until
+something happens (`watch`).
+
+- **Type aliases** (agent-friendly): `ticket.created | ticket.updated |
+  ticket.status_changed | ticket.assigned | ticket.blocked |
+  ticket.escalated | ticket.failed | ticket.moved | ticket.comment |
+  ticket.deliverable | ticket.deleted | sprint.{created,started,updated,
+  completed,deleted} | project.{created,updated,started,completed,
+  archived,deleted} | task.{created,updated,completed,deleted}`. Full RES
+  class names (`Projects::Tickets::TicketStatusChanged`) are also
+  accepted verbatim.
+- **Cursor**: each `ls` response includes `next_cursor` — pass it as
+  `--since` on the next call to resume. `watch` re-uses the same `since`
+  across empty polls (never skips an event that arrives mid-poll).
+- **Timeout**: `watch --timeout <s>` (default 60) — exit code 2 with a
+  `{ ok:false, reason:"timeout", waited_ms, since }` envelope on stderr
+  when the window expires. This is distinct from network errors (exit 1).
+- **Poll cadence**: `watch --poll-interval-ms <n>` (default 1000, min
+  100). Kept short so the perceived latency stays low; harmless because
+  each poll is a lightweight bare-array read.
+
+Two typical patterns:
+
+```bash
+# 1) Wait for the dispatched agent to finish before moving on.
+hubdoc events watch --project "$PID" --ticket "$TID" \
+    --type ticket.status_changed --timeout 900 --json \
+    | jq -r '.items[-1].data.new_status'   # → done / failed / blocked
+# (returns as soon as the first matching event arrives)
+
+# 2) Loop over the day's activity from a saved checkpoint.
+CURSOR=$(cat .last-cursor 2>/dev/null || echo "")
+hubdoc events ls --project "$PID" --since "$CURSOR" --limit 200 --json \
+    | tee day-batch.json | jq -r '.next_cursor' > .last-cursor
+```
+
 `hubdoc tasks --project=<pid> --ticket=<tid>` — `ls | show | create |
 update | delete | complete | reorder`. Sub-tasks live under a ticket;
 both parents are required on every call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinoia/hubdoc-tools",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {