@devflow-one/cli 0.1.15 → 0.1.17

package/README.md

@@ -182,9 +182,17 @@ devflow mr create "Title" feat/x --base release/2026.4 --project ABC
 # stamped with. Omitted or unrecognized, it is auto-selected by matching configured
 # type names against the title's conventional prefix, branch prefix, Jira issue type
 # and title keywords, falling back to the first type. Pass its id or label to pick one.
+# The template (its own {prMedia} uploads media) writes the description; --body is the
+# fallback, where {prMedia} is filled or removed.
 devflow mr create "Title" feat/x --type Bugfix --project ABC
 devflow mr types --project ABC                # configured types: id, label, default flag
 
+# ready for review: also applies the PR type's labels, assigns you when unassigned and
+# requests the type's missing reviewers (additive, best-effort). --type switches the
+# type by swapping its labels; to refresh this later, run `mr draft` then `mr ready` again
+devflow mr ready 42 --project ABC
+devflow mr ready 42 --type Bugfix --project ABC
+
 # issue key: parsed from the head branch by default; --issue sets it explicitly
 # ({parentWithChildIssueKeys}/{issueKey}/{issueTitle} template tokens) for a branch without one.
 # {issueTitle} needs the Jira API token set in Settings, else it renders empty.
@@ -198,51 +206,77 @@ devflow mr find ABC-123
 devflow pipeline status 42 deadbeef --issue ABC-9
 
 # commit a managed worktree with the project's commit-message template; it stages tracked
-# changes only (add --include-untracked for new files) and pushing needs --force
-devflow commit template /wt/ABC-123 --values '{"summary":"fix login"}' --project ABC --force
+# changes only (add --include-untracked for new files); pushing is destructive
+devflow commit template /wt/ABC-123 --values '{"summary":"fix login"}' --project ABC
 devflow commit template /wt/ABC-123 --no-push --project ABC   # commit locally, skip push
 
 # read a PR/MR's title + description, then edit it: --title/--description replace,
 # --append-description adds text after a `---` rule (skipped if already at the end);
-# --base retargets the PR/MR to an existing remote branch
+# --base retargets the PR/MR to an existing remote branch; `{prMedia}` in the description
+# uploads .devflow/media/<ISSUE-KEY>[-n].{mp4,png,jpg,jpeg} and is replaced with the links
+# (removed when the upload fails or the head branch names no issue; media.error says why)
 devflow mr get 42 --project ABC
 devflow mr update 42 --append-description "## Test plan" --project ABC
 devflow mr update 42 --title "Fix login redirect" --project ABC
 devflow mr update 42 --base release/2026.4 --project ABC
+devflow mr update 42 --description "$(cat body.md)" --project ABC   # body.md has {prMedia}
 
 # assembled fix-review-comments prompt (read-only; runs no AI, makes no writes)
 devflow mr fix-prompt 42                    # issue key inferred from the branch
 
+# issue status and the repo card's branches and PRs/MRs (read-only; the issue key is
+# inferred from the branch). Status needs the Jira API token set in Settings.
+devflow issue status                        # the issue's and its parent's status
+devflow issue branches ABC-123 --project ABC
+devflow issue prs                           # every state, merged and closed included
+
+# review comments: counts, then "Reply as Fixed" or an AI "Fix Comments" run, which
+# commits and pushes (so it is destructive). It returns at once: `started`, `prNumber` and
+# `queued` (true when an automation run is busy, so the fix starts on its next tick), or
+# `started: false` with a `reason` — e.g. while the panel or the timer is fixing that PR
+devflow mr comments 42                      # unfixed / fixed / resolved / prComments
+devflow mr reply-fixed 42                   # success / failed / resolved counts
+devflow mr fix-comments 42                   # then re-check the counts
+
 # notify the project's configured Slack channel(s)
 devflow slack notify "Review fixes ready on {pr}" --values '{"pr":"#42"}' --project ABC
 devflow slack channels --project ABC         # configured channels (read-only, no credentials)
 
+# reviewer notify: per channel, were reviewers already notified, and is the next step a
+# send or a ping? `source` says who posted: manual (panel), auto (auto-send), gateway
+# (`slack notify --pr`) or slack (found only in Slack history). `--pr` records the post
+# and threads a ping under the earlier message
+devflow mr notify-status 42
+devflow slack notify "Please review #42" --channel C123 --pr 42
+
 # force a specific profile when a key is ambiguous
 devflow mr ready 12 --profile prof-1
 ```
 
 ### Destructive actions
 
-`branch delete`, `mr close` and `mr merge` are destructive. They are **refused
-unless you confirm** with `--force` (or `--yes`); the gateway enforces the same
-gate server-side, so the confirmation can't be bypassed:
+`branch delete`, `mr close`, `mr merge`, `mr fix-comments` (its AI run commits and
+pushes) and `commit template` (unless `--no-push`) are destructive. By default they
+run without confirmation. Turn on **Require confirmation for destructive CLI/MCP
+actions** in a repo's DevFlow Git settings, and that repo then refuses them with
+`DESTRUCTIVE_BLOCKED` unless you confirm with `--force` (or `--yes`). The extension
+enforces the setting, so it can't be bypassed:
 
 ```sh
-devflow branch delete old --project ABC            # refused
-devflow branch delete old --project ABC --force    # executes
+devflow branch delete old --project ABC            # runs; refused if confirmation is on
+devflow branch delete old --project ABC --force    # always runs
 
 # merge a PR/MR, squashing and cleaning up the source branch
 devflow mr merge 42 --method squash --delete-source-branch --force
 ```
 
-Inference never softens this gate — a destructive command run with fully
-inferred routing still refuses without `--force`. Confirmation is always yours
-to give explicitly, precisely because inference makes mis-targeting easier.
+Inference never confirms — even with fully inferred routing, only an explicit
+`--force` counts, precisely because inference makes mis-targeting easier.
 
 ## Verify
 
 ```sh
-npm test      # unit: arg parsing, command resolution, routing, destructive gate
+npm test      # unit: arg parsing, command resolution, routing, destructive confirmation
 ```
 
 ## Releasing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-one/cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Terminal CLI wrapping the local DevFlow gateway so shell scripts can trigger repo actions.",
   "keywords": [
     "devflow",

package/src/cli.js

@@ -35,9 +35,9 @@ below is an override, applied ahead of anything inferred:
 
 Run \`devflow where\` to see what the current directory resolves to.
 
-Destructive actions (branch delete, mr close):
-  --force, --yes      Confirm a destructive action; required or it is refused.
-                      Never inferred — inference makes mis-targeting easier.
+Destructive actions (branch delete, mr close, mr merge, pushing commits):
+  --force, --yes      Confirm a destructive action. Needed only when confirmation
+                      is enabled for the repo in DevFlow settings. Never inferred.
 
 Output:
   --json              Print machine-readable JSON (envelope) for scripts.
@@ -199,16 +199,8 @@ export async function run(argv, io = {}) {
 
     assertRoutable(key, command, context, flags);
 
-    // Destructive gate: refuse before touching the gateway unless confirmed.
-    // Deliberately independent of inference — a confirmed target is never guessed.
-    const confirmed = Boolean(flags.force || flags.yes);
-    const destructive = isDestructiveCommand(command, flags);
-
-    if (destructive && !confirmed) {
-      throw new UsageError(
-        `"${key}" is destructive — re-run with --force (or --yes) to confirm. Usage: ${command.usage}`,
-      );
-    }
+    // Only an explicit --force/--yes confirms; inference makes mis-targeting easier.
+    const confirmed = Boolean(flags.force || flags.yes) && isDestructiveCommand(command, flags);
 
     // The owning profile is known but closed: say so by name rather than letting
     // the gateway answer with a bare NO_PROFILE.
@@ -220,7 +212,7 @@ export async function run(argv, io = {}) {
     const args = command.buildArgs ? command.buildArgs(rest, flags, context) : [];
     const body = {
       ...buildRoutingBody(context),
-      ...(destructive ? { allowDestructive: true } : {}),
+      ...(confirmed ? { allowDestructive: true } : {}),
       payload: {
         projectKey: projectKeyFrom(context),
         ...(context.repo ? { repo: context.repo } : {}),

package/src/client.js

@@ -27,13 +27,18 @@ export class GatewayError extends Error {
 export const RETRY_HINT =
   "The action may have completed — verify (e.g. findPrByIssueKey) before retrying.";
 
+export const DESTRUCTIVE_HINT =
+  "Confirmation is enabled in DevFlow settings for this repo — re-run with --force (or --yes).";
+
 /**
- * The "verify before retrying" hint for a TIMEOUT of a retry-unsafe action
- * that may already have run; undefined when a retry is safe.
+ * How to retry a failed call: confirm a DESTRUCTIVE_BLOCKED action, or verify a
+ * retry-unsafe TIMEOUT that may already have run; undefined when a retry is safe.
  * @param {unknown} err
  * @param {boolean} [retryUnsafe]
  */
 export function retryHint(err, retryUnsafe) {
+  if (err instanceof GatewayError && err.code === "DESTRUCTIVE_BLOCKED") return DESTRUCTIVE_HINT;
+
   const mayHaveRun =
     err instanceof GatewayError && err.code === "TIMEOUT" && err.delivered !== false;
 

package/src/commands.js

@@ -123,8 +123,8 @@ export class UsageError extends Error {
  * @property {"GET" | "POST" | "LOCAL"} method `LOCAL` runs in-process, no action call.
  * @property {string} [path]        For GET commands.
  * @property {string} [action]      Gateway action name for POST commands.
- * @property {boolean | ((flags: Record<string, unknown>) => boolean)} [destructive] Requires
- *   --force/--yes (gated by cli.js); a predicate when that depends on the flags.
+ * @property {boolean | ((flags: Record<string, unknown>) => boolean)} [destructive] Accepts
+ *   --force/--yes as confirmation; a predicate when that depends on the flags.
  * @property {boolean} [retryUnsafe] A retry may repeat its side effect; a TIMEOUT warns to verify first.
  * @property {(pos: string[], flags: Record<string, unknown>, context?: object) => unknown[]} [buildArgs]
  * @property {string} usage         One-line usage string.
@@ -182,7 +182,7 @@ const COMMANDS = {
     retryUnsafe: true,
     action: "deleteBranch",
     destructive: true,
-    usage: "branch delete <branchName> [--issue KEY] [--project KEY] --force",
+    usage: "branch delete <branchName> [--issue KEY] [--project KEY] [--force]",
     buildArgs: ([branchName]) => {
       if (!branchName) throw new UsageError("branch delete requires <branchName>.");
 
@@ -198,7 +198,7 @@ const COMMANDS = {
     destructive: (flags) => !flags["no-push"],
     usage:
       'commit template <worktreePath> [--values \'{"key":"val"}\'] [--include-untracked]' +
-      " [--issue KEY] [--project KEY] (--no-push | --force)" +
+      " [--issue KEY] [--project KEY] [--no-push | --force]" +
       " (stages every modified/deleted tracked file and pushes, refused from the base branch;" +
       " untracked files are refused unless --include-untracked;" +
       " --values keys fill the project's commit template, default" +
@@ -218,6 +218,32 @@ const COMMANDS = {
     },
   },
 
+  "issue status": {
+    method: "POST",
+    action: "getIssueStatus",
+    usage:
+      "issue status [issueKey] [--issue KEY] [--project KEY]" +
+      " (the issue's and its parent's Jira status; needs the Jira API token source; read-only)",
+    buildArgs: issueKeyArgs("issue status"),
+  },
+  "issue branches": {
+    method: "POST",
+    action: "listIssueBranches",
+    usage:
+      "issue branches [issueKey] [--issue KEY] [--project KEY]" +
+      " (each repo's remote branches for the issue and its parent, as the repo card lists them; read-only)",
+    buildArgs: issueKeyArgs("issue branches"),
+  },
+  "issue prs": {
+    method: "POST",
+    action: "listIssuePullRequests",
+    usage:
+      "issue prs [issueKey] [--issue KEY] [--project KEY]" +
+      " (each repo's PRs/MRs for the issue in every state, merged and closed included, with" +
+      " approvers on open ones; read-only)",
+    buildArgs: issueKeyArgs("issue prs"),
+  },
+
   "mr create": {
     method: "POST",
     retryUnsafe: true,
@@ -228,7 +254,8 @@ const COMMANDS = {
       " (a headBranch that exists on the remote is used as is; otherwise the repo's branch" +
       " template picks the head branch from the issue; --base defaults to the repo's configured base branch, expanding a {year}/{number} pattern;" +
       " --type is auto-selected by matching PR type names against the title prefix, branch prefix," +
-      " Jira issue type and title keywords, falling back to the first configured type)",
+      " Jira issue type and title keywords, falling back to the first configured type;" +
+      " the description comes from the PR type template, --body is the fallback where {prMedia} is filled or removed)",
     buildArgs: ([title, headBranch], flags, context = {}) => {
       const issueKey = templateIssueKey(headBranch, flags, context);
 
@@ -253,8 +280,18 @@ const COMMANDS = {
   "mr ready": {
     method: "POST",
     action: "markPrReadyForReview",
-    usage: "mr ready <prId> [--issue KEY] [--project KEY]",
-    buildArgs: ([prId]) => [toInt("prId", prId)],
+    usage:
+      "mr ready <prId> [--type <idOrLabel>] [--issue KEY] [--project KEY]" +
+      " (also applies the PR type's labels, assigns you when unassigned and requests the" +
+      " type's missing reviewers; --type switches the type by swapping its labels;" +
+      " run `mr draft` then `mr ready` again to refresh them)",
+    buildArgs: ([prId], flags) => {
+      const id = toInt("prId", prId);
+      const prType = toText("type", flags.type);
+
+      // An omitted prType is left out (not sent as null) so the gateway keeps the current type.
+      return prType === undefined ? [id] : [id, prType];
+    },
   },
   "mr draft": {
     method: "POST",
@@ -267,7 +304,7 @@ const COMMANDS = {
     retryUnsafe: true,
     action: "closePullRequest",
     destructive: true,
-    usage: "mr close <prId> [--issue KEY] [--project KEY] --force",
+    usage: "mr close <prId> [--issue KEY] [--project KEY] [--force]",
     buildArgs: ([prId]) => [toInt("prId", prId)],
   },
   "mr merge": {
@@ -277,7 +314,7 @@ const COMMANDS = {
     destructive: true,
     usage:
       "mr merge <prId> [--method merge|squash|rebase] [--delete-source-branch] " +
-      "[--issue KEY] [--project KEY] --force",
+      "[--issue KEY] [--project KEY] [--force]",
     buildArgs: ([prId], flags) => {
       const mergeMethod = flags.method === undefined ? undefined : toMergeMethod(flags.method);
       const deleteSourceBranch = flags["delete-source-branch"] ? true : undefined;
@@ -295,30 +332,6 @@ const COMMANDS = {
       return [toInt("prId", prId), assignee];
     },
   },
-  "mr labels": {
-    method: "POST",
-    action: "addPrLabels",
-    usage: "mr labels <prId> <label...> [--issue KEY] [--project KEY]",
-    buildArgs: ([prId, ...labels]) => {
-      if (labels.length === 0) {
-        throw new UsageError("mr labels requires <prId> and at least one <label>.");
-      }
-
-      return [toInt("prId", prId), labels];
-    },
-  },
-  "mr reviewers": {
-    method: "POST",
-    action: "requestPrReviewers",
-    usage: "mr reviewers <prId> <reviewer...> [--issue KEY] [--project KEY]",
-    buildArgs: ([prId, ...reviewers]) => {
-      if (reviewers.length === 0) {
-        throw new UsageError("mr reviewers requires <prId> and at least one <reviewer>.");
-      }
-
-      return [toInt("prId", prId), reviewers];
-    },
-  },
   "mr find": {
     method: "POST",
     action: "findPrByIssueKey",
@@ -341,7 +354,10 @@ const COMMANDS = {
       " [--base <branch>] [--issue KEY] [--project KEY]" +
       " (--title/--description replace; --append-description adds text after a `---` rule" +
       " and is skipped if it already ends the description after that rule; --base retargets" +
-      " the PR/MR to an existing remote branch)",
+      " the PR/MR to an existing remote branch; `{prMedia}` in --description or" +
+      " --append-description uploads .devflow/media/<ISSUE-KEY>[-n].{mp4,png,jpg,jpeg} and is" +
+      " replaced with the links, so swap old media links for `{prMedia}` to refresh them." +
+      " It is removed if the upload fails or the head branch names no issue; media.error says why)",
     buildArgs: ([prId], flags) => {
       const title = toText("title", flags.title);
       const body = toRawText("description", flags.description);
@@ -377,6 +393,46 @@ const COMMANDS = {
       return [parsedPrId, context.issueKey];
     },
   },
+  "mr comments": {
+    method: "POST",
+    action: "getPrReviewCommentCounts",
+    usage:
+      "mr comments <prId> [--issue KEY] [--project KEY]" +
+      " (unfixed / fixed / resolved review-thread and PR-level comment counts; read-only)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr notify-status": {
+    method: "POST",
+    action: "getReviewerNotifyStatus",
+    usage:
+      "mr notify-status <prId> [--issue KEY] [--project KEY]" +
+      " (per reviewer channel: whether reviewers were already notified on Slack and whether the" +
+      " next step is a send or a ping, and who posted; follow up with `slack notify` for that" +
+      " PR; read-only)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr fix-comments": {
+    method: "POST",
+    retryUnsafe: true,
+    action: "fixPrComments",
+    destructive: true,
+    usage:
+      "mr fix-comments <prId> [--issue KEY] [--project KEY] [--force]" +
+      " (starts an AI fix of the PR's unresolved review comments, which commits and pushes;" +
+      " returns at once: started / prNumber / queued, or a reason it was refused, e.g. that PR" +
+      " is already being fixed; re-check with `mr comments`)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr reply-fixed": {
+    method: "POST",
+    retryUnsafe: true,
+    action: "replyPrCommentsFixed",
+    usage:
+      "mr reply-fixed <prId> [--issue KEY] [--project KEY]" +
+      ' (replies "Fixed" to every unanswered review thread, resolving it when the repo is set to;' +
+      " prints success / failed counts)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
   "pipeline status": {
     method: "POST",
     action: "getPipelineStatus",
@@ -423,14 +479,19 @@ const COMMANDS = {
     retryUnsafe: true,
     action: "notifySlack",
     usage:
-      'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] [--issue KEY] [--project KEY]',
+      'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] [--pr <prId>]' +
+      " [--issue KEY] [--project KEY]" +
+      " (--pr records the post as that PR's reviewer notify; a channel already notified for it" +
+      " gets a ping threaded under the earlier message)",
     buildArgs: ([message], flags) => {
       if (!message) throw new UsageError("slack notify requires <message>.");
 
       const channel = flags.channel ? String(flags.channel) : undefined;
       const values = toValues("values", flags.values);
 
-      return [message, channel, values];
+      if (flags.pr === undefined) return [message, channel, values];
+
+      return [message, channel, values, { prNumber: toInt("pr", String(flags.pr)) }];
     },
   },
   "slack channels": {
@@ -442,7 +503,7 @@ const COMMANDS = {
 };
 
 /**
- * Does this invocation of `command` need --force/--yes?
+ * Is this invocation of `command` destructive?
  * @param {Command} command
  * @param {Record<string, unknown>} flags
  */