Skip to content

feat!: build, test, and package the TypeScript SDK standalone as @ai-openshell/sdk - #2

Merged
pimlock merged 8 commits into
mainfrom
feat/standalone-build/pimlock
Nov 18, 2026
Merged

pimlock merged 8 commits into
mainfrom
feat/standalone-build/pimlock

Conversation

@pimlock

@pimlock pimlock commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Makes the imported SDK build, test and package without a core checkout, and renames the package to @ai-openshell/sdk. This is the second step of the move, the counterpart of ai-openshell/sdk-python#3. It's stacked on the history import in #1; once #1 merges, this PR retargets to main. Tracking: ai-openshell/openshell#5480.

The package name changes to @ai-openshell/sdk. GitHub Packages ties an npm scope to the account that owns it, so a workflow in this repository can't publish @nvidia/openshell-sdk. The package becomes @ai-openshell/sdk, still on GitHub Packages for now, and moves to npmjs.org later under the same name (see the decisions in ai-openshell/openshell#5480). The entry points (. and ./raw) and the curated API stay the same. The core pin is v0.1.9; regenerated raw bindings now include ServiceDiscovery and its route snapshot and watch messages.

Commits

  1. Build from a pinned core release. OPENSHELL_CORE_REF = "v0.1.9" in mise.toml is the single pin. proto:fetch runs buf export against core's git repository at that tag (the same input sdk-go and sdk-python use), proto:gen runs the existing buf.gen.yaml on the exported protos, and proto:check fails when src/gen is stale. mise.toml implements the repository template's task contract (ci, check, test, build, format, format:check, lint, workflows:check), and mise.lock pins Node, actionlint, shellcheck and zizmor. buf, Biome, TypeScript and Vitest still come from package-lock.json, as in core.
  2. Generated bindings, alone in their own commit so reviewers can skip it. They are byte-identical to what core's sdk:ts:proto generates at v0.1.9. .gitattributes marks them linguist-generated.
  3. OAuth conformance fixture, vendored from core's sdk/conformance/ as in sdk-go and sdk-python. vendored:check compares it with core at the pin. Biome skips it so it stays byte-identical.
  4. Rename to @ai-openshell/sdk: package.json, the lockfile's root entry, doc comments and the README. The README tells existing users how to upgrade and documents the new tasks. prepublishOnly only builds, because the bindings are committed.
  5. CI, described below.

Why the generated bindings are committed

Same reasoning as sdk-python#3: here the protos live in another repository, so the choice is between needing core on every build and needing it only when the pin moves. Committing keeps npm install github:ai-openshell/sdk-typescript#<ref>-style builds, contributor setup and release builds independent of core, and makes every bump PR show how the generated API changed. Committing generated bindings does not change which files ship in the npm tarball.

CI

The template's ci workflow:

  • checks: format check, lint, typecheck, proto:check, vendored:check.
  • test (node 20.20.2), (22.23.4), (24.22.2): every Node version that engines (>=20.3) claims and that is still in use. Core only tested one. The job sets MISE_NODE_VERSION.
  • build: dist/, then npm pack --dry-run checks that both entry points and their declarations are in the package and that no tests or sources are.
  • workflows: actionlint, zizmor and shellcheck.
  • ci: fails unless every job above succeeded. This is the one check to require, with the same name as in sdk-go and sdk-python.

Validation

  • mise install --locked && mise run ci passes from a clean clone: 206 tests, coverage above the 80% gate, proto:check, vendored:check, and the package check.
  • MISE_NODE_VERSION=20.20.2 mise run test and MISE_NODE_VERSION=22.23.4 mise run test pass.
  • mise run workflows:check reports no findings.

Not in this PR

  • Repository template (CODEOWNERS, issue and PR templates, AGENTS.md, CONTRIBUTING, SECURITY, dependabot, CodeQL, .template.toml): a separate chore(template): bootstrap PR, as BOOTSTRAP.md in the template describes.
  • Publishing, core sync and E2E: release.yml to GitHub Packages, core-watch and core-drift, and an E2E workflow that runs e2e/interactive-exec.mjs against a published gateway. These need the sdk-bot environment and the bot app on this repository.
  • Core cutover: the freeze check (chore(sdk/ts): freeze core SDK changes at v0.1.9 openshell#5684), removing the SDK from core's CI and releases, and porting the open core PRs that edit sdk/typescript, tracked in chore(sdk/ts): migrate the TypeScript SDK to ai-openshell/sdk-typescript openshell#5480.

Core release refresh

Merged the refreshed history import without rewriting existing commits. The core pin and committed bindings now use v0.1.9; src/gen/openshell_pb.ts adds service-discovery descriptors and messages. Local mise run ci and mise run workflows:check pass with 206 tests and 93.54% line coverage.

OPENSHELL_CORE_REF in mise.toml pins core v0.1.8. proto:fetch exports the
protos at that tag with buf, proto:gen regenerates src/gen, and proto:check
fails when the committed bindings are stale. mise.toml implements the
repository template's task contract (ci, check, test, build, format,
format:check, lint, workflows:check), with Node 24, 22 and 20 locked in
mise.lock.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Generated by mise run proto:gen at core v0.1.8; byte-identical to what core's
sdk:ts:proto generates at that tag. .gitattributes marks them generated.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
src/oidc.test.ts read core's sdk/conformance fixture through a relative path.
The copy lives in test/fixtures, and vendored:check compares it with core at
the pinned ref. Biome skips it so it stays byte-identical.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
GitHub Packages ties an npm scope to the owning account, so this repository
can't publish @nvidia/openshell-sdk. The package becomes @ai-openshell/sdk,
still on GitHub Packages, with npmjs.org to follow under the same name. The
entry points and the API are unchanged. prepublishOnly only builds, because
the bindings are committed. The README explains the upgrade and the new
development tasks.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
The template's ci workflow: checks, test on every Node version in mise.toml,
build, workflows, and the aggregating ci job, which is the one check to
require.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@matthewgrossman

Copy link
Copy Markdown
Member

Review

All checks pass (checks, Node 20/22/24 tests, build, workflows, ci, DCO).

Overview

Makes the imported SDK build, test, and package without a core checkout (protos fetched at a pinned core tag, generated bindings committed) and renames the package to @ai-openshell/sdk.

Key design decisions

  • Single pin. OPENSHELL_CORE_REF = "v0.1.8" in mise.toml. proto:fetch runs buf export at that tag, and proto:check fails on a stale src/gen.
  • Committed bindings, in their own commit. This reverses core's src/gen/ ignore, so builds don't need core, and each bump PR shows how the generated API changed.
  • Vendored OAuth conformance fixture, checked against core at the pin by vendored:check.
  • CI. SHA-pinned actions, persist-credentials: false, zizmor/actionlint/shellcheck, and a final ci job that fails unless every job succeeded.

Potential concerns

  • Package rename breaks existing consumers. Before this PR, consumers installed @nvidia/openshell-sdk. With this PR, new releases come only as @ai-openshell/sdk, so imports and package.json need updating. The README documents the upgrade and this looks deliberate. A deprecation notice on the old package would help.
  • Drift is undetected for now. The bindings are pinned to v0.1.8 and core-watch/core-drift are out of scope. Until the cutover lands, core's sdk/typescript/ and this repo are both live, and core's AGENTS.md still describes the SDK as living in core.
  • No release workflow yet. prepublishOnly only builds, and nothing publishes @ai-openshell/sdk. The PR notes this as a follow-up.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
Base automatically changed from chore/import-history/pimlock to main November 18, 2026 20:44
@pimlock
pimlock dismissed matthewgrossman’s stale review November 18, 2026 20:44

The base branch was changed.

@pimlock
pimlock merged commit 67d9529 into main Nov 18, 2026
8 of 15 checks passed
@pimlock
pimlock deleted the feat/standalone-build/pimlock branch November 18, 2026 20:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants