@tryarcanist/cli 0.1.291 → 0.1.292

package/README.md

@@ -120,6 +120,18 @@ Mutation commands send an `Idempotency-Key` header. The CLI does not auto-retry
 
 ## Commands
 
+### `arcanist environments prepare|status`
+
+Prepare the current repository for Zeus, or inspect its machine-readable setup state. Pass `owner/repo` outside a checkout. A write-scoped token is required to prepare; read-scoped tokens can inspect status.
+
+```bash
+arcanist environments prepare --wait --json
+arcanist environments status owner/repo --json
+arcanist environments retry owner/repo --wait --json
+```
+
+Agents should follow `repository.nextAction` and request a Zeus review only when it is `review`. The command waits through internal handoffs until setup is ready or there is a real action for the user or Arcanist.
+
 ### `arcanist auth login`
 
 ```bash

package/dist/index.js

@@ -7404,18 +7404,25 @@ function parseApiErrorBody(body) {
   try {
     const parsed = JSON.parse(body);
     if (!parsed || typeof parsed !== "object") return null;
+    const details = parsed;
+    const recovery = {
+      ...typeof details.repository === "string" ? { repository: details.repository } : {},
+      ...typeof details.environmentsUrl === "string" ? { environmentsUrl: details.environmentsUrl } : {}
+    };
     const envelope = parseApiErrorEnvelope(parsed);
     if (!envelope) return null;
     if (typeof envelope.raw === "string" && envelope.raw) {
       return {
         ...envelope.code ? { serverCode: envelope.code } : {},
         rawError: envelope.raw,
-        ...envelope.message ? { message: envelope.message } : {}
+        ...envelope.message ? { message: envelope.message } : {},
+        ...recovery
       };
     }
     return envelope.message || envelope.code ? {
       ...envelope.message ? { message: envelope.message } : {},
-      ...envelope.code ? { serverCode: envelope.code, rawError: envelope.code } : {}
+      ...envelope.code ? { serverCode: envelope.code, rawError: envelope.code } : {},
+      ...recovery
     } : null;
   } catch {
     return null;
@@ -7462,9 +7469,13 @@ var ApiError = class extends CliError {
     const parsed = parseApiErrorBody(body);
     super(code, messageForApiError(status, body, parsed), {
       exitCode: exitCodeForHttpStatus(status),
-      hint: hintForHttpStatus(status, resourceNoun),
+      hint: hintForHttpStatus(status, resourceNoun, parsed),
       requestId,
-      data: parsed?.serverCode ? { serverCode: parsed.serverCode } : void 0
+      data: parsed?.serverCode || parsed?.repository || parsed?.environmentsUrl ? {
+        ...parsed.serverCode ? { serverCode: parsed.serverCode } : {},
+        ...parsed.repository ? { repository: parsed.repository } : {},
+        ...parsed.environmentsUrl ? { environmentsUrl: parsed.environmentsUrl } : {}
+      } : void 0
     });
     this.name = "ApiError";
     this.status = status;
@@ -7501,13 +7512,21 @@ function messageForApiError(status, body, parsed = parseApiErrorBody(body)) {
   if (parsed?.serverCode) return parsed.serverCode;
   return body ? `API error ${status}: ${body}` : `API error ${status}`;
 }
-function hintForHttpStatus(status, resourceNoun) {
+function hintForHttpStatus(status, resourceNoun, parsed) {
   if (status === 401 || status === 403) return "Run `arcanist auth login` or set `ARCANIST_TOKEN`.";
   if (status === 404) {
     if (resourceNoun === "token") return "List tokens with `arcanist tokens list`.";
     if (resourceNoun === "repo") return "Check accessible repositories with `arcanist repos list`.";
     return "List sessions with `arcanist sessions list`.";
   }
+  if (status === 409 && parsed?.repository) {
+    if (parsed.serverCode === "environment_required") {
+      return `Run \`arcanist environments prepare ${parsed.repository} --wait\`, then retry the review.`;
+    }
+    if (parsed.serverCode === "environment_preparing" || parsed.serverCode === "environment_needs_attention") {
+      return `Run \`arcanist environments status ${parsed.repository} --wait\` for the latest setup state.`;
+    }
+  }
   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;
@@ -8549,6 +8568,105 @@ async function egressValidateCommand(path = EGRESS_ALLOWLIST_SOURCE_PATH, option
   });
 }
 
+// src/commands/environments.ts
+var SETUP_POLL_INTERVAL_MS = 5e3;
+var SETUP_WAIT_TIMEOUT_MS = 2 * 60 * 60 * 1e3;
+function requestedRepo(repoArg) {
+  const repo = parseRepoArgOrCurrent(repoArg);
+  return { ...repo, fullName: `${repo.owner}/${repo.repo}` };
+}
+async function fetchSetupState(config, fullName) {
+  const response = await apiFetch(config, "/api/settings/repositories/onboarding");
+  const state = response.repositories.find((item) => item.fullName.toLowerCase() === fullName.toLowerCase()) ?? {
+    fullName,
+    status: "not_started",
+    stage: null
+  };
+  return { ...state, nextAction: nextAction(state) };
+}
+function isActive(state) {
+  return state.nextAction === "wait";
+}
+function nextAction(state) {
+  if (state.status === "not_started") return "prepare";
+  if (state.status === "ready") return "review";
+  if (state.secretRequest) return "add_credentials";
+  if (state.question) return "answer_question";
+  if (state.status === "failed") {
+    return state.failureReason === "installation_missing" ? "authorize_github" : "retry";
+  }
+  if (state.status === "escalated" && state.stage !== "escalated_to_customer" && state.stage !== "question_for_customer") {
+    return "wait_for_arcanist";
+  }
+  return "wait";
+}
+function printState(state) {
+  const detail = state.failureReason ?? state.stage ?? state.buildStatus ?? state.nextAction;
+  console.log(
+    `${sanitizeTerminalText(state.fullName)}: ${sanitizeTerminalText(state.status)}${detail ? ` (${sanitizeTerminalText(detail)})` : ""}`
+  );
+}
+async function waitForSetup(config, fullName, pollIntervalMs) {
+  return pollUntilSettled({
+    pollIntervalMs,
+    timeoutMs: SETUP_WAIT_TIMEOUT_MS,
+    timeoutMessage: `Timed out waiting for ${fullName} environment setup.`,
+    fetchStatus: async () => {
+      const state = await fetchSetupState(config, fullName);
+      return isActive(state) ? null : state;
+    }
+  });
+}
+async function environmentStatusCommand(repoArg, options = {}, command) {
+  const pollIntervalMs = options.wait ? parsePollInterval(options.pollInterval, { defaultMs: SETUP_POLL_INTERVAL_MS, maxMs: null }) : null;
+  const repo = requestedRepo(repoArg);
+  const { config } = resolveBusinessContext(command, options);
+  await apiFetch(config, "/api/repos");
+  const state = options.wait ? await waitForSetup(config, repo.fullName, pollIntervalMs ?? SETUP_POLL_INTERVAL_MS) : await fetchSetupState(config, repo.fullName);
+  emit(command, options, { repository: state }, ({ repository }) => printState(repository));
+}
+async function environmentPrepareCommand(repoArg, options = {}, command) {
+  const pollIntervalMs = options.wait ? parsePollInterval(options.pollInterval, { defaultMs: SETUP_POLL_INTERVAL_MS, maxMs: null }) : null;
+  const repo = requestedRepo(repoArg);
+  const { config } = resolveBusinessContext(command, options);
+  const response = await apiFetch(config, "/api/settings/repositories/onboarding", {
+    method: "POST",
+    body: JSON.stringify({ repositories: [{ owner: repo.owner, name: repo.repo }] })
+  });
+  const result = response.repositories[0];
+  if (!result) throw new CliError("server", "Environment setup returned no repository result.");
+  if (result.status === "forbidden") {
+    throw new CliError("auth", `You must have write access to ${repo.fullName} to prepare its environment.`);
+  }
+  if (result.status === "failed") {
+    throw new CliError("server", `Environment setup could not be started for ${repo.fullName}.`);
+  }
+  if (options.wait && (result.status === "queued" || result.status === "already_queued")) {
+    const state2 = await waitForSetup(config, repo.fullName, pollIntervalMs ?? SETUP_POLL_INTERVAL_MS);
+    emit(command, options, { repository: state2 }, ({ repository }) => printState(repository));
+    return;
+  }
+  const state = {
+    fullName: result.fullName,
+    status: result.status === "already_ready" ? "ready" : "pending",
+    stage: null,
+    nextAction: result.status === "already_ready" ? "review" : "wait"
+  };
+  emit(command, options, { repository: state }, ({ repository }) => printState(repository));
+}
+async function environmentRetryCommand(repoArg, options = {}, command) {
+  const pollIntervalMs = options.wait ? parsePollInterval(options.pollInterval, { defaultMs: SETUP_POLL_INTERVAL_MS, maxMs: null }) : null;
+  const repo = requestedRepo(repoArg);
+  const { config } = resolveBusinessContext(command, options);
+  await apiFetch(
+    config,
+    `/api/settings/repositories/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}/onboarding/retry`,
+    { method: "POST" }
+  );
+  const state = options.wait ? await waitForSetup(config, repo.fullName, pollIntervalMs ?? SETUP_POLL_INTERVAL_MS) : await fetchSetupState(config, repo.fullName);
+  emit(command, options, { repository: state }, ({ repository }) => printState(repository));
+}
+
 // src/commands/hades.ts
 async function hadesCommand(repo, options = {}, command) {
   assertArcanistSessionMutationAllowed("hades");
@@ -12556,6 +12674,24 @@ JSON:
 JSON mode returns {skills}
 `
 ).action((repo, options, command) => repoSkillsCommand(repo, options, command));
+var environments = program.command("environments").description("Zeus environment setup commands");
+environments.command("prepare").description("Prepare a repository for Zeus reviews").argument("[repo]", "Repository owner/name; defaults to current git remote").option("--wait", "Wait until setup is ready or needs attention").option("--poll-interval <ms>", "Polling interval while waiting (default 5000)").addHelpText(
+  "after",
+  `
+Examples:
+  arcanist environments prepare
+  arcanist environments prepare owner/repo --wait --json
+`
+).action((repo, options, command) => environmentPrepareCommand(repo, options, command));
+environments.command("status").description("Show repository environment setup status").argument("[repo]", "Repository owner/name; defaults to current git remote").option("--wait", "Wait until setup is ready or needs attention").option("--poll-interval <ms>", "Polling interval while waiting (default 5000)").addHelpText(
+  "after",
+  `
+JSON:
+Returns {repository: {fullName, status, stage, nextAction, buildStatus?, failureReason?, secretRequest?, question?}}.
+The stable status values are not_started, pending, running, escalated, succeeded, failed, and ready.
+`
+).action((repo, options, command) => environmentStatusCommand(repo, options, command));
+environments.command("retry").description("Retry a failed repository environment setup").argument("[repo]", "Repository owner/name; defaults to current git remote").option("--wait", "Wait until setup is ready or needs attention").option("--poll-interval <ms>", "Polling interval while waiting (default 5000)").action((repo, options, command) => environmentRetryCommand(repo, options, command));
 var models = program.command("models").description("Model discovery commands");
 models.command("list").description("List session-start models").addHelpText(
   "after",

package/package.json

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