Skip to content

feat(sdk): add native Deno process integration (post-v0.1.0) - #1423

Draft
samuv wants to merge 1 commit into
mainfrom
t3code/assess-deno-typescript-sdk
Draft

feat(sdk): add native Deno process integration (post-v0.1.0)#1423
samuv wants to merge 1 commit into
mainfrom
t3code/assess-deno-typescript-sdk

Conversation

@samuv

@samuv samuv commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Add native Deno integration for a release after v0.1.0.

This work is explicitly excluded from v0.1.0 at the directing user's request. Keep this PR in draft for post-v0.1.0 work; no later release version is assigned.

  • Export @stacklok-oss/mecatl-sdk/deno with native Deno.Command-backed spawn() and query() over loopback HTTP/SSE. Reuse the existing client and query state machine.
  • Add mecated serve --lifetime-stdin for parent-exit shutdown, with readiness/PID validation, bounded stderr reporting, signal fallbacks, and owned-directory cleanup.
  • Qualify stable declarations and real packed-package consumers on Deno 2.9.3/current 2.x. Release verification consumes the exact tarball selected for publication.
  • Update API reports, generated reference, guides, examples, and lifecycle documentation. Node/Bun retain real gRPC, Unix sockets, path media, and callback tools.

Development stage

  • Implementation — directing-user delivery exception; there is no separately merged Plan / Interface PR.

Contract linkage

  • Work classification: Architectural, because this adds a public runtime entry point and process-ownership contract.
  • Decision records: ADR 0329 and ADR 0330. ADR 0330 supersedes the earlier local-process exclusion. Renumbered to preserve main's ADR 0328 for public npm distribution.
  • Human waiver of spine: the directing user requested “a full integration with deno command,” then explicitly requested rebasing from origin/main and opening this PR. Implementation and acceptance documentation are therefore presented together; this is not the workflow-only Combined exception.
  • Acceptance plan: TypeScript SDK Deno support.
  • Decisions are recorded in the plan. Plan / Interface PR and approved commit baseline: none; no prior merged approval is claimed.

Interface conformance

The interface under review adds the ./deno export, Deno >=2.9.3 <3, and opt-in --lifetime-stdin. It does not change protobuf, exported Go APIs, persistence, or Node/Bun transport authority. Deno Deploy and Deno 3 are outside the qualification contract.

Issue relationship

Directing-user request; no issue assigned.

Type of change

  • New feature
  • Refactoring (shared query state machine)
  • Documentation/process

Test plan

  • Acceptance-plan checker; targeted strict trace: 4 ACs, 0 failures.
  • task sdk:deno, including stable type checks, session/run/attachment/query lifecycle, startup failure cleanup, and parent exit without client.close().
  • MECATL_SDK_PACKED_TARBALL=… node scripts/run-deno-integration.mjs, proving the supplied packed artifact path without repacking.
  • Deno-specific readiness negative tests: stale/invalid PID, non-loopback/unbound address, unsupported schema, and readiness timeout.
  • task sdk:lint and task sdk:typecheck.
  • task sdk:test: 221 tests passed (includes packed consumers, declarations, and examples).
  • task sdk:e2e with Node and Bun 1.4.1: 30 tests passed after the rebase.
  • task lint and task test (all modules and standalone hygiene proofs).
  • task lint:actions.
  • go run ./cmd/mecademo.
  • task docs, including SDK API reports, generated reference, and strict links.
  • task site:build.
  • Final panel review: all important findings addressed. Optional macOS Deno CI coverage remains advisory; local macOS Deno qualification passed.
  • Repository-wide task ac-trace-strict: blocked by the existing unsupported proposed status in docs/acceptance/callmcpwithquery-broker-support.md. The Deno plan's targeted strict trace passes.

User-facing change

Deno applications using this unreleased integration can connect remotely or own a local daemon through native Deno.Command, with explicit run, filesystem, and loopback-network permissions. The user guides document those grants, stdin-based shutdown, and the exclusion from SDK v0.1.0.

Special notes for reviewers

  • Rebased onto origin/main (470ab6ccb5994dbc97f9824cb66459397879ea9b), including the public npm migration in feat(sdk): publish TypeScript SDK to public npm as @stacklok-oss/mecatl-sdk #1421 and the performance-CI update in ci(perf): keep dashboard out of search results #1412.
  • Preserve main's public @stacklok-oss/mecatl-sdk identity, npmjs trusted-publishing configuration, and current development manifest version. This PR neither publishes a package nor changes the v0.1.0 release scope; no future version bump is invented.
  • The v0.1.0 release acceptance plan retains its Deno exclusion. The Deno acceptance contract and production-readiness tracker record the post-v0.1.0 deferral.
  • Scrutinize the native process lifecycle and the HTTP/SSE-only Deno authority boundary. The parent-exit fixture proves stdin EOF independently of disposal's TERM/KILL fallback.

@samuv samuv self-assigned this Sep 11, 2026
@samuv
samuv marked this pull request as draft September 11, 2026 16:46
Co-Authored-By: Codex <noreply@openai.com>

Signed-off-by: Samuele Verzi <samu@stacklok.com>
@samuv
samuv force-pushed the t3code/assess-deno-typescript-sdk branch from 1c7b305 to 2dffba3 Compare September 11, 2026 16:51
@samuv samuv changed the title feat(sdk): add native Deno process integration feat(sdk): add native Deno process integration (post-v0.1.0) Sep 11, 2026
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.

1 participant