@devflow-one/cli 0.1.10 → 0.1.12

package/README.md

@@ -156,7 +156,12 @@ devflow where                               # what this directory resolves to
 
 # inside a configured repo, routing is inferred — no flags
 devflow mr find                             # issue key from the branch
-devflow branch create feat/x
+
+# the issue's branch, from the repo's branch template (incl. {parentIssueKey}: a
+# sub-issue may resolve to its parent's branch). Check it out before `commit template`.
+devflow branch resolve ABC-124              # read-only: branch name + whether it exists
+devflow branch create --issue ABC-124       # creates it, or reuses an existing one
+devflow branch create feat/x                # a name is only a fallback when no issue key is known
 
 # or route explicitly, overriding whatever the directory implies
 devflow branch create feat/x --project ABC
@@ -177,6 +182,8 @@ devflow mr types --project ABC                # configured types: id, label, def
 # ({parentWithChildIssueKeys}/{issueKey}/{issueTitle} template tokens) for a branch without one.
 # {issueTitle} needs the Jira API token set in Settings, else it renders empty.
 devflow mr create "Title" feat/x --issue ABC-123
+devflow mr create "Title" --issue ABC-123   # head branch from the branch template
+# the template always picks the head branch; a different one is replaced (warning on stderr)
 
 # routed by issue key (project key = prefix before the last '-')
 devflow mr find ABC-123
@@ -186,6 +193,12 @@ devflow pipeline status 42 deadbeef --issue ABC-9
 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)
+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
+
 # assembled fix-review-comments prompt (read-only; runs no AI, makes no writes)
 devflow mr fix-prompt 42                    # issue key inferred from the branch
 

package/package.json

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

package/src/cli.js

@@ -4,7 +4,7 @@
 
 import { parseArgs } from "./args.js";
 import { resolveConfig, ConfigError } from "./config.js";
-import { gatewayRequest, GatewayError } from "./client.js";
+import { gatewayRequest, GatewayError, retryHint } from "./client.js";
 import { resolveCommand, listCommands, UsageError } from "./commands.js";
 import {
   createContextQuery,
@@ -86,17 +86,21 @@ function printWarnings(result, stderr) {
   }
 }
 
-/** Print an error, honoring --json, to stderr. */
-function printError(err, json, stderr) {
+/** Print an error (plus an optional retry hint), honoring --json, to stderr. */
+function printError(err, json, stderr, hint) {
   const code = err instanceof GatewayError ? err.code : err.name;
 
   if (json) {
-    stderr(JSON.stringify({ ok: false, error: { code, message: err.message } }, null, 2));
+    const error = { code, message: err.message, delivered: err.delivered, hint };
+
+    stderr(JSON.stringify({ ok: false, error }, null, 2));
 
     return;
   }
 
   stderr(`error${code ? ` [${code}]` : ""}: ${err.message}`);
+
+  if (hint) stderr(`hint: ${hint}`);
 }
 
 /**
@@ -231,7 +235,7 @@ export async function run(argv, io = {}) {
     return 0;
   } catch (err) {
     if (err instanceof UsageError || err instanceof GatewayError) {
-      printError(err, Boolean(flags.json), stderr);
+      printError(err, Boolean(flags.json), stderr, retryHint(err, command.retryUnsafe));
 
       return 1;
     }

package/src/client.js

@@ -9,15 +9,34 @@ export class GatewayError extends Error {
    * @param {string} [code]
    * @param {unknown} [result] the envelope's `result`, which some failures still
    *   carry — `/context` reports its ambiguity candidates there.
+   * @param {boolean} [delivered] on a TIMEOUT, whether the profile had already
+   *   picked the action up (undefined from daemons that predate the flag).
    */
-  constructor(message, code, result) {
+  constructor(message, code, result, delivered) {
     super(message);
     this.name = "GatewayError";
     this.code = code;
     this.result = result;
+    this.delivered = delivered;
   }
 }
 
+export const RETRY_HINT =
+  "The action may have completed — verify (e.g. findPrByIssueKey) before retrying.";
+
+/**
+ * The "verify before retrying" hint for a TIMEOUT of a retry-unsafe action
+ * that may already have run; undefined when a retry is safe.
+ * @param {unknown} err
+ * @param {boolean} [retryUnsafe]
+ */
+export function retryHint(err, retryUnsafe) {
+  const mayHaveRun =
+    err instanceof GatewayError && err.code === "TIMEOUT" && err.delivered !== false;
+
+  return retryUnsafe && mayHaveRun ? RETRY_HINT : undefined;
+}
+
 /**
  * Turn a network-level failure into an actionable message. ECONNREFUSED almost
  * always means the daemon isn't running.
@@ -83,5 +102,6 @@ export async function gatewayRequest(config, method, path, body) {
     error.message ?? `Gateway error (HTTP ${response.status}).`,
     error.code,
     envelope?.result,
+    error.delivered,
   );
 }

package/src/commands.js

@@ -79,6 +79,37 @@ function toText(flag, raw) {
   return text;
 }
 
+/** Read a value-taking flag verbatim (no trimming), failing when it was given no value. */
+function toRawText(flag, raw) {
+  if (raw === true) throw new UsageError(`"--${flag}" requires a value.`);
+
+  return raw === undefined ? undefined : String(raw);
+}
+
+/**
+ * The issue key whose branch template names `branch`: --issue, else — only when no
+ * branch was named — the inferred key, so an unrelated checkout never overrides it.
+ */
+function templateIssueKey(branch, flags, context) {
+  return toText("issue", flags.issue) ?? (branch ? undefined : context.issueKey);
+}
+
+/** buildArgs for a command whose only arg is an issue key: positional, else --issue / inferred. */
+function issueKeyArgs(name) {
+  return ([issueKey], _flags, context = {}) => {
+    const key = issueKey ?? context.issueKey;
+
+    if (!key) {
+      throw new UsageError(
+        `${name} needs an issue key: pass it positionally or with --issue ` +
+          "(none could be inferred from the current branch or directory).",
+      );
+    }
+
+    return [key];
+  };
+}
+
 /** A bad-invocation error (wrong/missing args) — printed with the command usage. */
 export class UsageError extends Error {
   constructor(message) {
@@ -93,6 +124,7 @@ export class UsageError extends Error {
  * @property {string} [path]        For GET commands.
  * @property {string} [action]      Gateway action name for POST commands.
  * @property {boolean} [destructive] Requires --force/--yes (gated by cli.js).
+ * @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.
  */
@@ -118,16 +150,33 @@ const COMMANDS = {
 
   "branch create": {
     method: "POST",
+    retryUnsafe: true,
     action: "createBranch",
-    usage: "branch create <branchName> [--issue KEY] [--project KEY]",
-    buildArgs: ([branchName]) => {
-      if (!branchName) throw new UsageError("branch create requires <branchName>.");
+    usage:
+      "branch create [branchName] [--issue KEY] [--project KEY]" +
+      " (the repo's branch template names the branch from the issue, incl. {parentIssueKey};" +
+      " branchName is only a fallback; an existing branch is reused)",
+    buildArgs: ([branchName], flags, context = {}) => {
+      const issueKey = templateIssueKey(branchName, flags, context);
+
+      if (!branchName && !issueKey) {
+        throw new UsageError("branch create needs an issue key (--issue) or a <branchName>.");
+      }
 
-      return [branchName];
+      return [branchName, issueKey];
     },
   },
+  "branch resolve": {
+    method: "POST",
+    action: "resolveBranchName",
+    usage:
+      "branch resolve [issueKey] [--issue KEY] [--project KEY]" +
+      " (prints the issue's configured branch name and whether it exists; read-only)",
+    buildArgs: issueKeyArgs("branch resolve"),
+  },
   "branch delete": {
     method: "POST",
+    retryUnsafe: true,
     action: "deleteBranch",
     destructive: true,
     usage: "branch delete <branchName> [--issue KEY] [--project KEY] --force",
@@ -140,13 +189,15 @@ const COMMANDS = {
 
   "commit template": {
     method: "POST",
+    retryUnsafe: true,
     action: "commitByTemplate",
     usage:
       'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] [--issue KEY] [--project KEY]' +
       " (--values keys fill the project's commit template, default" +
       ' "{summary}\\n\\n{changesList}\\n\\n{issueSlug}": summary, changesList (string array,' +
       " rendered as bullets), issueSlug, prNumber; missing keys are left empty and reported" +
-      " as warnings on stderr)",
+      " as warnings on stderr; commits the worktree's checked-out branch, so check out the" +
+      " one `branch resolve` prints first)",
     buildArgs: ([worktreePath], flags) => {
       if (!worktreePath) throw new UsageError("commit template requires <worktreePath>.");
 
@@ -159,22 +210,26 @@ const COMMANDS = {
 
   "mr create": {
     method: "POST",
+    retryUnsafe: true,
     action: "createPullRequest",
     usage:
-      "mr create <title> <headBranch> [--body <text>] [--base <branch>] [--type <idOrLabel>]" +
+      "mr create <title> [headBranch] [--body <text>] [--base <branch>] [--type <idOrLabel>]" +
       " [--issue KEY] [--project KEY]" +
-      " (--base defaults to the repo's configured base branch, expanding a {year}/{number} pattern;" +
+      " (the repo's branch template picks the head branch from the issue; headBranch is only" +
+      " a fallback; --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)",
-    buildArgs: ([title, headBranch], flags) => {
-      if (!title || !headBranch) {
-        throw new UsageError("mr create requires <title> and <headBranch>.");
+    buildArgs: ([title, headBranch], flags, context = {}) => {
+      const issueKey = templateIssueKey(headBranch, flags, context);
+
+      if (!title || (!headBranch && !issueKey)) {
+        throw new UsageError(
+          "mr create requires <title> and an issue key (--issue) or <headBranch>.",
+        );
       }
 
       const baseBranch = toBranch("base", flags.base);
       const prType = toText("type", flags.type);
-      // Only an explicit --issue is forwarded; the gateway otherwise parses the head branch.
-      const issueKey = toText("issue", flags.issue);
 
       // Trailing undefined is trimmed so the gateway resolves the repo's own
       // configured base branch (and expands a pattern) instead of seeing null.
@@ -199,6 +254,7 @@ const COMMANDS = {
   },
   "mr close": {
     method: "POST",
+    retryUnsafe: true,
     action: "closePullRequest",
     destructive: true,
     usage: "mr close <prId> [--issue KEY] [--project KEY] --force",
@@ -206,6 +262,7 @@ const COMMANDS = {
   },
   "mr merge": {
     method: "POST",
+    retryUnsafe: true,
     action: "mergePullRequest",
     destructive: true,
     usage:
@@ -258,17 +315,36 @@ const COMMANDS = {
     usage: "mr find [issueKey] [--issue KEY] [--project KEY]",
     // The positional wins, then --issue, then the issue key inferred from the
     // branch — so `devflow mr find` on `ABC-123-login` needs no argument at all.
-    buildArgs: ([issueKey], _flags, context = {}) => {
-      const key = issueKey ?? context.issueKey;
+    buildArgs: issueKeyArgs("mr find"),
+  },
+  "mr get": {
+    method: "POST",
+    action: "getPullRequest",
+    usage: "mr get <prId> [--issue KEY] [--project KEY] (title, description, state; read-only)",
+    buildArgs: ([prId]) => [toInt("prId", prId)],
+  },
+  "mr update": {
+    method: "POST",
+    action: "updatePullRequest",
+    usage:
+      "mr update <prId> [--title <text>] [--description <text> | --append-description <text>]" +
+      " [--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)",
+    buildArgs: ([prId], flags) => {
+      const title = toText("title", flags.title);
+      const body = toRawText("description", flags.description);
+      const appendBody = toRawText("append-description", flags["append-description"]);
 
-      if (!key) {
-        throw new UsageError(
-          "mr find needs an issue key: pass it positionally or with --issue " +
-            "(none could be inferred from the current branch or directory).",
-        );
+      if (title === undefined && body === undefined && appendBody === undefined) {
+        throw new UsageError("mr update needs --title, --description or --append-description.");
+      }
+
+      if (body !== undefined && appendBody !== undefined) {
+        throw new UsageError("mr update takes --description or --append-description, not both.");
       }
 
-      return [key];
+      return [toInt("prId", prId), { title, body, appendBody }];
     },
   },
   "mr types": {
@@ -309,6 +385,7 @@ const COMMANDS = {
   },
   "pipeline retry": {
     method: "POST",
+    retryUnsafe: true,
     action: "restartFailedJobs",
     usage: "pipeline retry <pipelineOrRunId> [--all] [--job <jobId>] [--issue KEY] [--project KEY]",
     buildArgs: ([id], flags) => {
@@ -329,6 +406,7 @@ const COMMANDS = {
 
   "slack notify": {
     method: "POST",
+    retryUnsafe: true,
     action: "notifySlack",
     usage:
       'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] [--issue KEY] [--project KEY]',