@motir/cli 0.1.0 → 0.1.1

package/README.md

@@ -43,9 +43,46 @@ pnpm --filter @motir/cli build      # produces dist/index.js (the `motir` binary
 node packages/cli/dist/index.js --help
 ```
 
-## Commands (this subtask)
+## Authenticate
 
 ```sh
+motir login
+```
+
+`motir login` is a **device grant**: it prints a short code and a URL, opens
+Motir in your browser, and waits for you to approve it there. Codes last 15
+minutes and nothing is written to disk until you approve. It is **headless by
+construction** — the code and URL are printed whether or not a browser opens, so
+an SSH session or a container uses the same command; `--no-browser` skips the
+launch attempt outright.
+
+The approval mints a CLI-scoped PAT: scopes `read`, `work_items:write`,
+`integration` (fixed — the grant can neither widen nor narrow them), 90-day
+expiry, labelled `CLI · <hostname>`. It lands in `~/.config/motir/config.json`,
+`chmod 600`, keyed by server URL.
+
+There are three credential tiers, and `motir login` is the middle one:
+
+| Tier                       | How                                | For                             |
+| -------------------------- | ---------------------------------- | ------------------------------- |
+| `MOTIR_TOKEN`              | export it — no login step, no file | CI, containers, read-only boxes |
+| `motir login`              | browser approval                   | a person at a terminal          |
+| `motir auth login --token` | paste a PAT you already hold       | scripts, older servers          |
+
+`MOTIR_TOKEN` is honoured by **every** command (paired with `MOTIR_SERVER` when
+there is no `.motir.json` to walk up to) and outranks a stored credential.
+
+**Disconnecting** is two different things: `motir logout` forgets the local copy
+on this machine, while **revoking the token in Settings → Account → API tokens**
+is the server-side kill switch. Full guide: [`docs/cli.md` §
+Authenticate](../../docs/cli.md#authenticate).
+
+## Setup commands
+
+```sh
+motir login        [--server <url>] [--no-browser]    # connect this terminal
+motir logout       [--server <url>]                   # forget the local credential
+
 motir auth login   [--server <url>] [--token <pat>]   # validate + store a PAT
 motir auth status  [--server <url>]                   # server, token prefix, owning user
 motir auth logout  [--server <url>]                   # forget the stored token
@@ -67,10 +104,19 @@ motir ready   [--kinds <list>] [--assignee <id|me|unassigned>] [--json]
 motir status  [--json]                                # ready / in-flight + active sprint
 motir sprints [--state <planned|active|complete>] [--json]
 motir sprint  [ref] [--kinds <list>] [--json]         # defaults to the ACTIVE sprint
-motir show    <key> [--json]                          # one item, in full
+motir show    <key> [--activity|--comments] [--json]  # one item, in full
 motir open    <key> [--print]                         # …in the browser
 ```
 
+**`motir show --activity` / `--comments`** add the DISCUSSION the aggregate does
+not carry: `--activity` interleaves comment threads with the change trail,
+`--comments` prints the threads alone. Both are opt-in — the stream is a second
+tool call, so a plain `show` stays one round-trip no matter how loud a card got —
+and comment bodies print **in full**, never excerpted. ONE page is printed and
+never drained: when more remains the footer says how much and points at `motir
+open <key>`; with `--json` the activity page rides along **unaltered** under an
+`activity` key. Passing both flags is refused rather than silently resolved.
+
 `motir sprint`'s **`ref` resolves in order**: omitted → the active sprint; then a
 sprint **id**; then an **exact name**; then a **name prefix** — each
 case-insensitive, first rule yielding exactly one sprint wins. An ambiguous
@@ -154,9 +200,11 @@ the item in the session exclude list so the next `motir next` moves past it;
 > `in_progress` status, so if the store cannot be written the CLI warns once and
 > the run continues rather than aborting.
 
-**Closing out.** After you merge, `motir done <key>`. The default workflow has
-no direct `in_progress → done` edge, so an item dispatched with `--print` (which
-never observed an agent finish) needs `motir done --via in_review <key>`; an
+**Closing out.** After you merge, `motir done <key>`. Since MOTIR-1625 the
+default workflow carries a direct `in_progress → done` edge, so this is one legal
+hop whether or not the item ever reached In Review. `motir done --via in_review
+<key>` still walks it through review explicitly — useful on a custom workflow
+that has no direct edge, or when you want the review hop on the record. An
 illegal flip surfaces the server's own allowed-targets error verbatim. A merged
 **session** PR closes out in bulk with `motir done --session <branch>`.
 

package/dist/index.js

@@ -4,7 +4,7 @@
 import { Command as Command2 } from "commander";
 
 // src/version.ts
-var CLI_VERSION = "0.1.0";
+var CLI_VERSION = "0.1.1";
 
 // src/mcpClient.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -220,6 +220,12 @@ var MotirClient = class {
   whoami() {
     return this.callStructured("whoami");
   }
+  /** The token workspace's browsable projects (MOTIR-1879). Takes no arguments:
+   * the workspace is the one the PAT is bound to. An empty workspace is an
+   * EMPTY LIST, not an error. */
+  listProjects() {
+    return this.callStructured("list_projects");
+  }
   listReady(args) {
     return this.callStructured("list_ready", { ...args });
   }
@@ -229,6 +235,21 @@ var MotirClient = class {
   getWorkItem(key) {
     return this.callStructured("get_work_item", { key });
   }
+  /**
+   * ONE page of a work item's discussion + change trail (MOTIR-1999).
+   *
+   * A SECOND call, made only when `motir show` is asked for it: the default read
+   * stays one round-trip, so a card with two hundred comments never slows down
+   * `show` or the dispatch path that leans on it.
+   *
+   * `cursor` and `order` are pass-through in both directions — the `all` cursor
+   * is an OPAQUE composite carrying both sources' positions, so the CLI must
+   * never construct, parse or merge one. Omitting `order` leaves each view on
+   * its own shipped default rather than the client inventing one.
+   */
+  getWorkItemActivity(args) {
+    return this.callStructured("get_work_item_activity", { ...args });
+  }
   transitionStatus(args) {
     return this.callStructured("transition_status", { ...args });
   }
@@ -351,25 +372,25 @@ function isInteractive() {
 function promptLine(question, defaultValue) {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
   const rl = createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     rl.question(`${question}${suffix}: `, (answer) => {
       rl.close();
       const trimmed = answer.trim();
-      resolve3(trimmed.length > 0 ? trimmed : defaultValue ?? "");
+      resolve4(trimmed.length > 0 ? trimmed : defaultValue ?? "");
     });
   });
 }
 function promptLineOrNull(question) {
   const rl = createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     let answered = false;
     rl.question(`${question}`, (answer) => {
       answered = true;
       rl.close();
-      resolve3(answer);
+      resolve4(answer);
     });
     rl.on("close", () => {
-      if (!answered) resolve3(null);
+      if (!answered) resolve4(null);
     });
   });
 }
@@ -378,11 +399,11 @@ function promptSecret(question) {
   rl._writeToOutput = () => {
   };
   process.stderr.write(`${question}: `);
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     rl.question("", (answer) => {
       rl.close();
       process.stderr.write("\n");
-      resolve3(answer.trim());
+      resolve4(answer.trim());
     });
   });
 }
@@ -533,6 +554,307 @@ async function authLogout(opts) {
   }
 }
 
+// src/commands/login.ts
+import { hostname } from "os";
+import { setTimeout as delay } from "timers/promises";
+
+// src/browser.ts
+import { spawn } from "child_process";
+function launcher(platform) {
+  if (platform === "darwin") return { cmd: "open", args: [] };
+  if (platform === "win32") return { cmd: "cmd", args: ["/c", "start", ""] };
+  return { cmd: "xdg-open", args: [] };
+}
+function hasDisplay(env, platform) {
+  if (platform === "darwin" || platform === "win32") return true;
+  return Boolean(env["DISPLAY"] || env["WAYLAND_DISPLAY"]);
+}
+function openUrl(url, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  if (!hasDisplay(env, platform)) return Promise.resolve(false);
+  const { cmd, args } = launcher(platform);
+  return new Promise((resolve4) => {
+    try {
+      const child = spawn(cmd, [...args, url], { stdio: "ignore", detached: true });
+      child.on("error", () => resolve4(false));
+      child.unref();
+      setTimeout(() => resolve4(true), 0);
+    } catch {
+      resolve4(false);
+    }
+  });
+}
+
+// src/projectLink.ts
+import { homedir as homedir2 } from "os";
+import { resolve as resolve2 } from "path";
+function describeProject(resolved, workspace) {
+  const where = resolved.sole ? `the only project in workspace ${workspace}` : `in workspace ${workspace}`;
+  return `${resolved.project.key} \u2014 ${resolved.project.name} (${where})`;
+}
+function nextLinkCommand(projectKey) {
+  return projectKey ? `motir link --project ${projectKey}` : "motir link";
+}
+async function resolveProject(client, workspace, serverUrl) {
+  const { projects } = await client.listProjects();
+  if (projects.length === 0) {
+    throw new CliError(`The workspace ${workspace} has no projects yet.`, {
+      hint: `Create one at ${serverUrl}, then run \`${nextLinkCommand()}\` again.`
+    });
+  }
+  const only = projects[0];
+  if (projects.length === 1 && only) return { project: only, sole: true };
+  const keys = projects.map((p) => p.key);
+  if (!isInteractive()) {
+    throw new CliError(`The workspace ${workspace} has ${projects.length} projects.`, {
+      hint: `Pass --project <key> \u2014 one of: ${keys.join(", ")}.`
+    });
+  }
+  info(`Projects in ${workspace}:`);
+  projects.forEach((p, index) => info(`  ${index + 1}) ${p.key} \u2014 ${p.name}`));
+  const answer = await promptLine(`Project [1-${projects.length}, or a key]`);
+  const picked = pickProject(projects, answer);
+  if (!picked) {
+    throw new CliError(`"${answer}" is not one of this workspace\u2019s projects.`, {
+      hint: `Choose 1-${projects.length}, or pass --project <key> \u2014 one of: ${keys.join(", ")}.`
+    });
+  }
+  return { project: picked, sole: false };
+}
+function pickProject(projects, answer) {
+  const trimmed = answer.trim();
+  if (/^\d+$/.test(trimmed)) return projects[Number(trimmed) - 1];
+  return projects.find((p) => p.key.toLowerCase() === trimmed.toLowerCase());
+}
+async function autoLinkAfterLogin(input) {
+  const cwd = resolve2(input.cwd ?? process.cwd());
+  const home = resolve2(input.home ?? homedir2());
+  let existing;
+  try {
+    existing = findLink(cwd);
+  } catch {
+    info(`Found a .motir.json that could not be read \u2014 leaving it alone.`);
+    info(`Run \`${nextLinkCommand()}\` to rewrite it once it is fixed.`);
+    return null;
+  }
+  if (existing) {
+    info(
+      `Already linked: ${existing.dir} \u2192 ${existing.config.workspace}/${existing.config.project}.`
+    );
+    info(`Run \`${nextLinkCommand(existing.config.project)}\` here to change it.`);
+    return null;
+  }
+  if (cwd === home) {
+    info(`Not linking your home directory \u2014 a link there would bind every folder under it.`);
+    info(`cd to your workspace root and run \`${nextLinkCommand()}\`.`);
+    return null;
+  }
+  let projects;
+  try {
+    projects = await input.listProjects();
+  } catch {
+    info(`Run \`${nextLinkCommand()}\` in your workspace root to bind it to a project.`);
+    return null;
+  }
+  const only = projects[0];
+  if (projects.length !== 1 || !only) {
+    if (projects.length === 0) {
+      info(`No projects in workspace ${input.workspace} yet \u2014 create one at ${input.serverUrl},`);
+      info(`then run \`${nextLinkCommand()}\` in your workspace root.`);
+    } else {
+      const keys = projects.map((p) => p.key).join(", ");
+      info(`${projects.length} projects in workspace ${input.workspace}: ${keys}.`);
+      info(`Run \`${nextLinkCommand("<key>")}\` in your workspace root to pick one.`);
+    }
+    return null;
+  }
+  const config = {
+    serverUrl: input.serverUrl,
+    workspace: input.workspace,
+    project: only.key
+  };
+  let path;
+  try {
+    path = writeLink(cwd, config);
+  } catch {
+    info(`Could not write a link in ${cwd}.`);
+    info(`Run \`${nextLinkCommand(only.key)}\` from a writable workspace root.`);
+    return null;
+  }
+  info(`Linked ${cwd} \u2192 ${describeProject({ project: only, sole: true }, input.workspace)}`);
+  info(`Wrote ${path} \u2014 move or delete it to bind a different folder.`);
+  return path;
+}
+
+// src/deviceAuth.ts
+var CLI_CLIENT_ID = "motir-cli";
+var DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+var DEVICE_START_PATH = "/api/cli/device/start";
+var DEVICE_TOKEN_PATH = "/api/cli/device/token";
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return void 0;
+  }
+}
+async function postJson(url, body, serverUrl) {
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify(body)
+    });
+  } catch {
+    throw new CliError(`Could not reach ${serverUrl}.`, {
+      hint: "Check the URL (--server <url> or MOTIR_SERVER) and that the server is running."
+    });
+  }
+}
+function oauthErrorCode(body) {
+  const error = body?.error;
+  return typeof error === "string" ? error : void 0;
+}
+async function startDeviceGrant(input) {
+  const res = await postJson(
+    input.serverUrl + DEVICE_START_PATH,
+    { hostname: input.hostname },
+    input.serverUrl
+  );
+  const body = await readJson(res);
+  if (!res.ok) {
+    throw new CliError(`${input.serverUrl} refused to start a login (HTTP ${res.status}).`, {
+      hint: "If this is a self-hosted Motir, it may predate `motir login` \u2014 use `motir auth login --token <pat>` instead."
+    });
+  }
+  const grant = body;
+  if (typeof grant?.device_code !== "string" || typeof grant.user_code !== "string") {
+    throw new CliError(`${input.serverUrl} did not return a device grant.`, {
+      hint: "Check that --server points at a Motir server (it should serve /api/cli/device/start)."
+    });
+  }
+  return grant;
+}
+async function pollDeviceGrant(input) {
+  const res = await postJson(
+    input.serverUrl + DEVICE_TOKEN_PATH,
+    {
+      grant_type: DEVICE_CODE_GRANT_TYPE,
+      device_code: input.deviceCode,
+      client_id: CLI_CLIENT_ID
+    },
+    input.serverUrl
+  );
+  const body = await readJson(res);
+  if (res.ok) {
+    const credential = body;
+    if (typeof credential?.access_token !== "string") {
+      throw new CliError(`${input.serverUrl} approved the login but returned no token.`);
+    }
+    return { state: "granted", credential };
+  }
+  switch (oauthErrorCode(body)) {
+    case "authorization_pending":
+      return { state: "pending" };
+    case "slow_down":
+      return { state: "slow_down" };
+    case "server_error":
+      return { state: "retry" };
+    case "access_denied":
+      throw new CliError("Approval was denied. No credential was written.", {
+        hint: "Run `motir login` again if that was not you \u2014 and revoke nothing: nothing was created."
+      });
+    case "expired_token":
+      throw new CliError("The code expired before it was approved.", {
+        hint: "Codes last 15 minutes. Run `motir login` again for a fresh one."
+      });
+    default:
+      throw new CliError(`The login could not be completed (HTTP ${res.status}).`, {
+        hint: "Run `motir login` again to start a fresh grant."
+      });
+  }
+}
+
+// src/commands/login.ts
+var SLOW_DOWN_STEP_MS = 5e3;
+var MIN_POLL_SECONDS = 1;
+var MIN_BUDGET_SECONDS = 60;
+async function listProjectsWith(input) {
+  const client = new MotirClient(input);
+  try {
+    await client.connect();
+    const { projects } = await client.listProjects();
+    return projects;
+  } finally {
+    await client.close();
+  }
+}
+function groupUserCode(code) {
+  if (code.includes("-")) return code;
+  const groups = code.match(/.{1,4}/g);
+  return groups ? groups.join("-") : code;
+}
+function printGrant(grant) {
+  info("");
+  info(`  Your code:  ${groupUserCode(grant.user_code)}`);
+  info(`  Open:       ${grant.verification_uri}`);
+  info("");
+}
+function storeCredential(serverUrl, credential) {
+  try {
+    setCredential(serverUrl, { token: credential.access_token, user: credential.user });
+  } catch {
+    throw new CliError(`Could not write the credential to ${configPath()}.`, {
+      hint: `Make that directory writable, point MOTIR_CONFIG_HOME at one that is, or set ${TOKEN_ENV_VAR} instead \u2014 the environment tier is never written to disk.`
+    });
+  }
+}
+async function awaitApproval(input) {
+  let intervalMs = Math.max(input.grant.interval, MIN_POLL_SECONDS) * 1e3;
+  const budgetMs = Math.max(input.grant.expires_in, MIN_BUDGET_SECONDS) * 1e3;
+  let waitedMs = 0;
+  for (; ; ) {
+    await input.sleep(intervalMs);
+    waitedMs += intervalMs;
+    const result = await pollDeviceGrant({
+      serverUrl: input.serverUrl,
+      deviceCode: input.grant.device_code
+    });
+    if (result.state === "granted") return result.credential;
+    if (result.state === "slow_down") intervalMs += SLOW_DOWN_STEP_MS;
+    if (waitedMs >= budgetMs) {
+      throw new CliError("Timed out waiting for approval.", {
+        hint: "Nothing was written. Run `motir login` again when you are ready to approve it."
+      });
+    }
+  }
+}
+async function loginCommand(opts, deps = {}) {
+  const sleep = deps.sleep ?? delay;
+  const open = deps.openUrl ?? openUrl;
+  const serverUrl = resolveServerUrl(opts.server);
+  const grant = await startDeviceGrant({ serverUrl, hostname: hostname() });
+  printGrant(grant);
+  const opened = opts.browser === false ? false : await open(grant.verification_uri_complete);
+  if (opened) info("Opened your browser \u2014 approve the request there.");
+  else info("Open that URL on any device, sign in, and enter the code.");
+  info("Waiting for approval\u2026");
+  const credential = await awaitApproval({ serverUrl, grant, sleep });
+  storeCredential(serverUrl, credential);
+  info(
+    `Logged in as ${credential.user.email} on ${serverUrl} (workspace ${credential.workspace.name}).`
+  );
+  const listProjects = deps.listProjects ?? listProjectsWith;
+  await autoLinkAfterLogin({
+    serverUrl,
+    workspace: credential.workspace.slug,
+    listProjects: () => listProjects({ serverUrl, token: credential.access_token }),
+    ...deps.cwd === void 0 ? {} : { cwd: deps.cwd },
+    ...deps.home === void 0 ? {} : { home: deps.home }
+  });
+}
+
 // src/commands/link.ts
 function tokenFor(serverUrl) {
   const cred = resolveCredential(serverUrl);
@@ -575,15 +897,17 @@ async function linkCommand(opts) {
         hint: "Pass --workspace <slug>."
       });
     }
-    let project = opts.project ?? existing?.config.project;
-    if (!project) {
-      if (!isInteractive()) {
-        throw new CliError("No project given.", { hint: "Pass --project <key>." });
-      }
-      project = await promptLine("Project key");
+    const asserted = opts.project ?? existing?.config.project;
+    let project;
+    let chosen = null;
+    if (asserted) {
+      await assertProjectAccessible(client, asserted);
+      project = asserted;
+    } else {
+      const resolved = await resolveProject(client, workspace, serverUrl);
+      project = resolved.project.key;
+      chosen = describeProject(resolved, workspace);
     }
-    if (!project) throw new CliError("A project key is required.");
-    await assertProjectAccessible(client, project);
     const config = {
       serverUrl,
       workspace,
@@ -594,6 +918,7 @@ async function linkCommand(opts) {
     const targetDir = existing?.dir ?? cwd;
     const path = writeLink(targetDir, withRepo);
     info(`Linked ${targetDir} \u2192 ${workspace}/${project} on ${serverUrl}`);
+    if (chosen) info(`Chose ${chosen}.`);
     info(`Wrote ${path}`);
     showLink(targetDir, withRepo);
   } finally {
@@ -980,6 +1305,160 @@ function renderReadinessLine(readiness) {
 function renderLineage(detail) {
   return [...detail.ancestors.map((a) => a.identifier), detail.item.identifier].join(" \u203A ");
 }
+var NO_VALUE = "\u2014";
+var NO_COMMENTS_LINE = "No comments yet.";
+var NO_ACTIVITY_LINE = "No activity yet.";
+var COMMENT_PREFIX = "[comment] ";
+var REPLY_PREFIX = "  \u21B3 reply ";
+var CHANGE_PREFIX = "[change]  ";
+var MINUTE = 6e4;
+var HOUR = 60 * MINUTE;
+var DAY = 24 * HOUR;
+var MONTH = 30 * DAY;
+var YEAR = 365 * DAY;
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function relativeTime(iso, now) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  const delta = now.getTime() - then;
+  if (delta < MINUTE) return "just now";
+  if (delta < HOUR) return `${plural(Math.floor(delta / MINUTE), "minute")} ago`;
+  if (delta < DAY) return `${plural(Math.floor(delta / HOUR), "hour")} ago`;
+  if (delta < MONTH) return `${plural(Math.floor(delta / DAY), "day")} ago`;
+  if (delta < YEAR) return `${plural(Math.floor(delta / MONTH), "month")} ago`;
+  return `${plural(Math.floor(delta / YEAR), "year")} ago`;
+}
+function activityValueText(value) {
+  if (value === null || value === void 0) return NO_VALUE;
+  if (typeof value === "string") return value;
+  switch (value.type) {
+    case "none":
+      return NO_VALUE;
+    case "text":
+      return value.text ?? NO_VALUE;
+    case "status":
+      return value.label ?? value.key ?? NO_VALUE;
+    case "user":
+      return value.name ?? value.userId ?? NO_VALUE;
+    case "date":
+      return value.date ?? NO_VALUE;
+    case "sprint":
+      return value.name ?? value.sprintId ?? NO_VALUE;
+    case "issue":
+      return value.identifier ?? value.workItemId ?? NO_VALUE;
+    default:
+      return value.label ?? value.name ?? value.identifier ?? value.text ?? value.key ?? NO_VALUE;
+  }
+}
+function activityPartText(part) {
+  switch (part.kind) {
+    case "created":
+      return "created the item";
+    case "archived":
+      return "archived the item";
+    case "unarchived":
+      return "restored the item";
+    case "field":
+      return `changed ${part.field}: ${activityValueText(part.from)} \u2192 ${activityValueText(part.to)}`;
+    // The trail records THAT a body field changed, never its text (the DTO
+    // carries none) — said plainly, so it never reads as a truncation.
+    case "fieldEdited":
+      return `edited ${part.field} (body not shown \u2014 the history trail records no text)`;
+    case "link":
+      return `${part.op} ${part.linkKind} link \u2192 ${activityValueText(part.target)}`;
+    case "collection":
+      return `${part.op} ${part.field}: ${(part.items ?? []).join(", ")}`;
+    case "commentDeleted": {
+      const replies = part.replyCount ?? 0;
+      return `deleted a comment by ${activityValueText(part.author)} (${replies} ${replies === 1 ? "reply" : "replies"})`;
+    }
+    case "generic":
+      return `${part.key}: ${activityValueText(part.from)} \u2192 ${activityValueText(part.to)}`;
+    default:
+      if (part.from === void 0 && part.to === void 0) {
+        return `${part.kind} (unknown change kind \u2014 update the CLI to read it in full)`;
+      }
+      return `${part.kind}: ${activityValueText(part.from)} \u2192 ${activityValueText(part.to)}`;
+  }
+}
+function attribution(who, iso, now) {
+  return `${who ?? "former member"} \xB7 ${relativeTime(iso, now)} (${iso})`;
+}
+function renderHistoryEntry(entry, now) {
+  const parts = entry.parts.map(activityPartText).join("; ");
+  return `${CHANGE_PREFIX}${attribution(entry.actor.name, entry.changedAt, now)} \u2014 ${parts}`;
+}
+function renderComment(comment, prefix, now) {
+  const edited = comment.editedAt === null ? "" : " (edited)";
+  const indent = " ".repeat(prefix.length);
+  const header = `${prefix}${attribution(comment.author.name, comment.createdAt, now)}${edited}`;
+  const body = comment.bodyMd.split("\n").map((line) => line === "" ? "" : `${indent}${line}`).join("\n");
+  return `${header}
+${body}`;
+}
+function renderCommentThread(thread, now) {
+  return [
+    renderComment(thread, COMMENT_PREFIX, now),
+    ...thread.replies.map((reply) => renderComment(reply, REPLY_PREFIX, now))
+  ].join("\n");
+}
+function commentsIn(threads) {
+  return threads.reduce((sum, thread) => sum + 1 + thread.replies.length, 0);
+}
+function shownOfTotal(shown, total, noun) {
+  return shown === total ? plural(total, noun) : `${shown} of ${plural(total, noun)}`;
+}
+function moreLine(remaining, identifier) {
+  const left = remaining.filter(([count]) => count > 0).map(([count, noun]) => plural(count, noun));
+  const what = left.length > 0 ? `${left.join(" and ")} not on this page` : "this page may be short \u2014 the stream is not exhausted";
+  return `MORE \u2014 ${what}. \`motir show\` prints ONE page and never drains the stream; read the rest in Motir: \`motir open ${identifier}\`.`;
+}
+function activitySection(heading, counts, blocks, emptyLine, more) {
+  const body = blocks.length === 0 ? [emptyLine] : blocks;
+  return [`${heading}
+${counts}`, body.join("\n\n"), ...more === null ? [] : [more]].join(
+    "\n\n"
+  );
+}
+function renderActivityStream(view, page, identifier, now) {
+  if (view === "comments") {
+    const p2 = page;
+    const shown = commentsIn(p2.threads);
+    const direction = p2.order === "asc" ? "oldest first" : "newest first";
+    return activitySection(
+      "COMMENTS",
+      `${shownOfTotal(shown, p2.totalCount, "comment")}, ${direction}`,
+      p2.threads.map((thread) => renderCommentThread(thread, now)),
+      NO_COMMENTS_LINE,
+      p2.nextCursor === null ? null : moreLine([[p2.totalCount - shown, "comment"]], identifier)
+    );
+  }
+  const p = page;
+  const shownComments = commentsIn(
+    p.entries.flatMap((entry) => entry.type === "comment" ? [entry.thread] : [])
+  );
+  const shownChanges = p.entries.filter((entry) => entry.type === "history").length;
+  return activitySection(
+    "ACTIVITY",
+    [
+      shownOfTotal(shownComments, p.totalComments, "comment"),
+      shownOfTotal(shownChanges, p.totalChanges, "change")
+    ].join(" \xB7 "),
+    p.entries.map(
+      (entry) => entry.type === "comment" ? renderCommentThread(entry.thread, now) : renderHistoryEntry(entry.entry, now)
+    ),
+    NO_ACTIVITY_LINE,
+    p.nextCursor === null ? null : moreLine(
+      [
+        [p.totalComments - shownComments, "comment"],
+        [p.totalChanges - shownChanges, "change"]
+      ],
+      identifier
+    )
+  );
+}
 function renderWorkItemDetail(detail, titleWidth = 60) {
   const sections = [
     renderItemHeader(detail.item),
@@ -1056,34 +1535,6 @@ async function collectSprintItems(client, projectKey, sprintId, filter = {}) {
   return { items, total };
 }
 
-// src/browser.ts
-import { spawn } from "child_process";
-function launcher(platform) {
-  if (platform === "darwin") return { cmd: "open", args: [] };
-  if (platform === "win32") return { cmd: "cmd", args: ["/c", "start", ""] };
-  return { cmd: "xdg-open", args: [] };
-}
-function hasDisplay(env, platform) {
-  if (platform === "darwin" || platform === "win32") return true;
-  return Boolean(env["DISPLAY"] || env["WAYLAND_DISPLAY"]);
-}
-function openUrl(url, opts = {}) {
-  const platform = opts.platform ?? process.platform;
-  const env = opts.env ?? process.env;
-  if (!hasDisplay(env, platform)) return Promise.resolve(false);
-  const { cmd, args } = launcher(platform);
-  return new Promise((resolve3) => {
-    try {
-      const child = spawn(cmd, [...args, url], { stdio: "ignore", detached: true });
-      child.on("error", () => resolve3(false));
-      child.unref();
-      setTimeout(() => resolve3(true), 0);
-    } catch {
-      resolve3(false);
-    }
-  });
-}
-
 // src/commands/read.ts
 var WORK_ITEM_KINDS = /* @__PURE__ */ new Set(["epic", "story", "task", "bug", "subtask"]);
 function parseKinds(raw) {
@@ -1194,14 +1645,33 @@ function parseItemKey(raw, command) {
   }
   return key;
 }
+function activityView(opts) {
+  if (opts.activity && opts.comments) {
+    throw new CliError("`--activity` and `--comments` cannot be combined.", {
+      hint: "`--activity` prints comments AND history; `--comments` prints just the comments. Pick one."
+    });
+  }
+  if (opts.activity) return "all";
+  if (opts.comments) return "comments";
+  return null;
+}
 async function showCommand(key, opts) {
   const identifier = parseItemKey(key, "show");
-  const detail = await withProjectSession(({ client }) => client.getWorkItem(identifier));
+  const view = activityView(opts);
+  const { detail, activity } = await withProjectSession(async ({ client }) => {
+    const detail2 = await client.getWorkItem(identifier);
+    const activity2 = view === null ? null : await client.getWorkItemActivity({ key: identifier, view });
+    return { detail: detail2, activity: activity2 };
+  });
   if (opts.json) {
-    json(detailWithWaves(detail));
+    json(view === null ? detailWithWaves(detail) : { ...detailWithWaves(detail), activity });
     return;
   }
   out(renderWorkItemDetail(detail));
+  if (view !== null && activity !== null) {
+    out();
+    out(renderActivityStream(view, activity, identifier, /* @__PURE__ */ new Date()));
+  }
 }
 async function openCommand(key, opts) {
   const trimmed = key.trim();
@@ -1215,9 +1685,9 @@ async function openCommand(key, opts) {
 }
 
 // src/commands/doctor.ts
-import { homedir as homedir2 } from "os";
+import { homedir as homedir3 } from "os";
 import { accessSync, constants, existsSync as existsSync3, statSync } from "fs";
-import { delimiter, isAbsolute as isAbsolute2, join as join4, resolve as resolve2 } from "path";
+import { delimiter, isAbsolute as isAbsolute2, join as join4, resolve as resolve3 } from "path";
 import { execFile } from "child_process";
 
 // src/agentProfiles.ts
@@ -1700,7 +2170,7 @@ function countByStatus(checks) {
   for (const check of checks) counts[check.status] += 1;
   return counts;
 }
-function plural(n, one, many) {
+function plural2(n, one, many) {
   return `${n} ${n === 1 ? one : many}`;
 }
 function renderDoctorReport(report) {
@@ -1714,7 +2184,7 @@ function renderDoctorReport(report) {
   }
   const counts = countByStatus(report.checks);
   const parts = STATUS_ORDER.filter((s) => counts[s] > 0).map(
-    (s) => s === "fail" ? plural(counts.fail, "failed", "failed") : s === "warn" ? plural(counts.warn, "warning", "warnings") : plural(counts.pass, "passed", "passed")
+    (s) => s === "fail" ? plural2(counts.fail, "failed", "failed") : s === "warn" ? plural2(counts.warn, "warning", "warnings") : plural2(counts.pass, "passed", "passed")
   );
   lines.push(
     "",
@@ -1777,7 +2247,7 @@ function resolveOnPath(binary, env = process.env, platform = process.platform) {
     return [base, ...exts.map((ext) => base + ext)];
   };
   if (binary.includes("/") || binary.includes("\\")) {
-    const direct = isAbsolute2(binary) ? binary : resolve2(binary);
+    const direct = isAbsolute2(binary) ? binary : resolve3(binary);
     return withExtensions(direct).find(isExecutableFile) ?? null;
   }
   for (const dir of (env["PATH"] ?? "").split(delimiter).filter(Boolean)) {
@@ -1840,9 +2310,9 @@ function defaultDoctorProbe() {
       const value = process.env[name];
       return typeof value === "string" && value.length > 0;
     },
-    home: () => homedir2(),
-    xdgConfigHome: () => process.env["XDG_CONFIG_HOME"] || join4(homedir2(), ".config"),
-    xdgDataHome: () => process.env["XDG_DATA_HOME"] || join4(homedir2(), ".local", "share")
+    home: () => homedir3(),
+    xdgConfigHome: () => process.env["XDG_CONFIG_HOME"] || join4(homedir3(), ".config"),
+    xdgDataHome: () => process.env["XDG_DATA_HOME"] || join4(homedir3(), ".local", "share")
   };
 }
 async function doctorCommand(opts, probe = defaultDoctorProbe()) {
@@ -1867,7 +2337,7 @@ async function runAgent(opts) {
   const promptFile = join5(dir, "prompt.md");
   writeFileSync3(promptFile, opts.prompt, { mode: PROMPT_FILE_MODE });
   try {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       const child = spawnFn(opts.command.binary, opts.command.args, {
         cwd: opts.cwd,
         // stdin piped (we write the prompt); stdout/stderr inherited so the
@@ -1889,7 +2359,7 @@ async function runAgent(opts) {
         stdin.end(opts.prompt);
       }
       child.on("close", (code, signal) => {
-        resolve3({ exitCode: signal ? 1 : code ?? 1, signal });
+        resolve4({ exitCode: signal ? 1 : code ?? 1, signal });
       });
     });
   } finally {
@@ -2037,6 +2507,17 @@ function cwdReasonLabel(target) {
 function workflowLabel(mode, sessionBranch) {
   return mode === "session_lineage" ? `session lineage on ${sessionBranch ?? "(unnamed branch)"}` : "one pull request of its own";
 }
+function renderDispatchAdvisories(dispatch) {
+  const advisories = dispatch.advisories ?? [];
+  if (advisories.length === 0) return null;
+  return [
+    `Advisory:   ${dispatch.key}'s acceptance criteria name work items it has no blocked_by edge to.`,
+    ...advisories.map((a) => `            - ${a.referenced} (${a.referencedStatus})`),
+    "            This is NOT a blocker \u2014 the dispatch proceeds. Before branching,",
+    "            check each one is already on origin/main; if it lives only on an open",
+    "            PR, add the blocked_by edge and stop instead of rebuilding its half."
+  ].join("\n");
+}
 function renderDispatchSummary(input) {
   const { key, title, dispatch, target, agent } = input;
   const lines = [
@@ -2117,13 +2598,16 @@ async function deliver(input) {
     target,
     agent: agent ? { command: agent.parsed.command, source: agent.source } : null
   });
+  const advisory = renderDispatchAdvisories(dispatch);
   if (!agent) {
     info(summary);
+    if (advisory) info(advisory);
     info("");
     outVerbatim(dispatch.prompt);
     return;
   }
   info(summary);
+  if (advisory) info(advisory);
   info("");
   const result = await runAgent({
     command: agent.parsed,
@@ -3334,9 +3818,9 @@ function nextStepHint(reviewUrl, anchored) {
 }
 
 // src/commands/plan.ts
-function delay(ms) {
-  return new Promise((resolve3) => {
-    setTimeout(resolve3, ms);
+function delay2(ms) {
+  return new Promise((resolve4) => {
+    setTimeout(resolve4, ms);
   });
 }
 async function planCommand(args = [], opts = {}, deps = {}) {
@@ -3428,7 +3912,7 @@ function reportDetached(submitted, reviewUrl, targetKeys) {
 }
 async function watchAndShow(client, planId, reviewUrl, targetKeys, deps) {
   const now = deps.now ?? Date.now;
-  const sleep = deps.sleep ?? delay;
+  const sleep = deps.sleep ?? delay2;
   const started = now();
   info(
     `Waiting for the planner (up to ${Math.round(WATCH_TIMEOUT_MS / 6e4)} minutes; --detach skips the wait)\u2026`
@@ -3588,13 +4072,17 @@ function findHelpTopic(name) {
 }
 var EXAMPLES = [
   "EXAMPLES:",
-  "  $ motir auth login --server https://app.motir.co   # store a token",
+  "  $ motir login                                      # connect this terminal",
+  "  $ motir login --no-browser                         # \u2026over SSH: print the code",
+  "  $ motir auth login --server https://app.motir.co   # paste a token you hold",
   "  $ motir link --project MOTIR                       # bind this folder",
   "  $ motir doctor                                     # preflight the setup",
   "  $ motir ready --kinds subtask --assignee me        # what can I pick up?",
   "  $ motir status --json                              # the project pulse",
   "  $ motir sprint                                     # what\u2019s in the active sprint",
   "  $ motir show MOTIR-7                               # the item, its edges, its body",
+  "  $ motir show MOTIR-7 --activity                    # \u2026plus comments + history",
+  "  $ motir show MOTIR-7 --comments                    # \u2026just what people said",
   "  $ motir open MOTIR-7 --print                       # the item\u2019s URL",
   "  $ motir auto --agent claude --max 5                # drain 5 items unattended",
   "  $ motir batch --agent claude                       # snapshot now, one PR each",
@@ -3704,11 +4192,36 @@ function buildProgram() {
     "Motir CLI \u2014 terminal dispatch of the work loop (an MCP client of the Motir server)."
   ).version(CLI_VERSION, "-v, --version", "Print the CLI version.");
   applyHelpConfiguration(program);
+  program.command("login").description("Connect this terminal: shows a code, opens Motir, waits for your approval.").helpGroup(HELP_GROUP.setup).option("--server <url>", "Server base URL, e.g. https://app.motir.co").option(
+    "--no-browser",
+    "Do not launch a browser \u2014 just print the code and the URL to open anywhere."
+  ).addHelpText(
+    "after",
+    [
+      "",
+      "No browser on this machine? The code and URL are printed either way, so an",
+      "SSH session or a container uses this same command \u2014 open the URL on any",
+      "device, sign in, and enter the code. For an unattended agent set MOTIR_TOKEN",
+      "instead (`motir help environment`)."
+    ].join("\n")
+  ).action((opts) => loginCommand(opts));
+  program.command("logout").description("Disconnect this terminal: remove the stored token for a server.").helpGroup(HELP_GROUP.setup).option("--server <url>", "Server to log out of (defaults to the linked / single server).").addHelpText(
+    "after",
+    [
+      "",
+      "This removes the credential from THIS machine only. The server-side kill",
+      "switch is revoking the token in Settings \u2192 Account \u2192 API tokens \u2014 a terminal",
+      "connected by `motir login` appears there as `CLI \xB7 <hostname>`."
+    ].join("\n")
+  ).action(authLogout);
   const auth = program.command("auth").description("Authenticate to a Motir server with a PAT.").helpGroup(HELP_GROUP.setup);
   auth.command("login").description("Validate and store a personal access token for a server.").option("--server <url>", "Server base URL, e.g. https://app.motir.co").option("--token <pat>", "Personal access token (or set MOTIR_TOKEN; prompted if omitted).").action(authLogin);
   auth.command("status").description("Show the resolved server, token prefix, and owning user.").option("--server <url>", "Server to report (defaults to the linked / single server).").action(authStatus);
   auth.command("logout").description("Remove the stored token for a server.").option("--server <url>", "Server to log out of (defaults to the linked / single server).").action(authLogout);
-  const link = program.command("link").description("Bind this workspace-root folder to a server + workspace + project.").helpGroup(HELP_GROUP.setup).option("--server <url>", "Server base URL (defaults to the existing link / single server).").option("--workspace <slug>", "Workspace slug (defaults to the token\u2019s active workspace).").option("--project <key>", "Project key, e.g. PROD.").option(
+  const link = program.command("link").description("Bind this workspace-root folder to a server + workspace + project.").helpGroup(HELP_GROUP.setup).option("--server <url>", "Server base URL (defaults to the existing link / single server).").option("--workspace <slug>", "Workspace slug (defaults to the token\u2019s active workspace).").option(
+    "--project <key>",
+    "Project key, e.g. PROD. Omit it and the workspace\u2019s only project is used."
+  ).option(
     "--repo <name>",
     'Mark THIS directory as a single repo\u2019s checkout (writes a "." override).'
   ).action(linkCommand);
@@ -3718,7 +4231,14 @@ function buildProgram() {
   program.command("status").description("Show the project pulse: ready / in-flight counts + the active sprint.").helpGroup(HELP_GROUP.read).option("--json", "Emit the pulse as JSON.").action(statusCommand);
   program.command("sprints").description("List the project\u2019s sprints: state, item count, points, window.").helpGroup(HELP_GROUP.read).option("--state <state>", "Only sprints in this state: planned, active, or complete.").option("--json", "Emit the sprint rows as JSON.").action(sprintsCommand);
   program.command("sprint [ref]").description("List ONE sprint\u2019s work items (defaults to the active sprint).").helpGroup(HELP_GROUP.read).option("--kinds <list>", "Comma-separated kinds: epic,story,task,bug,subtask.").option("--json", "Emit the sprint and its items as JSON.").action((ref, opts) => sprintCommand(ref, opts));
-  program.command("show <key>").description("Read one work item (e.g. PROD-7): fields, readiness, children, edges, body.").helpGroup(HELP_GROUP.read).option("--json", "Emit the get_work_item payload as JSON.").action(showCommand);
+  program.command("show <key>").description("Read one work item (e.g. PROD-7): fields, readiness, children, edges, body.").helpGroup(HELP_GROUP.read).option("--json", "Emit the get_work_item payload as JSON.").option("--activity", "Also print the activity stream: comments and history, one page.").option("--comments", "Also print the comment threads only, one page.").addHelpText(
+    "after",
+    [
+      "",
+      "ONE page of the stream is printed, never a drain loop: when more remains,",
+      "the output says how much and points at `motir open <key>` for the rest."
+    ].join("\n")
+  ).action(showCommand);
   program.command("doctor").description(
     "Preflight your BYOK setup: auth, project link, agent binary, credential presence."
   ).helpGroup(HELP_GROUP.setup).option("--agent <cmd>", "Check THIS agent command instead of the configured one.").option("--json", "Emit the check results as JSON.").action((opts) => doctorCommand(opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motir/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Motir CLI — terminal dispatch of the work loop (an MCP client of the Motir server).",
   "license": "GPL-3.0-only",
   "repository": {