@devflow-one/cli 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-one/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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

@@ -93,6 +93,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,6 +119,7 @@ const COMMANDS = {
 
   "branch create": {
     method: "POST",
+    retryUnsafe: true,
     action: "createBranch",
     usage: "branch create <branchName> [--issue KEY] [--project KEY]",
     buildArgs: ([branchName]) => {
@@ -128,6 +130,7 @@ const COMMANDS = {
   },
   "branch delete": {
     method: "POST",
+    retryUnsafe: true,
     action: "deleteBranch",
     destructive: true,
     usage: "branch delete <branchName> [--issue KEY] [--project KEY] --force",
@@ -140,6 +143,7 @@ const COMMANDS = {
 
   "commit template": {
     method: "POST",
+    retryUnsafe: true,
     action: "commitByTemplate",
     usage:
       'commit template <worktreePath> [--values \'{"key":"val"}\'] [--no-push] [--issue KEY] [--project KEY]' +
@@ -159,6 +163,7 @@ const COMMANDS = {
 
   "mr create": {
     method: "POST",
+    retryUnsafe: true,
     action: "createPullRequest",
     usage:
       "mr create <title> <headBranch> [--body <text>] [--base <branch>] [--type <idOrLabel>]" +
@@ -199,6 +204,7 @@ const COMMANDS = {
   },
   "mr close": {
     method: "POST",
+    retryUnsafe: true,
     action: "closePullRequest",
     destructive: true,
     usage: "mr close <prId> [--issue KEY] [--project KEY] --force",
@@ -206,6 +212,7 @@ const COMMANDS = {
   },
   "mr merge": {
     method: "POST",
+    retryUnsafe: true,
     action: "mergePullRequest",
     destructive: true,
     usage:
@@ -309,6 +316,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 +337,7 @@ const COMMANDS = {
 
   "slack notify": {
     method: "POST",
+    retryUnsafe: true,
     action: "notifySlack",
     usage:
       'slack notify <message> [--channel ID] [--values \'{"key":"val"}\'] [--issue KEY] [--project KEY]',