hey-axi 0.2.0 → 0.3.1

package/src/policy.js

@@ -21,17 +21,29 @@ export const DRAFT_NOTICE = "Saved as a DRAFT. Nothing was sent. Pass --allow-se
 const SECRET_COMMANDS = new Set(["auth token"]);
 
 // How a command runs. Anything not listed is "json": captured, parsed, rendered as TOON.
-//   interactive: HEY gets the terminal (inherited stdio); nothing is injected or parsed
-//   stream:      long-running NDJSON, relayed line by line as it arrives
-//   raw:         prints non-JSON (a script, a CSV); relayed untouched
-const INTERACTIVE = new Set(["tui", "mcp", "auth login", "login", "setup", "setup agents", "setup claude", "setup codex", "setup omarchy", "upgrade"]);
-// Interactive commands that can't do anything useful without a terminal.
-const NEEDS_TTY = new Set(["tui"]);
+//   stream: long-running NDJSON, relayed event by event as it arrives (TOON, or NDJSON with --json)
+//   raw:    prints non-JSON (a script, a CSV); relayed untouched
+// Captured runs give HEY a closed stdin and HEY_NONINTERACTIVE=1, so it can never prompt.
 const STREAM = new Set(["watch"]);
 const RAW = new Set(["shell-completion generate"]);
 
+// Commands that only work with a person at a terminal (a full-screen UI, a browser
+// sign-in, a wizard) or that hand stdio to another program (an MCP server). hey-axi never
+// runs them by default, TTY or not, so nothing can stop and wait for input. They run
+// only with the explicit `--interactive` opt-in, which hands HEY the terminal; the
+// person-facing ones also need a real terminal on stdin and stdout.
+const USER_ONLY = {
+  tui: { reason: "it is a full-screen terminal UI", hint: "ask the user to run `hey-axi tui --interactive` in their own terminal" },
+  mcp: { reason: "it is a long-running MCP server that takes over stdin/stdout", hint: "to use it as an MCP server, register `hey-axi mcp --interactive` in the agent's MCP settings", tty: false },
+  setup: { reason: "it is the first-run wizard (browser sign-in and prompts)", hint: "ask the user to run `hey-axi setup --interactive` in their terminal; `hey-axi setup agents`, `setup claude` and `setup codex` run without prompts" },
+  "auth login": { reason: "it opens a browser and waits for the user", hint: "pass --token <token>, or ask the user to run `hey-axi auth login --interactive` in their terminal", unless: ["--token", "--cookie"] },
+  login: { reason: "it opens a browser and waits for the user", hint: "pass --token <token>, or ask the user to run `hey-axi login --interactive` in their terminal", unless: ["--token", "--cookie"] },
+};
+
+const personCommand = (path, flags) => Boolean(USER_ONLY[path]) && !USER_ONLY[path].unless?.some((flag) => flags.has(flag));
+
 export function runMode(path, flags) {
-  if (INTERACTIVE.has(path)) return "interactive";
+  if (personCommand(path, flags) && flags.has("--interactive")) return "interactive";
   if (STREAM.has(path)) return "stream";
   if (RAW.has(path)) return "raw";
   // CSV goes to stdout unless --output names a file (then HEY answers with JSON).
@@ -39,8 +51,140 @@ export function runMode(path, flags) {
   return "json";
 }
 
+export function userOnly(path, flags = new Set(), io = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
+  if (!personCommand(path, flags)) {
+    if (!flags.has("--interactive")) return null;
+    return { error: "--interactive does not apply here", command: path, reason: `only ${Object.keys(USER_ONLY).join(", ")} (without --token) take over the terminal`, hint: `run \`hey-axi ${path}\` without --interactive` };
+  }
+  const rule = USER_ONLY[path];
+  if (!flags.has("--interactive")) return { error: "needs the user", command: path, reason: rule.reason, hint: rule.hint };
+  if (rule.tty !== false && !(io.stdin && io.stdout)) {
+    return { error: "needs the user", command: path, reason: `${rule.reason}, and --interactive needs a terminal on stdin and stdout`, hint: rule.hint };
+  }
+  return null;
+}
+
+export function userOnlyPaths() {
+  return Object.keys(USER_ONLY);
+}
+
+// Commands that fall back to opening $EDITOR when no content is given. hey-axi requires
+// the content up front (exit 2) so nothing ever waits on an editor. `--message -` (and
+// --note -, --content -) reads the content from stdin.
+export const STDIN_VALUE_FLAGS = ["--message", "-m", "--message-html", "--note", "--note-html", "--content", "--content-html"];
+const DATE_LIKE = /^(\d{4}-\d{2}-\d{2}|today|yesterday|tomorrow|(last|next|this)[ _-]\w+|mon|tue|wed|thu|fri|sat|sun)\w*$/i;
+const CONTENT = {
+  compose: { flags: ["--message", "-m", "--message-html", "--attach"], what: "a message", hint: "pass --message \"...\" (or --message - to read it from stdin)" },
+  reply: { flags: ["--message", "-m", "--message-html", "--attach", "--dry-run"], what: "a message", hint: "pass --message \"...\" (or --message - to read it from stdin); --dry-run previews without one" },
+  "bulk-reply send": { flags: ["--message", "-m", "--message-html", "--attach"], what: "a message", hint: "pass --message \"...\" (or --message - to read it from stdin)" },
+  "contact note set": { flags: ["--note", "--note-html"], positional: (words) => words.length >= 2, what: "the note", hint: "pass --note \"...\" (or the note as a second argument, or --note - for stdin)" },
+  "journal write": { flags: ["--content", "--content-html"], positional: (words) => words.length >= 2 || (words.length === 1 && !DATE_LIKE.test(words[0])), what: "the entry", hint: "pass --content \"...\" (or --content - to read it from stdin)" },
+  "draft edit": { own: true, what: "a field to change", hint: "pass the fields to change, e.g. --message \"...\" or --subject \"...\"" },
+};
+
+// Returns null, or a refusal when the command would open an editor.
+export function contentProblem(node, flags, positionals = []) {
+  const rule = CONTENT[node.path];
+  if (!rule) return null;
+  // Shorthands count as their long flag (`-n` is --note for contact note set).
+  const has = (name) => flags.has(name) || (node.flags || []).some((flag) => `--${flag.name}` === name && flag.shorthand && flags.has(`-${flag.shorthand}`));
+  if (rule.own) {
+    if ((node.flags || []).some((flag) => has(`--${flag.name}`))) return null;
+  } else if (rule.flags.some(has) || rule.positional?.(positionals)) return null;
+  return { error: `missing ${rule.what} for \`${node.path}\``, command: node.path, reason: "without it HEY would open an editor and wait", hint: rule.hint };
+}
+
+// Mutations whose desired end state may already hold. Only these commands can become a
+// no-op, and only when HEY's failure says that exact end state already holds (each
+// command has its own pattern; a generic "conflict" is not enough). Send, reply and read
+// commands never become no-ops. Deletes are idempotent too: deleting something that
+// is not there is a no-op.
+// Each delete, and the words HEY uses for its target. A not-found that names something
+// else ("calendar not found" for todo delete) is not a no-op.
+const DELETES = new Map([
+  ["draft delete", /\bdraft/i], ["event delete", /\bevent/i], ["todo delete", /\btodo/i], ["habit delete", /\bhabit/i],
+  ["clip delete", /\bclip/i], ["snippet delete", /\bsnippet/i], ["timetrack delete", /\b(time ?track|track|entry)/i],
+  ["timetrack category delete", /\bcategor/i], ["workflow delete", /\bworkflow/i], ["workflow stage delete", /\bstage/i],
+  ["set-aside group delete", /\bgroup/i], ["contact note delete", /\bnote/i],
+]);
+const GENERIC_NOT_FOUND = /^\s*(the )?((requested )?(resource|record|item|object) )?(was )?not found\.?\s*$|^\s*404\b/i;
+const ADDED = /\balready (in|on|has|have|added|labell?ed|a member|part of|belongs?)\b/i;
+const REMOVED = /\b(not (in|on|labell?ed|a member|part of)|already removed|isn'?t (in|on|labell?ed))\b/i;
+export const END_STATES = {
+  "todo complete": /\balready (been )?completed?\b/i,
+  "habit complete": /\balready (been )?completed?\b/i,
+  "todo uncomplete": /\b(already (incomplete|uncompleted|not completed?)|not (yet )?completed?)\b/i,
+  "habit uncomplete": /\b(already (incomplete|uncompleted|not completed?)|not (yet )?completed?)\b/i,
+  seen: /\balready (seen|read|marked (as )?(seen|read))\b/i,
+  unseen: /\balready (unseen|unread|marked (as )?(unseen|unread))\b/i,
+  move: /\balready in\b/i,
+  "label add": ADDED, "collection add": ADDED, "set-aside group add": ADDED, "workflow add": ADDED,
+  "label remove": REMOVED, "collection remove": REMOVED, "set-aside group remove": REMOVED, "workflow remove": REMOVED,
+  "screener approve": /\balready (screened in|approved)\b/i,
+  "screener deny": /\balready (screened out|denied)\b/i,
+  "screener clear": /\b(already cleared|not screened)\b/i,
+  "contact hide": /\balready hidden\b/i,
+  "contact show-again": /\b(already (shown|visible)|not hidden)\b/i,
+  "contact bundle": /\balready bundled\b/i,
+  "contact unbundle": /\b(already unbundled|not bundled)\b/i,
+  ignore: /\balready ignor/i,
+  "stop-ignoring": /\b(not ignor|already (unignored|not ignored))/i,
+  spam: /\balready (in |marked (as )?)?spam\b/i,
+  trash: /\balready (in (the )?)?trash(ed)?\b/i,
+  "bubble up": /\balready bubbled\b/i,
+  "bubble pop": /\b(already popped|not bubbled)\b/i,
+  "timetrack start": /\balready (running|started|tracking)\b/i,
+  "timetrack stop": /\bno (time ?track|timer|track)[^.]*running\b|\bnot running\b|\balready stopped\b/i,
+  "account use": /\balready (using|the default|selected)\b/i,
+  "config trust-local": /\balready trusted\b/i,
+  "config untrust-local": /\b(not trusted|already untrusted)\b/i,
+  share: /\balready shared\b/i,
+  unshare: /\b(not shared|already unshared)\b/i,
+};
+// Creates are not on the list: "already exists" doesn't say the existing one has the
+// settings asked for, so it stays an error the agent can check.
+
+// Commands whose end state names a destination: the failure must name the same one.
+const DESTINATION = { move: "to" };
+// Commands that add to / remove from a container given by a flag: a failure that names a
+// different container ("Already in label Other") is not a no-op for this one.
+const CONTAINER = {
+  "label add": "to", "collection add": "to", "set-aside group add": "to", "workflow add": "to",
+  "label remove": "from", "collection remove": "from", "set-aside group remove": "from", "workflow remove": "from",
+};
+const NAMED_CONTAINER = /\b(?:label|collection|group|workflow|box)\s+["'“]?([^\s"'”;,.]+)/gi;
+
+export function noopFor(path, failure, positionals = [], values = {}) {
+  const text = `${failure.error || ""} ${failure.hint || ""}`;
+  const target = positionals.length ? ` ${positionals.join(" ")}` : "";
+  if (DELETES.has(path) && failure.kind === "not_found" && (GENERIC_NOT_FOUND.test(failure.error || "") || DELETES.get(path).test(failure.error || ""))) {
+    return { ok: true, noop: true, command: path, result: `nothing to delete:${target || " it"} is already gone (no-op)`, note: "if you expected it to exist, check the id with the matching list command" };
+  }
+  const endState = END_STATES[path];
+  // Several targets: if HEY names some of them, it must name all of them.
+  const ids = positionals.filter((word) => /^\d+$/.test(word));
+  if (ids.length > 1) {
+    const named = ids.filter((id) => new RegExp(`\\b${id}\\b`).test(text));
+    if (named.length && named.length < ids.length) return null;
+  }
+  if (CONTAINER[path]) {
+    const wanted = String(values[CONTAINER[path]] ?? "").toLowerCase();
+    for (const match of text.matchAll(NAMED_CONTAINER)) {
+      if (!wanted || match[1].toLowerCase() !== wanted) return null;
+    }
+  }
+  const destination = DESTINATION[path] ? values[DESTINATION[path]] : undefined;
+  if (DESTINATION[path] && (!destination || !text.toLowerCase().includes(String(destination).toLowerCase()))) return null;
+  // A failure that also reports a failed part ("1 already seen; 2 failed") is not a no-op.
+  if (/\b(failed|cannot|can'?t|could ?n[o']t|unable|error)\b/i.test(failure.error || "")) return null;
+  if (endState && failure.kind !== "auth" && failure.kind !== "forbidden" && failure.kind !== "not_found" && endState.test(text)) {
+    return { ok: true, noop: true, command: path, result: `already done${target ? ` for${target}` : ""} (no-op)`, detail: failure.error };
+  }
+  return null;
+}
+
 export function interactivePaths() {
-  return [...INTERACTIVE];
+  return userOnlyPaths();
 }
 
 const truthy = (value) => ["1", "true", "yes"].includes(String(value || "").toLowerCase());
@@ -63,9 +207,8 @@ export function sendStaging(path, flags, env = process.env) {
 
 // Returns null when the command may run, or a structured refusal.
 export function checkPolicy(path, flags, env = process.env, io = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
-  if (NEEDS_TTY.has(path) && !(io.stdin && io.stdout)) {
-    return { error: "needs a terminal", command: path, reason: "interactive full-screen UI", hint: `run \`hey ${path}\` in a terminal` };
-  }
+  const person = userOnly(path, flags, io);
+  if (person) return person;
 
   if (SEND_COMMANDS.has(path)) {
     const rule = SEND_COMMANDS.get(path);

package/src/router.js

@@ -1,16 +1,17 @@
 // Data-driven command routing for hey-axi.
 //
-// The command tree comes from HEY's own `hey commands --json` catalog: a bundled
-// snapshot (src/manifest.json, refreshed with `npm run refresh-manifest`), plus
-// discovery from the installed binary at runtime when the snapshot doesn't know a
-// command.
+// The command tree comes from HEY's own `hey commands --json` catalog, bundled as
+// src/manifest.json (refreshed with `npm run refresh-manifest`). Routing never calls
+// HEY: an unknown command is rejected before any dependency runs.
 
 import { readFileSync } from "node:fs";
 
 const BOOLEAN_DEFAULTS = new Set(["true", "false"]);
 
-// Reduce HEY's catalog to what routing and help need.
-export function normalizeCatalog(nodes) {
+// Reduce HEY's catalog to what routing and help need. Every flag keeps its default,
+// including zero/false/empty ones, so `--help` can state each flag's default.
+// `types` maps "path --flag" to the value type HEY's --help prints (int, string, ...).
+export function normalizeCatalog(nodes, types = {}) {
   return (nodes || []).map((node) => {
     const out = { name: node.name, path: node.path || node.name, short: node.short || "" };
     if (node.compatibility_usage) out.usage = node.compatibility_usage;
@@ -20,13 +21,19 @@ export function normalizeCatalog(nodes) {
       .map((flag) => {
         const entry = { name: flag.name };
         if (flag.shorthand) entry.shorthand = flag.shorthand;
-        if (!BOOLEAN_DEFAULTS.has(String(flag.default))) entry.value = true;
+        const type = types[`${node.path || node.name} --${flag.name}`];
+        if (type ? type !== "count" : !BOOLEAN_DEFAULTS.has(String(flag.default))) {
+          entry.value = true;
+          // Flags HEY hides from --help have no printed type; they take a string.
+          entry.type = type || "string";
+        }
+        if (type === "count") entry.type = "count";
         if (flag.usage) entry.desc = flag.usage;
-        if (flag.default !== undefined && !["", "false", "[]", "0"].includes(String(flag.default))) entry.default = String(flag.default);
+        if (flag.default !== undefined) entry.default = String(flag.default);
         return entry;
       });
     if (flags.length) out.flags = flags;
-    if (node.subcommands?.length) out.subcommands = normalizeCatalog(node.subcommands);
+    if (node.subcommands?.length) out.subcommands = normalizeCatalog(node.subcommands, types);
     return out;
   });
 }
@@ -36,9 +43,11 @@ export function loadBundledManifest() {
 }
 
 // A group node can be invoked by itself when HEY documents a shortcut form for it
-// (`box <name|id>`, `label <id>`, ...) or when it takes flags of its own (`search`).
+// (`box <name|id>`, `label <id>`, ...), when it takes flags of its own (`search`), or
+// when its USAGE has a form without a subcommand (`hey set-aside [flags]`).
 export function isRunnable(node) {
-  return !node.subcommands?.length || Boolean(node.usage) || Boolean(node.flags?.length);
+  return !node.subcommands?.length || Boolean(node.usage) || Boolean(node.flags?.length)
+    || (node.synopsis || []).some((line) => !line.includes("<command>"));
 }
 
 // Resolve leading positional words to a command node.
@@ -80,3 +89,28 @@ export function listCommands(commands) {
   walk(commands);
   return paths;
 }
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const current = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length];
+}
+
+// Up to three command names close to a mistyped word, for "did you mean" help.
+export function closestNames(word, nodes) {
+  if (!word) return [];
+  return (nodes || [])
+    .map((node) => ({ name: node.name, score: node.name.startsWith(word) || word.startsWith(node.name) ? 0 : distance(word, node.name) }))
+    .filter(({ score }) => score <= Math.max(2, Math.floor(word.length / 3)))
+    .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
+    .slice(0, 3)
+    .map(({ name }) => name);
+}

package/src/scope.js

@@ -0,0 +1,177 @@
+// Directory scope for the home view and the session hook (AXI principle 7: show only
+// state relevant to the current directory). A `.hey-axi.json` in the working directory
+// or any parent focuses that tree on one box, label or search, and optionally one
+// linked account:
+//
+//   { "label": "Acme", "account": "12345", "limit": 10 }
+//
+// `hey-axi setup scope --label Acme` writes it; with no file the home view is the
+// account-wide Imbox and says so.
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { HOME_LIMIT } from "./guide.js";
+import { collapse } from "./home-path.js";
+
+export const SCOPE_FILE = ".hey-axi.json";
+const SOURCES = ["box", "label", "search"];
+const KEYS = new Set([...SOURCES, "account", "limit"]);
+
+export class ScopeError extends Error {}
+
+function validate(config, path) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) throw new ScopeError(`${collapse(path)} must hold a JSON object`);
+  const unknown = Object.keys(config).filter((key) => !KEYS.has(key));
+  if (unknown.length) throw new ScopeError(`${collapse(path)}: unknown key ${unknown.join(", ")} (allowed: ${[...KEYS].join(", ")})`);
+  const sources = SOURCES.filter((key) => config[key] !== undefined);
+  if (sources.length > 1) throw new ScopeError(`${collapse(path)}: use only one of ${SOURCES.join(", ")}`);
+  for (const key of [...SOURCES, "account"]) {
+    if (config[key] !== undefined && (typeof config[key] !== "string" || !config[key].trim())) throw new ScopeError(`${collapse(path)}: ${key} must be a non-empty string`);
+  }
+  if (config.limit !== undefined && !(Number.isInteger(config.limit) && config.limit > 0 && config.limit <= 100)) {
+    throw new ScopeError(`${collapse(path)}: limit must be a whole number from 1 to 100`);
+  }
+  return config;
+}
+
+// The nearest .hey-axi.json at or above `cwd`: { path, dir, config }, or null.
+export function findScope(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (;;) {
+    const path = join(dir, SCOPE_FILE);
+    if (existsSync(path)) {
+      let config;
+      try {
+        config = JSON.parse(readFileSync(path, "utf8"));
+      } catch (error) {
+        throw new ScopeError(`${collapse(path)} is not valid JSON: ${error.message}`);
+      }
+      return { path, dir, config: validate(config, path) };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// What the home view runs for a scope, and how to describe it.
+//   argv:     HEY arguments
+//   base:     the equivalent hey-axi command line (for help lines)
+//   carry:    selector args to carry into suggested commands
+//   label:    one line for the `scope:` field
+export function scopeQuery(scope) {
+  const config = scope?.config || {};
+  const limit = config.limit || HOME_LIMIT;
+  const carry = config.account ? ["--account", config.account] : [];
+  let argv;
+  let what;
+  if (config.search) {
+    argv = ["search", config.search];
+    what = `search ${config.search}`;
+  } else if (config.label) {
+    argv = ["label", "view", config.label, "--limit", String(limit)];
+    what = `label ${config.label}`;
+  } else {
+    const box = config.box || "imbox";
+    argv = ["box", "view", box, "--limit", String(limit)];
+    what = box === "imbox" ? "Imbox" : `box ${box}`;
+  }
+  const words = argv.filter((word, index) => !(word === "--limit" || argv[index - 1] === "--limit"));
+  // Single quotes: a search like $(date) or an account with spaces is shown literally.
+  const shell = (word) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${String(word).replace(/'/g, "'\\''")}'`);
+  const shownCarry = carry.map((word, index) => (index % 2 ? shell(word) : word));
+  const base = ["hey-axi", ...words.map(shell), ...shownCarry].join(" ");
+  const account = config.account ? `, account ${config.account}` : "";
+  const label = scope
+    ? `${what}${account} (from ${collapse(scope.path)})`
+    : `account-wide ${what} (no ${SCOPE_FILE} here; \`hey-axi setup scope --label <name>\` focuses this directory)`;
+  return { argv: [...argv, ...carry], base, carry: shownCarry, label, limit, path: argv[0] === "search" ? "search" : `${argv[0]} view` };
+}
+
+export const SCOPE_HELP = [
+  "hey-axi setup scope — focus the home view and session hook in this directory on one box, label or search",
+  "",
+  "usage: hey-axi setup scope (--box <name|id> | --label <name|id> | --search <query>) [--account <id>] [--limit <n>]",
+  "       hey-axi setup scope --status | --remove",
+  "",
+  "flags:",
+  "  --box <name|id>     show this box (default imbox)",
+  "  --label <name|id>   show threads with this label (default: none)",
+  "  --search <query>    show threads matching this search (default: none)",
+  "  --account <id>      use this linked account (default: HEY's default account)",
+  "  --limit <n>         threads to show, 1-100 (default 10)",
+  "  --status            show the scope that applies here; writes nothing (default false)",
+  "  --remove            delete ./.hey-axi.json (default false)",
+  "",
+  `Writes ./${SCOPE_FILE}; subdirectories inherit it. Re-running with the same settings changes nothing.`,
+  "",
+  "examples:",
+  "  hey-axi setup scope --label Acme",
+  "  hey-axi setup scope --search \"from:billing@acme.example\" --limit 5",
+  "  hey-axi setup scope --status",
+].join("\n");
+
+export const SCOPE_FLAGS = new Set(["--box", "--label", "--search", "--account", "--limit", "--status", "--remove", "--help", "-h"]);
+const SCOPE_VALUE_FLAGS = new Set(["--box", "--label", "--search", "--account", "--limit"]);
+
+// `hey-axi setup scope ...`. Returns { output, code }.
+export function setupScope(argv, cwd = process.cwd()) {
+  const values = {};
+  const flags = new Set();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg.indexOf("=");
+    const name = arg.startsWith("--") && eq !== -1 ? arg.slice(0, eq) : arg;
+    if (!SCOPE_FLAGS.has(name)) {
+      return { code: 2, output: { ok: false, error: arg.startsWith("-") ? `unknown flag ${name} for \`setup scope\`` : `unexpected argument "${arg}" for \`setup scope\``, help: ["valid flags for `setup scope`: --box, --label, --search, --account, --limit, --status, --remove", "Run `hey-axi setup scope --help`"] } };
+    }
+    if (eq !== -1 && !SCOPE_VALUE_FLAGS.has(name)) {
+      return { code: 2, output: { ok: false, kind: "usage", error: `${name} is a switch and takes no value: pass ${name}, or leave it out (got ${arg})`, help: "Run `hey-axi setup scope --help`" } };
+    }
+    flags.add(name);
+    if (SCOPE_VALUE_FLAGS.has(name)) {
+      const value = eq !== -1 ? arg.slice(eq + 1) : argv[i + 1];
+      if (value === undefined || (eq === -1 && value.startsWith("--"))) return { code: 2, output: { ok: false, error: `missing value for ${name}`, help: "Run `hey-axi setup scope --help`" } };
+      values[name.slice(2)] = value;
+      if (eq === -1) i += 1;
+    }
+  }
+  const path = join(resolve(cwd), SCOPE_FILE);
+  if (flags.has("--status") || flags.has("--remove")) {
+    if (Object.keys(values).length || (flags.has("--status") && flags.has("--remove"))) {
+      return { code: 2, output: { ok: false, error: "--status and --remove take no other flags", help: "Run `hey-axi setup scope --status` or `hey-axi setup scope --remove`" } };
+    }
+  }
+  if (flags.has("--status")) {
+    try {
+      const scope = findScope(cwd);
+      return { code: 0, output: { scope: scopeQuery(scope).label } };
+    } catch (error) {
+      return { code: 1, output: { ok: false, error: error.message, help: `Fix or delete the file, then run \`hey-axi setup scope --status\`` } };
+    }
+  }
+  if (flags.has("--remove")) {
+    if (!existsSync(path)) return { code: 0, output: { scope: `nothing to remove: no ${SCOPE_FILE} in this directory (no-op)` } };
+    rmSync(path);
+    return { code: 0, output: { scope: `removed ${collapse(path)}`, help: ["Run `hey-axi` to see the home view for this directory"] } };
+  }
+  const config = {};
+  for (const key of ["box", "label", "search", "account"]) if (values[key] !== undefined) config[key] = values[key];
+  if (values.limit !== undefined) {
+    if (!/^\d+$/.test(values.limit)) return { code: 2, output: { ok: false, error: `--limit needs a whole number, got "${values.limit}"` } };
+    config.limit = Number(values.limit);
+  }
+  if (!SOURCES.some((key) => config[key] !== undefined)) {
+    return { code: 2, output: { ok: false, error: "`setup scope` needs one of --box, --label, --search", help: ["usage: hey-axi setup scope (--box <name|id> | --label <name|id> | --search <query>) [--account <id>] [--limit <n>]"] } };
+  }
+  try {
+    validate(config, path);
+  } catch (error) {
+    return { code: 2, output: { ok: false, error: error.message.replace(`${collapse(path)}: `, ""), help: "Run `hey-axi setup scope --help`" } };
+  }
+  const next = `${JSON.stringify(config, null, 2)}\n`;
+  const current = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (current === next) return { code: 0, output: { scope: `already up to date (no changes): ${scopeQuery({ path, config }).label}` } };
+  writeFileSync(path, next);
+  return { code: 0, output: { scope: `${current === null ? "wrote" : "updated"} ${scopeQuery({ path, config }).label}`, help: ["Run `hey-axi` to see the scoped home view", "Run `hey-axi setup scope --remove` to undo"] } };
+}