feat(sdk): add TypeScript SDK (@nvidia/openshell-sdk)

[maxdubrinsky]

Summary

Adds the first native TypeScript SDK for the OpenShell gateway
(@nvidia/openshell-sdk), generated from the protobufs over connect-es with no
FFI or napi. It covers the v0.1 surface (sandbox lifecycle, health, streamed
exec) and wires up codegen, CI, and tagged publishing to GitHub Packages.

Related Issue

Supersedes the shared-FFI-core direction from RFC-0008 (#1764): the
frequently-changing surface (RPCs and messages) is already shared through
proto/, so each language builds a native client over the generated stubs
instead of binding a common Rust core.

Changes

• sdk/typescript/ — new package. OpenShellClient (create/get/list/delete
  plus waitReady/waitDeleted, health, streamed exec), transport/auth
  (h2c + Node TLS + OIDC bearer / CF-Access), and typed errors. Stubs are
  generated with protoc + @bufbuild/protoc-gen-es (pinned protoc 29.6);
  src/gen/ and dist/ are gitignored, and dist/ ships the compiled stubs so
  consumers never regenerate.
• Tasks / CI — tasks/typescript.toml
  (install/proto/typecheck/build/ci/publish); sdk:ts:typecheck added to
  check; new sdk-typescript job in branch-checks.yml running typecheck,
  build, and a --dry-run publish that validates the release path.
• Licensing — SPDX enforcement extended to .ts/.tsx/.mts/.cts (skips
  node_modules and generated gen/); two back-filled headers.
• Release — release.py gains an npm version format; release-tag.yml
  publishes to GitHub Packages on tag, stamping the version from the tag (repo
  keeps a 0.0.0 placeholder). Prerelease builds publish under the next
  dist-tag, stable under latest.

Distribution note: GitHub Packages forces the @nvidia scope and requires
consumers to add a project .npmrc and a token even for public installs. The
public API matches the eventual GA package (@openshell/sdk on public npm),
so only the install specifier changes at GA.

Open decision (for review)

Package name/scope is unsettled; see the resolvable thread on package.json
(the name field). Pre-GA is @nvidia/openshell-sdk; the proposed GA name is
@openshell/sdk on public npm.

Testing

• TS SDK: protoc codegen, tsc typecheck, and build all green; npm publish --dry-run produces a valid 30-file tarball (dist/** + README +
  package.json) and restores the placeholder.
• License check green (625 files); ruff clean on changed Python.
• mise run pre-commit: validated in CI. (Locally the alias also
  builds/tests the Rust workspace, which the sandbox blocks; that workspace
  is untouched here.)

Not included: a vitest unit suite and a gateway-gated live e2e test, both
follow-ups.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs — n/a (no published subsystem doc added)

[maxdubrinsky]

Naming decision to settle here (resolvable thread).

GH Packages forces the @nvidia scope, so pre-GA ships as @nvidia/openshell-sdk. Proposed GA target: @openshell/sdk on public npm — and reserve the @openshell org now to pre-empt squatting. Public API is identical across the move, so GA is an install-specifier change only.

👍 to confirm, or propose an alternative scope/name.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2122.docs.buildwithfern.com/openshell

[benoitf]

question: can it generate with namespaces ?

like one sandbox with list() method vs tons or root methods like listSandboxes, createSandbox

const myClient = OpenShellClient.connect(...);
await myClient.sandbox.create(...)
await myClient.sandbox.list(...)
await myClient.gateway.add(...)
await myClient.gateway.list(...)

like the CLI where we have verbs gateway, sandbox, policy, provider , etc.

[maxdubrinsky]

question: can it generate with namespaces ?

like one sandbox with list() method vs tons or root methods like listSandboxes, createSandbox

const myClient = OpenShellClient.connect(...);
await myClient.sandbox.create(...)
await myClient.sandbox.list(...)
await myClient.gateway.add(...)
await myClient.gateway.list(...)

like the CLI where we have verbs gateway, sandbox, policy, provider , etc.

@benoitf good question, no we can't but the client isn't generated so namespacing is something we can just do. Refactored this to be closer to the existing Python SDK with a SandboxClient which gets exported from a OpenShellClient class.