@devflow-one/cli 0.1.11 → 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.11",
+  "version": "0.1.12",
   "description": "Terminal CLI wrapping the local DevFlow gateway so shell scripts can trigger repo actions.",
   "keywords": [
     "devflow",

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) {
@@ -121,13 +152,28 @@ const COMMANDS = {
     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,
@@ -150,7 +196,8 @@ const COMMANDS = {
       " (--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>.");
 
@@ -166,20 +213,23 @@ const COMMANDS = {
     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.
@@ -265,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": {