@allocator-one/harness-cli 1.15.0 → 1.15.1

package/README.md

@@ -63,7 +63,10 @@ Only the presentation depends on the name you typed:
   `harness mcp` under `harness`. The tools are the same.
 
 Messages, exit codes and `--json` output are the same under both names, so
-a script written for `harness` works with `operator` unchanged. The CLI
+a script written for `harness` works with `operator` unchanged. The
+exceptions are the version label and the hints that tell you what to
+type, such as `operator login`: they name the command you typed, because
+someone who installed only `@allocator-one/operator` has no `harness`. The CLI
 tells the names apart by the command path it was started with. Launchers
 that start it by its file path instead, such as npm's Windows shims, pnpm,
 Volta and Yarn PnP, hide that path. In that case the CLI goes by the
@@ -84,8 +87,29 @@ worktree, and agent slot on the machine.
 - `harness logout`: revokes the stored login on the server and deletes it
   locally.
 - `harness whoami`: shows the resolved host and where the credential came
-  from. With an outside expert's `pxc_…` credential it also names the
-  expert's role and plan (see [Outside experts](#outside-experts)).
+  from. For a login it also shows the kind of credential, the user, the
+  organization and when it expires, as `GET /api/v1/session` describes it.
+  On a server without that route, or with an `aone_…` API token, those
+  fields are `null` under `--json`. With an outside expert's `pxc_…`
+  credential it names the expert's role and plan instead (see
+  [Outside experts](#outside-experts)).
+
+A login gets one of two kinds of credential. The server picks the kind from
+your standing in the organization you choose:
+
+- `harness-cli` is the full credential that Harness staff get.
+- `operator-cli` is the Operator-only credential that any other admin or
+  member Operator serves gets. It reaches the Operator commands, `whoami`
+  and `logout`, and the server refuses everything else (issues, plans,
+  gates) with 403.
+
+`login` says after signing in which kind you got (`kind` under `--json`).
+If the new credential fails verification, nothing is stored. A credential
+the browser login just minted is then revoked, in one best-effort attempt,
+so a 30-day credential isn't left behind. A token you pasted is never
+revoked, whatever the failure, since you may be using it elsewhere.
+Holders keep their kind even after gaining staff standing: they log in again
+to get the full credential.
 
 `operator login`, `operator logout` and `operator whoami` are the same
 commands and use the same stored login.
@@ -160,7 +184,12 @@ design, acceptance criteria, notes, and comments (up to 20, cached locally)
 and prints their paths. Screenshots are often the reproduction, so read
 them. `--no-images` skips the downloads. If a download fails, a stderr
 notice says so and the command still succeeds. `harness comments <id>`
-prints the full, untruncated comment thread with comment ids. The
+prints the full, untruncated comment thread with comment ids, oldest first.
+It requests up to 200 comments per page and follows the oldest comment id
+until the server reports `has_more=false`. `--json` and the MCP
+`comment_list` tool return the same complete array of full comment objects.
+Missing pagination metadata, repeated comment ids, or an older-page failure
+produce an error without presenting a partial thread as complete. The
 `Blocked:` line names a cancelled or archived blocker as such
 (`yes, by CLI-3 (cancelled), CLI-4 (archived), CLI-5`). When the issue has
 wait conditions, `Waiting:` says how many still hold it, and a
@@ -457,8 +486,11 @@ gate.
 you: it freezes the next revision and lets ready steps run.
 `--collaborator <id-or-email>` (repeatable) adds people to the plan room
 where its Operator steps run, and `--retry-budget` and
-`--spend-budget-cents` set the budgets. `harness plan hold <plan-id>`
-pauses every step until the plan is released again.
+`--spend-budget-cents` set the budgets. Each Operator step runs as a job
+(`harness jobs` names its plan step), and the changes a job proposes need a
+person's approval in the app, at the job's approval link. The CLI never
+approves. `harness plan hold <plan-id>` pauses every step until the plan is
+released again.
 
 **Gates.** `harness gate satisfy <issue> <gate>` ticks a gate and
 `harness gate unsatisfy <issue> <gate>` unticks it. `<gate>` is the gate's
@@ -469,10 +501,12 @@ refuses and lists each one's id, key, and label instead of choosing. Pass
 the condition id of the one you mean. Only when nothing matches exactly
 does a label or key match ignoring case, and that too is refused when more
 than one gate matches. Ticking a gate requires staff standing in the
-organization or a place in its plan's room. Only the owner can tick an
-owned gate, and only its owner or Harness staff can untick it. Anyone else
-gets an error that names the gate's owner as of the refusal, which the
-server sends with it, and exits `1`:
+organization or a place in its plan's room. The server refuses an
+Operator-only login (`operator-cli`) here, even for a person in the plan's
+room: it reaches only the Operator commands, `whoami` and `logout`. Only
+the owner can tick an owned gate, and only its owner or Harness staff can
+untick it. Anyone else gets an error that names the gate's owner as of
+the refusal, which the server sends with it, and exits `1`:
 
 ```text
 harness: Cannot satisfy gate "Compliance sign-off" on IO-121: only its owner, Compliance officer (role:compliance_officer), can tick it (HTTP 403)
@@ -979,7 +1013,7 @@ The server exposes 72 tools:
 | People | `member_list`, `member_add`, `member_set_role`, `user_list` |
 | Plans and gates | `plan_create`, `plan_show`, `plan_edit`, `plan_release`, `plan_hold`, `gate_set`, `condition_list` |
 | Outside experts | `assignment_list` |
-| Operator jobs | `jobs_list`, `job_show`, `job_changes`, `job_steer`, `job_cancel`, `job_pause` |
+| Operator jobs | `jobs_list`, `job_show`, `job_changes`, `job_start`, `job_steer`, `job_cancel`, `job_pause` |
 | Continue and procedures | `job_continue`, `procedure_save`, `procedure_show`, `procedure_run` |
 | Operator's catalog | `tools_search` (without `query` it browses the index; `domain`, `cursor`, `all`), `skills_list` |
 | Other | `stats`, `upload` |
@@ -1021,6 +1055,14 @@ Some tools behave differently from their commands:
   `cancelled`, or `waiting_on` is set. A person has to act exactly when
   `waiting_on` is set; a job paused without it resumes by itself. Neither
   tool approves anything; give a person the `approval_url`.
+- `job_start` is the CLI's `run`: `outcome`, and optionally `budget` (US
+  dollars; only the organization's admins) and `skill`; there is no `team`.
+  It returns `job_id`, `state`, `workbench_url` and, when a change set
+  waits, `approval_url`, and never approves: give a person the link. Each
+  call starts another job, so it is never retried; after an "Outcome
+  unknown" error look with `jobs_list` (`mine`) before calling again. It
+  carries `idempotentHint: false` and `destructiveHint: false`. The endpoint
+  needs a server that has the Operator start-job API.
 - `job_steer`, `job_cancel` and `job_pause` return the job as `job_show`
   does. None is idempotent, so none is retried: after an error that leaves
   the outcome unknown, read the job with `job_show` before calling one

package/dist/chunk-FQWV5MIC.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+// src/version.ts
+import { readFileSync } from "fs";
+var pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+var CLI_VERSION = pkg.version;
+var CLI_PACKAGE = pkg.name;
+
+// src/invocation.ts
+import { basename } from "path";
+var OPERATOR_PACKAGE = "@allocator-one/operator";
+function invokedName(argv1 = process.argv[1], packageName = CLI_PACKAGE) {
+  const typed = basename(argv1 ?? "").replace(/\.[cm]?js$/i, "").toLowerCase();
+  if (typed === "operator" || typed === "harness") return typed;
+  return packageName === OPERATOR_PACKAGE ? "operator" : "harness";
+}
+function named(text, name = invokedName()) {
+  if (name === "harness") return text;
+  return text.replace(/^harness: /gm, `${name}: `).replace(/(?<![\w@/.-])harness (?=[a-z])(?!disagree)/g, `${name} `).replaceAll("@allocator-one/harness-cli", OPERATOR_PACKAGE);
+}
+var OPERATOR_COMMANDS = [
+  "run",
+  "jobs",
+  "job",
+  "watch",
+  "steer",
+  "cancel",
+  "pause",
+  "continue",
+  "procedure",
+  "plan",
+  "gate",
+  "conditions",
+  "assignments",
+  "tools",
+  "tool",
+  "skills",
+  "mcp"
+];
+var GENERAL_COMMANDS = [
+  "login",
+  "logout",
+  "whoami",
+  "version",
+  "keys"
+];
+var OPERATOR_HEADING = "Operator:";
+var ISSUES_HEADING = "Issues:";
+var GENERAL_HEADING = "General:";
+function layoutOperatorHelp(program) {
+  const rank = (name) => {
+    const operator = OPERATOR_COMMANDS.indexOf(name);
+    if (operator !== -1) return operator;
+    return GENERAL_COMMANDS.includes(name) ? 2 * OPERATOR_COMMANDS.length : OPERATOR_COMMANDS.length;
+  };
+  const heading = (name) => OPERATOR_COMMANDS.includes(name) ? OPERATOR_HEADING : GENERAL_COMMANDS.includes(name) ? GENERAL_HEADING : ISSUES_HEADING;
+  for (const command of program.commands) command.helpGroup(heading(command.name()));
+  program.commands.sort(
+    (left, right) => rank(left.name()) - rank(right.name())
+  );
+  program.commandsGroup(GENERAL_HEADING).helpCommand(true);
+}
+
+export {
+  CLI_VERSION,
+  CLI_PACKAGE,
+  OPERATOR_PACKAGE,
+  invokedName,
+  named,
+  layoutOperatorHelp
+};