@sendbird/cli 0.0.0-stage → 0.4.0

package/dist/discovery.js

@@ -0,0 +1,846 @@
+import { relayMethodDescription } from "./calls-catalog.js";
+import { valueSemantics } from "./value-semantics.js";
+import { shellCommand } from "./shell.js";
+import { skillSchema } from "./skills.js";
+import { doctorSchema } from "./diagnostics.js";
+import { readbackPlan } from "./recovery.js";
+import { sdkConfigSchema } from "./sdk-config.js";
+import { definitions, jsonSchema, exampleFor, } from "./catalog.js";
+import { sdkDefinitions, sdkExample, } from "./sdk-catalog.js";
+import { localCommands, setupSchema } from "./local.js";
+import { CliError } from "./core.js";
+import { VERSION } from "./version.js";
+import { stdoutSchema } from "./presentation.js";
+export const introspectionNames = [
+    "agent",
+    "help",
+    "describe",
+    "workflows",
+    "commands",
+    "docs search",
+    "docs read",
+];
+export function commandNodes(root) {
+    const rows = [];
+    function walk(c, prefix = "") {
+        for (const child of c.commands) {
+            const path = [prefix, child.name()].filter(Boolean).join(" ");
+            if (child.commands.length) {
+                if (localCommands.some((d) => d.name === path))
+                    rows.push({ path, command: child });
+                walk(child, path);
+            }
+            else
+                rows.push({ path, command: child });
+        }
+    }
+    walk(root);
+    return rows;
+}
+export function definitionFor(path) {
+    return [...definitions, ...sdkDefinitions].find((d) => d.name === path);
+}
+export function transportFor(path) {
+    const d = definitionFor(path);
+    return d?.method === "SDK"
+        ? "sdk"
+        : d ||
+            [
+                "app sdk-config",
+                "auth status",
+                "doctor",
+                "auth login",
+                "auth signup",
+                "auth verify-email",
+                "auth resend-verification",
+                "app use",
+                "org use",
+                "org region list",
+                "org region use",
+            ].includes(path)
+            ? "dashboard"
+            : "local";
+}
+export function effectFor(path) {
+    if (path === "docs read")
+        return "read";
+    const d = definitionFor(path);
+    if (d?.method === "SDK")
+        return d.stream
+            ? "stream"
+            : d.mutates
+                ? "mutation"
+                : "sdk-read";
+    if (d)
+        return d.method === "GET" ? "read" : "mutation";
+    return [
+        "profile create",
+        "profile use",
+        "profile delete",
+        "org use",
+        "org clear",
+        "app use",
+        "app clear",
+        "project init",
+        "auth login",
+        "auth signup",
+        "auth verify-email",
+        "auth resend-verification",
+        "org region use",
+        "auth logout",
+        "setup",
+        "skills install",
+        "skills remove",
+    ].includes(path)
+        ? "local/auth mutation"
+        : ["auth status", "doctor", "app sdk-config", "org region list"].includes(path)
+            ? "read"
+            : "offline";
+}
+export function agentGuide() {
+    return {
+        protocol_version: 1,
+        version: VERSION,
+        entrypoint: "sendbird --json agent",
+        purpose: "Sendbird administration and Chat SDK operations.",
+        documentation: {
+            repository: "https://github.com/sendbird/sendbird-tools-docs",
+        },
+        first_rules: [
+            "Requests are instructions: a named actor plus parent message plus reply text means post that reply now (an empty thread is the starting state); never ask for identifiers already given.",
+            "A mute/freeze check ends with a recovery send by the restricted member after restore; the request authorizes that probe.",
+            "Search by task verb (commands --search translate|pin|reply|scheduled|poll) before calling an operation unsupported; never substitute model output for a CLI operation.",
+            "Operator-only SDK actions without a named actor: use a channel operator from chat channel members list as --as-user.",
+            "Future default target = org use + app use (saved profile); repository binding = project init --yes (./sendbird.json).",
+            "Diagnosis-only requests: reads and doctor only; report auth login or changes as steps, do not run them.",
+            "Reads for another org/app: run them with that exact --org-id/--app-id; on rejection report inaccessible and stop, never substitute the authenticated org's data.",
+            "scheduled_at is Unix epoch milliseconds.",
+            "Customer code for a staging app must pass the hosts from app sdk-config --raw (customApiHost/customWebSocketHost); default SDK hosts reach production only.",
+        ],
+        onboarding: {
+            skill: "sendbird-setup",
+            guide: "guide/official/plugins/cli/index#intro",
+            purpose: "Optional sendbird-setup Skill: inspect/reuse installation and auth, confirm an existing org/app, then verify an authorized first task. CLI-only registration installs the operational sendbird Skill. Installing a plugin is not authentication or runtime verification.",
+            hosts: ["Claude Code", "Codex"],
+        },
+        skill_registration: {
+            inspect: ["sendbird", "skills", "status"],
+            read_now: ["sendbird", "--json", "skills", "show"],
+            install: {
+                claude: [
+                    "sendbird",
+                    "skills",
+                    "install",
+                    "--agent",
+                    "claude",
+                    "--scope",
+                    "project",
+                ],
+                codex: [
+                    "sendbird",
+                    "skills",
+                    "install",
+                    "--agent",
+                    "codex",
+                    "--scope",
+                    "project",
+                ],
+            },
+            note: "Offline CLI Skill only; current host loading/selection is unverified. Client plugins use their official installation flow.",
+        },
+        value_meanings: "Numeric enum meanings are available in describe.value_semantics and --response-schema x-sendbird-value-semantics. --json and --raw preserve original wire values; do not guess undocumented codes.",
+        offline_discovery: "agent, commands, describe and workflows do not read saved profiles, credentials or remote state. They are already offline; --dry-run is accepted but has no effect on them.",
+        project_marker: {
+            file: "./sendbird.json",
+            purpose: "Optional visible, non-secret app context for a coding project and its Agents.",
+            inspect: ["sendbird", "project", "status"],
+            create: ["sendbird", "--app-id", "APP_ID", "project", "init", "--yes"],
+            first_step: ["sendbird", "--dry-run", "agent"],
+            precedence: "The marker is read only with --project. Explicit --profile/--org-id/--app-id flags override its app, organization and region context.",
+        },
+        discovery: [
+            {
+                argv: [
+                    "sendbird",
+                    "--json",
+                    "commands",
+                    "--compact",
+                    "--search",
+                    "message send",
+                ],
+                purpose: "Find a small set of operations",
+            },
+            {
+                argv: ["sendbird", "--json", "describe", "chat", "message", "send"],
+                purpose: "Exact flags, authentication, constraints, input/output and dry-run argv",
+            },
+            {
+                argv: ["sendbird", "--json", "workflows"],
+                purpose: "Choose a declarative, non-executing task recipe",
+            },
+            {
+                argv: ["sendbird", "--json", "docs", "search", "group chat"],
+                purpose: "Find a guide or tutorial section without loading the docs site",
+            },
+        ],
+        authentication: {
+            dashboard: {
+                credential: "Environment-bound CLI OAuth Bearer",
+                check: [
+                    "sendbird",
+                    "--json",
+                    "--profile",
+                    "PROFILE",
+                    "auth",
+                    "status",
+                    "--summary",
+                ],
+                login: ["sendbird", "--profile", "PROFILE", "auth", "login"],
+                note: "auth login opens browser OAuth for the selected environment. A human must approve it; never request tokens, passwords or cookies in the conversation.",
+            },
+            sdk: {
+                credential: "Existing Chat user access token read into memory through CLI OAuth, or explicit token file",
+                required: [
+                    "--app-id",
+                    "--as-user",
+                    "CLI OAuth login, or SDK-command --user-token-file PATH (private token file; check with chat sdk status)",
+                ],
+                token_file: [
+                    "sendbird",
+                    "--profile",
+                    "PROFILE",
+                    "--app-id",
+                    "APP_ID",
+                    "chat",
+                    "sdk",
+                    "status",
+                    "--user-token-file",
+                    "PRIVATE_TOKEN_FILE",
+                    "--as-user",
+                    "USER_ID",
+                ],
+                staging: [
+                    "sendbird",
+                    "--profile",
+                    "PROFILE",
+                    "--app-id",
+                    "APP_ID",
+                    "app",
+                    "sdk-config",
+                    "--raw",
+                ],
+                note: "Automatic Chat tokens always validate Gate's app/environment/hosts before retrieval, including host overrides. Only explicit token-file/guest credentials with explicit hosts skip discovery; staging otherwise discovers hosts. Never use management credentials. Guest access is explicit and may create a user.",
+            },
+        },
+        contract: {
+            stdout: "Default stdout is a bounded readable view. Add --json for full unstyled JSON envelopes {ok, command, effect, status, target, result, response}; watch then emits NDJSON events and completion. Status: preview=no request, accepted=write acknowledged (read back), verified=read completed, completed=stream ended, succeeded=local. --raw preserves legacy JSON result/event bodies and is required for SDK config files.",
+            stderr: "Readable errors by default; --json returns structured errors with recovery suggestions. Unknown means a write may have happened.",
+            input: "Typed flags or --body-file; flags win. stdin is read only for --body-file -.",
+            mutations: "Preview with --dry-run; destructive operations require --yes. Stay within the user-authorized target.",
+            retry: "No CLI automatic mutation retry. Timeout is an uncertain outcome; read back first.",
+            context: "Explicit --profile/--org-id/--app-id override saved context. Default profile is prod; confirm the intended environment.",
+            placeholders: "UPPERCASE values in templates must be replaced with actual task bindings.",
+        },
+        known_limits: [
+            "Browser signup and OAuth callback use the selected environment where Gate enables CLI OAuth. Email verification is a separate step.",
+            "The shared sendbird/sendbird-plugins marketplace owns one catalog read by both hosts; this repository/npm package ships plugin manifests and skills, not marketplace catalogs. Local candidate catalogs use sendbird-cli-local. npm installation alone does not register Skills. No hosted MCP is provided.",
+            "Supergroup and reactions depend on app entitlements. A successful read-mark acknowledgement is not proof of updated receipts.",
+        ],
+    };
+}
+export async function compactCommands(root, opts) {
+    const limit = Number(opts.limit ?? 20), offset = Number(opts.offset ?? 0);
+    if (!Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 100 ||
+        !Number.isInteger(offset) ||
+        offset < 0)
+        throw new CliError("E_INPUT", "Discovery limit must be 1–100 and offset a nonnegative integer", 2);
+    if (opts.transport && !["dashboard", "sdk", "local"].includes(opts.transport))
+        throw new CliError("E_INPUT", "Transport must be dashboard, sdk or local", 2);
+    const rows = commandNodes(root).filter((r) => !opts.transport || transportFor(r.path) === opts.transport);
+    let matches = rows;
+    const reasons = new Map();
+    if (opts.search?.trim()) {
+        const [{ createSearchIndex }, { commandIntents }] = await Promise.all([
+            import("./search-engine.js"),
+            import("./search-intents.js"),
+        ]);
+        if (opts.search.length > 256)
+            throw new CliError("E_INPUT", "Search query must be at most 256 characters", 2);
+        const index = createSearchIndex(rows.map((r) => ({
+            id: r.path,
+            title: r.path,
+            description: r.command.description(),
+            intents: commandIntents(r.path),
+        })));
+        const hits = index.search(opts.search, rows.length);
+        matches = hits.map((hit) => {
+            reasons.set(hit.document.id, {
+                match_type: hit.match_type,
+                matched_terms: hit.matched_terms,
+            });
+            return rows.find((r) => r.path === hit.document.id);
+        });
+    }
+    return {
+        version: VERSION,
+        total: matches.length,
+        offset,
+        limit,
+        next_offset: offset + limit < matches.length ? offset + limit : null,
+        commands: matches.slice(offset, offset + limit).map((r) => ({
+            command: `sendbird ${r.path}`,
+            description: r.command.description(),
+            transport: transportFor(r.path),
+            effect: effectFor(r.path),
+            inspect: ["sendbird", "describe", ...r.path.split(" ")],
+            ...(reasons.has(r.path) ? { match: reasons.get(r.path) } : {}),
+        })),
+        ...(matches.length
+            ? {}
+            : {
+                next: [
+                    ["sendbird", "commands", "--compact"],
+                    ["sendbird", "workflows"],
+                ],
+            }),
+    };
+}
+export function exampleArgv(d) {
+    const e = d.method === "SDK" ? sdkExample(d) : exampleFor(d);
+    const argv = ["sendbird", ...d.name.split(" ")];
+    if (d.scope === "app")
+        argv.push("--app-id", "APP_ID");
+    if (d.scope === "org" || d.name === "app feature set" || d.requiresOrg)
+        argv.push("--org-id", "ORG_UID");
+    if (d.method === "SDK")
+        argv.push("--as-user", "USER_ID");
+    let privateBody = false;
+    for (const part of ["params", "query", "body"]) {
+        const values = e[part];
+        for (const [k, v] of Object.entries(values)) {
+            if ((part === "body" && d.privateFields?.includes(k)) ||
+                ["password", "api_token", "access_token", "access_code"].includes(k)) {
+                privateBody = true;
+                continue;
+            }
+            argv.push("--" + k.replace(/_+/g, "-").toLowerCase(), typeof v === "string" ? v : JSON.stringify(v));
+        }
+    }
+    if (privateBody)
+        argv.push("--body-file", "PRIVATE_BODY_FILE");
+    if ([
+        "calls push create",
+        "calls push update",
+        "chat push create",
+        "chat push update",
+    ].includes(d.name))
+        argv.push("--credential-file", "PRIVATE_CREDENTIAL_FILE");
+    argv.push("--dry-run");
+    return {
+        argv,
+        shell: shellCommand(argv, /^[a-zA-Z0-9_./:=+-]+$/),
+        input: e,
+        ...(privateBody ? { private_body_file: e.body } : {}),
+        note: "Template only. Replace identifiers; dry-run does not validate remote existence. Automatic Chat tokens always validate the authoritative SDK route, including host overrides. Explicit token-file/guest credentials skip discovery only with explicit hosts; staging credentials without hosts discover them.",
+    };
+}
+function inputSchema(schema) {
+    const value = jsonSchema(schema);
+    const properties = (value.properties ?? {});
+    return {
+        ...value,
+        required: (value.required ?? []).filter((key) => !Object.hasOwn(properties[key], "default")),
+    };
+}
+export function describeCommand(root, path) {
+    path = path.replace(/^sendbird\s+/, "").trim();
+    const row = commandNodes(root).find((r) => r.path === path);
+    if (!row)
+        throw new CliError("E_DISCOVERY", "Unknown command path. Search with sendbird commands --compact --search WORDS.", 2);
+    const d = definitionFor(path);
+    const sdk = d?.method === "SDK";
+    const seenFlags = new Set();
+    const flags = [
+        ...row.command.options,
+        ...root.options.filter((o) => o.long !== "--version"),
+    ]
+        .filter((o) => {
+        if (!o.long || seenFlags.has(o.long))
+            return false;
+        seenFlags.add(o.long);
+        return true;
+    })
+        .map((o) => ({
+        flag: o.long,
+        syntax: o.flags,
+        description: o.description,
+        takes_value: o.required || o.optional,
+    }));
+    const required = [];
+    for (const part of ["params", "query", "body"]) {
+        const schema = inputSchema(d?.[part]);
+        for (const key of schema.required)
+            if (!(part === "body" && d?.privateFields?.includes(key)) &&
+                !["password", "api_token", "access_code"].includes(key))
+                required.push("--" + key.replace(/_+/g, "-").toLowerCase());
+    }
+    if (d?.scope === "app")
+        required.push("--app-id (or saved app)");
+    if (d?.scope === "org" || path === "app feature set" || d?.requiresOrg)
+        required.push("--org-id (or saved org)");
+    if (sdk)
+        required.push("--as-user", "CLI OAuth login (or explicit --user-token-file / --allow-guest)");
+    const constraints = [];
+    if (path === "setup")
+        constraints.push("Interactive only. Reviews the selected profile/environment, organization, app and region before asking to save defaults. Saving also activates the profile. Skipping/cancelling does not persist selections; login and any resources created earlier remain, and reauthentication can reset old account context. Returns defaults_saved and explicit next_argv. A default region is for future app creation, not app migration.");
+    if (path.startsWith("app feature "))
+        constraints.push("Feature activation is distinct from subscription entitlement and runtime readiness. set requires --yes and a bound active self-service org; Gate enforces application.settings.all and plan eligibility. Data Export, Desk and AI Engine are excluded. Enabling advanced_profanity_filter also disables profanity_filter. Message Search observes region/migration locks; its preflight status GET can reset a failed non-live pipeline and is never used by list/doctor/dry-run. Accepted writes include readback; do not replay on mismatch or failed readback. Usage charges may apply under the existing plan; no subscription purchase occurs.");
+    if (/^chat (settings|webhook|announcement|push|analytics|moderation) /.test(path) ||
+        /^app (delete|ip-allowlist|partition)/.test(path) ||
+        path.startsWith("org sso "))
+        constraints.push("Pro operations use Gate OAuth and Dashboard role permissions; no management-key fallback. Mutations require the original organization and explicit --yes. Read before changing settings; dry-run validates local inputs but proves neither eligibility nor runtime behavior. See docs search for Pro feature workflows.");
+    if (path === "app delete")
+        constraints.push("Irreversible app deletion requires an exact --confirm-app-name. Calls deregistration and backend deletion may partially succeed; inspect both before any retry.");
+    if (path === "chat push enabled set")
+        constraints.push("--confirm-shared-push true acknowledges that this switch affects both Chat and Calls. Credential registration never enables it automatically.");
+    if (path.startsWith("org sso "))
+        constraints.push("Certificate/IdP URL use private body input and masked output. set/delete require an exact organization name and --yes. Enforcement also needs --login-tested true; this is the user's assertion, not a verified login. Review member impact and recovery before execution.");
+    if (/^app ip-allowlist (add|remove)$/.test(path))
+        constraints.push("Confirm the app name and current source IP. Requests that would exclude that confirmed IP are rejected. The CLI does not discover or verify the network egress IP; preserve an authorized recovery path.");
+    if (path.startsWith("chat sdk poll "))
+        constraints.push("Poll create prepares an unattached poll. Attach with chat message send --poll-id; the two commands are not atomic. Preserve a known poll_id and do not recreate a poll after an uncertain result.");
+    if (path.startsWith("chat sdk report "))
+        constraints.push("A report is a real, non-retractable moderation submission. --yes is required; no CLI processing-status lookup is available. Do not submit test reports outside authorized resources.");
+    if (path.startsWith("chat sdk user device "))
+        constraints.push("Use private --body-file for device_token. Registration preserves other devices (unique=false); pending does not prove registration or notification delivery.");
+    if (path.startsWith("calls "))
+        constraints.push("Dashboard role permissions and Calls availability remain server-enforced. No calls are placed or credits purchased.");
+    if (/^calls settings general (get|set)$/.test(path))
+        constraints.push(relayMethodDescription);
+    if (path.startsWith("calls credits "))
+        constraints.push("Voucher reads and trial claims are bound to the authenticated organization. claim-trial requires OWNER, a self-service organization, no voucher history (including expired/depleted), --yes or explicit terminal confirmation (default No); JSON/raw and non-interactive use require --yes. Developer plans are blocked. Amount and duration are server-defined; no payment or auto-renewal is requested. A 400 may follow partial voucher creation; read calls credits list before any recovery.");
+    if (path === "calls activate")
+        constraints.push("Requires organization.applications.all, the original org/app and --yes. Uses the app's current region, never moves it. Trial consent is separate: --claim-trial requests the follow-up; --yes alone never authorizes credits. Eligible human terminals offer a default-No prompt; --no-claim-trial skips it. JSON/raw and non-TTY execution never offer it. Inspect calls_trial for the independent result; never repeat activation to recover credit errors. Readback can lag; inspect calls settings push get before retrying.");
+    if ([
+        "calls push create",
+        "calls push update",
+        "chat push create",
+        "chat push update",
+    ].includes(path))
+        constraints.push("APNs creation and FCM require --credential-file. Same-format APNs metadata updates may reuse the existing certificate after paginated lookup; format changes require a file. APNs format/environment and p8 identifiers are required; Huawei uses --body-file for its secret. No credentials are written to CLI config.");
+    if (path.startsWith("calls ") &&
+        d?.method !== "GET" &&
+        path !== "calls credits claim-trial")
+        constraints.push("--yes required. Writes are acknowledged; inspect readback. Failed readback must not trigger a repeated write.");
+    if (path === "app create")
+        constraints.push("Calls registration requires --is-calls-enabled true and --yes. Select the SDK family with --is-delight-region; Calls region/subscription eligibility remains server-enforced. After confirmed activation, --claim-trial explicitly authorizes a free trial; otherwise eligible human terminals offer a default-No prompt. --no-claim-trial skips it. --yes alone, JSON/raw and non-TTY runs do not automatically claim. Credit follow-up failure preserves app creation success; inspect calls_trial and do not recreate the app. No paid credit purchase is requested. Read back the created app and Calls settings; a created Chat app is not proof Calls registration succeeded.");
+    if (path === "chat channel create")
+        constraints.push("Group/Supergroup require user_ids; Open rejects group-only options.", "Supergroup cannot be distinct. App features and quotas remain server-enforced.");
+    if (path === "chat channel list" || path === "chat channel search")
+        constraints.push("Open supports --url-contains; Group/Supergroup use --channel-urls for exact URLs. The type selects the server's super_mode filter.");
+    if (path === "chat message file")
+        constraints.push("Exactly one of --file and --file-url. Local files <=25 MiB; URLs use HTTPS.");
+    if (path === "chat message list")
+        constraints.push("Use either --before-id or --before, not both. Continue using next_before_id.");
+    if (path === "chat message thread")
+        constraints.push("Timestamp pages may overlap; deduplicate by message_id. Not a complete export.");
+    if (d?.danger)
+        constraints.push("--yes required for actual execution; never treat this as permission to expand scope.");
+    if (sdk)
+        constraints.push("Automatic Chat tokens always validate authoritative app/environment/SDK hosts before token retrieval; --sdk-config-file or explicit hosts must match and cannot bypass discovery or its failures. Explicit user-token-file/guest credentials with explicit hosts skip discovery; staging credentials without hosts still discover them. Previews stay offline.", "SDK reads may temporarily enter Open channels. Every invocation disconnects afterward.");
+    if ([
+        "chat sdk channel my list",
+        "chat channel participants list",
+        "chat sdk channel members list",
+        "chat sdk message pins list",
+        "chat sdk message scheduled list",
+        "chat sdk poll list",
+    ].includes(path))
+        constraints.push("Start with --page 1 (maximum 100) and follow result.next_page. Keep limit and filters fixed; later pages replay earlier SDK query pages and may shift if data changes. At the page ceiling, next_page is null even when more results exist; inspect pagination and narrow the query.");
+    const localRequired = {
+        "docs search": ["<query...>"],
+        "docs read": ["<id>"],
+        "app sdk-config": ["--app-id (or saved app)"],
+        "skills install": ["--agent"],
+        "skills remove": ["--agent", "--yes (unless --dry-run)"],
+        "profile create": ["--name", "--env"],
+        "profile use": ["--name"],
+        "profile delete": ["--name", "--yes"],
+        "org use": ["--id"],
+        "org region use": ["--id"],
+        "app use": ["--id"],
+    };
+    required.push(...(localRequired[path] ?? []));
+    if (path === "profile create")
+        constraints.push("--env is prod or staging. A profile stores defaults; it does not authenticate.");
+    if (path === "profile delete")
+        constraints.push("Requires --yes. Revokes any saved OAuth grant and removes the local profile; deleting the active profile selects a remaining profile.");
+    if (path === "auth login")
+        constraints.push("Browser OAuth uses an environment-bound Gate issuer and loopback callback. Gate must advertise and enable CLI OAuth there. A human must approve in a browser; this is not a CI/headless runner grant.");
+    if (path === "auth signup")
+        constraints.push("Opens the selected environment's Dashboard signup with an OAuth next URL; the person enters details and accepts terms in the browser. After approval, the loopback callback resumes CLI setup. Email verification is separate.");
+    if (path === "auth verify-email")
+        constraints.push("Requires the signed-in account and a private --token-file containing the emailed link or token. The token is never returned in stdout. --dry-run sends no request.");
+    if (path === "app create")
+        constraints.push("Pass --region or select one with org region use. Use org region list to see allowed Chat regions.");
+    if (path === "docs read")
+        constraints.push("Reads only a section ID from the installed index; needs a matching docs server. Start npm run docs in a source checkout or set --base-url/SENDBIRD_DOCS_URL.", "Remote content is bounded to 24 KB and checked against the installed index digest.");
+    const local = localCommands.find((l) => l.name === path);
+    if (local &&
+        !path.startsWith("skills ") &&
+        ![
+            "profile",
+            "profile list",
+            "project status",
+            "auth verify-email",
+            "auth resend-verification",
+        ].includes(path))
+        constraints.push("--dry-run is unsupported for this local/interactive command and is rejected before any action. Use --help or --example instead.");
+    if (path === "app get")
+        constraints.push("current_premium_features is a Dashboard plan snapshot, not a runtime capability test. super_group_channel/reactions/poll=false does not prove an operation is blocked; true does not guarantee success. Missing values are unknown. Use doctor for separate plan, activation and prerequisite evidence.");
+    if (path === "auth status")
+        constraints.push("role.permissions contains server-reported Dashboard role permissions, not proof of access to every API. Human output shows up to 12 distinct entries; --json retains the full response. Missing permissions are unknown, not an empty grant.");
+    if (path === "doctor")
+        constraints.push("GET-only evidence collection. --command accepts one exact implemented command path; --type/--id/--as-user describe its target. No SDK connection, Chat user token read, feature activation or mutation probe. False feature snapshots do not prove runtime denial.");
+    if (path.startsWith("skills "))
+        constraints.push("Offline: no profile, credential or network access. --agent is claude|codex; --scope is project (current directory, default) or user. show has neither filter. Installs only the operational sendbird Skill; modified/unmanaged registrations and symlink search paths are refused. remove requires --yes except previews. Host loading and automatic invocation remain unverified.");
+    const docsOutput = skillSchema(path)
+        ? stdoutSchema(jsonSchema(skillSchema(path)), "local")
+        : path === "doctor"
+            ? stdoutSchema(jsonSchema(doctorSchema), "local")
+            : path === "docs search"
+                ? {
+                    type: "object",
+                    required: [
+                        "version",
+                        "query",
+                        "total",
+                        "offset",
+                        "limit",
+                        "next_offset",
+                        "results",
+                    ],
+                    properties: {
+                        version: { type: "string" },
+                        query: { type: "string" },
+                        total: { type: "integer" },
+                        offset: { type: "integer" },
+                        limit: { type: "integer" },
+                        next_offset: { type: ["integer", "null"] },
+                        results: { type: "array", items: { type: "object" } },
+                    },
+                }
+                : path === "docs read"
+                    ? {
+                        type: "object",
+                        required: [
+                            "version",
+                            "id",
+                            "title",
+                            "source",
+                            "source_url",
+                            "sha256",
+                            "content",
+                        ],
+                        properties: {
+                            version: { type: "string" },
+                            id: { type: "string" },
+                            title: { type: "string" },
+                            source: { type: "string" },
+                            source_url: { type: "string" },
+                            sha256: { type: "string" },
+                            content: {
+                                type: "string",
+                                description: "Markdown section, at most 24 KB",
+                            },
+                        },
+                    }
+                    : undefined;
+    return {
+        protocol_version: 1,
+        version: VERSION,
+        command: `sendbird ${path}`,
+        description: row.command.description(),
+        transport: transportFor(path),
+        effect: effectFor(path),
+        authentication: path === "auth signup"
+            ? "None before signup; browser approval returns a Gate CLI OAuth grant"
+            : sdk
+                ? "Existing Chat user token read into memory through environment-bound CLI OAuth, or explicit token file"
+                : d
+                    ? "Gate CLI OAuth Bearer for the selected environment"
+                    : path.startsWith("docs ")
+                        ? "None; docs read needs a matching docs server"
+                        : path === "app sdk-config" ||
+                            path === "auth status" ||
+                            path === "doctor"
+                            ? "Gate CLI OAuth Bearer for the selected environment"
+                            : "See command flags",
+        required,
+        flags,
+        arguments: row.command.registeredArguments.map((a) => ({
+            name: a.name(),
+            required: a.required,
+            variadic: a.variadic,
+            description: a.description,
+        })),
+        constraints,
+        input: {
+            params: inputSchema(d?.params),
+            query: inputSchema(d?.query),
+            body: inputSchema(d?.body),
+        },
+        output: docsOutput ??
+            stdoutSchema(d
+                ? jsonSchema(d.resultSchema ?? d.response)
+                : path === "setup"
+                    ? jsonSchema(setupSchema)
+                    : path === "app sdk-config"
+                        ? jsonSchema(sdkConfigSchema)
+                        : { type: "object", additionalProperties: true }, (sdk
+                ? d.stream
+                    ? "stream"
+                    : d.mutates
+                        ? "mutation"
+                        : "sdk-read"
+                : d
+                    ? d.method === "GET"
+                        ? "read"
+                        : "mutation"
+                    : "local")),
+        value_semantics: valueSemantics(path),
+        result_schema: (skillSchema(path) ? jsonSchema(skillSchema(path)) : undefined) ??
+            (path === "doctor" ? jsonSchema(doctorSchema) : undefined) ??
+            docsOutput ??
+            (d
+                ? jsonSchema(d.resultSchema ?? d.response)
+                : path === "setup"
+                    ? jsonSchema(setupSchema)
+                    : path === "app sdk-config"
+                        ? jsonSchema(sdkConfigSchema)
+                        : { type: "object", additionalProperties: true }),
+        example: path === "docs search"
+            ? {
+                argv: ["sendbird", "docs", "search", "group chat"],
+                shell: "sendbird docs search 'group chat'",
+            }
+            : path === "docs read"
+                ? {
+                    argv: [
+                        "sendbird",
+                        "docs",
+                        "read",
+                        "guide/official/getting-started/quickstart#intro",
+                    ],
+                    shell: "sendbird docs read 'guide/official/getting-started/quickstart#intro'",
+                }
+                : d
+                    ? exampleArgv(d)
+                    : { shell: local?.example ?? `sendbird ${path} --help` },
+        recovery: [
+            "Use next and recovery.reads in structured errors to read the original target. Recovery is a plan, never an automatic retry.",
+            "mutation_state distinguishes not_attempted, rejected, unknown and acknowledged. A read match is not proof this request caused the state.",
+            "Do not retry uncertain mutations blindly.",
+        ],
+    };
+}
+export function invocationCommand(root, args) {
+    let current = root;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith("-")) {
+            const opt = [...current.options, ...root.options].find((o) => o.long === arg.split("=")[0] || o.short === arg);
+            if (!opt)
+                break;
+            if ((opt.required || opt.optional) && !arg.includes("="))
+                i++;
+            continue;
+        }
+        const child = current.commands.find((c) => c.name() === arg);
+        if (!child)
+            break;
+        current = child;
+    }
+    return current;
+}
+export function commandPath(command) {
+    const names = [];
+    let c = command;
+    while (c?.parent) {
+        names.unshift(c.name());
+        c = c.parent;
+    }
+    return names.join(" ");
+}
+export function recovery(error, command, root) {
+    const path = commandPath(command);
+    const opts = command.optsWithGlobals();
+    const prefix = [
+        "sendbird",
+        ...(error.recoverySnapshot?.profile
+            ? ["--profile", error.recoverySnapshot.profile]
+            : typeof opts.profile === "string"
+                ? ["--profile", opts.profile]
+                : []),
+    ];
+    const next = [];
+    const inspect = () => next.push({
+        argv: ["sendbird", "describe", ...path.split(" ")],
+        reason: "Read exact flags, input requirements and examples.",
+    });
+    if (path && commandNodes(root).some((r) => r.path === path))
+        inspect();
+    else
+        next.push({
+            argv: ["sendbird", "agent"],
+            reason: "Start with the compact discovery guide.",
+        });
+    if (error.code === "E_SCHEMA" &&
+        path === "chat channel create" &&
+        !error.recoverySnapshot &&
+        error.details &&
+        typeof error.details === "object" &&
+        "channel_url" in error.details &&
+        typeof error.details.channel_url === "string") {
+        const actual = "actual" in error.details ? error.details.actual : undefined;
+        if (actual &&
+            typeof actual === "object" &&
+            "is_super" in actual &&
+            typeof actual.is_super === "boolean")
+            next.unshift({
+                argv: [
+                    ...prefix,
+                    ...(typeof opts.appId === "string" ? ["--app-id", opts.appId] : []),
+                    "chat",
+                    "channel",
+                    "get",
+                    "--type",
+                    actual.is_super ? "supergroup" : "group",
+                    "--id",
+                    error.details.channel_url,
+                ],
+                reason: "Read the created channel using its actual type before deciding how to clean up; do not repeat creation.",
+            });
+    }
+    if (path === "chat channel create" &&
+        opts.type === "supergroup" &&
+        error.details &&
+        typeof error.details === "object" &&
+        "upstream_code" in error.details &&
+        error.details.upstream_code === 400108 &&
+        "status" in error.details &&
+        error.details.status === 400) {
+        const appId = error.recoverySnapshot?.app_id ?? opts.appId;
+        const orgId = error.recoverySnapshot?.org_id ?? opts.orgId;
+        next.unshift({
+            argv: [
+                ...prefix,
+                ...(typeof orgId === "string" ? ["--org-id", orgId] : []),
+                ...(typeof appId === "string" ? ["--app-id", appId] : []),
+                "doctor",
+                "--command",
+                "chat channel create",
+                "--type",
+                "supergroup",
+                "--json",
+            ],
+            reason: "Inspect plan, feature activation and role evidence without creating a channel. 400108 alone does not prove Supergroup is unsupported. Do not enable paid features or change roles automatically.",
+        });
+    }
+    if (error.code === "E_AUTH" && transportFor(path) === "sdk")
+        next.push(error.message.startsWith("Login required")
+            ? {
+                argv: [...prefix, "auth", "login"],
+                reason: "Approve CLI OAuth for the selected environment before reading the Chat user's existing access token.",
+            }
+            : {
+                argv: ["sendbird", "describe", "chat", "user", "token", "issue"],
+                reason: "The Chat user has no access token. Issue one explicitly, use an existing token file, or choose guest mode only when app policy allows it.",
+            });
+    else if (error.code === "E_AUTH")
+        next.push({
+            argv: [...prefix, "auth", "login"],
+            reason: "Use a human terminal for Dashboard login; never paste credentials into chat.",
+        });
+    if (error.code === "E_CAPABILITY" && path.startsWith("calls "))
+        next.push({
+            argv: [
+                ...prefix,
+                ...(typeof opts.appId === "string" ? ["--app-id", opts.appId] : []),
+                "app",
+                "get",
+            ],
+            reason: "Inspect the selected application and region. Calls activation does not guarantee regional API availability; do not change regions, activate trials, or switch apps without authorization.",
+        });
+    if (error.code === "E_SECRET_STORE")
+        next.push({
+            argv: ["sendbird", "docs", "search", "Secret Service"],
+            reason: "Install and unlock an OS credential store before browser OAuth login.",
+        });
+    if (error.code === "E_SDK_AUTH")
+        next.push({
+            argv: ["sendbird", "workflows", "staging-sdk"],
+            reason: "Check user-token identity and app/region binding; Dashboard tokens are not SDK credentials.",
+        });
+    if (error.code === "E_SDK_PERMISSION")
+        next.push({
+            argv: ["sendbird", "describe", ...path.split(" ")],
+            reason: "Check the actor's channel membership, operator role and app feature entitlement; do not switch credentials to bypass it.",
+        });
+    if (["E_CONTEXT", "E_PROFILE"].includes(error.code))
+        next.push({
+            argv: [...prefix, "profile", "list"],
+            reason: "Inspect saved profile and context before selecting a target.",
+        });
+    if (error.code === "E_PERMISSION")
+        next.push({
+            argv: [...prefix, "auth", "status", "--summary"],
+            reason: "Check actual role permissions. Never elevate roles automatically.",
+        });
+    if (error.code === "E_CALLS_NO_VOUCHER")
+        next.push({
+            argv: ["sendbird", "describe", "calls", "credits", "list"],
+            reason: "Inspect voucher status and expiry for the intended organization. The usage error can also result from an upstream lookup failure; it does not prove no voucher was ever issued.",
+        });
+    if (error.code === "E_INTERRUPTED" && path === "setup")
+        next.push({
+            argv: [...prefix, "doctor"],
+            reason: "Inspect the account, organization and app selected before the prompt was cancelled.",
+        });
+    if (error.code === "E_DOCS_UNAVAILABLE" || error.code === "E_DOCS_VERSION")
+        next.push({
+            argv: ["sendbird", "docs", "search", "setup"],
+            reason: "Search the offline index; for full text, start a matching docs build or set --base-url.",
+        });
+    const uncertain = error.mutationState !== undefined
+        ? error.mutationState === "unknown" ||
+            error.mutationState === "acknowledged"
+        : [
+            "E_NETWORK",
+            "E_TIMEOUT",
+            "E_INTERRUPTED",
+            "E_SDK_RUNTIME",
+            "E_SDK",
+            "E_SCHEMA",
+            "E_UPSTREAM",
+            "E_INTERNAL",
+        ].includes(error.code) &&
+            (effectFor(path) === "mutation" ||
+                (transportFor(path) === "sdk" && opts.allowGuest === true));
+    const readback = uncertain && error.recoverySnapshot
+        ? readbackPlan(error.recoverySnapshot, error.details)
+        : undefined;
+    if (readback)
+        next.unshift(...readback.reads);
+    return {
+        command: path ? `sendbird ${path}` : undefined,
+        automatic_retry: false,
+        outcome_unknown: uncertain,
+        ...(error.mutationState ? { mutation_state: error.mutationState } : {}),
+        ...(readback ? { recovery: readback } : {}),
+        next: next.filter((entry, index, all) => all.findIndex((other) => JSON.stringify(other.argv) === JSON.stringify(entry.argv)) === index),
+    };
+}
+//# sourceMappingURL=discovery.js.map