@weirgate/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astraen Labs 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

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# `@weirgate/cli`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Weirgate CLI and local stdio MCP server. Both are clients of the public Weirgate
+management API (`https://api.weirgate.com`, `Weirgate-Api-Version: 2026-07-18`), with
+the same scoped, proposal-first workflows as the hosted MCP server at
+`https://mcp.weirgate.com/mcp`. Guide: https://weirgate.com/guides/cli/
+
+```sh
+npm install -g @weirgate/cli
+weirgate auth login                      # browser consent; stores the key in the macOS Keychain
+weirgate auth status --output json
+weirgate init --app example-app --output json
+```
+
+`weirgate auth login --stdin` accepts an already-minted `wgk_` key. On any platform,
+`WEIRGATE_API_KEY` overrides the keychain. `WEIRGATE_API_URL` (or `--api-url`) must be an
+HTTPS URL.
+
+The local MCP server runs over stdio and reads `WEIRGATE_API_KEY`:
+
+```sh
+npx -y --package @weirgate/cli weirgate-mcp
+```
+
+`weirgate mcp install --client codex --transport stdio` writes that command into the
+Codex config; `--transport hosted` (the default) points Codex at the hosted server
+instead.
+
+Provider-key values are entered only through `weirgate provider-keys put|rotate` (a
+local browser page by default, or hidden terminal input with `--stdin`) and never appear
+in output. Exit codes are listed in the guide.
+
+MIT licensed. Copyright 2026 Astraen Labs LLC.

package/dist/cli/browser-session-grant.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { API_VERSION, WeirgateApiError } from "../shared/api-client.js";
+const SUCCESS_PATH = "/cli/access-granted";
+const FAILURE_PATH = "/cli/access-failed";
+export async function browserSessionGrant(input, dependencies = {}) {
+    const { apiUrl, dashboardUrl } = requireHttpsUrls(input);
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const openExternal = dependencies.openExternal ?? openInBrowser;
+    const notify = dependencies.notify ?? ((message) => process.stderr.write(message));
+    const state = (dependencies.stateFactory ?? randomUUID)();
+    return new Promise((resolveGrant, rejectGrant) => {
+        let callbackInProgress = false;
+        let settled = false;
+        const server = createServer((request, response) => {
+            const callback = new URL(request.url ?? "/", "http://127.0.0.1");
+            const code = callback.searchParams.get("code");
+            const receivedState = callback.searchParams.get("state");
+            if (request.method !== "GET" || callback.pathname !== "/callback" || !code || receivedState !== state) {
+                respondText(response, 400, "Invalid Weirgate authorization callback.");
+                return;
+            }
+            if (callbackInProgress) {
+                respondText(response, 409, "Weirgate authorization is already being completed.");
+                return;
+            }
+            callbackInProgress = true;
+            void exchangeSessionGrantCode(apiUrl, code, fetchImpl).then((grant) => {
+                redirect(response, new URL(SUCCESS_PATH, dashboardUrl));
+                finish(() => resolveGrant(grant));
+            }).catch((error) => {
+                redirect(response, new URL(FAILURE_PATH, dashboardUrl));
+                finish(() => rejectGrant(error));
+            });
+        });
+        const finish = (settle) => {
+            if (settled)
+                return;
+            settled = true;
+            server.close();
+            settle();
+        };
+        server.once("error", (error) => finish(() => rejectGrant(error)));
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                finish(() => rejectGrant(invalidInvocation("Could not start the local authorization callback.")));
+                return;
+            }
+            const redirectUri = `http://127.0.0.1:${address.port}/callback`;
+            const consent = new URL("/consent", dashboardUrl);
+            consent.searchParams.set("client", "cli");
+            consent.searchParams.set("redirect_uri", redirectUri);
+            consent.searchParams.set("state", state);
+            consent.searchParams.set("scope", input.scope);
+            try {
+                openExternal(consent.toString());
+                notify("Opened Weirgate consent in your browser.\n");
+            }
+            catch (error) {
+                finish(() => rejectGrant(error));
+            }
+        });
+    });
+}
+async function exchangeSessionGrantCode(apiUrl, code, fetchImpl) {
+    const response = await fetchImpl(new URL("/v1/session-grants/exchange", apiUrl), {
+        method: "POST",
+        headers: { Accept: "application/json", "Content-Type": "application/json", "Weirgate-Api-Version": API_VERSION },
+        body: JSON.stringify({ code }),
+    });
+    const requestId = response.headers.get("X-Weirgate-Request-Id") ?? "unknown";
+    const apiVersion = response.headers.get("Weirgate-Api-Version") ?? "unknown";
+    const payload = await response.json().catch(() => ({}));
+    if (apiVersion !== API_VERSION) {
+        throw new WeirgateApiError({ message: `API version mismatch: expected ${API_VERSION}, received ${apiVersion}`, errorType: "api_version_mismatch", status: 502, requestId, apiVersion, detail: { expected: API_VERSION, received: apiVersion } });
+    }
+    if (!response.ok || typeof payload.value !== "string") {
+        throw new WeirgateApiError({ message: payload.error?.message ?? `Weirgate API returned HTTP ${response.status}`, errorType: response.headers.get("X-Weirgate-Error-Type") ?? payload.error?.type ?? "remote_error", status: response.status, requestId, apiVersion, ...(payload.error?.detail ? { detail: payload.error.detail } : {}) });
+    }
+    return payload.value;
+}
+function requireHttpsUrls(input) {
+    try {
+        const apiUrl = new URL(input.apiUrl);
+        const dashboardUrl = new URL(input.dashboardUrl);
+        if (apiUrl.protocol === "https:" && dashboardUrl.protocol === "https:")
+            return { apiUrl, dashboardUrl };
+    }
+    catch {
+        // Use the same stable invocation error for malformed and non-HTTPS URLs.
+    }
+    throw invalidInvocation("Browser grants require HTTPS API and dashboard URLs.");
+}
+function redirect(response, destination) {
+    response.writeHead(303, {
+        "cache-control": "no-store",
+        location: destination.toString(),
+        "referrer-policy": "no-referrer",
+    });
+    response.end();
+}
+function respondText(response, status, message) {
+    response.writeHead(status, {
+        "cache-control": "no-store",
+        "content-type": "text/plain; charset=utf-8",
+        "referrer-policy": "no-referrer",
+    });
+    response.end(message);
+}
+function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", url] : [url];
+    spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+}
+function invalidInvocation(message) {
+    return new WeirgateApiError({ message, errorType: "invalid_invocation", status: 400, requestId: "local", apiVersion: API_VERSION });
+}

package/dist/cli/exit-codes.js

@@ -0,0 +1,44 @@
+/**
+ * Stable CLI exit codes, so scripts can retry, ask a human, or stop. Explicit error types
+ * win; the HTTP status is the fallback for types this table doesn't name.
+ *
+ * 0 success · 2 invalid invocation · 3 invalid request or not found · 4 authentication or
+ * scope · 5 conflict or stale proposal · 6 blocked by policy or limits · 7 provider or
+ * upstream failure · 8 anything else
+ */
+const EXIT_CODES_BY_TYPE = {
+    invalid_invocation: 2,
+    invalid_request: 3,
+    resource_not_found: 3,
+    feature_not_found: 3,
+    telemetry_request_unavailable: 3,
+    invalid_token: 4,
+    insufficient_scope: 4,
+    invalid_api_key: 4,
+    platform_key_rejected: 4,
+    resource_conflict: 5,
+    proposal_stale: 5,
+    provider_policy_blocked: 6,
+    abuse_blocked: 6,
+    feature_disabled: 6,
+    rate_limited: 6,
+    funding_rail_unavailable: 6,
+    provider_unavailable: 7,
+    output_contract_violation: 7,
+};
+export function exitCodeFor(errorType, status) {
+    const explicit = EXIT_CODES_BY_TYPE[errorType];
+    if (explicit !== undefined)
+        return explicit;
+    if (status === 400 || status === 404 || status === 422)
+        return 3;
+    if (status === 401 || status === 403)
+        return 4;
+    if (status === 409)
+        return 5;
+    if (status === 429)
+        return 6;
+    if (status >= 502)
+        return 7;
+    return 8;
+}

package/dist/cli/index.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { stdin, stdout } from "node:process";
+import YAML from "yaml";
+import { AgentApiClient, API_VERSION, DEFAULT_API_URL, pathPart, WeirgateApiError } from "../shared/api-client.js";
+import { invokeTool } from "../shared/tools.js";
+import { browserSessionGrant } from "./browser-session-grant.js";
+import { exitCodeFor } from "./exit-codes.js";
+let deferringRequiredFlags = false;
+const parsed = parse(process.argv.slice(2));
+try {
+    const result = await run(parsed);
+    if (result)
+        printSuccess(result, parsed.flags);
+}
+catch (error) {
+    const exitCode = printError(error, parsed.flags);
+    process.exitCode = exitCode;
+}
+function parse(argv) {
+    const words = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value.startsWith("--")) {
+            words.push(value);
+            continue;
+        }
+        const [rawKey, inline] = value.slice(2).split("=", 2);
+        const key = rawKey.replace(/^no-/, "");
+        if (rawKey.startsWith("no-")) {
+            flags[key] = false;
+            continue;
+        }
+        if (inline !== undefined) {
+            flags[key] = inline;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next && !next.startsWith("--")) {
+            flags[key] = next;
+            index += 1;
+        }
+        else
+            flags[key] = true;
+    }
+    return { words, flags };
+}
+async function run({ words, flags }) {
+    if (flags.help || words.length === 0) {
+        stdout.write(help());
+        return undefined;
+    }
+    const [noun, verb] = words;
+    if (noun === "completion") {
+        stdout.write(completion(verb ?? "bash"));
+        return undefined;
+    }
+    if (noun === "mcp" && verb === "install")
+        return installMcp(flags);
+    if (noun === "auth" && ["login", "status", "logout"].includes(verb ?? ""))
+        return authCommand(verb, flags);
+    const client = await clientFromEnvironment(flags);
+    if (noun === "init")
+        return init(client, flags);
+    if (noun === "provider-keys" && ["put", "rotate", "revoke"].includes(verb ?? ""))
+        return providerMutation(client, verb, flags);
+    if (noun === "config" && verb === "validate")
+        return validateConfig(flags);
+    const call = await commandToTool(client, noun, verb, flags);
+    return call;
+}
+async function clientFromEnvironment(flags) {
+    const key = process.env.WEIRGATE_API_KEY ?? keychainRead();
+    if (!key)
+        throw invocation("No key reference resolved. Set WEIRGATE_API_KEY or run `weirgate auth login`.");
+    return new AgentApiClient({ apiKey: key, baseUrl: stringFlag(flags, "api-url") ?? process.env.WEIRGATE_API_URL ?? DEFAULT_API_URL });
+}
+async function authCommand(verb, flags) {
+    if (verb === "logout") {
+        spawnSync("security", ["delete-generic-password", "-s", "weirgate-cli"], { stdio: "ignore" });
+        return localResult({ logged_in: false });
+    }
+    if (verb === "login") {
+        const apiUrl = stringFlag(flags, "api-url") ?? process.env.WEIRGATE_API_URL ?? DEFAULT_API_URL;
+        if (!process.env.WEIRGATE_API_KEY && !flags.stdin && flags.browser === false) {
+            throw invocation("Choose --browser or --stdin.");
+        }
+        const key = process.env.WEIRGATE_API_KEY
+            ?? (flags.stdin ? await readSecret(flags) : await browserSessionGrant({
+                apiUrl,
+                dashboardUrl: stringFlag(flags, "dashboard-url") ?? "https://dashboard.weirgate.com",
+                scope: stringFlag(flags, "scope") ?? "propose",
+            }));
+        const client = new AgentApiClient({ apiKey: key, baseUrl: apiUrl });
+        const identity = await client.whoami();
+        if (identity.data.actor.type === "platform_super_admin")
+            throw invocation("Platform super-admin credentials are rejected.");
+        const stored = spawnSync("security", ["add-generic-password", "-U", "-s", "weirgate-cli", "-a", "default", "-w", key], { stdio: "ignore" });
+        if (stored.status !== 0)
+            throw invocation("Unable to store key in macOS Keychain; use WEIRGATE_API_KEY instead.");
+        return identity;
+    }
+    const client = await clientFromEnvironment(flags);
+    return client.whoami();
+}
+function keychainRead() {
+    const result = spawnSync("security", ["find-generic-password", "-s", "weirgate-cli", "-a", "default", "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+async function commandToTool(client, noun, verb, flags) {
+    const app_id = requiredContext(flags, "app");
+    const data = await dataFlag(flags);
+    const common = { ...data, app_id, idempotency_key: stringFlag(flags, "idempotency-key") };
+    deferringRequiredFlags = true;
+    const map = {
+        "apps:list": ["weirgate_list_apps", { limit: numberFlag(flags, "limit"), cursor: stringFlag(flags, "cursor") }],
+        "apps:get": ["weirgate_get_app", common],
+        "apps:propose": ["weirgate_propose_app", { app: data }],
+        "apps:auth": ["weirgate_propose_auth", { ...common, auth: data }],
+        "config:export": ["weirgate_export_config", {}],
+        "config:propose": ["__config_propose", data],
+        "config:apply": ["weirgate_apply_proposal", { proposal_id: requiredFlag(flags, "proposal"), expected_base_revision: numberFlag(flags, "expected-base-revision"), idempotency_key: requiredFlag(flags, "idempotency-key") }],
+        "auth-presets:list": ["__auth_presets", {}],
+        "features:list": ["weirgate_list_features", common],
+        "features:get": ["weirgate_get_feature", { ...common, feature_id: requiredFlag(flags, "feature") }],
+        "features:propose": ["weirgate_propose_feature", { ...common, feature_id: requiredFlag(flags, "feature"), feature: data }],
+        "tiers:list": ["__tiers_list", common],
+        "tiers:get": ["__tiers_get", { ...common, tier_id: requiredFlag(flags, "tier") }],
+        "tiers:propose": ["weirgate_propose_tier", { ...common, tier_id: requiredFlag(flags, "tier"), tier: data }],
+        "rules:get": ["weirgate_get_rules", common],
+        "rules:preview": ["weirgate_preview_rules", { ...common, ruleset: data, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until") }],
+        "rules:propose": ["weirgate_propose_rules", { ...common, ruleset: data, preview_id: requiredFlag(flags, "preview") }],
+        "overrides:propose": ["weirgate_propose_user_override", { ...common, external_id: requiredFlag(flags, "user"), override: data, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until") }],
+        "proposals:list": ["weirgate_list_proposals", { ...common, kind: stringFlag(flags, "kind"), status: stringFlag(flags, "status"), limit: numberFlag(flags, "limit") }],
+        "proposals:get": ["weirgate_get_proposal", { proposal_id: requiredFlag(flags, "proposal") }],
+        "proposals:cancel": ["weirgate_cancel_proposal", { proposal_id: requiredFlag(flags, "proposal") }],
+        "proposals:apply": ["weirgate_apply_proposal", { proposal_id: requiredFlag(flags, "proposal"), expected_base_revision: numberFlag(flags, "expected-base-revision"), idempotency_key: requiredFlag(flags, "idempotency-key") }],
+        "usage:query": ["weirgate_query_usage", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until"), group_by: stringFlag(flags, "group-by"), limit: numberFlag(flags, "limit") }],
+        "pricing-insights:get": ["weirgate_get_pricing_insights", { ...common, since: requiredFlag(flags, "since"), until: requiredFlag(flags, "until") }],
+        "users:timeline": ["weirgate_get_user_timeline", { ...common, external_id: requiredFlag(flags, "user") }],
+        "events:list": ["weirgate_list_events", common],
+        "audit:list": ["weirgate_list_audit_events", { ...common, since: stringFlag(flags, "since"), until: stringFlag(flags, "until"), action: stringFlag(flags, "action") }],
+        "provider-keys:list": ["weirgate_list_provider_key_slots", common],
+        "provider-keys:test": ["weirgate_test_provider_key", { ...common, provider: requiredFlag(flags, "provider") }],
+        "grants:create": ["weirgate_grant_allowance", { ...common, external_id: requiredFlag(flags, "user"), units: numberRequired(flags, "units"), source: stringFlag(flags, "source") }],
+        "grants:reverse": ["weirgate_reverse_grant", { ...common, grant_id: requiredFlag(flags, "grant") }],
+        "user-tiers:assign": ["weirgate_assign_user_tier", { ...common, external_id: requiredFlag(flags, "user"), tier: requiredFlag(flags, "tier"), top_up_now: booleanFlag(flags, "top-up-now") }],
+        "user-tiers:revert": ["weirgate_revert_user_tier", { ...common, external_id: requiredFlag(flags, "user"), top_up_now: booleanFlag(flags, "top-up-now") }],
+        "doctor:all": ["weirgate_run_config_doctor", { ...common, checks: ["auth", "provider", "webhook", "payments"] }],
+        "doctor:auth": ["weirgate_run_config_doctor", { ...common, checks: ["auth"] }],
+        "doctor:provider": ["weirgate_run_config_doctor", { ...common, checks: ["provider"] }],
+        "doctor:webhook": ["weirgate_run_config_doctor", { ...common, checks: ["webhook"] }],
+        "doctor:payments": ["weirgate_run_config_doctor", { ...common, checks: ["payments"] }],
+        "sandbox:call": ["weirgate_run_mock_call", { ...common, fixture: stringFlag(flags, "fixture") ?? "success", session_name: stringFlag(flags, "session-name") }],
+        "docs:search": ["weirgate_search_docs", { query: requiredFlag(flags, "query"), section: stringFlag(flags, "section"), limit: numberFlag(flags, "limit") }],
+        "docs:get": ["weirgate_get_doc", { page_id: requiredFlag(flags, "page") }],
+    };
+    deferringRequiredFlags = false;
+    const entry = map[`${noun}:${verb}`];
+    if (!entry)
+        throw invocation(`Unknown command: ${noun} ${verb}`);
+    assertRequiredFlags(entry[1]);
+    if (flags["dry-run"] && ["proposals:apply", "config:apply", "grants:create", "grants:reverse", "user-tiers:assign", "user-tiers:revert"].includes(`${noun}:${verb}`)) {
+        if (noun === "proposals" || noun === "config")
+            return invokeTool(client, "weirgate_get_proposal", { proposal_id: entry[1].proposal_id });
+        return localResult({ dry_run: true, operation: `${noun}:${verb}`, input: redact(entry[1]) });
+    }
+    if (entry[0] === "__auth_presets")
+        return client.request("/v1/admin/auth-presets");
+    if (entry[0] === "__config_propose")
+        return client.request("/v1/admin/config/proposals", { method: "POST", body: entry[1] });
+    if (entry[0].startsWith("__tiers")) {
+        const result = await invokeTool(client, "weirgate_get_app", common);
+        const appData = result.data.app;
+        const tiers = appData?.tiers;
+        return { ...result, data: entry[0] === "__tiers_get" ? tiers?.[String(entry[1].tier_id)] : { tiers } };
+    }
+    return invokeTool(client, entry[0], entry[1]);
+}
+async function providerMutation(client, verb, flags) {
+    const provider = pathPart(requiredFlag(flags, "provider"));
+    if (verb === "revoke") {
+        if (flags["dry-run"])
+            return localResult({ dry_run: true, operation: "provider-key revoke", provider });
+        return client.request(`/v1/admin/provider-keys/${provider}`, { method: "DELETE", idempotencyKey: requiredFlag(flags, "idempotency-key") });
+    }
+    if (flags["dry-run"])
+        return localResult({ dry_run: true, operation: `provider-key ${verb}`, provider, key_value: "[omitted]" });
+    // Check every flag before asking the human for the secret, so a missing flag never wastes an entry.
+    const idempotencyKey = requiredFlag(flags, "idempotency-key");
+    const key = await readSecret(flags);
+    const path = `/v1/admin/provider-keys/${provider}${verb === "rotate" ? "/rotate" : ""}`;
+    const result = await client.request(path, { method: verb === "put" ? "PUT" : "POST", body: { value: key }, idempotencyKey });
+    return { ...result, data: redact(result.data) };
+}
+async function readSecret(flags) {
+    if (flags.stdin) {
+        if (!stdin.isTTY && !flags["allow-pipe"])
+            throw invocation("Refusing piped secret input without --allow-pipe.");
+        return readAllStdin();
+    }
+    if (flags.browser === false)
+        throw invocation("Choose --browser or --stdin. Secret values are never positional arguments.");
+    return browserSecretCeremony();
+}
+async function browserSecretCeremony() {
+    return new Promise((resolveSecret, reject) => {
+        const server = createServer((request, response) => {
+            if (request.method === "GET") {
+                response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+                response.end("<!doctype html><title>Weirgate local secret entry</title><form method=post><label>Scoped key or provider key <input name=key type=password autofocus required></label><button>Continue</button></form><p>The value is sent only to this localhost process.</p>");
+                return;
+            }
+            let body = "";
+            request.on("data", (chunk) => { body += String(chunk); });
+            request.on("end", () => {
+                const key = new URLSearchParams(body).get("key") ?? "";
+                response.writeHead(key ? 200 : 400, { "content-type": "text/plain", "cache-control": "no-store" });
+                response.end(key ? "Captured locally. You may close this tab." : "Missing value.");
+                server.close();
+                key ? resolveSecret(key) : reject(invocation("No secret entered."));
+            });
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string")
+                return reject(invocation("Could not start local secret entry."));
+            const url = `http://127.0.0.1:${address.port}`;
+            const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+            const args = process.platform === "win32" ? ["/c", "start", url] : [url];
+            spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+            process.stderr.write(`Opened one-time localhost secret entry: ${url}\n`);
+        });
+    });
+}
+async function installMcp(flags) {
+    const target = stringFlag(flags, "client") ?? "codex";
+    const transport = stringFlag(flags, "transport") ?? "hosted";
+    if (target !== "codex")
+        throw invocation("This build currently installs Codex config; use --client codex.");
+    const configPath = resolve(stringFlag(flags, "config") ?? `${homedir()}/.codex/config.toml`);
+    const config = await readFile(configPath, "utf8").catch(() => "");
+    if (/\[mcp_servers\.weirgate\]/.test(config))
+        return localResult({ installed: false, reason: "already_configured", path: configPath });
+    const block = transport === "stdio"
+        ? '\n[mcp_servers.weirgate]\ncommand = "npx"\nargs = ["-y", "--package", "@weirgate/cli", "weirgate-mcp"]\nenv_vars = ["WEIRGATE_API_KEY"]\n'
+        : '\n[mcp_servers.weirgate]\nurl = "https://mcp.weirgate.com/mcp"\nbearer_token_env_var = "WEIRGATE_API_KEY"\n';
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${config.replace(/\s*$/, "")}\n${block}`, { mode: 0o600 });
+    return localResult({ installed: true, path: configPath, transport, credential: { kind: "environment_reference", name: "WEIRGATE_API_KEY" } });
+}
+async function init(client, flags) {
+    const app = requiredFlag(flags, "app");
+    const identity = await client.whoami();
+    try {
+        const readiness = await invokeTool(client, "weirgate_get_onboarding_state", { app_id: app });
+        return { ...readiness, data: { app_id: app, readiness: readiness.data, next: "Resolve the first missing readiness item, enter provider material locally when requested, then run doctor and sandbox proof." } };
+    }
+    catch (error) {
+        if (!(error instanceof WeirgateApiError) || error.status !== 404)
+            throw error;
+        const candidate = await dataFlag(flags);
+        if (Object.keys(candidate).length === 0) {
+            return { ...identity, data: { app_id: app, readiness: { state: "app_not_proposed" }, next: "Re-run init with --file <app.json> to create a durable app proposal." } };
+        }
+        const appDocument = "app_id" in candidate ? candidate : candidate.app;
+        if (!appDocument || appDocument.app_id !== app)
+            throw invocation("The init document must describe the --app identifier.");
+        const proposal = await invokeTool(client, "weirgate_propose_app", { app: appDocument });
+        return { ...proposal, data: { app_id: app, proposal: proposal.data, next: "Review and apply this proposal with an apply-scoped test key, then re-run init." } };
+    }
+}
+async function validateConfig(flags) {
+    const data = await dataFlag(flags);
+    const valid = typeof data.tenant_id === "string" && Array.isArray(data.apps);
+    if (!valid)
+        throw new WeirgateApiError({ message: "Config must contain tenant_id and apps[]", errorType: "validation_error", status: 400, requestId: "local", apiVersion: API_VERSION });
+    return localResult({ valid: true });
+}
+async function dataFlag(flags) {
+    const file = stringFlag(flags, "file");
+    const raw = file ? await readFile(resolve(file), "utf8") : stringFlag(flags, "data");
+    if (!raw)
+        return {};
+    const value = file?.endsWith(".yaml") || file?.endsWith(".yml") ? YAML.parse(raw) : JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invocation("--data/--file must contain an object.");
+    return value;
+}
+function printSuccess(result, flags) {
+    const output = stringFlag(flags, "output") ?? (stdout.isTTY && !flags.json ? "table" : "json");
+    const envelope = { ok: true, data: result.data, request_id: result.request_id, api_version: result.api_version };
+    if (output === "yaml")
+        stdout.write(`${YAML.stringify(envelope)}`);
+    else if (output === "table")
+        stdout.write(`${human(result.data)}${flags["request-id"] ? `\nrequest_id: ${result.request_id}` : ""}\n`);
+    else
+        stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+function printError(error, flags) {
+    const typed = error instanceof WeirgateApiError ? error : new WeirgateApiError({ message: error instanceof Error ? error.message : String(error), errorType: "internal", status: 500, requestId: "local", apiVersion: API_VERSION });
+    const envelope = { ok: false, error: { type: typed.errorType, message: typed.message, request_id: typed.requestId, ...(typed.detail ? { detail: typed.detail } : {}) }, api_version: typed.apiVersion };
+    if (flags.json || !process.stderr.isTTY)
+        process.stderr.write(`${JSON.stringify(envelope)}\n`);
+    else
+        process.stderr.write(`weirgate: ${typed.errorType}: ${typed.message}\n`);
+    return exitCodeFor(typed.errorType, typed.status);
+}
+function localResult(data) { return { data, request_id: "local", api_version: API_VERSION }; }
+function invocation(message) { return new WeirgateApiError({ message, errorType: "invalid_invocation", status: 400, requestId: "local", apiVersion: API_VERSION }); }
+function stringFlag(flags, name) { const value = flags[name]; return typeof value === "string" ? value : undefined; }
+function requiredFlag(flags, name) { const value = stringFlag(flags, name); if (!value) {
+    if (deferringRequiredFlags)
+        return `\u0000required:${name}`;
+    throw invocation(`--${name} is required`);
+} return value; }
+function requiredContext(flags, name) { return stringFlag(flags, name); }
+function numberFlag(flags, name) { const value = stringFlag(flags, name); return value === undefined ? undefined : Number(value); }
+function numberRequired(flags, name) { const raw = stringFlag(flags, name); if (raw === undefined && deferringRequiredFlags)
+    return requiredFlag(flags, name); const value = raw === undefined ? undefined : Number(raw); if (!Number.isFinite(value))
+    throw invocation(`--${name} is required and must be a number`); return value; }
+function booleanFlag(flags, name) {
+    const value = flags[name];
+    if (value === undefined || value === false || value === "false")
+        return false;
+    if (value === true || value === "true")
+        return true;
+    throw invocation(`--${name} must be true or false`);
+}
+function assertRequiredFlags(value) { if (typeof value === "string" && value.startsWith("\u0000required:"))
+    throw invocation(`--${value.slice(10)} is required`); if (Array.isArray(value))
+    value.forEach(assertRequiredFlags);
+else if (value && typeof value === "object")
+    Object.values(value).forEach(assertRequiredFlags); }
+function readAllStdin() { return new Promise((resolveInput, reject) => { let value = ""; stdin.setEncoding("utf8"); stdin.on("data", (chunk) => { value += chunk; }); stdin.on("end", () => resolveInput(value.trim())); stdin.on("error", reject); }); }
+function human(data) { return typeof data === "string" ? data : YAML.stringify(data).trimEnd(); }
+function redact(value) { if (Array.isArray(value))
+    return value.map(redact); if (!value || typeof value !== "object")
+    return value; return Object.fromEntries(Object.entries(value).map(([key, item]) => [/^(key|secret|token|password|credential|authorization)$/i.test(key) ? key : key, /^(key|secret|token|password|credential|authorization)$/i.test(key) ? "[redacted]" : redact(item)])); }
+function help() {
+    return `weirgate <noun> <verb> [flags]\n\nAuth: auth login|status|logout, mcp install, init\nApps: apps list|get|propose, config export|validate|propose|apply, auth-presets list\nConfig: features/tiers/rules/overrides/proposals, doctor, sandbox\nOps: usage, pricing-insights, users, user-tiers, events, audit, provider-keys, grants, docs\nOutput: --output json|table|yaml; --json; mutations use --idempotency-key\nAuth login: browser consent by default; --stdin accepts a pre-minted key\nSecrets: provider-keys put|rotate defaults to --browser; --stdin rejects pipes without --allow-pipe\n`;
+}
+function completion(shell) {
+    const commands = "auth mcp init apps config auth-presets features tiers rules overrides proposals usage pricing-insights users user-tiers events audit provider-keys grants doctor sandbox docs completion";
+    if (shell === "zsh")
+        return `#compdef weirgate\n_arguments '1:command:(${commands})'\n`;
+    if (shell === "fish")
+        return commands.split(" ").map((c) => `complete -c weirgate -f -a '${c}'`).join("\n") + "\n";
+    return `complete -W '${commands}' weirgate\n`;
+}

package/dist/mcp/server.js

@@ -0,0 +1,86 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { AgentApiClient, API_VERSION, WeirgateApiError } from "../shared/api-client.js";
+import { allowedTools, invokeTool, toolGroupAllowed, TOOL_DEFINITIONS } from "../shared/tools.js";
+export async function authenticateAgent(apiKey, baseUrl) {
+    const client = new AgentApiClient({ apiKey, baseUrl });
+    const result = await client.whoami();
+    if (result.data.actor.type === "platform_super_admin") {
+        throw new WeirgateApiError({
+            message: "The platform super-admin credential is never accepted by agent surfaces",
+            errorType: "platform_key_rejected",
+            status: 403,
+            requestId: result.request_id,
+            apiVersion: result.api_version,
+        });
+    }
+    return { client, identity: result.data, identityRequestId: result.request_id };
+}
+const rank = { read: 0, propose: 1, apply: 2 };
+export function createMcpServer(auth) {
+    const server = new Server({ name: "weirgate", version: API_VERSION }, {
+        capabilities: { tools: { listChanged: false } },
+        instructions: "Operate Weirgate only through the frozen 2026-07-18 public API. Propose before apply. Provider keys are entered outside the model-facing MCP surface.",
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: allowedTools({ scope: auth.identity.scope, tool_groups: auth.identity.tool_groups }).map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+                readOnlyHint: tool.scope === "read",
+                destructiveHint: false,
+                idempotentHint: tool.scope === "read" || [
+                    "weirgate_apply_proposal",
+                    "weirgate_grant_allowance",
+                    "weirgate_reverse_grant",
+                    "weirgate_assign_user_tier",
+                    "weirgate_revert_user_tier",
+                ].includes(tool.name),
+                openWorldHint: false,
+            },
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const definition = TOOL_DEFINITIONS.find((tool) => tool.name === request.params.name);
+        if (!definition)
+            return errorResult("invalid_request", `Unknown tool: ${request.params.name}`, auth.identityRequestId);
+        const groups = auth.identity.tool_groups ?? ["*"];
+        if (rank[auth.identity.scope] < rank[definition.scope] || !toolGroupAllowed(definition, groups)) {
+            return errorResult("insufficient_scope", `${definition.name} requires ${definition.scope} scope and ${definition.group} tool access`, auth.identityRequestId);
+        }
+        try {
+            const result = await invokeTool(auth.client, definition.name, request.params.arguments);
+            const safeResult = removeSecretValues(result);
+            return {
+                content: [{ type: "text", text: JSON.stringify(safeResult) }],
+                structuredContent: safeResult,
+            };
+        }
+        catch (error) {
+            if (error instanceof WeirgateApiError)
+                return errorResult(error.errorType, error.message, error.requestId, error.detail, error.apiVersion);
+            return errorResult("invalid_request", error instanceof Error ? error.message : String(error), "local");
+        }
+    });
+    return server;
+}
+function removeSecretValues(value) {
+    if (Array.isArray(value))
+        return value.map(removeSecretValues);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => /^(signing_secret|secret|token|password|credential|authorization|provider_key|key_value)$/i.test(key)
+        ? []
+        : [[key, removeSecretValues(item)]]));
+}
+/** Mirrors the HTTP error envelope (`error.type`, `message`, `request_id`, `detail`), plus `api_version`. */
+function errorResult(type, message, requestId, detail, apiVersion = API_VERSION) {
+    const body = { error: { type, message, request_id: requestId, ...(detail === undefined ? {} : { detail }) }, api_version: apiVersion };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(body) }],
+        structuredContent: body,
+    };
+}

package/dist/mcp/stdio.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { authenticateAgent, createMcpServer } from "./server.js";
+const apiKey = process.env.WEIRGATE_API_KEY;
+if (!apiKey)
+    throw new Error("WEIRGATE_API_KEY must reference a minted scoped wgk_ key");
+const auth = await authenticateAgent(apiKey, process.env.WEIRGATE_API_URL);
+const server = createMcpServer(auth);
+await server.connect(new StdioServerTransport());

package/dist/shared/api-client.js

@@ -0,0 +1,104 @@
+export const API_VERSION = "2026-07-18";
+export const DEFAULT_API_URL = "https://api.weirgate.com";
+export class WeirgateApiError extends Error {
+    errorType;
+    status;
+    requestId;
+    apiVersion;
+    /** The API error's `detail` (for example `detail.reason`), as the HTTP envelope carries it. */
+    detail;
+    constructor(input) {
+        super(input.message);
+        this.name = "WeirgateApiError";
+        this.errorType = input.errorType;
+        this.status = input.status;
+        this.requestId = input.requestId;
+        this.apiVersion = input.apiVersion;
+        this.detail = input.detail;
+    }
+}
+export class AgentApiClient {
+    baseUrl;
+    apiKey;
+    constructor(input) {
+        if (!/^wgk_[a-f0-9]{64}$/.test(input.apiKey)) {
+            throw new WeirgateApiError({
+                message: "A minted wgk_ management key is required",
+                errorType: "invalid_api_key",
+                status: 401,
+                requestId: "local",
+                apiVersion: API_VERSION,
+            });
+        }
+        this.apiKey = input.apiKey;
+        this.baseUrl = (input.baseUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+        if (new URL(this.baseUrl).protocol !== "https:") {
+            throw new WeirgateApiError({
+                message: "Agent surfaces require the public API over HTTPS",
+                errorType: "invalid_request",
+                status: 400,
+                requestId: "local",
+                apiVersion: API_VERSION,
+            });
+        }
+    }
+    async request(path, options = {}) {
+        const url = new URL(path, `${this.baseUrl}/`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const headers = new Headers({
+            Accept: "application/json",
+            "X-Admin-Key": this.apiKey,
+            "Weirgate-Api-Version": API_VERSION,
+        });
+        if (options.body !== undefined)
+            headers.set("Content-Type", "application/json");
+        if (options.idempotencyKey)
+            headers.set("X-Idempotency-Key", options.idempotencyKey);
+        const response = await fetch(url, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+        const requestId = response.headers.get("X-Weirgate-Request-Id") ?? "unknown";
+        const apiVersion = response.headers.get("Weirgate-Api-Version") ?? "unknown";
+        let payload;
+        const contentType = response.headers.get("content-type") ?? "";
+        payload = contentType.includes("json") ? await response.json() : await response.text();
+        if (apiVersion !== API_VERSION) {
+            throw new WeirgateApiError({
+                message: `API version mismatch: expected ${API_VERSION}, received ${apiVersion}`,
+                errorType: "api_version_mismatch",
+                status: 502,
+                requestId,
+                apiVersion,
+                detail: { expected: API_VERSION, received: apiVersion },
+            });
+        }
+        if (!response.ok) {
+            const body = payload;
+            throw new WeirgateApiError({
+                message: body?.error?.message ?? `Weirgate API returned HTTP ${response.status}`,
+                errorType: response.headers.get("X-Weirgate-Error-Type") ?? body?.error?.type ?? "remote_error",
+                status: response.status,
+                requestId,
+                apiVersion,
+                ...(body?.error?.detail ? { detail: body.error.detail } : {}),
+            });
+        }
+        return { data: payload, request_id: requestId, api_version: API_VERSION };
+    }
+    whoami() {
+        return this.request("/v1/admin/whoami");
+    }
+}
+export function pathPart(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error("missing required identifier");
+    return encodeURIComponent(value);
+}
+export function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/dist/shared/tools.js

@@ -0,0 +1,194 @@
+import { API_VERSION, pathPart, record, WeirgateApiError } from "./api-client.js";
+const objectSchema = (properties = {}, required = []) => ({
+    type: "object",
+    additionalProperties: false,
+    properties,
+    ...(required.length ? { required } : {}),
+});
+const str = (description) => ({ type: "string", ...(description ? { description } : {}) });
+const integer = () => ({ type: "integer" });
+const document = () => ({ type: "object", additionalProperties: true, description: "Public API document; secret-valued fields are not accepted." });
+const app = { app_id: str("Application identifier") };
+const appRequired = ["app_id"];
+export const TOOL_DEFINITIONS = [
+    { name: "weirgate_whoami", title: "Who am I", description: "Inspect the current tenant grant, scope, environment, and tool groups.", scope: "read", group: "identity", inputSchema: objectSchema() },
+    { name: "weirgate_list_apps", title: "List apps", description: "List apps visible to the current scoped key.", scope: "read", group: "setup", inputSchema: objectSchema({ cursor: str(), limit: integer() }) },
+    { name: "weirgate_get_app", title: "Get app", description: "Get one visible app configuration.", scope: "read", group: "setup", inputSchema: objectSchema(app, appRequired) },
+    { name: "weirgate_list_features", title: "List features", description: "List configured features for an app.", scope: "read", group: "setup", inputSchema: objectSchema(app, appRequired) },
+    { name: "weirgate_get_feature", title: "Get feature", description: "Get a configured feature.", scope: "read", group: "setup", inputSchema: objectSchema({ ...app, feature_id: str() }, ["app_id", "feature_id"]) },
+    { name: "weirgate_search_docs", title: "Search docs", description: "Search the authenticated canonical Markdown corpus.", scope: "read", group: "docs", inputSchema: objectSchema({ query: str(), section: str(), limit: integer() }, ["query"]) },
+    { name: "weirgate_get_doc", title: "Get doc", description: "Read one canonical Markdown document.", scope: "read", group: "docs", inputSchema: objectSchema({ page_id: str() }, ["page_id"]) },
+    { name: "weirgate_get_onboarding_state", title: "Get onboarding state", description: "Read durable onboarding readiness evidence.", scope: "read", group: "setup", inputSchema: objectSchema(app, appRequired) },
+    { name: "weirgate_run_config_doctor", title: "Run config doctor", description: "Run non-billable configuration checks.", scope: "read", group: "setup", inputSchema: objectSchema({ ...app, checks: { type: "array", items: { enum: ["auth", "provider", "webhook", "payments"] } } }, appRequired) },
+    { name: "weirgate_list_provider_key_slots", title: "List provider key slots", description: "List write-only provider slot metadata. No key values are returned.", scope: "read", group: "provider_keys", inputSchema: objectSchema(app) },
+    { name: "weirgate_test_provider_key", title: "Test provider key", description: "Run a non-billable metadata probe for an existing provider slot.", scope: "read", group: "provider_keys", inputSchema: objectSchema({ ...app, provider: str() }, ["app_id", "provider"]) },
+    { name: "weirgate_get_integration_snippet", title: "Get integration snippet", description: "Generate an HTTP/curl integration snippet.", scope: "read", group: "setup", inputSchema: objectSchema({ ...app, mode: { enum: ["http", "curl"] }, feature_id: str() }, appRequired) },
+    { name: "weirgate_run_mock_call", title: "Run mock call", description: "Run a deterministic sandbox fixture; never invokes live inference.", scope: "apply", group: "sandbox", inputSchema: objectSchema({ ...app, fixture: str(), session_name: str(), idempotency_key: str() }, ["app_id", "fixture"]) },
+    { name: "weirgate_query_usage", title: "Query usage", description: "Query windowed usage rollups.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str(), until: str(), group_by: { enum: ["feature", "user"] }, limit: integer() }, ["app_id", "since", "until"]) },
+    { name: "weirgate_get_pricing_insights", title: "Get pricing insights", description: "Read closed-window pricing evidence.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, since: str(), until: str() }, ["app_id", "since", "until"]) },
+    { name: "weirgate_get_user_timeline", title: "Get user timeline", description: "Read one user's tenant-scoped operational timeline.", scope: "read", group: "usage", inputSchema: objectSchema({ ...app, external_id: str() }, ["app_id", "external_id"]) },
+    { name: "weirgate_list_events", title: "List events", description: "List webhook delivery events for an app.", scope: "read", group: "webhooks", inputSchema: objectSchema({ ...app, status: str(), cursor: str(), limit: integer() }, appRequired) },
+    { name: "weirgate_get_provider_health", title: "Get provider health", description: "Get configured provider health from non-secret slot metadata.", scope: "read", group: "provider_keys", inputSchema: objectSchema(app, appRequired) },
+    { name: "weirgate_list_audit_events", title: "List audit events", description: "List tenant-scoped management audit events.", scope: "read", group: "audit", inputSchema: objectSchema({ ...app, action: str(), since: str(), until: str(), cursor: str(), limit: integer() }) },
+    { name: "weirgate_export_config", title: "Export config", description: "Export the visible tenant configuration.", scope: "read", group: "setup", inputSchema: objectSchema() },
+    { name: "weirgate_propose_app", title: "Propose app", description: "Create a durable proposal to add or replace an app.", scope: "propose", group: "setup", inputSchema: objectSchema({ app: document() }, ["app"]) },
+    { name: "weirgate_propose_auth", title: "Propose auth", description: "Create a durable proposal to change app authentication.", scope: "propose", group: "setup", inputSchema: objectSchema({ ...app, auth: document() }, ["app_id", "auth"]) },
+    { name: "weirgate_propose_feature", title: "Propose feature", description: "Create a durable proposal to add or replace an app feature.", scope: "propose", group: "setup", inputSchema: objectSchema({ ...app, feature_id: str(), feature: document() }, ["app_id", "feature_id", "feature"]) },
+    { name: "weirgate_propose_tier", title: "Propose tier", description: "Create a durable proposal to add or replace an app tier.", scope: "propose", group: "setup", inputSchema: objectSchema({ ...app, tier_id: str(), tier: document() }, ["app_id", "tier_id", "tier"]) },
+    { name: "weirgate_propose_webhook", title: "Propose webhook", description: "Propose updating or deleting an existing webhook endpoint. Proposals cannot create endpoints: a new endpoint's signing secret is shown only once, so the developer creates it in the dashboard.", scope: "propose", group: "webhooks", inputSchema: objectSchema({ ...app, operation: { enum: ["update", "delete"] }, endpoint_id: str(), url: str(), event_types: { type: "array", items: str() }, enabled: { type: "boolean" }, base_revision: integer() }, ["app_id", "operation", "endpoint_id", "base_revision"]) },
+    { name: "weirgate_get_proposal", title: "Get proposal", description: "Read a config, rules, or webhook proposal.", scope: "read", group: "setup", inputSchema: objectSchema({ proposal_id: str() }, ["proposal_id"]) },
+    { name: "weirgate_list_proposals", title: "List proposals", description: "List visible durable proposals.", scope: "read", group: "setup", inputSchema: objectSchema({ ...app, kind: str(), status: str(), cursor: str(), limit: integer() }) },
+    { name: "weirgate_cancel_proposal", title: "Cancel proposal", description: "Cancel a pending proposal without applying it.", scope: "propose", group: "setup", inputSchema: objectSchema({ proposal_id: str() }, ["proposal_id"]) },
+    { name: "weirgate_apply_proposal", title: "Apply proposal", description: "Apply a reviewed proposal using base-revision CAS.", scope: "apply", group: "setup", inputSchema: objectSchema({ proposal_id: str(), expected_base_revision: integer(), idempotency_key: str() }, ["proposal_id", "idempotency_key"]) },
+    { name: "weirgate_get_rules", title: "Get rules", description: "Read the current revisioned app ruleset.", scope: "read", group: "rules", inputSchema: objectSchema(app, appRequired) },
+    { name: "weirgate_preview_rules", title: "Preview rules", description: "Preview rules against recent traffic and bind a content hash.", scope: "propose", group: "rules", inputSchema: objectSchema({ ...app, ruleset: document(), since: str(), until: str() }, ["app_id", "ruleset", "since", "until"]) },
+    { name: "weirgate_propose_rules", title: "Propose rules", description: "Create a preview-hash-bound rules proposal.", scope: "propose", group: "rules", inputSchema: objectSchema({ ...app, ruleset: document(), preview_id: str() }, ["app_id", "ruleset", "preview_id"]) },
+    { name: "weirgate_propose_user_override", title: "Propose user override", description: "Preview and propose a per-user velocity override.", scope: "propose", group: "rules", inputSchema: objectSchema({ ...app, external_id: str(), override: document(), since: str(), until: str() }, ["app_id", "external_id", "override"]) },
+    { name: "weirgate_grant_allowance", title: "Grant allowance", description: "Grant units idempotently to a user.", scope: "apply", group: "credits", inputSchema: objectSchema({ ...app, external_id: str(), units: { type: "number", exclusiveMinimum: 0 }, source: str(), idempotency_key: str() }, ["app_id", "external_id", "units", "idempotency_key"]) },
+    { name: "weirgate_reverse_grant", title: "Reverse grant", description: "Reverse an allowance grant idempotently.", scope: "apply", group: "credits", inputSchema: objectSchema({ ...app, grant_id: str(), idempotency_key: str() }, ["app_id", "grant_id", "idempotency_key"]) },
+    { name: "weirgate_assign_user_tier", title: "Assign user tier", description: "Schedule a configured user tier for the next monthly grant, with an optional current-period delta top-up.", scope: "apply", group: "plans", inputSchema: objectSchema({ ...app, external_id: str(), tier: str(), top_up_now: { type: "boolean" }, idempotency_key: str() }, ["app_id", "external_id", "tier", "idempotency_key"]) },
+    { name: "weirgate_revert_user_tier", title: "Revert user tier", description: "Schedule a user to return to the app default tier, with an optional current-period delta top-up.", scope: "apply", group: "plans", inputSchema: objectSchema({ ...app, external_id: str(), top_up_now: { type: "boolean" }, idempotency_key: str() }, ["app_id", "external_id", "idempotency_key"]) },
+];
+const scopeRank = { read: 0, propose: 1, apply: 2 };
+export function allowedTools(identity) {
+    const groups = identity.tool_groups ?? ["*"];
+    return TOOL_DEFINITIONS.filter((tool) => scopeRank[identity.scope] >= scopeRank[tool.scope] && toolGroupAllowed(tool, groups));
+}
+export function toolGroupAllowed(tool, groups) {
+    if (tool.group === "identity" || groups.includes("*") || groups.includes(tool.group))
+        return true;
+    return ["weirgate_get_proposal", "weirgate_list_proposals", "weirgate_cancel_proposal", "weirgate_apply_proposal"].includes(tool.name)
+        && groups.some((group) => ["setup", "rules", "webhooks"].includes(group));
+}
+function configTenant(data) {
+    const value = record(data);
+    return "tenant_id" in value ? value : record(value.tenants?.[0]);
+}
+function apps(data) {
+    return configTenant(data).apps ?? [];
+}
+function findApp(data, appId) {
+    const value = apps(data).find((item) => item.app_id === appId);
+    if (!value)
+        throw new Error(`App ${appId} is not visible`);
+    return value;
+}
+async function mutateConfig(client, change) {
+    const current = await client.request("/v1/admin/config");
+    const tenant = structuredClone(configTenant(current.data));
+    change(tenant);
+    return client.request("/v1/admin/config/proposals", { method: "POST", body: tenant });
+}
+const q = (input, keys) => Object.fromEntries(keys.map((key) => [key, input[key]]));
+export async function invokeTool(client, name, rawInput) {
+    const input = record(rawInput);
+    const a = () => pathPart(input.app_id);
+    switch (name) {
+        case "weirgate_whoami": return client.whoami();
+        case "weirgate_list_apps": {
+            const r = await client.request("/v1/admin/config");
+            const limit = Math.max(1, Math.min(Number(input.limit ?? 100), 100));
+            const all = apps(r.data);
+            const start = input.cursor ? Math.max(0, all.findIndex((item) => item.app_id === input.cursor) + 1) : 0;
+            const page = all.slice(start, start + limit);
+            return { ...r, data: { data: page, pagination: { limit, returned: page.length, truncated: start + limit < all.length, next_cursor: start + limit < all.length ? page.at(-1)?.app_id ?? null : null } } };
+        }
+        case "weirgate_get_app": {
+            const r = await client.request("/v1/admin/config");
+            const readiness = await client.request(`/v1/admin/apps/${a()}/readiness`);
+            return { ...r, data: { app: findApp(r.data, String(input.app_id)), readiness: readiness.data } };
+        }
+        case "weirgate_list_features": {
+            const r = await client.request("/v1/admin/config");
+            return { ...r, data: { features: record(findApp(r.data, String(input.app_id)).features) } };
+        }
+        case "weirgate_get_feature": {
+            const r = await client.request("/v1/admin/config");
+            return { ...r, data: record(findApp(r.data, String(input.app_id)).features)[String(input.feature_id)] };
+        }
+        case "weirgate_search_docs": return client.request("/v1/admin/docs/search", { query: q(input, ["query", "section", "limit"]) });
+        case "weirgate_get_doc": return client.request(`/v1/admin/docs/${pathPart(input.page_id)}`);
+        case "weirgate_get_onboarding_state": return client.request(`/v1/admin/apps/${a()}/readiness`);
+        case "weirgate_run_config_doctor": return client.request(`/v1/admin/apps/${a()}/doctor`, { method: "POST", body: { checks: input.checks ?? ["auth", "provider", "webhook", "payments"] } });
+        case "weirgate_list_provider_key_slots": return client.request("/v1/admin/provider-keys", { query: q(input, ["app_id"]) });
+        case "weirgate_test_provider_key": return client.request(`/v1/admin/provider-keys/${pathPart(input.provider)}/health`, { method: "POST", query: { app_id: String(input.app_id) } });
+        case "weirgate_get_integration_snippet": return client.request(`/v1/admin/apps/${a()}/integration-snippet`, { query: q(input, ["mode", "feature_id"]) });
+        case "weirgate_run_mock_call": {
+            const session = await client.request(`/v1/admin/apps/${a()}/sandbox/sessions`, { method: "POST", body: { name: input.session_name ?? "agent mock call" }, idempotencyKey: input.idempotency_key });
+            return client.request(`/v1/admin/apps/${a()}/sandbox/sessions/${pathPart(session.data.id)}/runs`, { method: "POST", body: { fixture: input.fixture } });
+        }
+        case "weirgate_query_usage": return client.request(`/v1/admin/apps/${a()}/usage`, { query: q(input, ["since", "until", "group_by", "limit"]) });
+        case "weirgate_get_pricing_insights": return client.request(`/v1/admin/apps/${a()}/pricing-insights`, { query: q(input, ["since", "until"]) });
+        case "weirgate_get_user_timeline": return client.request(`/v1/admin/apps/${a()}/users/${pathPart(input.external_id)}`);
+        case "weirgate_list_events": return client.request(`/v1/admin/apps/${a()}/webhooks/deliveries`, { query: q(input, ["status", "cursor", "limit"]) });
+        case "weirgate_get_provider_health": {
+            const config = await client.request("/v1/admin/config");
+            const slots = await client.request("/v1/admin/provider-keys", { query: { app_id: String(input.app_id) } });
+            const target = findApp(config.data, String(input.app_id));
+            return { ...config, data: { providers: slots.data, effective_feature_policy: Object.fromEntries(Object.entries(record(target.features)).map(([id, feature]) => [id, record(feature).provider_policy])) } };
+        }
+        case "weirgate_list_audit_events": return client.request("/v1/admin/audit", { query: q(input, ["app_id", "action", "since", "until", "cursor", "limit"]) });
+        case "weirgate_export_config": return client.request("/v1/admin/config");
+        case "weirgate_propose_app": return mutateConfig(client, (tenant) => { const list = tenant.apps ?? []; const next = record(input.app); tenant.apps = [...list.filter((x) => x.app_id !== next.app_id), next]; });
+        case "weirgate_propose_auth": return mutateConfig(client, (tenant) => { findApp(tenant, String(input.app_id)).auth = input.auth; });
+        case "weirgate_propose_feature": return mutateConfig(client, (tenant) => { const target = findApp(tenant, String(input.app_id)); target.features = { ...record(target.features), [String(input.feature_id)]: input.feature }; });
+        case "weirgate_propose_tier": return mutateConfig(client, (tenant) => { const target = findApp(tenant, String(input.app_id)); target.tiers = { ...record(target.tiers), [String(input.tier_id)]: input.tier }; });
+        case "weirgate_propose_webhook": return client.request(`/v1/admin/apps/${a()}/webhook-proposals`, { method: "POST", body: { operation: input.operation, endpoint_id: input.endpoint_id, url: input.url, event_types: input.event_types, enabled: input.enabled, base_revision: input.base_revision } });
+        case "weirgate_get_proposal": return getProposal(client, pathPart(input.proposal_id));
+        case "weirgate_list_proposals": {
+            const config = await optionalScopeRequest(client, "/v1/admin/config/proposals", q(input, ["app_id", "kind", "status", "cursor", "limit"]));
+            const webhooks = await optionalScopeRequest(client, "/v1/admin/webhook-proposals", q(input, ["app_id", "status", "cursor", "limit"]));
+            return { ...config, data: { config: config.data, webhooks: webhooks.data } };
+        }
+        case "weirgate_cancel_proposal": return proposalAction(client, pathPart(input.proposal_id), "cancel", input);
+        case "weirgate_apply_proposal": return proposalAction(client, pathPart(input.proposal_id), "apply", input);
+        case "weirgate_get_rules": return client.request(`/v1/admin/apps/${a()}/rules`);
+        case "weirgate_preview_rules": return client.request(`/v1/admin/apps/${a()}/rules:preview`, { method: "POST", body: { ruleset: input.ruleset, since: input.since, until: input.until } });
+        case "weirgate_propose_rules": return client.request(`/v1/admin/apps/${a()}/rules/proposals`, { method: "POST", body: { ruleset: input.ruleset, preview_id: input.preview_id } });
+        case "weirgate_propose_user_override": {
+            const current = await client.request(`/v1/admin/apps/${a()}/rules`);
+            const ruleset = structuredClone(record(record(current.data).ruleset ?? current.data));
+            const velocity = record(ruleset.velocity);
+            ruleset.velocity = velocity;
+            velocity.user_overrides = { ...record(velocity.user_overrides), [String(input.external_id)]: input.override };
+            const preview = await client.request(`/v1/admin/apps/${a()}/rules:preview`, { method: "POST", body: { ruleset, since: input.since, until: input.until } });
+            return client.request(`/v1/admin/apps/${a()}/rules/proposals`, { method: "POST", body: { ruleset, preview_id: preview.data.preview_id } });
+        }
+        case "weirgate_grant_allowance": return client.request(`/v1/admin/apps/${a()}/users/${pathPart(input.external_id)}/grants`, { method: "POST", idempotencyKey: String(input.idempotency_key), body: { units: input.units, ...(input.source === undefined ? {} : { source: input.source }) } });
+        case "weirgate_reverse_grant": return client.request(`/v1/admin/apps/${a()}/grants/${pathPart(input.grant_id)}/reverse`, { method: "POST", idempotencyKey: String(input.idempotency_key) });
+        case "weirgate_assign_user_tier": return client.request(`/v1/admin/apps/${a()}/users/${pathPart(input.external_id)}/tier`, { method: "PUT", idempotencyKey: String(input.idempotency_key), body: { tier: input.tier, top_up_now: input.top_up_now ?? false } });
+        case "weirgate_revert_user_tier": return client.request(`/v1/admin/apps/${a()}/users/${pathPart(input.external_id)}/tier`, { method: "DELETE", idempotencyKey: String(input.idempotency_key), body: { top_up_now: input.top_up_now ?? false } });
+        default: throw new WeirgateApiError({ message: `Unknown tool: ${name}`, errorType: "invalid_request", status: 400, requestId: "local", apiVersion: API_VERSION });
+    }
+}
+async function optionalScopeRequest(client, path, query) {
+    try {
+        return await client.request(path, { query });
+    }
+    catch (error) {
+        if (!(error instanceof WeirgateApiError) || error.errorType !== "insufficient_scope")
+            throw error;
+        return { data: { data: [], pagination: { limit: 0, returned: 0, truncated: false, next_cursor: null } }, request_id: error.requestId, api_version: API_VERSION };
+    }
+}
+async function getProposal(client, proposalId) {
+    try {
+        return await client.request(`/v1/admin/config/proposals/${proposalId}`);
+    }
+    catch (error) {
+        if (!(error instanceof WeirgateApiError) || error.status !== 404)
+            throw error;
+        return client.request(`/v1/admin/webhook-proposals/${proposalId}`);
+    }
+}
+async function proposalAction(client, proposalId, action, input) {
+    const options = { method: "POST", body: action === "apply" ? { expected_base_revision: input.expected_base_revision } : undefined, idempotencyKey: input.idempotency_key };
+    try {
+        return await client.request(`/v1/admin/config/proposals/${proposalId}/${action}`, options);
+    }
+    catch (error) {
+        if (!(error instanceof WeirgateApiError) || error.status !== 404)
+            throw error;
+        return client.request(`/v1/admin/webhook-proposals/${proposalId}/${action}`, options);
+    }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@weirgate/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Weirgate CLI and local stdio MCP server: scoped, proposal-first management of Weirgate apps.",
+  "license": "MIT",
+  "author": "Astraen Labs LLC",
+  "type": "module",
+  "homepage": "https://weirgate.com/guides/cli/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "weirgate": "dist/cli/index.js",
+    "weirgate-mcp": "dist/mcp/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.9.0"
+  }
+}