@sinoia/hubdoc-tools 1.11.0 → 1.12.0

package/cli.js

@@ -42589,9 +42589,9 @@ var require_follow_redirects = __commonJS({
       "search",
       "hash"
     ];
-    var events = ["abort", "aborted", "connect", "error", "socket", "timeout"];
+    var events2 = ["abort", "aborted", "connect", "error", "socket", "timeout"];
     var eventHandlers = /* @__PURE__ */ Object.create(null);
-    events.forEach(function(event) {
+    events2.forEach(function(event) {
       eventHandlers[event] = function(arg1, arg2, arg3) {
         this._redirectable.emit(event, arg1, arg2, arg3);
       };
@@ -42805,7 +42805,7 @@ var require_follow_redirects = __commonJS({
       }
       var request = this._currentRequest = nativeProtocol.request(this._options, this._onNativeResponse);
       request._redirectable = this;
-      for (var event of events) {
+      for (var event of events2) {
         request.on(event, eventHandlers[event]);
       }
       this._currentUrl = /^\//.test(this._options.path) ? url3.format(this._options) : (
@@ -43020,7 +43020,7 @@ var require_follow_redirects = __commonJS({
       return CustomError;
     }
     function destroyRequest(request, error2) {
-      for (var event of events) {
+      for (var event of events2) {
         request.removeListener(event, eventHandlers[event]);
       }
       request.on("error", noop2);
@@ -50043,7 +50043,7 @@ var require_parser = __commonJS({
   "node_modules/xml2js/lib/parser.js"(exports2) {
     (function() {
       "use strict";
-      var bom, defaults3, defineProperty, events, isEmpty, processItem, processors, sax, setImmediate2, bind2 = function(fn, me) {
+      var bom, defaults3, defineProperty, events2, isEmpty, processItem, processors, sax, setImmediate2, bind2 = function(fn, me) {
         return function() {
           return fn.apply(me, arguments);
         };
@@ -50060,7 +50060,7 @@ var require_parser = __commonJS({
         return child;
       }, hasProp = {}.hasOwnProperty;
       sax = require_sax();
-      events = require("events");
+      events2 = require("events");
       bom = require_bom();
       processors = require_processors();
       setImmediate2 = require("timers").setImmediate;
@@ -50398,7 +50398,7 @@ var require_parser = __commonJS({
           })(this));
         };
         return Parser;
-      })(events);
+      })(events2);
       exports2.parseString = function(str, a3, b3) {
         var cb, options, parser;
         if (b3 != null) {
@@ -73349,7 +73349,7 @@ var require_dist_cjs69 = __commonJS({
         return value2;
       };
     };
-    var sleep = (seconds) => {
+    var sleep2 = (seconds) => {
       return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
     };
     var waiterServiceDefaults = {
@@ -73416,7 +73416,7 @@ var require_dist_cjs69 = __commonJS({
         if (Date.now() + delay5 * 1e3 > waitUntil) {
           return { state: exports2.WaiterState.TIMEOUT, observedResponses };
         }
-        await sleep(delay5);
+        await sleep2(delay5);
         const { state: state5, reason: reason2 } = await acceptorChecks(client, input);
         if (reason2) {
           const message = createMessageFromResponse(reason2);
@@ -86010,7 +86010,7 @@ var require_dist_cjs72 = __commonJS({
     var abortController = require_dist_cjs71();
     var middlewareEndpoint = require_dist_cjs42();
     var smithyClient = require_dist_cjs20();
-    var events = require("events");
+    var events2 = require("events");
     var buffer2 = require("buffer");
     var runtimeConfig = require_runtimeConfig3();
     var stream5 = require("stream");
@@ -86166,7 +86166,7 @@ var require_dist_cjs72 = __commonJS({
       }
       throw new Error("Body Data is unsupported format, expected data to be one of: string | Uint8Array | Buffer | Readable | ReadableStream | Blob;.");
     };
-    var Upload2 = class _Upload extends events.EventEmitter {
+    var Upload2 = class _Upload extends events2.EventEmitter {
       static MIN_PART_SIZE = 1024 * 1024 * 5;
       MAX_PARTS = 1e4;
       queueSize = 4;
@@ -86229,7 +86229,7 @@ var require_dist_cjs72 = __commonJS({
         const params = { ...this.params, Body: dataPart.data };
         const clientConfig = this.client.config;
         const requestHandler = clientConfig.requestHandler;
-        const eventEmitter = requestHandler instanceof events.EventEmitter ? requestHandler : null;
+        const eventEmitter = requestHandler instanceof events2.EventEmitter ? requestHandler : null;
         const uploadEventListener = (event) => {
           this.bytesUploadedSoFar = event.loaded;
           this.totalBytes = event.total;
@@ -86325,7 +86325,7 @@ var require_dist_cjs72 = __commonJS({
           }
           const partSize = byteLength(dataPart.data) || 0;
           const requestHandler = this.client.config.requestHandler;
-          const eventEmitter = requestHandler instanceof events.EventEmitter ? requestHandler : null;
+          const eventEmitter = requestHandler instanceof events2.EventEmitter ? requestHandler : null;
           let lastSeenBytes = 0;
           const uploadEventListener = (event, request) => {
             const requestPartSize = Number(request.query["partNumber"]) || -1;
@@ -95034,7 +95034,7 @@ var require_bignumber = __commonJS({
   "node_modules/bignumber.js/bignumber.js"(exports2, module2) {
     (function(globalObject) {
       "use strict";
-      var BigNumber, isNumeric = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i, mathceil = Math.ceil, mathfloor = Math.floor, bignumberError = "[BigNumber Error] ", tooManyDigits = bignumberError + "Number primitive has more than 15 significant digits: ", BASE5 = 1e14, LOG_BASE = 14, MAX_SAFE_INTEGER = 9007199254740991, POWS_TEN = [1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13], SQRT_BASE = 1e7, MAX = 1e9;
+      var BigNumber, isNumeric = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i, mathceil = Math.ceil, mathfloor = Math.floor, bignumberError = "[BigNumber Error] ", tooManyDigits = bignumberError + "Number primitive has more than 15 significant digits: ", BASE6 = 1e14, LOG_BASE = 14, MAX_SAFE_INTEGER = 9007199254740991, POWS_TEN = [1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13], SQRT_BASE = 1e7, MAX = 1e9;
       function clone(configObject) {
         var div, convertBase, parseNumeric, P = BigNumber2.prototype = { constructor: BigNumber2, toString: null, valueOf: null }, ONE = new BigNumber2(1), DECIMAL_PLACES = 20, ROUNDING_MODE = 4, TO_EXP_NEG = -7, TO_EXP_POS = 21, MIN_EXP = -1e7, MAX_EXP = 1e7, CRYPTO = false, MODULO_MODE = 1, POW_PRECISION = 0, FORMAT = {
           prefix: "",
@@ -95286,7 +95286,7 @@ var require_bignumber = __commonJS({
               if (String(c3[0]).length == i3) {
                 for (i3 = 0; i3 < c3.length; i3++) {
                   n3 = c3[i3];
-                  if (n3 < 0 || n3 >= BASE5 || n3 !== mathfloor(n3)) break out;
+                  if (n3 < 0 || n3 >= BASE6 || n3 !== mathfloor(n3)) break out;
                 }
                 if (n3 !== 0) return true;
               }
@@ -95503,7 +95503,7 @@ var require_bignumber = __commonJS({
             e3 = x3.e - y2.e;
             s3 = dp + e3 + 1;
             if (!base) {
-              base = BASE5;
+              base = BASE6;
               e3 = bitFloor(x3.e / LOG_BASE) - bitFloor(y2.e / LOG_BASE);
               s3 = s3 / LOG_BASE | 0;
             }
@@ -95582,7 +95582,7 @@ var require_bignumber = __commonJS({
               more = rem[0] != null;
               if (!qc[0]) qc.splice(0, 1);
             }
-            if (base == BASE5) {
+            if (base == BASE6) {
               for (i3 = 1, s3 = qc[0]; s3 >= 10; s3 /= 10, i3++) ;
               round(q3, dp + (q3.e = i3 + e3 * LOG_BASE - 1) + 1, rm, more);
             } else {
@@ -95741,12 +95741,12 @@ var require_bignumber = __commonJS({
                     for (k3 = 1; j3 >= 10; j3 /= 10, k3++) ;
                     if (i3 != k3) {
                       x3.e++;
-                      if (xc[0] == BASE5) xc[0] = 1;
+                      if (xc[0] == BASE6) xc[0] = 1;
                     }
                     break;
                   } else {
                     xc[ni] += k3;
-                    if (xc[ni] != BASE5) break;
+                    if (xc[ni] != BASE6) break;
                     xc[ni--] = 0;
                     k3 = 1;
                   }
@@ -95955,12 +95955,12 @@ var require_bignumber = __commonJS({
           }
           b3 = (j3 = yc.length) - (i3 = xc.length);
           if (b3 > 0) for (; b3--; xc[i3++] = 0) ;
-          b3 = BASE5 - 1;
+          b3 = BASE6 - 1;
           for (; j3 > a3; ) {
             if (xc[--j3] < yc[j3]) {
               for (i3 = j3; i3 && !xc[--i3]; xc[i3] = b3) ;
               --xc[i3];
-              xc[j3] += BASE5;
+              xc[j3] += BASE6;
             }
             xc[j3] -= yc[j3];
           }
@@ -96022,7 +96022,7 @@ var require_bignumber = __commonJS({
             ycL = i3;
           }
           for (i3 = xcL + ycL, zc = []; i3--; zc.push(0)) ;
-          base = BASE5;
+          base = BASE6;
           sqrtBase = SQRT_BASE;
           for (i3 = ycL; --i3 >= 0; ) {
             c3 = 0;
@@ -96088,8 +96088,8 @@ var require_bignumber = __commonJS({
             b3 = a3;
           }
           for (a3 = 0; b3; ) {
-            a3 = (xc[--b3] = xc[b3] + yc[b3] + a3) / BASE5 | 0;
-            xc[b3] = BASE5 === xc[b3] ? 0 : xc[b3] % BASE5;
+            a3 = (xc[--b3] = xc[b3] + yc[b3] + a3) / BASE6 | 0;
+            xc[b3] = BASE6 === xc[b3] ? 0 : xc[b3] % BASE6;
           }
           if (a3) {
             xc = [a3].concat(xc);
@@ -672699,11 +672699,11 @@ var ListPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
-    events.normalizedUpKey.pipe((0, import_rxjs3.takeUntil)(events.line)).forEach(this.onUpKey.bind(this));
-    events.normalizedDownKey.pipe((0, import_rxjs3.takeUntil)(events.line)).forEach(this.onDownKey.bind(this));
-    events.numberKey.pipe((0, import_rxjs3.takeUntil)(events.line)).forEach(this.onNumberKey.bind(this));
-    events.line.pipe(
+    const events2 = observe(this.rl);
+    events2.normalizedUpKey.pipe((0, import_rxjs3.takeUntil)(events2.line)).forEach(this.onUpKey.bind(this));
+    events2.normalizedDownKey.pipe((0, import_rxjs3.takeUntil)(events2.line)).forEach(this.onDownKey.bind(this));
+    events2.numberKey.pipe((0, import_rxjs3.takeUntil)(events2.line)).forEach(this.onNumberKey.bind(this));
+    events2.line.pipe(
       (0, import_rxjs3.take)(1),
       (0, import_rxjs3.map)(this.getCurrentValue.bind(this)),
       (0, import_rxjs3.flatMap)(
@@ -672816,12 +672816,12 @@ var InputPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
-    const submit = events.line.pipe((0, import_rxjs4.map)(this.filterInput.bind(this)));
+    const events2 = observe(this.rl);
+    const submit = events2.line.pipe((0, import_rxjs4.map)(this.filterInput.bind(this)));
     const validation = this.handleSubmitEvents(submit);
     validation.success.forEach(this.onEnd.bind(this));
     validation.error.forEach(this.onError.bind(this));
-    events.keypress.pipe((0, import_rxjs4.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
+    events2.keypress.pipe((0, import_rxjs4.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
     this.render();
     return this;
   }
@@ -672918,9 +672918,9 @@ var ConfirmPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
-    events.keypress.pipe((0, import_rxjs5.takeUntil)(events.line)).forEach(this.onKeypress.bind(this));
-    events.line.pipe((0, import_rxjs5.take)(1)).forEach(this.onEnd.bind(this));
+    const events2 = observe(this.rl);
+    events2.keypress.pipe((0, import_rxjs5.takeUntil)(events2.line)).forEach(this.onKeypress.bind(this));
+    events2.line.pipe((0, import_rxjs5.take)(1)).forEach(this.onEnd.bind(this));
     this.render();
     return this;
   }
@@ -673001,14 +673001,14 @@ var RawListPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
-    const submit = events.line.pipe((0, import_rxjs6.map)(this.getCurrentValue.bind(this)));
+    const events2 = observe(this.rl);
+    const submit = events2.line.pipe((0, import_rxjs6.map)(this.getCurrentValue.bind(this)));
     const validation = this.handleSubmitEvents(submit);
     validation.success.forEach(this.onEnd.bind(this));
     validation.error.forEach(this.onError.bind(this));
-    events.normalizedUpKey.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onUpKey.bind(this));
-    events.normalizedDownKey.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onDownKey.bind(this));
-    events.keypress.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
+    events2.normalizedUpKey.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onUpKey.bind(this));
+    events2.normalizedDownKey.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onDownKey.bind(this));
+    events2.keypress.pipe((0, import_rxjs6.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
     this.render();
     return this;
   }
@@ -673145,13 +673145,13 @@ var ExpandPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
+    const events2 = observe(this.rl);
     const validation = this.handleSubmitEvents(
-      events.line.pipe((0, import_rxjs7.map)(this.getCurrentValue.bind(this)))
+      events2.line.pipe((0, import_rxjs7.map)(this.getCurrentValue.bind(this)))
     );
     validation.success.forEach(this.onSubmit.bind(this));
     validation.error.forEach(this.onError.bind(this));
-    this.keypressObs = events.keypress.pipe((0, import_rxjs7.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
+    this.keypressObs = events2.keypress.pipe((0, import_rxjs7.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
     this.render();
     return this;
   }
@@ -673338,18 +673338,18 @@ var CheckboxPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
+    const events2 = observe(this.rl);
     const validation = this.handleSubmitEvents(
-      events.line.pipe((0, import_rxjs8.map)(this.getCurrentValue.bind(this)))
+      events2.line.pipe((0, import_rxjs8.map)(this.getCurrentValue.bind(this)))
     );
     validation.success.forEach(this.onEnd.bind(this));
     validation.error.forEach(this.onError.bind(this));
-    events.normalizedUpKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onUpKey.bind(this));
-    events.normalizedDownKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onDownKey.bind(this));
-    events.numberKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onNumberKey.bind(this));
-    events.spaceKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onSpaceKey.bind(this));
-    events.aKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onAllKey.bind(this));
-    events.iKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onInverseKey.bind(this));
+    events2.normalizedUpKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onUpKey.bind(this));
+    events2.normalizedDownKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onDownKey.bind(this));
+    events2.numberKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onNumberKey.bind(this));
+    events2.spaceKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onSpaceKey.bind(this));
+    events2.aKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onAllKey.bind(this));
+    events2.iKey.pipe((0, import_rxjs8.takeUntil)(validation.success)).forEach(this.onInverseKey.bind(this));
     this.render();
     this.firstRender = false;
     return this;
@@ -673502,12 +673502,12 @@ var PasswordPrompt = class extends Prompt {
    */
   _run(cb) {
     this.done = cb;
-    const events = observe(this.rl);
-    const submit = events.line.pipe((0, import_rxjs9.map)(this.filterInput.bind(this)));
+    const events2 = observe(this.rl);
+    const submit = events2.line.pipe((0, import_rxjs9.map)(this.filterInput.bind(this)));
     const validation = this.handleSubmitEvents(submit);
     validation.success.forEach(this.onEnd.bind(this));
     validation.error.forEach(this.onError.bind(this));
-    events.keypress.pipe((0, import_rxjs9.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
+    events2.keypress.pipe((0, import_rxjs9.takeUntil)(validation.success)).forEach(this.onKeypress.bind(this));
     this.render();
     return this;
   }
@@ -673774,8 +673774,8 @@ var EditorPrompt = class extends Prompt {
   _run(cb) {
     this.done = cb;
     this.editorResult = new import_rxjs10.Subject();
-    const events = observe(this.rl);
-    this.lineSubscription = events.line.subscribe(this.startExternalEditor.bind(this));
+    const events2 = observe(this.rl);
+    this.lineSubscription = events2.line.subscribe(this.startExternalEditor.bind(this));
     const waitUserInput = this.opt.waitUserInput === void 0 ? true : this.opt.waitUserInput;
     const validation = this.handleSubmitEvents(this.editorResult);
     validation.success.forEach(this.onEnd.bind(this));
@@ -730850,7 +730850,7 @@ var DeviceAuthService = class {
    * Honors `slow_down` by widening the interval (RFC 8628 §3.5).
    */
   async pollUntilDone(deviceCode, opts) {
-    const sleep = opts.sleep || defaultSleep;
+    const sleep2 = opts.sleep || defaultSleep;
     let intervalMs = Math.max(1, opts.interval) * 1e3;
     const caps = [Date.now() + opts.expiresIn * 1e3];
     if (opts.timeoutMs != null) caps.push(Date.now() + opts.timeoutMs);
@@ -730880,7 +730880,7 @@ var DeviceAuthService = class {
           "Timed out waiting for device approval. Run `hubdoc login --start` again."
         );
       }
-      await sleep(intervalMs);
+      await sleep2(intervalMs);
     }
   }
 };
@@ -734683,6 +734683,136 @@ async function handleAgentsShow(id, opts) {
   }
 }
 
+// apps/cli/cli/handlers/event-handlers.ts
+var BASE5 = "/api/v1/events";
+var EVENT_COLUMNS = [
+  { header: "Event ID", key: "event_id" },
+  { header: "Type", key: "type", format: (v6) => shortType(v6) },
+  { header: "At", key: "timestamp" }
+];
+var TYPE_ALIASES = {
+  // Projects
+  "project.created": "Projects::Projects::ProjectCreated",
+  "project.updated": "Projects::Projects::ProjectUpdated",
+  "project.started": "Projects::Projects::ProjectStarted",
+  "project.completed": "Projects::Projects::ProjectCompleted",
+  "project.archived": "Projects::Projects::ProjectArchived",
+  "project.deleted": "Projects::Projects::ProjectDeleted",
+  // Sprints
+  "sprint.created": "Projects::Sprints::SprintCreated",
+  "sprint.updated": "Projects::Sprints::SprintUpdated",
+  "sprint.started": "Projects::Sprints::SprintStarted",
+  "sprint.completed": "Projects::Sprints::SprintCompleted",
+  "sprint.deleted": "Projects::Sprints::SprintDeleted",
+  // Tickets
+  "ticket.created": "Projects::Tickets::TicketCreated",
+  "ticket.updated": "Projects::Tickets::TicketUpdated",
+  "ticket.assigned": "Projects::Tickets::TicketAssigned",
+  "ticket.blocked": "Projects::Tickets::TicketBlocked",
+  "ticket.escalated": "Projects::Tickets::TicketEscalated",
+  "ticket.failed": "Projects::Tickets::TicketFailed",
+  "ticket.moved": "Projects::Tickets::TicketMoved",
+  "ticket.status_changed": "Projects::Tickets::TicketStatusChanged",
+  "ticket.deleted": "Projects::Tickets::TicketDeleted",
+  "ticket.comment": "Projects::Tickets::ChannelMessagePosted",
+  "ticket.deliverable": "Projects::Tickets::DeliverableAttached",
+  // Tasks
+  "task.created": "Projects::Tasks::TaskCreated",
+  "task.updated": "Projects::Tasks::TaskUpdated",
+  "task.completed": "Projects::Tasks::TaskCompleted",
+  "task.deleted": "Projects::Tasks::TaskDeleted"
+};
+function expandTypes(raw) {
+  if (raw == null) return void 0;
+  const items = raw.split(",").map((s3) => s3.trim()).filter(Boolean).map((s3) => TYPE_ALIASES[s3] ?? s3);
+  return items.length > 0 ? items.join(",") : void 0;
+}
+function shortType(fq) {
+  if (!fq) return "";
+  const inverted = Object.entries(TYPE_ALIASES).find(([, v6]) => v6 === fq)?.[0];
+  if (inverted) return inverted;
+  return fq.split("::").pop() ?? fq;
+}
+async function fetchEventsPage(ctx, opts) {
+  const params = {};
+  if (opts.project) params.project_id = opts.project;
+  if (opts.ticket) params.ticket_id = opts.ticket;
+  const expanded = expandTypes(opts.type);
+  if (expanded) params.type = expanded;
+  if (opts.since) params.since = opts.since;
+  if (opts.limit) params.limit = Number(opts.limit);
+  const res = await ctx.axios.get(BASE5, { params });
+  const items = Array.isArray(res.data) ? res.data : [];
+  const headers = res.headers ?? {};
+  const nextCursor = headers["x-next-cursor"] ?? headers["X-Next-Cursor"] ?? null;
+  return { items, nextCursor };
+}
+async function handleEventsList(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  try {
+    const { items, nextCursor } = await fetchEventsPage(ctx, opts);
+    if (opts.json) {
+      out.show({ items, next_cursor: nextCursor });
+      return;
+    }
+    out.list(items, EVENT_COLUMNS);
+    if (nextCursor) {
+      out.note(`next_cursor: ${nextCursor} (pass to --since to continue)`);
+    }
+  } catch (err) {
+    out.fail(err);
+  }
+}
+async function handleEventsWatch(opts) {
+  const out = output(opts);
+  const ctx = await buildApiContext(out);
+  const timeoutMs = Math.max(1e3, Number(opts.timeout ?? "60") * 1e3);
+  const intervalMs = Math.max(100, Number(opts.pollIntervalMs ?? "1000"));
+  const startedAt = Date.now();
+  let cursor2 = opts.since;
+  try {
+    while (Date.now() - startedAt < timeoutMs) {
+      const page = await fetchEventsPage(ctx, { ...opts, since: cursor2 });
+      if (page.items.length > 0) {
+        if (opts.json) {
+          out.show({
+            items: page.items,
+            next_cursor: page.nextCursor,
+            waited_ms: Date.now() - startedAt
+          });
+        } else {
+          out.list(page.items, EVENT_COLUMNS);
+          if (page.nextCursor) {
+            out.note(`next_cursor: ${page.nextCursor}`);
+          }
+        }
+        return;
+      }
+      await sleep(intervalMs);
+    }
+  } catch (err) {
+    out.fail(err);
+  }
+  const waited = Date.now() - startedAt;
+  const payload2 = {
+    ok: false,
+    reason: "timeout",
+    waited_ms: waited,
+    since: cursor2 ?? null
+  };
+  if (opts.json) {
+    process.stderr.write(JSON.stringify(payload2, null, 2) + "\n");
+  } else {
+    process.stderr.write(`Timed out after ${waited}ms with no matching event.
+`);
+  }
+  process.exit(2);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // apps/cli/cli/handlers/task-handlers.ts
 var tasksBase = (pid, tid) => `/api/v1/projects/${encodeURIComponent(pid)}/tickets/${encodeURIComponent(tid)}/tasks`;
 var TASK_COLUMNS = [
@@ -734857,7 +734987,7 @@ async function handleTasksReorder(opts) {
 // apps/cli/cli.ts
 var getVersion = () => {
   try {
-    if (true) return "1.11.0";
+    if (true) return "1.12.0";
   } catch {
   }
   for (const candidate of [
@@ -735139,13 +735269,13 @@ members.command("remove <membership-id>").description("Remove a membership by it
   await handleGroupMembersRemove(id, withGlobals(options));
 });
 var permissions = program2.command("permissions").description("Manage ACL: grant / list / revoke permissions on documents resources");
-permissions.command("ls").description("List permissions on a specific resource").requiredOption("--on <resource-id>", "Permissible resource UUID").option("--on-type <type>", "workspace | folder | file | share_link", "workspace").option("--to <actor-id>", "Filter by actor id (client-side)").option("--to-type <type>", "Filter by actor type (user | group | contact)").option("--level <level>", "Filter by level (read|write|admin|owner|forbidden)").action(async (options) => {
+permissions.command("ls").description("List permissions on a specific resource").requiredOption("--on <resource-id>", "Permissible resource UUID").option("--on-type <type>", "workspace | folder | file | share_link | project", "workspace").option("--to <actor-id>", "Filter by actor id (client-side)").option("--to-type <type>", "Filter by actor type (user | group | contact)").option("--level <level>", "Filter by level (read|write|admin|owner|forbidden)").action(async (options) => {
   await handlePermissionsList(withGlobals(options));
 });
 permissions.command("show <id>").description("Show a permission by id").action(async (id, options) => {
   await handlePermissionsShow(id, withGlobals(options));
 });
-permissions.command("grant").description("Grant a permission on a resource to a user or group").requiredOption("--to <actor-id>", "Actor UUID (user/group/contact)").requiredOption("--to-type <type>", "user | group | contact").requiredOption("--on <resource-id>", "Permissible resource UUID").requiredOption("--on-type <type>", "workspace | folder | file | share_link").requiredOption("--level <level>", "read | write | admin | owner | forbidden").option("--temporary", "Mark as temporary (auto-expiring per server policy)").action(async (options) => {
+permissions.command("grant").description("Grant a permission on a resource to a user or group").requiredOption("--to <actor-id>", "Actor UUID (user/group/contact)").requiredOption("--to-type <type>", "user | group | contact").requiredOption("--on <resource-id>", "Permissible resource UUID").requiredOption("--on-type <type>", "workspace | folder | file | share_link | project").requiredOption("--level <level>", "read | write | admin | owner | forbidden").option("--temporary", "Mark as temporary (auto-expiring per server policy)").action(async (options) => {
   await handlePermissionsGrant(withGlobals(options));
 });
 permissions.command("revoke <id>").description("Revoke a permission by id").option("--yes", "Skip the interactive confirmation").action(async (id, options) => {
@@ -735267,6 +735397,13 @@ agents.command("ls").alias("list").description("List agents").option("--active",
 agents.command("show <id>").description("Show an agent").action(async (id, options) => {
   await handleAgentsShow(id, withGlobals(options));
 });
+var events = program2.command("events").description("Read the Rails Event Store stream (corex#593)");
+events.command("ls").alias("list").description("One-shot cursor-paginated read of the event stream").option("--project <id>", "Filter to events touching a specific project").option("--ticket <id>", "Filter to events on a specific ticket").option("--type <a,b,c>", "Comma-separated event types (aliases like ticket.status_changed OR full RES class names)").option("--since <cursor>", "Read events strictly after this event_id").option("--limit <n>", "Max events (default 100, server-side max 1000)").action(async (options) => {
+  await handleEventsList(withGlobals(options));
+});
+events.command("watch").description("Block until a matching event arrives or the timeout expires (client-side long-poll)").option("--project <id>", "Filter to events touching a specific project").option("--ticket <id>", "Filter to events on a specific ticket").option("--type <a,b,c>", "Comma-separated event types (aliases or full class names)").option("--since <cursor>", "Start watching from this event_id (exclusive)").option("--limit <n>", "Max events per poll (default 100)").option("--timeout <s>", "Give up after this many seconds (default 60, exit 2 on timeout)").option("--poll-interval-ms <ms>", "Delay between polls (default 1000, min 100)").action(async (options) => {
+  await handleEventsWatch(withGlobals(options));
+});
 program2.parse();
 /*! Bundled license information:
 

package/docs/llm-usage.md

@@ -408,6 +408,48 @@ 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`.
 
+### 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.12.0",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {