@allocator-one/harness-cli 1.9.0 → 1.10.0

package/README.md

@@ -52,7 +52,7 @@ the browser login attributes writes to the real user.
 ## For agents
 
 `harness mcp` runs a stdio MCP server exposing every operation as a typed
-tool — issue_list, issue_show, issue_create, issue_update, issue_claim,
+tool — issue_list, issue_show, activity_list, issue_create, issue_update, issue_claim,
 issue_close, issue_comment, issue_comment_edit, issue_comment_delete,
 relation_list/create/update/delete, relation_add/rm (blocking shorthand),
 link_list/add/update/rm,
@@ -71,6 +71,12 @@ Example tool call: `issue_list` with `{"ready": true, "team": "ALL"}`
 returns the ready queue as JSON; `issue_claim` with `{"id": "IO-123"}`
 claims atomically (a conflict means someone else holds it).
 
+Read the same mixed timeline shown in an issue's Activity section with
+`harness activity IO-123`. It returns the newest 20 entries and points out
+when older entries exist; pass `--all` to follow the opaque cursors through
+the full history. `activity_list` exposes the same `id`, `limit`, and `all`
+inputs to MCP clients.
+
 Typed issue relations are available without losing the concise blocking
 workflow. `harness dep add|rm` and the `relation_add`/`relation_rm` MCP tools
 remain the blocker-first shorthand; the full surface is:
@@ -181,10 +187,15 @@ CI regenerates the types and fails on drift.
 
 ## Release
 
-Tag a version and push — the Release workflow builds and publishes to npm:
+First bump `package.json` and `package-lock.json` through a pull request. After
+that PR is squash-merged, fetch `main` and tag the merge commit — never the
+pre-merge branch tip. Pushing the tag starts the Release workflow, which builds,
+tests, and publishes to npm:
 
 ```sh
-git tag v1.0.0 && git push origin v1.0.0
+git fetch origin main
+git tag -a vX.Y.Z MERGE_COMMIT_SHA -m "Release vX.Y.Z"
+git push origin vX.Y.Z
 ```
 
 Publishing requires the `NPM_TOKEN` actions secret (an automation token for

package/dist/{chunk-NQVQNKMC.js → chunk-KKAAKRKF.js}

@@ -166,11 +166,16 @@ var Client = class {
       throw new TransportError(transportMessage(error));
     }
     if (text === "") return { data: void 0 };
+    let parsed;
     try {
-      return JSON.parse(text);
+      parsed = JSON.parse(text);
     } catch {
       throw new TransportError(`the API answered with a non-JSON body (HTTP ${response.status})`);
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new TransportError(`the API answered with an invalid JSON envelope (HTTP ${response.status})`);
+    }
+    return parsed;
   }
   async toHttpError(response) {
     let parsed = {};
@@ -255,6 +260,101 @@ ${indent(String(text))}
 `).join("");
   return header + fieldLines + sectionText + relationsSection(issue["relations"]) + childrenSection(issue["children"]) + commentsSection(issue["comments"]) + imagesSection(images);
 }
+function activityEntries(entries) {
+  if (entries.length === 0) return "No activity.\n";
+  return entries.map(activityEntry).join("\n");
+}
+function activityEntry(entry) {
+  switch (entry["kind"]) {
+    case "comment":
+      return activityComment(entry);
+    case "state_event":
+      return activityStateEvent(entry);
+    default:
+      throw new CommandError(`Unknown activity entry kind: ${clean(entry["kind"])}`);
+  }
+}
+function activityComment(entry) {
+  const comment2 = requiredRecord(entry["comment"], "activity comment");
+  const authorValue = comment2["author"];
+  const author = authorValue === null ? "unknown" : optionalLabel(requiredRecord(authorValue, "comment author")["name"], "unknown", "comment author name");
+  const deleted = comment2["deleted"];
+  if (typeof deleted !== "boolean") throw new CommandError("Invalid comment deleted flag.");
+  const body = activityCommentBody(comment2["body"], deleted);
+  const text = cleanMultiline(body).split("\n").map((line) => "  " + line).join("\n");
+  return `[${clean(requiredString(entry["occurred_at"], "activity occurrence time"))}] ${clean(author)} (${clean(requiredString(comment2["id"], "comment id"))}):
+${text}
+`;
+}
+function activityCommentBody(value, deleted) {
+  if (deleted) return "[deleted comment]";
+  if (value === null || value === "") return "[comment has no text]";
+  return requiredString(value, "comment body");
+}
+function activityStateEvent(entry) {
+  const actor = activityActor(requiredRecord(entry["actor"], "activity actor"));
+  const provenance = activityProvenance(requiredRecord(entry["provenance"], "activity provenance"));
+  let description;
+  switch (entry["action"]) {
+    case "created":
+      description = `${actor} created the issue in ${stateName(entry["to_state"], "created to_state")}`;
+      break;
+    case "transition":
+      description = `${actor} moved the issue from ${nullableStateName(entry["from_state"], "transition from_state")} to ${stateName(entry["to_state"], "transition to_state")}`;
+      break;
+    case "milestone":
+      description = `${actor} recorded the ${stateName(entry["to_state"], "milestone to_state")} milestone`;
+      break;
+    default:
+      throw new CommandError(`Unknown activity action: ${clean(entry["action"])}`);
+  }
+  return `[${clean(requiredString(entry["occurred_at"], "activity occurrence time"))}] ${description} \xB7 ${provenance}
+`;
+}
+function activityActor(actor) {
+  switch (actor["kind"]) {
+    case "user":
+      return optionalLabel(actor["name"], "Unknown actor", "activity actor name");
+    case "system":
+      return "System";
+    case "deleted_user":
+      return "Deleted user";
+    case "unknown":
+      return "Unknown actor";
+    default:
+      throw new CommandError(`Unknown activity actor kind: ${clean(actor["kind"])}`);
+  }
+}
+function activityProvenance(provenance) {
+  switch (provenance["kind"]) {
+    case "live":
+    case "import":
+    case "backfill":
+      return String(provenance["kind"]);
+    default:
+      throw new CommandError(`Unknown activity provenance: ${clean(provenance["kind"])}`);
+  }
+}
+function stateName(value, field2) {
+  return optionalLabel(requiredRecord(value, field2)["name"], "Unknown state", `${field2} name`);
+}
+function nullableStateName(value, field2) {
+  return value === null ? "Unknown state" : stateName(value, field2);
+}
+function optionalLabel(value, fallback, field2) {
+  if (value === null || value === "") return fallback;
+  return clean(requiredString(value, field2));
+}
+function requiredRecord(value, field2) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new CommandError(`Invalid ${field2}.`);
+  }
+  return value;
+}
+function requiredString(value, field2) {
+  if (typeof value !== "string" || value === "") throw new CommandError(`Invalid ${field2}.`);
+  return value;
+}
 function stats(data) {
   const teams = data["teams"] ?? [];
   const totals = data["totals"] ?? {};
@@ -594,6 +694,61 @@ async function show(ctx, identifier, opts) {
 `).join("");
   return notice === "" ? { json: json2, human } : { json: json2, human, notice };
 }
+var ACTIVITY_MAX_LIMIT = 100;
+async function activity(ctx, identifier, opts) {
+  requireIdentifiers([identifier]);
+  let page = await activityPage(ctx, identifier, opts.limit);
+  let entries = page.entries;
+  if (opts.all === true) {
+    const pages = [page.entries];
+    const seenCursors = /* @__PURE__ */ new Set();
+    while (page.hasMore) {
+      const cursor = page.nextCursor;
+      if (seenCursors.has(cursor)) {
+        throw new CommandError("Activity response repeated a cursor.");
+      }
+      seenCursors.add(cursor);
+      page = await activityPage(ctx, identifier, opts.limit, cursor);
+      pages.push(page.entries);
+    }
+    entries = pages.reverse().flat();
+  }
+  const notice = opts.all !== true && page.hasMore ? `harness: showing the newest ${entries.length} activity entries \u2014 pass --all for older activity.
+` : void 0;
+  return { json: entries, human: activityEntries(entries), notice };
+}
+async function activityPage(ctx, identifier, limit, before) {
+  const body = await ctx.client.get(`/api/v1/issues/${identifier}/activity`, { limit, before });
+  if (!Array.isArray(body.data)) throw new CommandError("Activity response data is not an array.");
+  if (body.data.some((entry) => typeof entry !== "object" || entry === null || Array.isArray(entry))) {
+    throw new CommandError("Activity response contains a non-object entry.");
+  }
+  const meta = body.meta;
+  if (typeof meta !== "object" || meta === null) {
+    throw new CommandError("Activity response has no pagination metadata.");
+  }
+  const hasMore = meta.has_more;
+  const nextCursor = meta.next_cursor;
+  if (typeof hasMore !== "boolean") {
+    throw new CommandError("Activity response has an invalid has_more value.");
+  }
+  if (nextCursor !== null && typeof nextCursor !== "string") {
+    throw new CommandError("Activity response has an invalid next_cursor value.");
+  }
+  if (hasMore) {
+    if (nextCursor === null || nextCursor === "") {
+      throw new CommandError("Activity response says older entries exist but provides no cursor.");
+    }
+    if (body.data.length === 0) {
+      throw new CommandError("Activity response says older entries exist but contains no entries.");
+    }
+    return { entries: body.data, hasMore: true, nextCursor };
+  }
+  if (nextCursor !== null) {
+    throw new CommandError("Activity response provides a cursor when no older entries exist.");
+  }
+  return { entries: body.data, hasMore: false, nextCursor: null };
+}
 async function stats2(ctx) {
   const body = await ctx.client.get("/api/v1/stats");
   return { json: body.data, human: stats(body.data) };
@@ -992,19 +1147,19 @@ async function claimFirst(ctx, issues) {
   }
   throw new CommandError("No claimable ready issues.");
 }
-async function setState(ctx, identifier, stateName) {
+async function setState(ctx, identifier, stateName2) {
   const showBody = await ctx.client.get(`/api/v1/issues/${identifier}`);
   const teamKey = str2((showBody.data["team"] ?? {})["key"]);
   const statesBody = await ctx.client.get(
     `/api/v1/teams/${teamKey}/workflow_states`
   );
-  const wanted = stateName.toLowerCase();
+  const wanted = stateName2.toLowerCase();
   const state = statesBody.data.find(
     (candidate) => str2(candidate["name"]).toLowerCase() === wanted || str2(candidate["type"]) === wanted
   );
   if (state === void 0) {
     const names = statesBody.data.map((candidate) => str2(candidate["name"])).join(", ");
-    throw new CommandError(`No workflow state matches "${stateName}". States: ${names}`);
+    throw new CommandError(`No workflow state matches "${stateName2}". States: ${names}`);
   }
   const body = await ctx.client.put(`/api/v1/issues/${identifier}/state`, { state_id: state["id"] });
   return body.data;
@@ -1951,6 +2106,8 @@ export {
   list,
   search,
   show,
+  ACTIVITY_MAX_LIMIT,
+  activity,
   stats2 as stats,
   prime,
   version,

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  ACTIVITY_MAX_LIMIT,
   CLI_VERSION,
   Client,
   CommandError,
@@ -11,6 +12,7 @@ import {
   TransportError,
   UpgradeRequiredError,
   UsageError,
+  activity,
   archive,
   attachImage,
   blocked,
@@ -80,7 +82,7 @@ import {
   version,
   workflowStates,
   writeCredentials
-} from "./chunk-NQVQNKMC.js";
+} from "./chunk-KKAAKRKF.js";
 
 // src/cli.ts
 import { createInterface as createInterface2 } from "readline";
@@ -1238,6 +1240,15 @@ function integer(value) {
     throw new InvalidArgumentError("expected a non-negative integer");
   return Number.parseInt(value, 10);
 }
+function activityLimit(value) {
+  const limit = integer(value);
+  if (limit < 1 || limit > ACTIVITY_MAX_LIMIT) {
+    throw new InvalidArgumentError(
+      `expected an integer from 1 to ${ACTIVITY_MAX_LIMIT}`
+    );
+  }
+  return limit;
+}
 function collect(value, previous) {
   return [...previous, value];
 }
@@ -1424,6 +1435,17 @@ program.command("show").description("full issue detail; downloads attached image
     });
   }
 );
+program.command("activity").description("mixed issue activity: comments, creation, and state changes").argument("[id]").option(
+  "--limit <n>",
+  `entries per page (default 20, max ${ACTIVITY_MAX_LIMIT})`,
+  activityLimit
+).option("--all", "read all older activity").option("--json", "emit JSON").action(async (id, opts) => {
+  await withConfig(opts.json === true, false, (ctx) => {
+    if (id === void 0) throw new UsageError("usage: harness activity <id>");
+    requireIdentifiers2([id]);
+    return activity(ctx, id, opts);
+  });
+});
 program.command("stats").description("per-team and total counts").option("--json", "emit JSON").action(async (opts) => {
   await withConfig(opts.json === true, false, (ctx) => stats(ctx));
 });
@@ -1889,7 +1911,7 @@ program.command("upload").description("upload a file; prints markdown to referen
   });
 });
 program.command("mcp").description("run the MCP server over stdio (for agents)").action(async () => {
-  const { startMcpServer } = await import("./server-FWNT3HMX.js");
+  const { startMcpServer } = await import("./server-QVYSED3Z.js");
   await startMcpServer();
 });
 program.command("login").description("sign in via the browser (infra.one session)").option("--url <url>", "host to sign in to").option("--no-browser", "print the URL and prompt for a pasted token instead").option(

package/dist/{server-FWNT3HMX.js → server-QVYSED3Z.js}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  ACTIVITY_MAX_LIMIT,
   CLI_VERSION,
   Client,
   HttpError,
@@ -7,6 +8,7 @@ import {
   RELATION_UPDATE_TYPES,
   TransportError,
   UsageError,
+  activity,
   archive,
   blocked,
   close,
@@ -59,7 +61,7 @@ import {
   upload,
   userList,
   workflowStates
-} from "./chunk-NQVQNKMC.js";
+} from "./chunk-KKAAKRKF.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -161,6 +163,17 @@ var TOOLS = [
     shape: { id: identifier, images: z.boolean().optional() },
     handler: (ctx, args) => show(ctx, args["id"], { images: args["images"] === true })
   },
+  {
+    name: "activity_list",
+    description: "Mixed issue activity: comments, creation, and state changes. Returns the newest page unless all=true.",
+    readOnly: true,
+    shape: {
+      id: identifier,
+      limit: z.number().int().min(1).max(ACTIVITY_MAX_LIMIT).optional().describe(`entries per page (default 20, max ${ACTIVITY_MAX_LIMIT})`),
+      all: z.boolean().optional().describe("follow cursors through all older activity")
+    },
+    handler: (ctx, args) => activity(ctx, args["id"], args)
+  },
   {
     name: "issue_create",
     description: "Create an issue. type becomes a type/ label.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",

package/spec/openapi.json

@@ -973,6 +973,9 @@
                     "type": "string"
                   }
                 },
+                "required": [
+                  "url"
+                ],
                 "type": "object"
               }
             }
@@ -1280,6 +1283,361 @@
         "tags": []
       }
     },
+    "/api/v1/issues/{identifier}/activity": {
+      "get": {
+        "callbacks": {},
+        "deprecated": false,
+        "description": "Requires the `harness:read` scope. The newest mixed page of comments and issue-state events, returned oldest-first. `has_more` means older entries exist. Pass the opaque `next_cursor` back as `before`; cursors are bound to the issue and viewer and expire after 24 hours.",
+        "parameters": [
+          {
+            "description": "Issue identifier, e.g. ALL-4901 or CLI-12 (issues minted before team-prefixed numbering carry IO-)",
+            "in": "path",
+            "name": "identifier",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "description": "Opaque cursor returned as `meta.next_cursor` by the preceding newer page",
+            "in": "query",
+            "name": "before",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "description": "Entries per page (default 20, max 100)",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "data": {
+                      "items": {
+                        "oneOf": [
+                          {
+                            "additionalProperties": false,
+                            "properties": {
+                              "comment": {
+                                "properties": {
+                                  "author": {
+                                    "nullable": true,
+                                    "properties": {
+                                      "email": {
+                                        "nullable": true,
+                                        "type": "string"
+                                      },
+                                      "id": {
+                                        "format": "uuid",
+                                        "nullable": true,
+                                        "type": "string"
+                                      },
+                                      "name": {
+                                        "nullable": true,
+                                        "type": "string"
+                                      }
+                                    },
+                                    "required": [
+                                      "id",
+                                      "name",
+                                      "email"
+                                    ],
+                                    "type": "object"
+                                  },
+                                  "body": {
+                                    "description": "Comment text; null may mean a deleted tombstone or no stored text. Use `deleted` to identify tombstones",
+                                    "nullable": true,
+                                    "type": "string"
+                                  },
+                                  "deleted": {
+                                    "description": "Whether the comment is a deleted tombstone",
+                                    "type": "boolean"
+                                  },
+                                  "id": {
+                                    "format": "uuid",
+                                    "type": "string"
+                                  },
+                                  "inserted_at": {
+                                    "format": "date-time",
+                                    "type": "string"
+                                  },
+                                  "mentions": {
+                                    "items": {
+                                      "properties": {
+                                        "email": {
+                                          "nullable": true,
+                                          "type": "string"
+                                        },
+                                        "name": {
+                                          "nullable": true,
+                                          "type": "string"
+                                        },
+                                        "user_id": {
+                                          "format": "uuid",
+                                          "nullable": true,
+                                          "type": "string"
+                                        }
+                                      },
+                                      "required": [
+                                        "user_id",
+                                        "name",
+                                        "email"
+                                      ],
+                                      "type": "object"
+                                    },
+                                    "type": "array"
+                                  },
+                                  "reactions": {
+                                    "items": {
+                                      "properties": {
+                                        "count": {
+                                          "type": "integer"
+                                        },
+                                        "emoji": {
+                                          "type": "string"
+                                        },
+                                        "reacted_by_current_actor": {
+                                          "type": "boolean"
+                                        }
+                                      },
+                                      "required": [
+                                        "emoji",
+                                        "count",
+                                        "reacted_by_current_actor"
+                                      ],
+                                      "type": "object"
+                                    },
+                                    "type": "array"
+                                  },
+                                  "updated_at": {
+                                    "format": "date-time",
+                                    "type": "string"
+                                  }
+                                },
+                                "required": [
+                                  "id",
+                                  "body",
+                                  "deleted",
+                                  "author",
+                                  "mentions",
+                                  "reactions",
+                                  "inserted_at",
+                                  "updated_at"
+                                ],
+                                "type": "object"
+                              },
+                              "id": {
+                                "type": "string"
+                              },
+                              "kind": {
+                                "enum": [
+                                  "comment"
+                                ],
+                                "type": "string"
+                              },
+                              "occurred_at": {
+                                "format": "date-time",
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "id",
+                              "kind",
+                              "occurred_at",
+                              "comment"
+                            ],
+                            "type": "object"
+                          },
+                          {
+                            "additionalProperties": false,
+                            "properties": {
+                              "action": {
+                                "enum": [
+                                  "created",
+                                  "milestone",
+                                  "transition"
+                                ],
+                                "type": "string"
+                              },
+                              "actor": {
+                                "properties": {
+                                  "kind": {
+                                    "enum": [
+                                      "system",
+                                      "user",
+                                      "deleted_user",
+                                      "unknown"
+                                    ],
+                                    "type": "string"
+                                  },
+                                  "name": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  }
+                                },
+                                "required": [
+                                  "kind",
+                                  "name"
+                                ],
+                                "type": "object"
+                              },
+                              "from_state": {
+                                "nullable": true,
+                                "properties": {
+                                  "key": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  },
+                                  "name": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  },
+                                  "type": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  }
+                                },
+                                "required": [
+                                  "key",
+                                  "name",
+                                  "type"
+                                ],
+                                "type": "object"
+                              },
+                              "id": {
+                                "type": "string"
+                              },
+                              "kind": {
+                                "enum": [
+                                  "state_event"
+                                ],
+                                "type": "string"
+                              },
+                              "occurred_at": {
+                                "format": "date-time",
+                                "type": "string"
+                              },
+                              "provenance": {
+                                "properties": {
+                                  "kind": {
+                                    "enum": [
+                                      "live",
+                                      "import",
+                                      "backfill"
+                                    ],
+                                    "type": "string"
+                                  },
+                                  "witnessed": {
+                                    "type": "boolean"
+                                  }
+                                },
+                                "required": [
+                                  "kind",
+                                  "witnessed"
+                                ],
+                                "type": "object"
+                              },
+                              "to_state": {
+                                "properties": {
+                                  "key": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  },
+                                  "name": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  },
+                                  "type": {
+                                    "nullable": true,
+                                    "type": "string"
+                                  }
+                                },
+                                "required": [
+                                  "key",
+                                  "name",
+                                  "type"
+                                ],
+                                "type": "object"
+                              }
+                            },
+                            "required": [
+                              "id",
+                              "kind",
+                              "occurred_at",
+                              "action",
+                              "actor",
+                              "provenance",
+                              "from_state",
+                              "to_state"
+                            ],
+                            "type": "object"
+                          }
+                        ]
+                      },
+                      "type": "array"
+                    },
+                    "meta": {
+                      "properties": {
+                        "has_more": {
+                          "description": "Whether older entries exist",
+                          "type": "boolean"
+                        },
+                        "next_cursor": {
+                          "description": "Opaque cursor to pass as `before`; null when no older entries exist",
+                          "nullable": true,
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "has_more",
+                        "next_cursor"
+                      ],
+                      "type": "object"
+                    }
+                  },
+                  "required": [
+                    "data",
+                    "meta"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "400": {
+            "description": "Invalid input. Error code is `invalid_cursor` for an invalid or expired cursor, or `bad_request` for a malformed `before` value or invalid limit."
+          },
+          "401": {
+            "description": "Missing or invalid token"
+          },
+          "403": {
+            "description": "Token not permitted (org-scoped, non-admin, or missing scope)"
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "422": {
+            "description": "Validation error"
+          }
+        },
+        "summary": "List issue activity",
+        "tags": []
+      }
+    },
     "/api/v1/users": {
       "get": {
         "callbacks": {},
@@ -2479,9 +2837,12 @@
                           "type": "object"
                         },
                         "body": {
+                          "description": "Comment text; null may mean a deleted tombstone or no stored text. Use `deleted` to identify tombstones",
+                          "nullable": true,
                           "type": "string"
                         },
                         "deleted": {
+                          "description": "Whether the comment is a deleted tombstone",
                           "type": "boolean"
                         },
                         "id": {