@devflow-one/cli 0.1.12 → 0.1.14

package/README.md

@@ -99,6 +99,9 @@ so this action cannot run. Open that Chrome profile and retry.
 - The **DevFlow desktop app must be running** — it hosts the gateway and writes
   the token. v1 also needs the browser extension connected so a profile owns
   project keys.
+- A **matching desktop app version** — this CLI proves the gateway's identity
+  with a challenge before sending the token, which older desktop builds don't
+  answer. Update the desktop app alongside the CLI.
 - Node **>= 20**.
 
 ## Install / run
@@ -127,7 +130,7 @@ cd cli && npm link             # or link it onto your PATH as `devflow`
 ## Token & port (zero-config)
 
 The CLI discovers the gateway automatically — no setup — by reading the token
-file the desktop daemon writes on first run, under its userData dir:
+file the desktop daemon writes on every start, under its userData dir:
 
 | Platform | Token path                                                     |
 | -------- | -------------------------------------------------------------- |
@@ -142,6 +145,9 @@ The file is written owner-only (`0600`). Override for CI / non-standard installs
 | `DEVFLOW_GATEWAY_TOKEN` | Provide the token directly (skips the file lookup). |
 | `DEVFLOW_GATEWAY_PORT`  | Gateway port (default `8787`).                      |
 
+The daemon mints a new token on every restart, so a `DEVFLOW_GATEWAY_TOKEN` pin
+goes stale each time the desktop app restarts — prefer the file lookup.
+
 Routing defaults can also come from the environment — handy in CI or a shell
 profile. They lose to the equivalent flag and win over anything inferred:
 `DEVFLOW_PROJECT`, `DEVFLOW_ISSUE`, `DEVFLOW_REPO`, `DEVFLOW_PROFILE`.
@@ -162,6 +168,7 @@ devflow mr find                             # issue key from the branch
 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
+devflow branch create --issue ABC-124 --from release/2026.4   # start from another remote branch
 
 # or route explicitly, overriding whatever the directory implies
 devflow branch create feat/x --project ABC
@@ -183,21 +190,25 @@ devflow mr types --project ABC                # configured types: id, label, def
 # {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)
+# a head branch that exists on the remote is used as is; otherwise the template picks it
+# and a different one is replaced (warning on stderr)
 
 # routed by issue key (project key = prefix before the last '-')
 devflow mr find ABC-123
 devflow pipeline status 42 deadbeef --issue ABC-9
 
-# commit a managed worktree with the project's commit-message template
-devflow commit template /wt/ABC-123 --values '{"summary":"fix login"}' --project ABC
+# 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
 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)
+# --append-description adds text after a `---` rule (skipped if already at the end);
+# --base retargets the PR/MR to an existing remote branch
 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
 
 # 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.12",
+  "version": "0.1.14",
   "description": "Terminal CLI wrapping the local DevFlow gateway so shell scripts can trigger repo actions.",
   "keywords": [
     "devflow",

package/src/args.js

@@ -11,6 +11,7 @@ const BOOLEAN_FLAGS = new Set([
   "force",
   "yes",
   "no-push",
+  "include-untracked",
   "delete-source-branch",
 ]);
 

package/src/cli.js

@@ -5,7 +5,7 @@
 import { parseArgs } from "./args.js";
 import { resolveConfig, ConfigError } from "./config.js";
 import { gatewayRequest, GatewayError, retryHint } from "./client.js";
-import { resolveCommand, listCommands, UsageError } from "./commands.js";
+import { resolveCommand, listCommands, isDestructiveCommand, UsageError } from "./commands.js";
 import {
   createContextQuery,
   resolveCliContext,
@@ -202,8 +202,9 @@ export async function run(argv, io = {}) {
     // 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 (command.destructive && !confirmed) {
+    if (destructive && !confirmed) {
       throw new UsageError(
         `"${key}" is destructive — re-run with --force (or --yes) to confirm. Usage: ${command.usage}`,
       );
@@ -219,7 +220,7 @@ export async function run(argv, io = {}) {
     const args = command.buildArgs ? command.buildArgs(rest, flags, context) : [];
     const body = {
       ...buildRoutingBody(context),
-      ...(command.destructive ? { allowDestructive: true } : {}),
+      ...(destructive ? { allowDestructive: true } : {}),
       payload: {
         projectKey: projectKeyFrom(context),
         ...(context.repo ? { repo: context.repo } : {}),

package/src/client.js

@@ -1,6 +1,9 @@
-// Thin HTTP client of the local gateway. Sends the Bearer token, parses the
-// `{ ok, result, error }` envelope the server returns, and turns transport /
-// envelope failures into a tagged GatewayError the CLI can print clearly.
+// Thin HTTP client of the local gateway. Sends the Bearer token only after the
+// listener proves it holds it, parses the `{ ok, result, error }` envelope the
+// server returns, and turns transport / envelope failures into a tagged
+// GatewayError the CLI can print clearly.
+
+import { UntrustedGatewayError, verifyGateway } from "./gatewayChallenge.js";
 
 /** A gateway call failure carrying the server's error `code` (when present). */
 export class GatewayError extends Error {
@@ -64,7 +67,7 @@ function describeTransportError(err, baseUrl) {
  * @param {string} path e.g. `/actions/createBranch`
  * @param {unknown} [body] JSON body for POST
  * @returns {Promise<unknown>} the envelope's `result`
- * @throws {GatewayError} on transport failure or an `{ ok: false }` envelope
+ * @throws {GatewayError} on a failed challenge, transport failure, or an `{ ok: false }` envelope
  */
 export async function gatewayRequest(config, method, path, body) {
   const headers = { Authorization: `Bearer ${config.token}` };
@@ -74,12 +77,15 @@ export async function gatewayRequest(config, method, path, body) {
   let response;
 
   try {
+    await verifyGateway(config.baseUrl, config.token);
     response = await fetch(`${config.baseUrl}${path}`, {
       method,
       headers,
       body: body !== undefined ? JSON.stringify(body) : undefined,
     });
   } catch (err) {
+    if (err instanceof UntrustedGatewayError) throw new GatewayError(err.message, err.code);
+
     throw describeTransportError(err, config.baseUrl);
   }
 

package/src/commands.js

@@ -123,7 +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} [destructive] Requires --force/--yes (gated by cli.js).
+ * @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} [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.
@@ -153,17 +154,19 @@ const COMMANDS = {
     retryUnsafe: true,
     action: "createBranch",
     usage:
-      "branch create [branchName] [--issue KEY] [--project KEY]" +
+      "branch create [branchName] [--issue KEY] [--from <branch>] [--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)",
+      " branchName is only a fallback; an existing branch is reused; --from picks the remote" +
+      " branch to start from instead of the repo's configured base branch)",
     buildArgs: ([branchName], flags, context = {}) => {
       const issueKey = templateIssueKey(branchName, flags, context);
+      const from = toBranch("from", flags.from);
 
       if (!branchName && !issueKey) {
         throw new UsageError("branch create needs an issue key (--issue) or a <branchName>.");
       }
 
-      return [branchName, issueKey];
+      return from === undefined ? [branchName, issueKey] : [branchName, issueKey, from];
     },
   },
   "branch resolve": {
@@ -191,9 +194,14 @@ const COMMANDS = {
     method: "POST",
     retryUnsafe: true,
     action: "commitByTemplate",
+    // Pushing is permanent; a local-only commit is not.
+    destructive: (flags) => !flags["no-push"],
     usage:
-      'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] [--issue KEY] [--project KEY]' +
-      " (--values keys fill the project's commit template, default" +
+      'commit template <worktreePath> [--values \'{"key":"val"}\'] [--include-untracked]' +
+      " [--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" +
       ' "{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; commits the worktree's checked-out branch, so check out the" +
@@ -204,7 +212,9 @@ const COMMANDS = {
       const values = toValues("values", flags.values);
       const push = flags["no-push"] ? false : undefined;
 
-      return [worktreePath, values, push];
+      return flags["include-untracked"]
+        ? [worktreePath, values, push, true]
+        : [worktreePath, values, push];
     },
   },
 
@@ -215,8 +225,8 @@ const COMMANDS = {
     usage:
       "mr create <title> [headBranch] [--body <text>] [--base <branch>] [--type <idOrLabel>]" +
       " [--issue KEY] [--project KEY]" +
-      " (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;" +
+      " (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)",
     buildArgs: ([title, headBranch], flags, context = {}) => {
@@ -328,23 +338,27 @@ const COMMANDS = {
     action: "updatePullRequest",
     usage:
       "mr update <prId> [--title <text>] [--description <text> | --append-description <text>]" +
-      " [--issue KEY] [--project KEY]" +
+      " [--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)",
+      " and is skipped if it already ends the description after that rule; --base retargets" +
+      " the PR/MR to an existing remote branch)",
     buildArgs: ([prId], flags) => {
       const title = toText("title", flags.title);
       const body = toRawText("description", flags.description);
       const appendBody = toRawText("append-description", flags["append-description"]);
+      const baseBranch = toBranch("base", flags.base);
 
-      if (title === undefined && body === undefined && appendBody === undefined) {
-        throw new UsageError("mr update needs --title, --description or --append-description.");
+      if ([title, body, appendBody, baseBranch].every((value) => value === undefined)) {
+        throw new UsageError(
+          "mr update needs --title, --description, --append-description or --base.",
+        );
       }
 
       if (body !== undefined && appendBody !== undefined) {
         throw new UsageError("mr update takes --description or --append-description, not both.");
       }
 
-      return [toInt("prId", prId), { title, body, appendBody }];
+      return [toInt("prId", prId), { title, body, appendBody, baseBranch }];
     },
   },
   "mr types": {
@@ -421,6 +435,17 @@ const COMMANDS = {
   },
 };
 
+/**
+ * Does this invocation of `command` need --force/--yes?
+ * @param {Command} command
+ * @param {Record<string, unknown>} flags
+ */
+export function isDestructiveCommand(command, flags) {
+  return typeof command.destructive === "function"
+    ? command.destructive(flags)
+    : command.destructive === true;
+}
+
 /** Every command key (for help / discovery). */
 export function listCommands() {
   return Object.keys(COMMANDS);

package/src/contextResolver.js

@@ -159,7 +159,8 @@ function fill(resolved, source, origin) {
  * @param {{ projectKey?: string, issueKey?: string, repo?: string, profile?: string }} [options.explicit]
  * @param {Record<string, string | undefined>} [options.env]
  * @param {string} [options.cwd]
- * @param {(args: string[]) => string | null} [options.runGit]
+ * @param {((args: string[]) => string | null) | null} [options.runGit] `null` = git is not
+ *   allowed in `cwd`, so only the path is matched
  * @param {(q: { cwd?: string, remote?: string, branch?: string }) => Promise<object | null>} [options.queryContext]
  * @returns {Promise<{
  *   projectKey?: string, issueKey?: string, repo?: string, baseBranch?: string,
@@ -190,9 +191,9 @@ export async function resolveContext({
   fill(resolved, readEnvContext(env), "env");
 
   // An explicit issue key implies its project, but only if nothing better said so.
-  const git = readGitFacts(runGit);
+  const git = runGit ? readGitFacts(runGit) : {};
 
-  if (!git.root && clean(cwd)) {
+  if (runGit && !git.root && clean(cwd)) {
     resolved.warnings.push(`${cwd} is not inside a git repository; inferring from the path only.`);
   }
 

package/src/gatewayChallenge.js

@@ -0,0 +1,94 @@
+// GENERATED FILE — do not edit.
+// Source of truth: shared/gatewayChallenge.js. Regenerate with:
+//   node scripts/sync-context-resolver.mjs
+
+// Mutual-auth challenge for the loopback gateway. Loopback ports aren't per-user,
+// so before a client sends its Bearer token it makes the listener prove it already
+// holds that token: client nonce in, HMAC(token, nonce) out.
+
+import crypto from "node:crypto";
+
+/** Unauthenticated route that answers the challenge. */
+export const CHALLENGE_PATH = "/auth/challenge";
+
+const PROOF_CONTEXT = "devflow-gateway-challenge-v1:";
+const NONCE_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+const DEFAULT_CHALLENGE_TIMEOUT_MS = 5_000;
+
+/** A fresh URL-safe 256-bit nonce. */
+function createNonce() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+/** Is `nonce` a well-formed client nonce? */
+export function isValidNonce(nonce) {
+  return typeof nonce === "string" && NONCE_PATTERN.test(nonce);
+}
+
+/**
+ * The proof a token holder returns for `nonce`.
+ * @param {string} token
+ * @param {string} nonce
+ * @returns {string}
+ */
+export function computeProof(token, nonce) {
+  return crypto
+    .createHmac("sha256", token)
+    .update(PROOF_CONTEXT + nonce)
+    .digest("base64url");
+}
+
+/**
+ * Constant-time string comparison; false for any non-string.
+ * @param {unknown} provided
+ * @param {string} expected
+ * @returns {boolean}
+ */
+export function safeEqual(provided, expected) {
+  if (typeof provided !== "string") return false;
+
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+/** The listener at `baseUrl` could not prove it holds the token; the token was not sent. */
+export class UntrustedGatewayError extends Error {
+  /** @param {string} baseUrl */
+  constructor(baseUrl) {
+    super(
+      `The process listening at ${baseUrl} could not prove it holds the DevFlow gateway ` +
+        `token, so the token was not sent. Another program may own the port, the token ` +
+        `may be stale (restart the DevFlow desktop app), or the app may need updating.`,
+    );
+    this.name = "UntrustedGatewayError";
+    this.code = "GATEWAY_UNTRUSTED";
+  }
+}
+
+/**
+ * Challenge the gateway at `baseUrl` and resolve only if it proves it holds `token`.
+ * Transport failures (e.g. ECONNREFUSED) reject as-is so callers keep their own messaging.
+ * @param {string} baseUrl e.g. `http://127.0.0.1:8787`
+ * @param {string} token
+ * @param {{ timeoutMs?: number }} [options]
+ * @returns {Promise<void>}
+ * @throws {UntrustedGatewayError} when the proof is missing or wrong
+ */
+export async function verifyGateway(baseUrl, token, options = {}) {
+  const nonce = createNonce();
+  const response = await fetch(`${baseUrl}${CHALLENGE_PATH}?nonce=${nonce}`, {
+    signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_CHALLENGE_TIMEOUT_MS),
+  });
+
+  let proof;
+
+  try {
+    proof = (await response.json())?.result?.proof;
+  } catch {
+    proof = undefined;
+  }
+
+  if (!safeEqual(proof, computeProof(token, nonce))) throw new UntrustedGatewayError(baseUrl);
+}

package/src/gitFacts.js

@@ -7,17 +7,50 @@
 // fake runner. Generated copies ship inside cli/ and mcp/ — edit THIS file only.
 
 import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 /** Hard ceiling so a wedged git can never hang a CLI invocation. */
 const GIT_TIMEOUT_MS = 2000;
 
+/** Config that keeps a repo's own settings from running hooks, a monitor, or a transport. */
+const SAFE_GIT_CONFIG = [
+  "-c",
+  "core.hooksPath=/dev/null",
+  "-c",
+  "core.fsmonitor=false",
+  "-c",
+  "protocol.allow=never",
+];
+
+/** Mirrors the desktop host's per-user worktree root (desktop/src/handlers/git/worktree.js). */
+function managedWorktreeRoot() {
+  const uid = process.getuid?.() ?? null;
+  const dirName = uid == null ? "devflow-worktrees" : `devflow-worktrees-${uid}`;
+
+  return path.join(fs.realpathSync(os.tmpdir()), dirName);
+}
+
+/**
+ * True when `dir` (already realpath'd) is inside a DevFlow-managed worktree.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function isManagedWorktreePath(dir) {
+  const relative = path.relative(managedWorktreeRoot(), dir);
+
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
 /**
  * Build a read-only, non-interactive git runner rooted at `cwd`.
  *
  * Every invocation is incapable of blocking on input: `--no-pager` rules out a
  * pager, `GIT_TERMINAL_PROMPT=0` and an empty `GIT_ASKPASS`/`SSH_ASKPASS` stop a
- * credential helper prompting, and stdin is closed. A non-repo directory or any
- * other failure yields `null` rather than throwing.
+ * credential helper prompting, and stdin is closed. {@link SAFE_GIT_CONFIG} turns
+ * off hooks, fsmonitor and transports. A non-repo directory or any other failure
+ * yields `null` rather than throwing.
  *
  * @param {string} cwd
  * @returns {(args: string[]) => string | null} stdout (trimmed), or null on failure
@@ -25,7 +58,7 @@ const GIT_TIMEOUT_MS = 2000;
 export function createGitRunner(cwd) {
   return (args) => {
     try {
-      const stdout = execFileSync("git", ["--no-pager", ...args], {
+      const stdout = execFileSync("git", [...SAFE_GIT_CONFIG, "--no-pager", ...args], {
         cwd: cwd || process.cwd(),
         encoding: "utf8",
         timeout: GIT_TIMEOUT_MS,