@dharta/cli 0.6.77

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LifeSage LLC
+
+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,167 @@
+# @dharta/cli
+
+The unified `dharta` CLI ([RFC 0013](../../docs/rfcs/0013-unified-cli.md)):
+one tool from `setup` to `open`. Wraps the [`@dharta/sdk`](../typescript)
+TypeScript SDK for its API calls; `dharta dev` bootstraps the Python
+`dharta-runtime` package (the harness-adapter engine, pinned per CLI release)
+via uv.
+
+## Install
+
+```sh
+npm install -g @dharta/cli
+```
+
+That is the only install channel today (brew/curl installers are Phase 2).
+From a checkout:
+
+```sh
+cd sdks/typescript && npm install && npm run build
+cd ../typescript-cli && npm install && npm run build
+node dist/cli.js --help      # or `npm link` to get `dharta` on PATH
+```
+
+## The golden path
+
+```sh
+dharta login                  # device flow, browser approve
+dharta create support-bot --harness claude-code  # scaffold a starter agent
+cd support-bot
+dharta setup --enable --method git # persist this agent's delivery method
+dharta dev                    # chat locally, hot reload
+dharta deploy                 # deploy this agent folder only
+dharta open
+```
+
+For git deploys, a fresh clone, worktree, or GitHub Actions checkout without a
+`dharta` remote reuses source identity from its canonical remote and any
+already-bound sibling agent. The local checkout directory name is only a
+fallback. Each agent folder is a self-contained release boundary: materialize
+shared runtime inputs inside it before deploying.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `dharta login` | Device flow: prints a one-time code, you approve it in the browser (signed-in dashboard session), and the CLI receives a named, revocable credential visible on the dashboard keys page. Also installs the git credential helper for `git push dharta`. |
+| `dharta login --with-token` | Read an API key from piped stdin instead (CI, air-gapped): `echo $DHARTA_API_KEY \| dharta login --with-token`. |
+| `dharta auth status` | Show who you are, per profile (includes the `DHARTA_API_KEY` env credential when set). |
+| `dharta auth token` | Print the active token, for piping. |
+| `dharta auth logout [--profile <name>]` | Remove the stored credential (the key stays revocable on the dashboard). |
+| `dharta whoami` | Show the authenticated principal. |
+| `dharta create [path] [--name <n>] [--template <key>] [--harness <type>] [--harness-version <version>]` | Scaffold a brand-new starter agent in a supported harness format (`claude-code`, `opencode`, `deepagents`, `goose`, or `codex-cli`): native template files plus a default `dharta.toml` (deploy off). Omit `--harness` for Claude Code. Local only. |
+| `dharta setup [path] [--name <n>] [--enable\|--disable] [--method git\|folder] [--ci github] [--login]` | Configure exactly one existing agent folder and persist its deploy method. `name` is a 1-100 character display name; Dharta derives the org-unique deploy slug from it, and changing that slug targets a different agent. At an ambiguous repo root, interactive setup asks for one agent; rerun setup for each sibling. GitHub is optional per-agent automation pinned to the selected method, not a third transport; rerun setup and rotate that agent's CI secret when changing methods. Local only. |
+| `dharta dev [path] [-m <msg>] [--user <id>] [--port <port>]` | Run the agent locally behind the consumer session API: chat REPL, hot reload, approval prompts, and a printed local URL a widget can target. `[path]` (or cwd) selects the agent; in a multi-agent repo it picks the sole one or asks. Spawns `dharta-runtime dev-serve` via uv (see Runtime below). |
+| `dharta dev --release vN [--env remote [--include-secrets]]` | Parity axes: run the exact built tree prod serves, and/or bind prod env vars instead of `.env` (`--include-secrets` needs `env:secrets:read`; audited). |
+| `dharta deploy [slug] [--mode git\|folder] [--dir <path>] [--reconcile-source]` | Create and activate a new immutable release from exactly one agent folder. Its checked-in `deploy_method` selects committed git or working-tree upload; `--mode` is a one-run override. Git uses a per-agent deploy ref, so sibling agents never fan out implicitly. After inspecting intentionally divergent hosted history, `--reconcile-source` aligns only Dharta's hosted branch. |
+| `dharta status` | Every agent in this repo (resolved from the git root, like `git status`) joined to its live release/version on the active profile - the "what's here" view. Works before the first deploy. |
+| `dharta rollback [slug] --to vN` | Flip the agent's current release to a previous version (`releases:write`); slug is inferred from this folder when omitted. |
+| `dharta logs [slug] [--tail] [--since <iso>]` | Stream agent logs via SSE (`--tail`) or poll with `--since`; slug is inferred from this folder when omitted. |
+| `dharta open [target]` | Open the hosted chat page, `console`, or handoff targets: `billing`, `security`, `api-keys`, `model-keys`, `webhooks`, `connected-accounts`. Per-agent commands resolve the agent from `dharta.toml`: explicit `--agent`/`[path]`, the repo's sole agent, then the legacy `DHARTA_PROJECT` alias. |
+| `dharta env list\|set NAME=value [--secret]\|unset NAME` | Manage the agent's prod env bindings (declare-or-bind; secret values are never shown). |
+| `dharta env pull [--force] [--include-secrets]` | Hydrate `.env` from prod values (audited; secrets excluded unless `--include-secrets` uses `env:secrets:read`). |
+| `dharta env diff` | Report drift between `.env`, prod bindings, and the `dharta.toml` `[env]` declarations. |
+| `dharta sessions [show\|view <id>]` | List transcript sessions from the deployed agent host; `show`/`view` renders a transcript (requires the org's transcript-access setting). |
+| `dharta session <id>` | Direct alias for viewing one deployed session transcript. |
+| `dharta ps` | Sessions active right now: count, age, model, tokens. |
+| `dharta files ls <agent> <karta>` | List a karta's durable workspace files (path and size) via the owner read channel (requires a `workspace:read` key + the agent's `owners.api` grant). |
+| `dharta files get <agent> <karta> <path> [-o <file>]` | Fetch one workspace file; writes bytes to `--out`, or streams them to stdout. |
+| `dharta artifact put\|list\|remove` | Designate, inspect, or remove durable workspace work product through the release-declared artifact schema. This delegates to the pinned `dharta-runtime` helper and never publishes or shares an artifact. |
+| `dharta send "<message>"` (alias `run`) | Send a one-shot message to the DEPLOYED agent and print its reply (prod smoke test; tool approvals auto-denied). |
+| `dharta agent list\|show [slug]` | List all agents in your org, or show one + its recent releases (the agent in this folder if no slug). |
+| `dharta agent sessions [slug]\|sessions show\|view <id> [slug]\|session <id> [slug]` | List transcript sessions for an agent, or view one transcript without leaving the `agent` namespace. |
+| `dharta agent releases [slug]\|activate <version> [slug]` | List release history or activate an existing production release. |
+| `dharta agent serving\|dashboard-edits\|workspace-inspectable on\|off [slug]` | Toggle serving, browser-console edits, and read-only workspace inspection. |
+| `dharta agent workspace-access show\|set <path>=<on\|off> [slug]` | Show or set the workspace access grant matrix. Paths: `owners.git`, `owners.api`, `users.widget`, `users.agent_definition`. |
+| `dharta agent model [slug] --source inherit\|platform [--model <id>]` | Clear the model override or pin the platform connector. |
+| `dharta agent model [slug] --connector-id <id> [--model <id>]` | Pin a BYOK connector from `dharta model-keys list`; omit `--source`. |
+| `dharta agent delete [slug]` | Archive an agent. |
+| `dharta schedules list\|create [--run-now]\|pause\|resume\|run\|delete\|rm` | Manage recurring runs for an agent. `--run-now` queues a test run immediately after creation. |
+| `dharta keys list\|create <name> [--scope ...]\|rename <id> <name>\|revoke <id>` | Manage API keys (plaintext shown exactly once on create). |
+| `dharta usage` | Current-period totals and budget. |
+| `dharta doctor` | Diagnose PATH shadowing (a stale pip-installed `dharta`), the uv/runtime bootstrap, and login state. Exits non-zero when unhealthy. |
+| `dharta update` | Self-update on the standalone channel; npm installs get the `npm install -g @dharta/cli@latest` pointer. |
+| `dharta completion <bash\|zsh>` | Print a shell completion script generated from the command tree. |
+
+Additional command groups:
+
+| Command | Description |
+| --- | --- |
+| `dharta audit-log` | Export audit events as a table, JSON, or CSV. |
+| `dharta analytics agents\|users\|instances\|sessions\|models\|cost` | Usage and cost rollups with bounded ranges and JSON output. |
+| `dharta api [METHOD] /path` | Authenticated passthrough for documented public API reads and curated scoped writes. |
+| `dharta model-keys list\|create\|revoke` | Manage encrypted BYOK provider credentials. |
+| `dharta members list\|invite\|set-role\|remove` | Manage organization members and invitations. |
+| `dharta kartas list\|show\|configure\|grant\|set-role\|revoke` | Manage durable Dharta names, agent-scoped vanity URLs, access audience, and per-Karta member ACLs. |
+| `dharta embed-keys list\|create\|rotate\|enable\|disable\|revoke\|enable-identity\|disable-identity` | Manage publishable widget embed keys and their verified-identity secret for an agent. |
+| `dharta caps budget [set]\|set\|instance\|instance-set\|end-user\|end-user-set\|seat\|seat-set` | Inspect and update monthly budget, durable dharta caps, verified-user caps, and per-seat caps. |
+| `dharta appearance get\|set` | Read or merge an agent's appearance JSON. |
+| `dharta directories instances\|end-users\|users\|sessions` | Read agent-scoped durable kartas, verified users, and sessions. |
+| `dharta webhooks list\|create\|update\|enable\|delete\|rm` | Manage webhook endpoints and one-time signing secrets. |
+
+Every command that prints a result payload also takes `--json` for
+machine-readable output (RFC 0013 §3). Stream-shaped commands (`dev`, `logs`,
+`deploy` (git mode), `completion`) reject the flag instead of silently ignoring
+it. `dharta open --json` prints the URL object without opening a browser, and
+`dharta send --json` buffers the reply into one `{agent, session_id, reply}`
+payload.
+
+`dharta git-credential` is a hidden subcommand: the credential-helper protocol
+endpoint that `dharta login` wires into git config.
+
+## Configuration
+
+`dharta login` writes `~/.dharta/config.toml` with mode `0600`:
+
+```toml
+default_profile = "default"
+
+[profiles.default]
+api_key = "dh_live_…"
+base_url = "https://dharta.ai"
+git_base_url = "https://git.dharta.ai"
+```
+
+- `--profile <name>` selects a non-default profile.
+- `--base-url` / `--git-base-url` (on `login`) override the production hosts
+  for staging / self-hosted deployments.
+- `DHARTA_API_KEY` overrides the stored credential everywhere (the CI path;
+  `DHARTA_BASE_URL` pairs with it).
+
+## Runtime (`dharta dev`)
+
+The harness adapters live in the Python `dharta-runtime` package,
+single-sourced with production. On first `dharta dev`, the CLI resolves the
+pinned version through uv (`uvx --from dharta-runtime==<pin>`); the pin ships
+inside each CLI release. `DHARTA_RUNTIME` is the escape hatch - point it at a
+checkout (runs `uv run --project`) or an executable. `dharta doctor` diagnoses
+the bootstrap.
+
+## Auth and scopes
+
+Every authenticated command sends `Authorization: Bearer dh_live_…`. The
+server validates the bearer by prefix lookup + constant-time bcrypt comparison
+(see `Api::BaseController` in the Rails app).
+
+Required scopes:
+- `dharta login` - grants routine operation scopes
+  for non-admin CLI workflows: analytics/usage, agent settings, releases,
+  schedules, webhooks, embed keys, appearance, directories, caps,
+  Dharta identity/ACLs, model connector/member listing, env list/set/unset, deploy, status, logs,
+  and open. Member listing still requires the key to have been created by a
+  current owner or admin.
+- separately scoped keys - sensitive or tenant-admin commands such as
+  `audit-log`, `members invite|set-role|remove`, `model-keys create|revoke`,
+  `keys create|rename|revoke`, `agent workspace-inspectable`,
+  `agent workspace-access set`, `agent delete`, and `env pull --include-secrets`.
+- `setup` is local-only and needs no auth.
+
+## Tests
+
+```sh
+npm test     # vitest + msw, covers each command's happy path
+```
+
+The Rails-side controllers are tested under
+`apps/dharta-web/test/controllers/api/` (e.g. `publishes_controller_test.rb`,
+`rollbacks_controller_test.rb`).

package/dist/agent.d.ts

@@ -0,0 +1,17 @@
+import { type AgentFolder } from "./setup-scan.js";
+export interface AgentInferOptions {
+    agent?: string;
+    project?: string;
+    path?: string;
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+    scan?: (root: string, opts: {
+        isGitRepo: boolean;
+    }) => Promise<AgentFolder[]>;
+}
+export declare function inferAgentSlug(opts?: AgentInferOptions): Promise<string>;
+export declare function validateAgentSelectorOptions(opts?: Pick<AgentInferOptions, "agent" | "project" | "dir">): void;
+export declare function slugFromRemote(url: string): string | null;
+export declare function deriveSlug(name: string): string;
+export declare function validateAgentSlug(value: string, label: string): string;
+export declare function validateAgentName(value: string, label?: string): string;

package/dist/agent.js

@@ -0,0 +1,134 @@
+// Agent identity inference, shared by every per-agent command (RFC 0024 + the
+// CLI surface spec). The agent a command targets comes from its dharta.toml -
+// NOT the `dharta` git remote, which now points at the SOURCE REPO (one repo,
+// many agents), so remote-slug inference would resolve the wrong thing.
+import * as path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { findGitRoot, scanAgentFolders, describeFolder } from "./setup-scan.js";
+import { normalizeNonBlank } from "./validators.js";
+const AGENT_SLUG_FORMAT = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const MAX_AGENT_NAME_CHARACTERS = 100;
+// Resolve the agent slug a per-agent command operates on. Order (explicit
+// beats inferred): --agent/-p, an explicit [path], the nearest containing
+// agent folder, the repo's sole agent, then DHARTA_PROJECT (CI). A multi-agent
+// repo root with no selector is a loud error rather than a wrong guess.
+// Identity for a scanned agent folder: an explicit dharta.toml `slug` wins
+// (pinned identity, free-form display name); otherwise derive from the name.
+function slugForFolder(folder) {
+    if (folder.slug)
+        return validateAgentSlug(folder.slug, "dharta.toml slug");
+    return deriveSlug(folder.name);
+}
+export async function inferAgentSlug(opts = {}) {
+    validateAgentSelectorOptions(opts);
+    if (opts.agent !== undefined)
+        return normalizeAgentSlug(opts.agent, "--agent");
+    if (opts.project !== undefined)
+        return normalizeAgentSlug(opts.project, "--project");
+    const cwd = path.resolve(opts.dir ?? process.cwd());
+    if (opts.path) {
+        const dir = path.resolve(cwd, opts.path);
+        const folder = await describeFolder(dir, path.basename(dir));
+        if (folder.name)
+            return slugForFolder(folder);
+        throw new Error(`No agent at ${opts.path} - it has no dharta.toml with a name.`);
+    }
+    const gitRoot = findGitRoot(cwd);
+    let localDir = cwd;
+    for (;;) {
+        if (existsSync(path.join(localDir, "dharta.toml"))) {
+            const local = await describeFolder(localDir, path.basename(localDir));
+            if (local.name)
+                return slugForFolder(local);
+            throw new Error(`${path.join(localDir, "dharta.toml")} must declare an agent name.`);
+        }
+        if (gitRoot && localDir === path.resolve(gitRoot))
+            break;
+        const parent = path.dirname(localDir);
+        if (parent === localDir)
+            break;
+        localDir = parent;
+    }
+    const scan = opts.scan ?? scanAgentFolders;
+    const agents = (await scan(gitRoot ?? cwd, { isGitRepo: !!gitRoot })).filter((f) => f.name);
+    const containing = agents
+        .filter((folder) => cwd === path.resolve(folder.dir) || cwd.startsWith(`${path.resolve(folder.dir)}${path.sep}`))
+        .sort((a, b) => path.resolve(b.dir).length - path.resolve(a.dir).length);
+    if (containing.length > 0)
+        return slugForFolder(containing[0]);
+    if (agents.length === 1)
+        return slugForFolder(agents[0]);
+    // The sole local agent wins over the env (local context beats CI); the env
+    // is the fallback when the local context is empty or ambiguous (a monorepo
+    // CI job names its target with DHARTA_PROJECT).
+    const envAgent = (opts.env ?? process.env).DHARTA_PROJECT;
+    if (envAgent !== undefined)
+        return normalizeAgentSlug(envAgent, "DHARTA_PROJECT");
+    if (agents.length === 0) {
+        throw new Error("No agent here. Run inside an agent folder (one with a dharta.toml), or pass --agent <slug>.");
+    }
+    const list = agents.map((f) => f.rel).join(", ");
+    throw new Error(`Multiple agents here (${list}). Pass --agent <slug> or a [path] to pick one.`);
+}
+export function validateAgentSelectorOptions(opts = {}) {
+    if (opts.agent !== undefined)
+        validateAgentSlug(opts.agent, "--agent");
+    if (opts.project !== undefined)
+        validateAgentSlug(opts.project, "--project");
+    if (opts.dir === undefined)
+        return;
+    const dir = path.resolve(normalizeNonBlank(opts.dir, "--dir"));
+    try {
+        if (!statSync(dir).isDirectory()) {
+            throw new Error(`Cannot use --dir ${dir}: expected a directory.`);
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Cannot use --dir ${dir}: directory does not exist.`);
+        }
+        throw error;
+    }
+}
+// https://git.dharta.ai/{org}/{slug}.git -> slug. Still used by `deploy` to read
+// the wired `dharta` remote (a source-repo slug there, which is what deploy wants).
+export function slugFromRemote(url) {
+    const match = url.match(/\/([^/]+)\/([^/]+?)(\.git)?$/);
+    return match ? match[2] : null;
+}
+// Port of the server's Agent.derive_slug: lowercase, underscores/spaces
+// -> hyphens, drop disallowed chars, truncate to 63, strip edge hyphens, fall
+// back to "agent". Shared by setup (default name), the agent resolver above,
+// and the live preview JS.
+export function deriveSlug(name) {
+    let base = name.toLowerCase().replace(/[_\s]+/g, "-").replace(/[^a-z0-9-]/g, "");
+    base = base.slice(0, 63).replace(/^-+|-+$/g, "");
+    return base || "agent";
+}
+export function validateAgentSlug(value, label) {
+    const normalized = normalizeNonBlank(value, label);
+    if (!AGENT_SLUG_FORMAT.test(normalized)) {
+        const suggestion = slugSuggestion(normalized);
+        throw new Error(`${label} must be a valid agent slug: lowercase letters, digits, hyphens; max 63.` +
+            (suggestion ? ` Did you mean ${suggestion}?` : ""));
+    }
+    return normalized;
+}
+// Mirrors Agent's public display-name contract. Count Unicode code points,
+// rather than UTF-16 code units, so client-side validation agrees with Ruby's
+// String#length for non-ASCII names.
+export function validateAgentName(value, label = "agent name") {
+    const normalized = normalizeNonBlank(value, label);
+    if ([...normalized].length > MAX_AGENT_NAME_CHARACTERS) {
+        throw new Error(`${label} must be 1-${MAX_AGENT_NAME_CHARACTERS} characters.`);
+    }
+    return normalized;
+}
+const normalizeAgentSlug = validateAgentSlug;
+function slugSuggestion(value) {
+    if (!/^[A-Za-z0-9 _-]+$/.test(value))
+        return null;
+    const suggestion = deriveSlug(value);
+    return suggestion !== value && AGENT_SLUG_FORMAT.test(suggestion) ? suggestion : null;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/api-error.d.ts

@@ -0,0 +1,3 @@
+export declare function cliFormatError(status: number, parsed: unknown): Error;
+export declare function cliFormatNetworkError(url: string, error: unknown): Error;
+export declare function cliFormatRawError(res: Response): Promise<Error>;

package/dist/api-error.js

@@ -0,0 +1,80 @@
+// Error formatting for the CLI's control-plane calls. Passed to the SDK
+// HttpClient as `formatError` so CLI errors keep their human message + the
+// `err.status`/`err.body` shape (instead of the SDK's typed errorFor()
+// hierarchy, which the CLI doesn't surface).
+import { SENSITIVE_API_KEY_SCOPES } from "./commands/scopes.js";
+export function cliFormatError(status, parsed) {
+    // Server messages already name fixes (e.g. the transcript-access 403 points
+    // at the settings page) - keep them verbatim. Rails sends `message`; the
+    // agent host (FastAPI) sends `detail`; some raw upload endpoints send
+    // `error`.
+    const body = parsed && typeof parsed === "object" ? parsed : {};
+    const serverMessage = typeof body.message === "string"
+        ? body.message
+        : typeof body.detail === "string"
+            ? body.detail
+            : typeof body.error === "string" && !looksLikeMachineCode(body.error)
+                ? body.error
+                : null;
+    let message = serverMessage ?? `Dharta API error ${status}`;
+    if (status === 401) {
+        message += `${message.endsWith(".") ? "" : "."} Run \`dharta login\` to re-authenticate (or check DHARTA_API_KEY).`;
+    }
+    else if (status === 403 && /scope/i.test(message)) {
+        message += `${message.endsWith(".") ? "" : "."} Run \`dharta auth status\` to inspect the active key, or \`dharta open api-keys\` to manage key scopes.`;
+        const sensitiveScopes = missingSensitiveScopes(message);
+        if (sensitiveScopes.length > 0) {
+            message += ` Sensitive scopes (${sensitiveScopes.join(", ")}) require a bounded key with --expires-at within 90 days.`;
+        }
+    }
+    else if (status === 404 && (!serverMessage || isGenericNotFound(serverMessage))) {
+        message +=
+            `${message.endsWith(".") ? "" : "."} ` +
+                "Check the id or agent slug; for agent commands, run `dharta agent list`. " +
+                "Run `dharta auth status` to confirm the active host; DHARTA_BASE_URL must point at the Dharta control API.";
+    }
+    const err = new Error(message);
+    err.status = status;
+    err.body = parsed;
+    return err;
+}
+export function cliFormatNetworkError(url, error) {
+    const origin = new URL(url).origin;
+    return new Error(`Could not reach Dharta at ${origin} (${formatCause(error)}). ` +
+        "Check your network and DHARTA_BASE_URL, then try again.");
+}
+export async function cliFormatRawError(res) {
+    const text = await res.text();
+    let parsed = null;
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+    }
+    return cliFormatError(res.status, parsed);
+}
+function missingSensitiveScopes(message) {
+    const mentioned = new Set(mentionedScopes(message));
+    if (/one of required scopes/i.test(message) && Array.from(mentioned).some((scope) => !SENSITIVE_API_KEY_SCOPES.has(scope))) {
+        return [];
+    }
+    return Array.from(SENSITIVE_API_KEY_SCOPES).filter((scope) => mentioned.has(scope));
+}
+function mentionedScopes(message) {
+    const required = message.match(/required scopes?:\s*([a-z0-9_:,\s-]+)/i)?.[1];
+    const source = required ?? message;
+    return source.match(/[a-z][a-z0-9_]*(?::[a-z][a-z0-9_]*)?/g) ?? [];
+}
+function formatCause(error) {
+    return error instanceof Error && error.message ? error.message : String(error);
+}
+function looksLikeMachineCode(value) {
+    return /^[a-z][a-z0-9_:-]*$/.test(value);
+}
+function isGenericNotFound(value) {
+    return /^resource not found\.?$/i.test(value.trim()) || /^not found\.?$/i.test(value.trim());
+}
+//# sourceMappingURL=api-error.js.map

package/dist/api-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export declare function openBrowser(url: string): Promise<boolean>;

package/dist/browser.js

@@ -0,0 +1,19 @@
+import { spawn } from "node:child_process";
+// Best-effort browser launch; callers always print the URL too, so a
+// headless box still works.
+export function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "explorer"
+            : "xdg-open";
+    return new Promise((resolve) => {
+        const proc = spawn(cmd, [url], { stdio: "ignore", detached: true });
+        proc.on("error", () => resolve(false));
+        proc.on("spawn", () => {
+            proc.unref();
+            resolve(true);
+        });
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,qEAAqE;AACrE,4BAA4B;AAC5B,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,GAAG,GACP,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAC3B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO;YAC5B,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACpB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+export declare function buildProgram(): Command;
+export declare function main(argv: string[]): Promise<void>;
+export declare function readStdin(): Promise<string>;