gsc-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raditya Surya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+<h1 align="center">gsc-axi</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/gsc-axi"><img alt="npm" src="https://img.shields.io/npm/v/gsc-axi?style=flat-square" /></a>
+  <a href="https://axi.md"><img alt="AXI" src="https://img.shields.io/badge/built%20with-AXI-black?style=flat-square" /></a>
+</p>
+
+<h3 align="center">Google Search Console CLI for agents.</h3>
+
+Search performance, indexing status, and sitemaps from the shell, designed with
+[AXI](https://axi.md) (Agent eXperience Interface).
+
+Talks to the Search Console API directly. No `googleapis` dependency — the service-account
+flow is an RS256 JWT, which `node:crypto` signs in a dozen lines — so the install is
+[`axi-sdk-js`](https://www.npmjs.com/package/axi-sdk-js) and a TOON encoder.
+
+## Why
+
+Search Console has no CLI. Agents reach for the API and re-derive the same three things every
+time: minting a token, guessing which property string is verified, and remembering that the
+data lags.
+
+- **Windows that end today show a decline that isn't real.** Search Console finalises data on
+  a 2-3 day delay. Every named `--range` here ends where the data is final.
+- **`https://example.com/` and `sc-domain:example.com` are different properties.** Passing the
+  wrong one returns 404 with no hint. `gsc-axi` accepts a bare domain, resolves it to whichever
+  is verified, and refuses to guess when both are.
+- **A 403 is almost never the credentials.** It is the service account's `client_email` not
+  being a user on the property. The error says that instead of sending you back to Google Cloud.
+
+## Quick Start
+
+```sh
+npx skills add radityasurya/gsc-axi --skill gsc-axi -g
+```
+
+Then give it credentials. A **service account** is the headless path:
+
+1. Google Cloud → create a service account → download its JSON key
+2. Enable the **Google Search Console API** for that project
+3. In Search Console → Settings → Users and permissions → add the service account's
+   `client_email` as a user (its own address, not yours)
+
+```sh
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+export GSC_SITE=https://example.com/    # optional when the account sees one property
+```
+
+An OAuth refresh token works too, if you already have one:
+
+```sh
+export GSC_CLIENT_ID=... GSC_CLIENT_SECRET=... GSC_REFRESH_TOKEN=...
+```
+
+## Usage
+
+```bash
+gsc-axi                                        # dashboard — traffic, change, top queries
+gsc-axi sites                                  # properties and permission level
+
+gsc-axi performance                            # top queries
+gsc-axi performance --by page --range 90d
+gsc-axi performance --by country --limit 10
+gsc-axi performance --by query --contains pricing --device mobile
+
+gsc-axi compare                                # vs the preceding window
+gsc-axi compare --by query                     # which queries moved, ranked by swing
+
+gsc-axi opportunities                          # queries ranking 4-20
+gsc-axi opportunities --min-impressions 200 --range 90d
+
+gsc-axi inspect https://example.com/blog/post  # indexed? canonical? last crawl?
+gsc-axi sitemaps                               # submitted, last read, errors
+gsc-axi sitemaps submit https://example.com/sitemap.xml
+```
+
+### Commands
+
+| Command | Purpose |
+| --- | --- |
+| *(none)* | Dashboard: clicks, impressions, CTR, position, change, top queries |
+| `sites` | Properties this account can reach |
+| `performance` | Break traffic down by query, page, country, device, date, or appearance |
+| `compare` | This window against the one before it |
+| `opportunities` | Queries ranking 4-20 with real volume |
+| `inspect` | Index status, canonical, crawl time, mobile and rich-result verdicts |
+| `sitemaps` | `list`, `submit` |
+| `setup` | Agent session integration: `hooks`, `status`, `uninstall` |
+
+### Windows
+
+`--range` takes `7d`, `28d` (default), `90d`, `6m`, `12m`, `16m` — Search Console keeps 16
+months and nothing older. `--start` / `--end` take `YYYY-MM-DD` and override the range.
+
+## Behaviour worth relying on
+
+- **Reads, plus sitemap submission.** It never deletes a sitemap or removes a property.
+- **`sitemaps submit` is idempotent** — an already-submitted sitemap reports `unchanged`.
+- **Refuses to guess the property** when the account sees several and none was named.
+- **CTR and position are formatted** — `3.5%` and `8.4`, not `0.0352941` and `8.43219`.
+- **Fails loud.** Unknown flags, ranges, and dimensions exit 2 and name the valid values.
+- **TOON output** on stdout, structured errors on stdout too, diagnostics on stderr.
+
+## Relationship to openpanel-axi
+
+[`openpanel-axi`](https://github.com/radityasurya/openpanel-axi) also has a `gsc` command. It
+reads Search Console data **that OpenPanel has synced**, which requires connecting GSC to
+OpenPanel and is limited to what OpenPanel stores. `gsc-axi` talks to Google directly, needs
+no OpenPanel, and covers what OpenPanel does not: URL inspection, sitemaps, arbitrary
+dimension and filter combinations, and properties you do not track in OpenPanel at all.
+
+## Development
+
+```sh
+npm install
+npm test              # node:test, no framework, no network
+npm run build:skill
+node bin/gsc-axi.js --help
+```
+
+The suite stubs `fetch` with a route table standing in for Google, and generates a real RSA
+key so the JWT signing path is exercised rather than mocked. No Google account required.
+
+See [AGENTS.md](AGENTS.md) for architecture notes and [VISION.md](VISION.md) for scope.
+
+## License
+
+MIT

package/bin/gsc-axi.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js";
+
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+  const { main } = await import("../src/cli.js");
+  await main();
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "gsc-axi",
+  "version": "0.1.0",
+  "description": "AXI-compliant Google Search Console CLI — search performance, URL inspection, and sitemaps with token-efficient TOON output",
+  "keywords": ["axi", "google-search-console", "gsc", "seo", "agent", "cli", "toon"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/radityasurya/gsc-axi.git"
+  },
+  "homepage": "https://github.com/radityasurya/gsc-axi#readme",
+  "bugs": { "url": "https://github.com/radityasurya/gsc-axi/issues" },
+  "license": "MIT",
+  "type": "module",
+  "bin": { "gsc-axi": "bin/gsc-axi.js" },
+  "exports": { ".": "./src/cli.js" },
+  "files": ["bin", "src", "skills", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "test": "node --test",
+    "build:skill": "node scripts/build-skill.mjs",
+    "check:skill": "node scripts/build-skill.mjs --check"
+  },
+  "dependencies": {
+    "axi-sdk-js": "^0.1.11",
+    "@toon-format/toon": "^0.9.0"
+  }
+}

package/skills/gsc-axi/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gsc-axi
+description: >
+  Read Google Search Console through the gsc-axi CLI — search performance by query, page, country and device; period-over-period comparisons; queries ranking 4-20 worth improving; URL indexing status; and sitemaps. Use whenever a task touches SEO or Google Search: why traffic moved, which queries a page ranks for, whether a URL is indexed, or whether a sitemap was read.
+user-invocable: false
+metadata:
+  hermes:
+    tags: [seo, google-search-console, search, indexing, sitemaps, analytics]
+---
+
+# gsc-axi
+
+Run the CLI with no arguments first — it prints this month's search traffic, how it moved,
+and the top queries, plus the next commands to run.
+
+```sh
+npx -y gsc-axi
+```
+
+Requires Google credentials with access to the property. A **service account** is the
+headless path and the one to prefer:
+
+```sh
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+export GSC_SITE=https://example.com/     # or sc-domain:example.com; optional with one property
+```
+
+The service account's own `client_email` must be added as a user on the property in Search
+Console (Settings → Users and permissions). Adding *your* email does nothing for it.
+
+## Commands
+
+```sh
+npx -y gsc-axi                                  # dashboard: traffic, change, top queries
+npx -y gsc-axi sites                            # properties this account can reach
+npx -y gsc-axi performance --by page --range 90d
+npx -y gsc-axi performance --by query --contains pricing
+npx -y gsc-axi compare --by query               # what moved vs the previous window
+npx -y gsc-axi opportunities                    # queries ranking 4-20 with real volume
+npx -y gsc-axi inspect https://example.com/post # is it indexed, and what did Google see
+npx -y gsc-axi sitemaps                         # submitted sitemaps and read status
+npx -y gsc-axi sitemaps submit https://example.com/sitemap.xml
+```
+
+Every command takes `--help`, and `--site <property>` to target a specific property.
+
+## What to rely on
+
+- **Windows end where the data is final.** Search Console lags 2-3 days, so a named
+  `--range` ends there rather than today. Ending today would show a decline that is not real.
+- **Property strings are exact.** A domain property is `sc-domain:example.com`; a URL-prefix
+  property is `https://example.com/`. A bare `example.com` resolves to whichever exists, and
+  refuses to guess when both do.
+- **Ranking 4-20 is where the wins are.** `opportunities` filters to that band because those
+  queries already rank on page one or just off it — position gains there convert fastest.
+- **`sitemaps submit` is idempotent**, and says `unchanged` when the sitemap was already
+  submitted rather than implying it did something.
+- **Errors name the cause.** A 403 points at the property's user list, not at the credentials,
+  because that is almost always what is wrong with a service account.
+
+This CLI reads Search Console and submits sitemaps. It never removes a property or a sitemap.
+
+Prefer this over calling the Search Console API with `curl`, which means minting an OAuth
+token by hand on every invocation.

package/src/api.js

@@ -0,0 +1,241 @@
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { AxiError } from "axi-sdk-js";
+import { BIN } from "./args.js";
+
+const WEBMASTERS = "https://www.googleapis.com/webmasters/v3";
+const SEARCHCONSOLE = "https://searchconsole.googleapis.com/v1";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+const READ_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+const WRITE_SCOPE = "https://www.googleapis.com/auth/webmasters";
+
+export const CREDENTIAL_HELP = [
+  "Service account: create one in Google Cloud, enable the Search Console API, download its JSON key",
+  "Add the service account's email as a user on the property in Search Console (Settings -> Users)",
+  "Export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json",
+  "Or use an OAuth refresh token: GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN",
+];
+
+export function hasCredentials(env = process.env) {
+  return Boolean(
+    env.GOOGLE_APPLICATION_CREDENTIALS ||
+      (env.GSC_CLIENT_ID && env.GSC_CLIENT_SECRET && env.GSC_REFRESH_TOKEN),
+  );
+}
+
+function base64url(input) {
+  return Buffer.from(input).toString("base64url");
+}
+
+/**
+ * Mint an access token from a service account key. Signing an RS256 JWT is the
+ * whole of the flow, and `node:crypto` does RS256 — so this needs no googleapis
+ * dependency, which would be an order of magnitude more install weight than the
+ * rest of this tool put together.
+ */
+async function serviceAccountToken(keyPath, scope, fetchImpl) {
+  let key;
+  try {
+    key = JSON.parse(readFileSync(keyPath, "utf8"));
+  } catch (cause) {
+    throw new AxiError(`Could not read the service account key: ${cause.message}`, "AUTH_REQUIRED", [
+      `GOOGLE_APPLICATION_CREDENTIALS points at ${keyPath}`,
+      "It must be the JSON key file downloaded from Google Cloud",
+    ]);
+  }
+  if (!key.client_email || !key.private_key) {
+    throw new AxiError("That JSON is not a service account key", "AUTH_REQUIRED", [
+      "A service account key has `client_email` and `private_key` fields",
+      "Download it from Google Cloud -> IAM -> Service Accounts -> Keys",
+    ]);
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const claim = {
+    iss: key.client_email,
+    scope,
+    aud: TOKEN_URL,
+    iat: now,
+    exp: now + 3600,
+  };
+  const unsigned = `${base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }))}.${base64url(JSON.stringify(claim))}`;
+  const signature = createSign("RSA-SHA256").update(unsigned).sign(key.private_key, "base64url");
+
+  return exchange(
+    { grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: `${unsigned}.${signature}` },
+    fetchImpl,
+    { email: key.client_email },
+  );
+}
+
+async function refreshTokenGrant(env, fetchImpl) {
+  return exchange(
+    {
+      grant_type: "refresh_token",
+      client_id: env.GSC_CLIENT_ID,
+      client_secret: env.GSC_CLIENT_SECRET,
+      refresh_token: env.GSC_REFRESH_TOKEN,
+    },
+    fetchImpl,
+    {},
+  );
+}
+
+async function exchange(body, fetchImpl, context) {
+  let response;
+  try {
+    response = await fetchImpl(TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(body).toString(),
+    });
+  } catch (cause) {
+    throw new AxiError(`Could not reach Google to mint a token: ${cause.message}`, "NETWORK_ERROR", [
+      "Check network connectivity to oauth2.googleapis.com",
+    ]);
+  }
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const detail = payload.error_description || payload.error || `HTTP ${response.status}`;
+    throw new AxiError(`Google refused the credentials: ${detail}`, "AUTH_ERROR", [
+      ...(context.email
+        ? [`Check the Search Console API is enabled for the project owning ${context.email}`]
+        : ["Check GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN are current"]),
+      "A revoked key or a disabled API both land here",
+    ]);
+  }
+  return payload.access_token;
+}
+
+let cached;
+export async function accessToken(options = {}) {
+  const { env = process.env, write = false, fetchImpl = fetch } = options;
+  if (cached) return cached;
+  if (!hasCredentials(env)) {
+    throw new AxiError("No Google credentials in the environment", "AUTH_REQUIRED", CREDENTIAL_HELP);
+  }
+  const scope = write ? WRITE_SCOPE : READ_SCOPE;
+  cached = env.GOOGLE_APPLICATION_CREDENTIALS
+    ? await serviceAccountToken(env.GOOGLE_APPLICATION_CREDENTIALS, scope, fetchImpl)
+    : await refreshTokenGrant(env, fetchImpl);
+  return cached;
+}
+
+export function resetTokenCache() {
+  cached = undefined;
+}
+
+function apiError(status, payload, path) {
+  const error = payload?.error ?? {};
+  const message = error.message || `Search Console request failed (HTTP ${status})`;
+
+  if (status === 401) {
+    return new AxiError(message, "AUTH_ERROR", [
+      "The token was rejected — the key may be revoked or the API disabled",
+      ...CREDENTIAL_HELP.slice(0, 2),
+    ]);
+  }
+  if (status === 403) {
+    return new AxiError(message, "AUTH_ERROR", [
+      "This account has no access to that property",
+      "Add it as a user in Search Console: Settings -> Users and permissions",
+      `Run \`${BIN} sites\` to see the properties it can reach`,
+    ]);
+  }
+  if (status === 404) {
+    return new AxiError(message, "NOT_FOUND", [
+      `Run \`${BIN} sites\` to list the exact property strings`,
+      "A domain property is written `sc-domain:example.com`, not `https://example.com/`",
+    ]);
+  }
+  if (status === 429) {
+    return new AxiError(message, "RATE_LIMITED", [
+      "Search Console allows 1200 queries per minute per property; wait and retry",
+    ]);
+  }
+  return new AxiError(message, "API_ERROR", [`while requesting ${path}`]);
+}
+
+/** One authenticated request against the Search Console API. */
+export async function gsc(path, options = {}) {
+  const { method = "GET", body, base = WEBMASTERS, env = process.env, fetchImpl = fetch, write = false } = options;
+  const token = await accessToken({ env, write, fetchImpl });
+
+  let response;
+  try {
+    response = await fetchImpl(base + path, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (cause) {
+    throw new AxiError(`Could not reach the Search Console API: ${cause.message}`, "NETWORK_ERROR", [
+      "Check network connectivity to googleapis.com",
+    ]);
+  }
+
+  if (response.status === 204) return {};
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw apiError(response.status, payload, path);
+  return payload;
+}
+
+export const inspectionBase = SEARCHCONSOLE;
+
+/** Property strings are URLs or `sc-domain:` prefixed, and must be encoded whole. */
+export function sitePath(site, suffix = "") {
+  return `/sites/${encodeURIComponent(site)}${suffix}`;
+}
+
+export async function listSites(options = {}) {
+  const payload = await gsc("/sites", options);
+  return (payload.siteEntry ?? []).filter((entry) => entry.permissionLevel !== "siteUnverifiedUser");
+}
+
+/**
+ * Resolve the property to act on: the flag, the environment, or the only one
+ * the account can see. Refuses to guess between several, the way an ambiguous
+ * name should — acting on the wrong property is a silent wrong answer.
+ */
+export async function resolveSite(selector, options = {}) {
+  const env = options.env ?? process.env;
+  const wanted = selector || env.GSC_SITE;
+  const sites = await listSites(options);
+
+  if (wanted) {
+    const exact = sites.find((entry) => entry.siteUrl === wanted);
+    if (exact) return exact.siteUrl;
+    // Accept `example.com` for either property shape rather than making the
+    // agent remember which kind was verified.
+    const bare = wanted.replace(/^sc-domain:/, "").replace(/^https?:\/\//, "").replace(/\/$/, "");
+    const near = sites.filter((entry) =>
+      entry.siteUrl.replace(/^sc-domain:/, "").replace(/^https?:\/\//, "").replace(/\/$/, "") === bare,
+    );
+    if (near.length === 1) return near[0].siteUrl;
+    if (near.length > 1) {
+      throw new AxiError(`${wanted} matches ${near.length} properties`, "VALIDATION_ERROR", [
+        "Pass the exact property string instead",
+        ...near.map((entry) => `Run with --site ${entry.siteUrl}`),
+      ]);
+    }
+    throw new AxiError(`no property matching ${wanted}`, "NOT_FOUND", [
+      ...sites.slice(0, 5).map((entry) => `Run with --site ${entry.siteUrl}`),
+      `Run \`${BIN} sites\` to see all ${sites.length}`,
+    ]);
+  }
+
+  if (sites.length === 1) return sites[0].siteUrl;
+  if (sites.length === 0) {
+    throw new AxiError("This account can not see any Search Console property", "AUTH_ERROR", [
+      "Add the account as a user on the property: Settings -> Users and permissions",
+    ]);
+  }
+  throw new AxiError(`the property is ambiguous: this account sees ${sites.length}`, "VALIDATION_ERROR", [
+    "Pass `--site <property>` to choose one, or set GSC_SITE",
+    ...sites.slice(0, 5).map((entry) => `Run with --site ${entry.siteUrl}`),
+  ]);
+}

package/src/args.js

@@ -0,0 +1,128 @@
+import { parseArgs } from "node:util";
+import { AxiError } from "axi-sdk-js";
+
+export const BIN = "gsc-axi";
+
+// Always-allowed globals, per AXI §6: they pass on every command and are never
+// reported as unknown.
+const GLOBAL_FLAGS = {
+  site: { type: "string" },
+  help: { type: "boolean" },
+};
+
+const RENAMED = {
+  property: "--site",
+  domain: "--site",
+  url: "--site",
+  period: "--range",
+  days: "--range",
+  since: "--start",
+  until: "--end",
+};
+
+/**
+ * Strict parse for one subcommand. Unknown flags fail loud (exit 2) and the
+ * error carries that subcommand's valid flags, so the agent self-corrects in
+ * one turn instead of making a follow-up `--help` call.
+ */
+export function parse(argv, { command, flags = {} }) {
+  const options = { ...GLOBAL_FLAGS, ...flags };
+  try {
+    const { values, positionals } = parseArgs({
+      args: argv,
+      options,
+      allowPositionals: true,
+      strict: true,
+    });
+    return { values, positionals };
+  } catch (error) {
+    throw usageError(error, command, options);
+  }
+}
+
+function usageError(error, command, options) {
+  const valid = Object.keys(options)
+    .map((name) => `--${name}`)
+    .join(", ");
+  const raw = String(error.message);
+  const unknown = raw.match(/'?(--?[\w-]+)'?/)?.[1];
+
+  if (error.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+    const bare = unknown?.replace(/^--?/, "");
+    const replacement = bare && RENAMED[bare];
+    return new AxiError(`unknown flag ${unknown} for \`${command}\``, "VALIDATION_ERROR", [
+      replacement
+        ? `${unknown} was renamed; use ${replacement} instead`
+        : `valid flags for \`${command}\`: ${valid}`,
+    ]);
+  }
+  if (error.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+    return new AxiError(raw, "VALIDATION_ERROR", [
+      `Pass a value: \`${BIN} ${command} ${unknown ?? "--flag"} <value>\``,
+    ]);
+  }
+  return new AxiError(raw, "VALIDATION_ERROR", [`valid flags for \`${command}\`: ${valid}`]);
+}
+
+export function required(value, name, command, example) {
+  if (value === undefined || value === null || value === "") {
+    throw new AxiError(`${name} is required`, "VALIDATION_ERROR", [example]);
+  }
+  return value;
+}
+
+/** Positive-integer flag values, so `--limit abc` fails before any API call. */
+export function positiveInt(value, name, fallback) {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new AxiError(`${name} must be a positive integer`, "VALIDATION_ERROR", [
+      `Example: ${name} 20`,
+    ]);
+  }
+  return parsed;
+}
+
+/** Concise per-subcommand reference (AXI §10). */
+export function helpFor({ command, description, usage, flags, examples }) {
+  return {
+    command,
+    description,
+    ...(usage ? { usage } : {}),
+    ...(flags && Object.keys(flags).length ? { flags } : {}),
+    ...(examples?.length ? { examples } : {}),
+  };
+}
+
+export function wantsHelp(argv) {
+  return argv.includes("--help");
+}
+
+/**
+ * Shared subcommand dispatch for grouped nouns. Flags in the first position
+ * fall through to the group's default subcommand, so `events --limit 5`
+ * behaves like `events list --limit 5`.
+ */
+export function makeDispatcher(group, handlers, { fallback, summary }) {
+  const groupHelp = {
+    command: group,
+    subcommands: summary,
+    help: [`Run \`${BIN} ${group} <subcommand> --help\` for a subcommand reference`],
+  };
+  return async function dispatch(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand === undefined || subcommand.startsWith("-")) {
+      if (wantsHelp(argv)) return groupHelp;
+      if (fallback) return handlers[fallback](argv);
+      return groupHelp;
+    }
+    const handler = handlers[subcommand];
+    if (!handler) {
+      throw new AxiError(`unknown subcommand \`${group} ${subcommand}\``, "VALIDATION_ERROR", [
+        `valid subcommands: ${Object.keys(handlers).join(", ")}`,
+        `Run \`${BIN} ${group} --help\``,
+      ]);
+    }
+    return handler(rest);
+  };
+}