@sendbird/cli 0.0.0-stage → 0.4.0

package/skills/sendbird-setup/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: sendbird-setup
+description: Install or update Sendbird CLI for Claude Code or Codex, connect an account in the selected environment, select an existing organization and app, ask about saving defaults, and offer an optional authorized chat practice or client-plugin handoff. Use when Sendbird is missing or the user asks to connect or get started.
+---
+
+Prepare a working Sendbird connection and verify account/app read access. Chat practice is optional; setup alone does not authorize resource creation. Installing a plugin, authenticating, sending an SDK message and completing a customer app are separate outcomes. Reuse the user's working installation and login when possible. Read [installation and first task](references/onboarding.md) for the complete procedure and per-host commands.
+
+1. **Check the installation.** Resolve the actual executable, Node version and `sendbird --version`, then run `sendbird --json agent`. Inspect the commands needed for the task. An equal version does not prove an old npm link is current. If missing/incompatible, run this skill's `scripts/install-cli.mjs` with Node, resolving its absolute path from the installed skill location. It prints JSON with a verified executable; use that path for later commands or add its bin directory to this session's PATH. Never invent an npm release, overwrite an unmanaged executable, or edit shell rc files without a separate request. If project Skill registration is denied because the host protects `.agents` or `.claude`, give the exact `sendbird skills install --agent HOST --scope project` command for the person’s normal terminal. Do not retry through a different path, create custom permission rules, or disable the host sandbox. Restart or reload the host after registration and check actual Skill consumption.
+2. **Connect the intended environment.** CLI browser OAuth supports the selected prod/staging profile where Gate advertises and enables its CLI client. Use the requested profile/environment explicitly; ask if the intended target is unclear. Run `--profile PROFILE --json auth status --summary`. If missing/expired, start `auth login` and wait for the person to approve in their browser, then recheck. Do not request passwords, cookies, callback codes or tokens in chat. Explain OS credential store failures; there is no credential-file fallback. Do not rerun login after a role denial.
+3. **Select existing resources.** List the accessible organizations and apps, confirm the intended organization and exact app, then use explicit IDs on commands. Ask whether to save this exact organization/app as defaults in the selected profile or use them only for this session. Reuse a choice already supplied; do not silently choose either. Inspect `--profile PROFILE profile` before saving. `org use` clears the saved app and region, so skip it when the same org is already saved; use `app use` to save the app. Ask before making the profile globally active with `profile use`; storing context and activating a profile are separate choices. Read the profile back and report what was saved. If declined, keep explicit IDs on commands and report that defaults were not changed. No results or ambiguous results need a user choice. Do not create an organization/app as a setup shortcut. If the user wants an account or new resources, route to the CLI's `new-account-chat` workflow and preserve human signup/terms approval.
+4. **Offer optional Chat practice.** After read-only connection checks, offer to finish setup or run a two-user Chat practice. Default to finishing without writes until the person authorizes practice. Reuse explicit authorization for this target/task; do not ask again. A generic request to install, connect or set up is not permission to create users/channels, issue tokens, send messages or delete resources. If practice is authorized, read `describe` and the matching workflow, then show the planned target/resources and supported offline previews. A safe Chat practice uses two dedicated test users and a private Group channel in the user-approved app, issues user access tokens explicitly, sends a unique message as each user and reads it as the other. Inventory collisions first and never modify existing customer users/channels to make the demo pass. Write acknowledgement alone is not delivery or read state. Record returned user/channel/message IDs without tokens. Clean up only resources this run created when authorized. With no permission for writes, stop after read-only checks and previews and label practice unexecuted.
+5. **Choose assistance only when customer code is requested.** Read the sibling Skill's [three app-assistance modes](../sendbird/references/build-chat-app.md). Offer official plugin information/installation, pinned guide-only assistance in this conversation, or no client assistance; reuse an explicit selection for the same task. Do not guess or auto-switch. Show the notice summary and publisher README link before installation/execution guidance. Native installation/loading can remain pending; the separate advanced ZIP route starts a separate edit-only Claude process only after an explicit ZIP request and emits the notice before launch. Preserve prior guide-only selections; never treat them as permission to launch a model. CLI setup does not require a client plugin.
+
+Report the executable/version, plugin loaded, authentication status, verified org/app, saved defaults (or session-only context), optional practice completed/skipped/pending, first-task checks and customer-app handoff separately. Keep pending human approvals and server/account restrictions visible. Do not label a dry-run, mock, plugin install or build as first-chat success. Billing changes stay in Dashboard; never use onboarding as permission to buy credits, change a plan, start a trial, enroll 2FA or enable guest access.
+
+## Windows execution
+
+Use Windows 11 x64 with Node 22.23.4+ (22.x) or 24.22.1+ (24.x) and PowerShell 7 for native Windows work. Prefer npm's generated PowerShell shim; keep command arguments as an array. Generated `describe` examples on Windows use PowerShell quoting; Bash backslash continuations and environment assignments are not portable. If organization policy blocks a `.ps1` shim, use `node` with the installed `dist/cli.js` and separate arguments. Do not disable execution policy or elevate privileges automatically. Login uses Windows Credential Manager; if unavailable, stop and report the storage error. Never fall back to credential files or request tokens in chat. Git Bash still uses Windows Node; WSL is a separate Linux environment requiring Secret Service. Actual browser approval and complete customer app validation are separate from CI.

package/skills/sendbird-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Set up Sendbird"
+  short_description: "Connect the CLI, choose defaults, and offer optional chat practice"
+  default_prompt: "Use $sendbird-cli:sendbird-setup to connect my coding agent to Sendbird, ask whether to save defaults, and offer optional Chat practice without creating resources until authorized."

package/skills/sendbird-setup/references/onboarding.md

@@ -0,0 +1,73 @@
+# Install and connect Sendbird
+
+The npm package is `@sendbird/cli`; the executable is `sendbird`. Node.js 22.23.4+ (22.x) or 24.22.1+ (24.x) is required. Install the published package with npm; use an approved bundled artifact when testing an unpublished candidate. The installer checks the exact plugin version and required command capabilities, prefers a checksum-verified bundled CLI archive, and otherwise tries npm before building a temporary copy of a trusted Git-installed plugin checkout. It never stores Sendbird credentials or changes shell rc files. Duplicate flags or missing option values are rejected before installation. An incomplete cached install is rechecked using the returned executable, including its npm bin link.
+
+Resolve `../scripts/install-cli.mjs` relative to this reference's skill folder:
+
+```sh
+node /ABSOLUTE/INSTALLED/SKILL/scripts/install-cli.mjs --bin-dir "$HOME/.local/bin"
+```
+
+Use the returned `executable` or prepend the returned bin directory to PATH for the current session. If that bin directory contains an unmanaged command, use another directory or the prefix executable; do not remove the existing file. `--package-file /path/to/sendbird-cli.tgz` supports an explicitly supplied trusted CLI archive. `--source-root /path/to/sendbird-cli` supports an approved source checkout when npm is unavailable. `--prefix /path/to/cache` isolates installation without touching an existing CLI. A matching version with missing required commands (including skills install/status/show/remove) fails verification. CLI version strings alone do not establish that the current Skill-registration interface exists.
+
+## Native plugin installation
+
+The shared `sendbird/sendbird-plugins` repository owns the `sendbird` marketplace for both CLI and client plugins. Once its catalogs are available, hosts with repository access can install the CLI plugin:
+
+```sh
+# Claude Code
+claude plugin marketplace add sendbird/sendbird-plugins
+claude plugin install sendbird-cli@sendbird
+# Start a new session, then invoke /sendbird-cli:sendbird-setup.
+
+# Codex
+codex plugin marketplace add sendbird/sendbird-plugins
+codex plugin add sendbird-cli@sendbird
+# Start a new session, then use $sendbird-cli:sendbird-setup.
+```
+
+For an unpublished branch or offline alpha artifact, add the absolute generated marketplace directory and install `sendbird-cli@sendbird-cli-local` instead. The local catalog uses a separate name so it can coexist with the shared `sendbird` marketplace. `npm run plugins:build` creates a self-contained marketplace with both host catalogs, a CLI tarball and its checksum. This is private/local distribution, not publication in either host's public directory. GitHub access and OAuth approval remain separate prerequisites. Installation does not run authentication or mutate Sendbird resources.
+
+## Registering Skills from a sandboxed Agent
+
+Codex can protect `.agents` and `.codex` even when the project is otherwise writable. A denied `skills install` is a local host-permission issue, not a Sendbird account or server error. Run the CLI registration from a normal terminal outside that sandbox, then start a fresh Agent session. Do not repeatedly create the directory, write to another hidden folder, relax sandbox rules, or bypass a denied command through the underlying Node entrypoint. File registration and actual host loading are separate checks.
+
+## Agent-led account and app selection
+
+Use the installed CLI path in place of `sendbird` when PATH still points to an old link:
+
+```sh
+sendbird --profile staging --json auth status --summary
+# Only if missing/expired; the person approves the browser screen.
+sendbird --profile staging auth login
+sendbird --profile staging --json auth status --summary
+sendbird --profile staging --json org list
+sendbird --profile staging --org-id ORG_UID --json app list
+sendbird --profile staging --org-id ORG_UID --app-id APP_ID --json app get
+```
+
+List pages must be followed far enough to find the user's intended target. Never guess an app ID from its name or reuse another profile's context. Ask whether to persist the exact selection in this profile or keep session-only IDs; reuse an existing answer. Inspect `sendbird --profile PROFILE profile` first. If approved, use `org use --id ORG_UID` only when changing the saved org (it clears app/region), then `app use --id APP_ID`. These are real local changes and do not support dry-run. Verify the result with `profile`. Ask separately before `profile use --name PROFILE` makes the profile globally active. If declined, keep explicit profile/org/app options and report that defaults were not changed. Normal Agent setup uses explicit noninteractive commands; the human `setup` wizard requires a TTY.
+
+When a person uses `setup`, it reviews the profile/environment, org, app and
+region before asking to save defaults. Saving also activates the profile.
+Read `defaults_saved` and use the returned `next_argv` when defaults were not
+saved; never infer persistence from setup success alone. Skipping/cancelling
+does not save selections, but sign-in and already-created resources remain.
+Reauthentication may reset the old account context. The default region is for
+future app creation, not migration of the selected app.
+
+After read-only setup, offer to finish or run optional Chat practice. Installing/connecting alone does not authorize users, channels, token issuance, messages or cleanup. Until practice is authorized for the selected app, finish without writes and report practice as skipped/pending. Reuse a prior explicit authorization rather than asking again. Once authorized, read `sendbird --json workflows first-message` and `sendbird --json describe chat message send` before preparing the first Chat practice. Use task search if that workflow ID is unavailable in the installed version. User-token issuance is explicit; the default SDK path retrieves an existing token into memory. Do not export it for ordinary CLI practice. Keep the exact app and profile on every operation. Customer UI integration must implement runtime authentication under the selected assistance mode; a Dashboard login is not an end user's Chat identity.
+
+## Completion and recovery
+
+- CLI/plugin installed: package and host loader checked; no Sendbird access implied.
+- Connected: auth read succeeded for the intended environment/account.
+- Context verified: exact org/app read succeeded.
+- First Chat verified: the acknowledged messages were independently read as the other test user.
+- Customer app: selected assistance mode, native-plugin/guide source when used, build and live UI checks are separate, reported individually.
+
+401/expired grant requires approval again. 403 requires the stated permission, not account switching. Region/service errors require a compatible approved app. Unknown mutation outcomes require readback before retry. Only delete IDs in this run's created-resource record. Do not publish tokens, private files or raw agent logs in the completion report.
+
+This flow borrows Bird's inspect/reuse → browser sign-in → workspace confirmation → first operation → verification sequence. It does not copy Bird's MCP dependency or assume server enablement/approval for production OAuth or quoted paid operations.
+
+When reusing the same installer prefix and bin directory, a link from a completed installation is upgraded atomically after the new CLI is verified. The installer checks the previous receipt and cache boundary; merely pointing inside versions/ is not enough. Regular files, foreign links, unreceipted paths and links escaping the cache are preserved. Previous version caches are retained.

package/skills/sendbird-setup/scripts/install-cli.mjs

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+import { npmInvocation } from "./npm-run.mjs";
+// Explicit onboarding action, never an install hook. No credentials or shell
+// configuration are read/copied by this helper. npm lifecycle scripts are off.
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  mkdtempSync,
+  cpSync,
+  rmSync,
+  symlinkSync,
+  lstatSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join, resolve, relative, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const run = (exe, args, cwd) => {
+  if (exe === "npm") {
+    const invocation = npmInvocation(args);
+    exe = invocation.command;
+    args = invocation.args;
+  } else if (process.platform === "win32" && exe.endsWith("sendbird.cmd")) {
+    args = [
+      join(dirname(exe), "..", "@sendbird", "cli", "dist", "cli.js"),
+      ...args,
+    ];
+    exe = process.execPath;
+  }
+  return execFileSync(exe, args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 180_000,
+  });
+};
+const json = (file) => JSON.parse(readFileSync(file, "utf8"));
+const digest = (file) =>
+  createHash("sha256").update(readFileSync(file)).digest("hex");
+function fail(code, message) {
+  const e = Error(message);
+  e.code = code;
+  throw e;
+}
+function inside(base, path) {
+  const r = relative(base, path);
+  return r && !r.startsWith("..") && !isAbsolute(r);
+}
+// A path inside versions/ is not ownership evidence by itself. Require the
+// receipt from a completed install and reject cache symlinks escaping the root.
+export function isManagedExecutable(target, dataRoot) {
+  try {
+    const prefix = resolve(dirname(target), "../..");
+    if (
+      !inside(join(dataRoot, "versions"), prefix) ||
+      target !==
+        join(
+          prefix,
+          "node_modules",
+          ".bin",
+          process.platform === "win32" ? "sendbird.cmd" : "sendbird",
+        )
+    )
+      return false;
+    const receipt = json(join(prefix, "installation.json"));
+    return (
+      receipt.ok === true &&
+      receipt.installed === true &&
+      typeof receipt.version === "string" &&
+      /^[a-f0-9]{64}$/.test(receipt.sha256) &&
+      prefix ===
+        join(
+          dataRoot,
+          "versions",
+          `${receipt.version}-${receipt.sha256.slice(0, 16)}`,
+        ) &&
+      receipt.executable === target &&
+      inside(realpathSync(dataRoot), realpathSync(target))
+    );
+  } catch {
+    return false;
+  }
+}
+export function publishExecutable(link, executable, dataRoot) {
+  let existing;
+  try {
+    existing = lstatSync(link);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  if (!existing) {
+    symlinkSync(executable, link);
+    return;
+  } // No-replace creation.
+  const bin = dirname(link);
+  const oldTarget = existing.isSymbolicLink()
+    ? resolve(bin, readlinkSync(link))
+    : undefined;
+  if (oldTarget === executable) return;
+  if (!oldTarget || !isManagedExecutable(oldTarget, dataRoot))
+    fail(
+      "E_INSTALL_CONFLICT",
+      `A different sendbird already exists in ${bin}; use the verified executable or choose another bin directory`,
+    );
+  const pending = join(bin, `.sendbird-${randomUUID()}.tmp`);
+  let created = false;
+  try {
+    symlinkSync(executable, pending);
+    created = true;
+    // Detect ordinary concurrent replacement before atomic publication. The
+    // caller's own bin/cache directories remain a local filesystem trust boundary.
+    const current = lstatSync(link);
+    if (
+      !current.isSymbolicLink() ||
+      current.dev !== existing.dev ||
+      current.ino !== existing.ino ||
+      resolve(bin, readlinkSync(link)) !== oldTarget
+    )
+      fail(
+        "E_INSTALL_CONFLICT",
+        "sendbird changed during installation; inspect the existing link before retrying",
+      );
+    renameSync(pending, link);
+  } finally {
+    if (created)
+      try {
+        unlinkSync(pending);
+      } catch (e) {
+        if (e.code !== "ENOENT") throw e;
+      }
+  }
+}
+
+export function installCli(argv = process.argv) {
+  const opts = {};
+  let stage = "input",
+    temporary,
+    verifiedExecutable;
+  try {
+    if (argv.length === 3 && ["--help", "-h"].includes(argv[2])) {
+      process.stdout.write(
+        "Install a verified Sendbird CLI for agent onboarding.\nOptions: --package-file FILE --source-root DIR --prefix DIR --bin-dir DIR\nNo shell rc changes; an existing unmanaged executable is never overwritten.\n",
+      );
+    } else {
+      for (let i = 2; i < argv.length; i += 2) {
+        if (
+          ![
+            "--package-file",
+            "--source-root",
+            "--prefix",
+            "--bin-dir",
+          ].includes(argv[i]) ||
+          !argv[i + 1] ||
+          argv[i + 1].startsWith("--") ||
+          Object.hasOwn(opts, argv[i])
+        )
+          fail("E_INPUT", "Use --help for supported installation options");
+        opts[argv[i]] = resolve(argv[i + 1]);
+      }
+      const version = process.versions.node;
+      const [major, minor, patch] = version.split(".").map(Number);
+      const supported =
+        /^\d+\.\d+\.\d+$/.test(version) &&
+        ((major === 22 && (minor > 23 || (minor === 23 && patch >= 4))) ||
+          (major === 24 && (minor > 22 || (minor === 22 && patch >= 1))));
+      if (!supported)
+        fail(
+          "E_NODE_VERSION",
+          "Sendbird CLI requires Node.js 22.23.4+ (22.x) or 24.22.1+ (24.x); update Node.js before installing",
+        );
+      const source = opts["--source-root"] ?? root;
+      const expected = json(join(root, "plugin.json")).version;
+      const dataRoot =
+        opts["--prefix"] ??
+        (process.platform === "win32"
+          ? join(process.env.LOCALAPPDATA ?? homedir(), "Sendbird", "CLI")
+          : join(homedir(), ".local", "share", "sendbird-cli"));
+      temporary = mkdtempSync(join(tmpdir(), "sendbird-cli-install-"));
+      let archive = opts["--package-file"],
+        origin = "explicit_archive";
+      if (!archive && existsSync(join(root, "release-manifest.json"))) {
+        stage = "integrity";
+        const manifest = json(join(root, "release-manifest.json"));
+        archive = resolve(root, manifest.cli.file);
+        if (
+          !inside(root, archive) ||
+          !/^[a-f0-9]{64}$/.test(manifest.cli.sha256) ||
+          digest(archive) !== manifest.cli.sha256
+        )
+          fail(
+            "E_INTEGRITY",
+            "Bundled CLI checksum is invalid; obtain the original plugin archive",
+          );
+        origin = "bundled_archive";
+      }
+      if (!archive) {
+        stage = "registry";
+        try {
+          const packed = JSON.parse(
+            run("npm", [
+              "pack",
+              `@sendbird/cli@${expected}`,
+              "--ignore-scripts",
+              "--json",
+              "--pack-destination",
+              temporary,
+            ]),
+          );
+          archive = join(temporary, packed[0].filename);
+          origin = "npm";
+        } catch {
+          // Private alpha: a Git-installed plugin can build its own trusted
+          // checkout in a temporary copy, without mutating the host's cache.
+          if (!existsSync(join(source, "src", "cli.ts")))
+            fail(
+              "E_INSTALL_UNAVAILABLE",
+              "This CLI version is not available from npm. Use a CLI/plugin release archive or a trusted source checkout with --source-root",
+            );
+          stage = "source_build";
+          const build = join(temporary, "source");
+          mkdirSync(build);
+          for (const path of [
+            "src",
+            "skills",
+            "references",
+            "package.json",
+            "package-lock.json",
+            "tsconfig.json",
+            "README.md",
+            "PROVENANCE.md",
+            "LICENSE",
+            "NOTICE.md",
+            "plugin.json",
+            ".claude-plugin",
+            ".codex-plugin",
+            ".agents",
+          ])
+            if (existsSync(join(source, path)))
+              cpSync(join(source, path), join(build, path), {
+                recursive: true,
+              });
+          mkdirSync(join(build, "scripts"));
+          cpSync(
+            join(source, "scripts/build.mjs"),
+            join(build, "scripts/build.mjs"),
+          );
+          const metadata = json(join(build, "package.json"));
+          if (
+            metadata.name !== "@sendbird/cli" ||
+            metadata.version !== expected
+          )
+            fail(
+              "E_VERSION",
+              "Source CLI identity/version differs from this plugin",
+            );
+          run(
+            "npm",
+            ["ci", "--ignore-scripts", "--no-audit", "--no-fund"],
+            build,
+          );
+          run("npm", ["run", "build"], build);
+          const packed = JSON.parse(
+            run(
+              "npm",
+              [
+                "pack",
+                "--ignore-scripts",
+                "--json",
+                "--pack-destination",
+                temporary,
+              ],
+              build,
+            ),
+          );
+          archive = join(temporary, packed[0].filename);
+          origin = "plugin_source";
+        }
+      }
+      stage = "package";
+      const metadata = JSON.parse(
+        run("tar", ["-xOf", archive, "package/package.json"]),
+      );
+      if (metadata.name !== "@sendbird/cli" || metadata.version !== expected)
+        fail(
+          "E_VERSION",
+          "CLI archive identity/version differs from this plugin",
+        );
+      const sha256 = digest(archive);
+      const prefix = join(
+        dataRoot,
+        "versions",
+        `${expected}-${sha256.slice(0, 16)}`,
+      );
+      const cli = join(
+        prefix,
+        "node_modules",
+        "@sendbird",
+        "cli",
+        "dist",
+        "cli.js",
+      );
+      stage = "install";
+      mkdirSync(prefix, { recursive: true, mode: 0o700 });
+      const executable = join(
+        prefix,
+        "node_modules",
+        ".bin",
+        process.platform === "win32" ? "sendbird.cmd" : "sendbird",
+      );
+      if (!existsSync(cli) || !existsSync(executable))
+        run("npm", [
+          "install",
+          "--prefix",
+          prefix,
+          "--omit=dev",
+          "--ignore-scripts",
+          "--no-audit",
+          "--no-fund",
+          archive,
+        ]);
+      stage = "verify";
+      const guide = JSON.parse(run(executable, ["--json", "agent"]));
+      if (guide.version !== expected)
+        fail("E_VERSION", "Installed CLI version does not match");
+      const names = new Set();
+      for (let offset = 0; offset < 500; offset += 100) {
+        const page = JSON.parse(
+          run(executable, [
+            "--json",
+            "commands",
+            "--compact",
+            "--limit",
+            "100",
+            "--offset",
+            String(offset),
+          ]),
+        );
+        for (const d of page.commands) names.add(d.command);
+        if (page.next_offset == null) break;
+      }
+      for (const name of [
+        "skills install",
+        "skills status",
+        "skills show",
+        "skills remove",
+        "auth login",
+        "org list",
+        "app list",
+        "chat channel create",
+        "chat message send",
+        "billing plan check",
+        "calls settings general get",
+      ])
+        if (!names.has(`sendbird ${name}`))
+          fail("E_VERSION", "Installed CLI lacks required onboarding commands");
+      verifiedExecutable = executable;
+      let binDir = opts["--bin-dir"];
+      if (binDir) {
+        stage = "link";
+        mkdirSync(binDir, { recursive: true });
+        if (process.platform === "win32") {
+          // Shims require no symlink privilege. Never replace an unrelated file.
+          const launchers = {
+            "sendbird.cmd": `@echo off\r\nsetlocal DisableDelayedExpansion\r\nchcp 65001 >nul\r\nrem Sendbird CLI managed launcher\r\n"${process.execPath}" "${cli}" %*\r\n`,
+            "sendbird.ps1": `# Sendbird CLI managed launcher\r\n& '${process.execPath.replaceAll("'", "''")}' '${cli.replaceAll("'", "''")}' @args\r\nexit $LASTEXITCODE\r\n`,
+          };
+          // cmd expands % and interprets control characters even inside quoted paths.
+          if (/[%%\r\n"]/u.test(process.execPath + cli))
+            fail(
+              "E_INPUT",
+              "Windows launcher paths cannot contain percent, quotes or newlines",
+            );
+          for (const name of Object.keys(launchers)) {
+            const path = join(binDir, name);
+            if (existsSync(path))
+              fail(
+                "E_LINK_EXISTS",
+                "A Windows launcher already exists; choose an empty --bin-dir. No launcher was replaced",
+              );
+          }
+          const created = [];
+          try {
+            for (const [name, body] of Object.entries(launchers)) {
+              const path = join(binDir, name);
+              writeFileSync(path, body, { flag: "wx" });
+              created.push(path);
+            }
+          } catch (error) {
+            for (const path of created) unlinkSync(path);
+            throw error;
+          }
+        } else {
+          const link = join(binDir, "sendbird");
+          publishExecutable(link, executable, dataRoot);
+        }
+      }
+      const output = {
+        ok: true,
+        installed: true,
+        version: expected,
+        source: origin,
+        sha256,
+        executable,
+        bin_dir: binDir ?? null,
+        commands_verified: names.size,
+        authentication: "not_checked",
+      };
+      writeFileSync(
+        join(prefix, "installation.json"),
+        JSON.stringify(output, null, 2) + "\n",
+        { mode: 0o600 },
+      );
+      process.stdout.write(JSON.stringify(output) + "\n");
+    }
+  } catch (e) {
+    process.stderr.write(
+      JSON.stringify({
+        ok: false,
+        ...(verifiedExecutable
+          ? { executable: verifiedExecutable, cli_verified: true }
+          : {}),
+        code: /^E_[A-Z_]+$/.test(e.code ?? "") ? e.code : "E_INSTALL",
+        stage,
+        message: /^E_[A-Z_]+$/.test(e.code ?? "")
+          ? e.message
+          : `CLI ${stage} failed; check Node/npm access and retry the explicit installation. No authentication was performed.`,
+      }) + "\n",
+    );
+    process.exitCode = 1;
+  } finally {
+    if (temporary) rmSync(temporary, { recursive: true, force: true });
+  }
+}
+if (
+  process.argv[1] &&
+  realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)
+)
+  installCli();

package/skills/sendbird-setup/scripts/npm-run.mjs

@@ -0,0 +1,34 @@
+/** Execute npm without a shell, including Windows' non-executable npm.cmd shim. */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, delimiter } from "node:path";
+export function npmInvocation(args) {
+  if (process.platform !== "win32") return { command: "npm", args };
+  const candidates = [
+    process.env.npm_execpath,
+    join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+    ...(process.env.PATH ?? "")
+      .split(delimiter)
+      .map((p) =>
+        join(
+          p.replace(/^"|"$/g, ""),
+          "node_modules",
+          "npm",
+          "bin",
+          "npm-cli.js",
+        ),
+      ),
+  ];
+  const cli = candidates.find(
+    (p) => p && /[\\/]npm-cli\.js$/i.test(p) && existsSync(p),
+  );
+  if (!cli)
+    throw Error(
+      "Cannot locate npm-cli.js; install Node.js with npm and reopen the terminal",
+    );
+  return { command: process.execPath, args: [cli, ...args] };
+}
+export function runNpm(args, options) {
+  const invocation = npmInvocation(args);
+  return execFileSync(invocation.command, invocation.args, options);
+}