@tryarcanist/cli 0.1.167 → 0.1.169

package/README.md

@@ -53,9 +53,12 @@ Supported environment variables:
 ```bash
 export ARCANIST_TOKEN=arc_...
 export ARCANIST_API_URL=https://api.tryarcanist.com
+export ARCANIST_HTTP_TIMEOUT_MS=30000
 ```
 
 `--token` and `--api-url` are available for one-off invocations. Prefer `ARCANIST_TOKEN` over `--token` for persistent use; CLI flags can appear in shell history and process lists.
+Each HTTP request times out after `ARCANIST_HTTP_TIMEOUT_MS` milliseconds, default `30000`.
+The value must be between `1000` and `600000`; invalid values fail closed instead of falling back silently.
 
 Non-local API URLs must use HTTPS and must not embed credentials.
 
@@ -89,10 +92,18 @@ With `--json`, successful command output is machine-readable and newline-termina
 
 ```json
 {
-  "error": { "code": "auth", "message": "Not logged in.", "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`." }
+  "error": {
+    "code": "auth",
+    "message": "Not logged in.",
+    "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`.",
+    "data": { "serverCode": "token_revoked" }
+  }
 }
 ```
 
+`error.data` is omitted when there is no structured recovery data.
+Stable fields are `serverCode` for server-provided error codes and `sessionId`/`sessionUrl` when `sessions create` created the session but failed to enqueue the prompt.
+
 Exit codes:
 
 ```text
@@ -105,7 +116,7 @@ Exit codes:
 130 interrupted
 ```
 
-Mutation commands send an `Idempotency-Key` header. The CLI does not auto-retry mutation endpoints; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. `--idempotency-key` is available on `sessions create` and `sessions send`.
+Mutation commands send an `Idempotency-Key` header. The CLI does not auto-retry mutation endpoints; retry explicitly with the same `--idempotency-key` when a request may have already reached the server. `--idempotency-key` is available on `sessions create`, `sessions send`, `tokens create`, and `sandbox build`. `tokens create` and `sandbox build` use auto-random keys by default, so only an explicit key makes cross-invocation retries safe.
 
 ## Commands
 
@@ -349,6 +360,7 @@ Creates a CLI token and prints the plaintext token exactly once.
 ```bash
 arcanist tokens create --scope read
 arcanist tokens create --scope read --expires-in-days 30 --json
+arcanist tokens create --scope read --idempotency-key 1f0e6f1a-...
 ```
 
 Read-scoped tokens cannot create write-scoped tokens; the server enforces that and returns 403.

package/dist/index.js

@@ -24,6 +24,7 @@ var CliError = class extends Error {
   exitCode;
   hint;
   requestId;
+  data;
   constructor(code, message, options = {}) {
     super(message);
     this.name = "CliError";
@@ -31,17 +32,20 @@ var CliError = class extends Error {
     this.exitCode = options.exitCode ?? exitCodeForErrorCode(code);
     this.hint = options.hint;
     this.requestId = options.requestId;
+    this.data = options.data;
   }
 };
 var ApiError = class extends CliError {
   status;
   body;
-  constructor(status, body, requestId) {
+  constructor(status, body, requestId, resourceNoun) {
     const code = codeForHttpStatus(status);
-    super(code, messageForApiError(status, body), {
+    const parsed = parseApiErrorBody(body);
+    super(code, messageForApiError(status, body, parsed), {
       exitCode: exitCodeForHttpStatus(status),
-      hint: hintForHttpStatus(status),
-      requestId
+      hint: hintForHttpStatus(status, resourceNoun),
+      requestId,
+      data: parsed?.serverCode ? { serverCode: parsed.serverCode } : void 0
     });
     this.name = "ApiError";
     this.status = status;
@@ -73,9 +77,9 @@ function codeForHttpStatus(status) {
 function exitCodeForHttpStatus(status) {
   return exitCodeForErrorCode(codeForHttpStatus(status));
 }
-function messageForApiError(status, body) {
-  const parsed = parseApiErrorBody(body);
-  if (parsed) return parsed;
+function messageForApiError(status, body, parsed = parseApiErrorBody(body)) {
+  if (parsed?.message) return parsed.message;
+  if (parsed?.serverCode) return parsed.serverCode;
   return body ? `API error ${status}: ${body}` : `API error ${status}`;
 }
 function parseApiErrorBody(body) {
@@ -83,14 +87,36 @@ function parseApiErrorBody(body) {
     const parsed = JSON.parse(body);
     if (!parsed || typeof parsed !== "object") return null;
     const error = parsed.error;
-    return typeof error === "string" && error.length > 0 ? error : null;
+    if (typeof error === "string" && error.length > 0) {
+      const message2 = parsed.message;
+      const code = parsed.code;
+      return {
+        serverCode: typeof code === "string" && code ? code : error,
+        ...typeof message2 === "string" && message2 ? { message: message2 } : { message: error }
+      };
+    }
+    if (error && typeof error === "object") {
+      const code = error.code;
+      const message2 = error.message;
+      return {
+        ...typeof message2 === "string" && message2 ? { message: message2 } : {},
+        ...typeof code === "string" && code ? { serverCode: code } : {}
+      };
+    }
+    const message = parsed.message;
+    return typeof message === "string" && message.length > 0 ? { message } : null;
   } catch {
     return null;
   }
 }
-function hintForHttpStatus(status) {
+function hintForHttpStatus(status, resourceNoun) {
   if (status === 401 || status === 403) return "Run `arcanist auth login` or set `ARCANIST_TOKEN`.";
-  if (status === 404) return "List sessions with `arcanist sessions list`.";
+  if (status === 404) {
+    if (resourceNoun === "token") return "List tokens with `arcanist tokens list`.";
+    if (resourceNoun === "sandbox") return "Check sandbox state with `arcanist sandbox status`.";
+    if (resourceNoun === "repo") return "Check accessible repositories with `arcanist repos list`.";
+    return "List sessions with `arcanist sessions list`.";
+  }
   if (status === 409) return "Check the current resource state and retry the command when it is ready.";
   if (status >= 500) return "Retry later or check the control-plane logs.";
   return void 0;
@@ -106,7 +132,8 @@ function formatJsonError(err) {
       code: err.code,
       message: err.message,
       ...err.hint ? { hint: err.hint } : {},
-      ...err.requestId ? { requestId: err.requestId } : {}
+      ...err.requestId ? { requestId: err.requestId } : {},
+      ...err.data ? { data: err.data } : {}
     }
   });
 }
@@ -115,33 +142,72 @@ function formatJsonError(err) {
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var CLI_USER_AGENT = `arcanist-cli/${version}`;
-async function apiRequest(config, path, init) {
-  let res;
+var DEFAULT_HTTP_TIMEOUT_MS = 3e4;
+var MIN_HTTP_TIMEOUT_MS = 1e3;
+var MAX_HTTP_TIMEOUT_MS = 6e5;
+var HTTP_TIMEOUT_ENV = "ARCANIST_HTTP_TIMEOUT_MS";
+function parseHttpTimeoutMs(env = process.env) {
+  const raw = env[HTTP_TIMEOUT_ENV];
+  if (!raw) return DEFAULT_HTTP_TIMEOUT_MS;
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be a positive integer between 1000 and 600000.`);
+  }
+  const value = Number(raw);
+  if (value < MIN_HTTP_TIMEOUT_MS || value > MAX_HTTP_TIMEOUT_MS) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be between 1000 and 600000 milliseconds.`);
+  }
+  return value;
+}
+function isAbortError(err) {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+function timeoutError(timeoutMs) {
+  return new CliError("server", `Network timeout after ${timeoutMs}ms.`, {
+    hint: `Increase ${HTTP_TIMEOUT_ENV} for slow links, or check the API connection.`
+  });
+}
+async function apiRequest(config, path, init, read) {
+  const timeoutMs = parseHttpTimeoutMs();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const headers = new Headers(init?.headers);
     headers.set("Content-Type", "application/json");
     headers.set("User-Agent", CLI_USER_AGENT);
     headers.set("Authorization", `Bearer ${config.token}`);
-    res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
+    const res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
       ...init,
-      headers
+      headers,
+      signal: controller.signal
     });
+    if (!res.ok) {
+      const body = await res.text().catch((err) => {
+        if (isAbortError(err)) throw timeoutError(timeoutMs);
+        return "";
+      });
+      throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0, resourceNounForPath(path));
+    }
+    return await read(res);
   } catch (err) {
+    if (err instanceof CliError) throw err;
+    if (isAbortError(err)) throw timeoutError(timeoutMs);
     throw new CliError("server", `Network error: ${stringifyError(err)}`);
+  } finally {
+    clearTimeout(timeout);
   }
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0);
-  }
-  return res;
+}
+function resourceNounForPath(path) {
+  if (path.startsWith("/api/cli-tokens")) return "token";
+  if (path.startsWith("/api/repos")) return "repo";
+  if (path.startsWith("/api/sandbox")) return "sandbox";
+  if (path.startsWith("/api/sessions")) return "session";
+  return void 0;
 }
 async function apiFetch(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.json();
+  return apiRequest(config, path, init, (res) => res.json());
 }
 async function apiFetchText(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.text();
+  return apiRequest(config, path, init, (res) => res.text());
 }
 async function resolveBusinessId(config, options) {
   if (options.business && options.business.trim()) return options.business.trim();
@@ -1126,8 +1192,9 @@ function isTerminalPhase(phase, _sessionKind) {
 }
 
 // src/constants/watch.ts
-var MIN_WATCH_POLL_INTERVAL_MS = 1;
+var MIN_WATCH_POLL_INTERVAL_MS = 250;
 var DEFAULT_WATCH_POLL_INTERVAL_MS = 1e3;
+var MAX_WATCH_POLL_INTERVAL_MS = 6e4;
 var WATCH_REPLAY_PAGE_SIZE = 200;
 function isWatchTerminal(phase) {
   return isTerminalPhase(phase);
@@ -2702,7 +2769,14 @@ function parsePollInterval(raw) {
   if (!/^\d+$/.test(raw)) {
     throw new CliError("user", "Polling interval must be a non-negative integer.");
   }
-  return Number(raw);
+  const value = Number(raw);
+  if (value < MIN_WATCH_POLL_INTERVAL_MS || value > MAX_WATCH_POLL_INTERVAL_MS) {
+    throw new CliError(
+      "user",
+      `Polling interval must be between ${MIN_WATCH_POLL_INTERVAL_MS} and ${MAX_WATCH_POLL_INTERVAL_MS} milliseconds.`
+    );
+  }
+  return value;
 }
 function parseNonNegativeInteger(raw, name, defaultValue) {
   if (!raw) return defaultValue;
@@ -2762,7 +2836,6 @@ async function watchCommand(sessionId, options, command) {
   const runtime = getRuntimeOptions(command, options);
   const config = requireConfig(runtime);
   const pollIntervalMs = parsePollInterval(options.pollInterval);
-  const effectivePollIntervalMs = Math.max(pollIntervalMs, MIN_WATCH_POLL_INTERVAL_MS);
   const initialAfterSequence = parseNonNegativeInteger(options.afterSequence, "--after-sequence", 0);
   const pageSize = parseNonNegativeInteger(options.limit, "--limit", WATCH_REPLAY_PAGE_SIZE);
   if (pageSize === 0) {
@@ -2845,7 +2918,7 @@ async function watchCommand(sessionId, options, command) {
         }
         break;
       }
-      await sleep(effectivePollIntervalMs);
+      await sleep(pollIntervalMs);
     }
   } finally {
     if (textOpen) process.stdout.write("\n");
@@ -3020,7 +3093,12 @@ async function createCommand(repoUrl, promptArg, options, command) {
       {
         exitCode: err instanceof CliError ? err.exitCode : void 0,
         hint: `Retry with: arcanist sessions send ${sessionId} --prompt-stdin`,
-        requestId: err instanceof CliError ? err.requestId : void 0
+        requestId: err instanceof CliError ? err.requestId : void 0,
+        data: {
+          ...err instanceof CliError && err.data ? err.data : {},
+          sessionId,
+          ...sessionData.sessionUrl ? { sessionUrl: sessionData.sessionUrl } : {}
+        }
       }
     );
   }
@@ -3232,16 +3310,16 @@ async function loginCommand(options, command) {
     console.log(`Logged in. API: ${apiUrl}`);
   }
   try {
-    const res = await fetch(`${apiUrl}/api/cli-tokens`, {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": CLI_USER_AGENT }
-    });
-    if (res.ok && !runtime.json && !runtime.quiet) {
-      console.log("Token verified.");
-    } else if (res.status === 401 && !runtime.json && !runtime.quiet) {
-      console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+    await apiFetch({ apiUrl, token }, "/api/cli-tokens");
+    if (!runtime.json && !runtime.quiet) console.log("Token verified.");
+  } catch (err) {
+    if (!runtime.json && !runtime.quiet) {
+      if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
+        console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+      } else {
+        console.warn("Warning: Could not reach API to verify token.");
+      }
     }
-  } catch {
-    if (!runtime.json && !runtime.quiet) console.warn("Warning: Could not reach API to verify token.");
   }
 }
 
@@ -4235,20 +4313,34 @@ async function sandboxBuildCommand(sourceRepoArg, options = {}, command) {
   const targetRepo = options.targetRepo ? parseRepoArg2(options.targetRepo, currentRepo) : null;
   const businessId = await resolveBusinessId(config, options);
   const ref = options.ref ?? currentRef();
-  const payload = await apiFetch(
-    config,
-    `/api/businesses/${encodeURIComponent(businessId)}/repos/${encodeURIComponent(sourceRepo.owner)}/${encodeURIComponent(
-      sourceRepo.repo
-    )}/sandbox-layer/build-requests`,
-    {
-      method: "POST",
-      body: JSON.stringify({
-        ref,
-        manifestPath,
-        ...targetRepo ? { targetRepo: { owner: targetRepo.owner, name: targetRepo.repo } } : {}
-      })
+  let payload;
+  try {
+    payload = await apiFetch(
+      config,
+      `/api/businesses/${encodeURIComponent(businessId)}/repos/${encodeURIComponent(sourceRepo.owner)}/${encodeURIComponent(
+        sourceRepo.repo
+      )}/sandbox-layer/build-requests`,
+      {
+        method: "POST",
+        headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
+        body: JSON.stringify({
+          ref,
+          manifestPath,
+          ...targetRepo ? { targetRepo: { owner: targetRepo.owner, name: targetRepo.repo } } : {}
+        })
+      }
+    );
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409 && err.data?.serverCode === "duplicate_request") {
+      throw new CliError(err.code, err.message, {
+        exitCode: err.exitCode,
+        requestId: err.requestId,
+        data: err.data,
+        hint: "Use the same --idempotency-key only for retrying the original sandbox build request."
+      });
     }
-  );
+    throw err;
+  }
   emit(command, options, payload, (buildPayload) => printBuildRequest(buildPayload.buildRequest));
   if (!options.wait && !options.follow) return;
   const json = isJson(command, options);
@@ -4416,6 +4508,9 @@ async function sandboxAssignRepoCommand(targetRepoArg, sourceRepoArg, options =
   });
 }
 async function sandboxUnassignDefaultCommand(options = {}, command) {
+  if (isJson(command, options) && options.yes !== true) {
+    throw new CliError("user", "`sandbox unassign default --json` requires --yes.");
+  }
   const { config } = resolveBusinessContext(command, options);
   const businessId = await resolveBusinessId(config, options);
   if (!options.yes) await confirmOrThrow("Clear the business default sandbox layer source?");
@@ -4427,6 +4522,9 @@ async function sandboxUnassignDefaultCommand(options = {}, command) {
   emit(command, options, payload, () => console.log("Cleared default sandbox layer source."));
 }
 async function sandboxUnassignRepoCommand(targetRepoArg, options = {}, command) {
+  if (isJson(command, options) && options.yes !== true) {
+    throw new CliError("user", "`sandbox unassign repo --json` requires --yes.");
+  }
   const { config } = resolveBusinessContext(command, options);
   const businessId = await resolveBusinessId(config, options);
   const targetRepo = parseRepoArg2(targetRepoArg, currentRepo);
@@ -4712,13 +4810,27 @@ async function createTokenCommand(options, command) {
   if (expiresInDays !== void 0 && (!Number.isInteger(expiresInDays) || expiresInDays <= 0)) {
     throw new CliError("user", "expiresInDays must be a positive integer.");
   }
-  const payload = await apiFetch(config, "/api/cli-tokens", {
-    method: "POST",
-    body: JSON.stringify({
-      scope: options.scope ?? "read",
-      ...expiresInDays !== void 0 ? { expiresInDays } : {}
-    })
-  });
+  let payload;
+  try {
+    payload = await apiFetch(config, "/api/cli-tokens", {
+      method: "POST",
+      headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
+      body: JSON.stringify({
+        scope: options.scope ?? "read",
+        ...expiresInDays !== void 0 ? { expiresInDays } : {}
+      })
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409 && err.data?.serverCode === "duplicate_request") {
+      throw new CliError(err.code, err.message, {
+        exitCode: err.exitCode,
+        requestId: err.requestId,
+        data: err.data,
+        hint: "Use a new --idempotency-key for a new token, or retry the original command only if the first result was lost."
+      });
+    }
+    throw err;
+  }
   emit(command, options, payload, (tokenPayload) => {
     console.log(`Token: ${String(tokenPayload.token)}`);
     console.log(`ID: ${String(tokenPayload.id)}`);
@@ -4984,7 +5096,7 @@ Examples:
 var sandbox = program.command("sandbox").description("Sandbox layer commands");
 sandbox.command("init").description("Create sandbox layer source files").action((options, command) => sandboxInitCommand(options, command));
 sandbox.command("validate").description("Validate local sandbox layer source files").option("--manifest <path>", "Manifest path", ".arcanist/sandbox.yaml").action((options, command) => sandboxValidateCommand(options, command));
-sandbox.command("build").description("Build a repo-sourced sandbox layer").argument("[source-repo]", "Source repository owner/name; defaults to current git remote").option("--manifest <path>", "Manifest path", ".arcanist/sandbox.yaml").option("--ref <ref>", "Git ref to build").option("--target-repo <repo>", "Target repository owner/name for resource-profile coverage").option("--business <id>", "Business ID; defaults to authenticated user's business").option("--wait", "Wait for the build to finish").option("--follow", "Follow logs while waiting").option("--poll-interval <ms>", "Polling interval in milliseconds").action((sourceRepo, options, command) => sandboxBuildCommand(sourceRepo, options, command));
+sandbox.command("build").description("Build a repo-sourced sandbox layer").argument("[source-repo]", "Source repository owner/name; defaults to current git remote").option("--manifest <path>", "Manifest path", ".arcanist/sandbox.yaml").option("--ref <ref>", "Git ref to build").option("--target-repo <repo>", "Target repository owner/name for resource-profile coverage").option("--business <id>", "Business ID; defaults to authenticated user's business").option("--wait", "Wait for the build to finish").option("--follow", "Follow logs while waiting").option("--poll-interval <ms>", "Polling interval in milliseconds").option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").action((sourceRepo, options, command) => sandboxBuildCommand(sourceRepo, options, command));
 sandbox.command("status").description("Show sandbox layer status").argument("[repo]", "Repository owner/name; defaults to current git remote").option("--business <id>", "Business ID; defaults to authenticated user's business").action((repo, options, command) => sandboxStatusCommand(repo, options, command));
 sandbox.command("history").description("Show sandbox layer build history").argument("[source-repo]", "Source repository owner/name; defaults to current git remote").option("--business <id>", "Business ID; defaults to authenticated user's business").option("--target-repo <repo>", "Target repository owner/name for resource-profile coverage").option("--status <status>", "Filter by build status").option("--limit <n>", "Maximum builds to return").action((sourceRepo, options, command) => sandboxHistoryCommand(sourceRepo, options, command));
 sandbox.command("logs").description("Print sandbox layer build logs").argument("<build-id>", "Build ID").option("--business <id>", "Business ID; defaults to authenticated user's business").option("--follow", "Follow logs").option("--after-sequence <n>", "Return logs after this sequence").option("--limit <n>", "Maximum log chunks to return").option("--poll-interval <ms>", "Polling interval in milliseconds").action((buildId, options, command) => sandboxLogsCommand(buildId, options, command));
@@ -5006,7 +5118,7 @@ egress.command("sync").description("Apply the merged egress allowlist source fil
 egress.command("validate").description("Validate a local egress allowlist source file").argument("[path]", "Path to validate", ".arcanist/egress-allowlist.txt").action((path, options, command) => egressValidateCommand(path, options, command));
 var tokens = program.command("tokens").description("CLI token commands");
 tokens.command("list").description("List CLI tokens").option("--limit <n>", "Maximum tokens to return").option("--cursor <cursor>", "Pagination cursor").action((options, command) => listTokensCommand(options, command));
-tokens.command("create").description("Create a CLI token and print it once").option("--scope <scope>", "Token scope: read or write", "read").option("--expires-in-days <days>", "Token expiry in days").addHelpText(
+tokens.command("create").description("Create a CLI token and print it once").option("--scope <scope>", "Token scope: read or write", "read").option("--expires-in-days <days>", "Token expiry in days").option("--idempotency-key <uuid>", "Request idempotency key for safe manual retries").addHelpText(
   "after",
   `
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.167",
+  "version": "0.1.169",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {