@teatoolkit/sbud 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 teaToolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# sbud for Node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Node client for the sbud service, for Node 20 and later. This early preview has one call, `service()` on `SbudClient`, which reads the running service's version. The service itself has not been released yet, so the preview has been tested only against a stand-in service.
+
+```js
+import { SbudClient } from "@teatoolkit/sbud";
+
+console.log((await new SbudClient().service()).version);
+```

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+export interface ServiceInfo {
+    apiVersion: number;
+    version: string;
+    pid: number;
+    endpoint: string;
+    startedAt: string;
+}
+/** Talks to the sbud service over its named pipe (Windows) or Unix socket (macOS, Linux). */
+export declare class SbudClient {
+    readonly endpoint: string;
+    constructor(endpoint?: string);
+    /** GET /v1/service: the running service's API version, version, process and endpoint. */
+    service(): Promise<ServiceInfo>;
+    private send;
+}

package/dist/client.js

@@ -0,0 +1,37 @@
+import { request } from "node:http";
+import { defaultEndpoint } from "./endpoint.js";
+import { SbudError } from "./errors.js";
+/** Talks to the sbud service over its named pipe (Windows) or Unix socket (macOS, Linux). */
+export class SbudClient {
+    endpoint;
+    constructor(endpoint) {
+        this.endpoint = endpoint ?? defaultEndpoint();
+    }
+    /** GET /v1/service: the running service's API version, version, process and endpoint. */
+    service() {
+        return this.send("GET", "/v1/service");
+    }
+    send(method, path) {
+        return new Promise((resolve, reject) => {
+            const req = request({ socketPath: this.endpoint, method, path, headers: { Accept: "application/json" } }, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(chunk));
+                res.on("end", () => {
+                    const text = Buffer.concat(chunks).toString("utf8");
+                    const body = text ? JSON.parse(text) : null;
+                    const status = res.statusCode ?? 0;
+                    if (status >= 400) {
+                        const problem = (body ?? {});
+                        reject(new SbudError(problem.kind ?? "failed", problem.title ?? `HTTP ${status}`, status));
+                    }
+                    else {
+                        resolve(body);
+                    }
+                });
+                res.on("error", reject);
+            });
+            req.on("error", () => reject(new SbudError("unavailable", `The sbud service is not answering at ${this.endpoint}.`)));
+            req.end();
+        });
+    }
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,2 @@
+/** The service's endpoint: SBUD_SOCKET if set, else the named pipe or socket the service uses by default. */
+export declare function defaultEndpoint(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;

package/dist/endpoint.js

@@ -0,0 +1,14 @@
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+/** The service's endpoint: SBUD_SOCKET if set, else the named pipe or socket the service uses by default. */
+export function defaultEndpoint(env = process.env, platform = process.platform) {
+    if (env.SBUD_SOCKET)
+        return env.SBUD_SOCKET;
+    if (platform === "win32") {
+        const user = userInfo().username.replace(/[^A-Za-z0-9._-]/g, "_");
+        return `\\\\.\\pipe\\sbud-${user}`;
+    }
+    if (env.XDG_RUNTIME_DIR)
+        return join(env.XDG_RUNTIME_DIR, "sbud.sock");
+    return join(env.SBUD_HOME || join(homedir(), ".sbud"), "sbud.sock");
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A request the service refused or could not answer. `kind` is the problem kind the service sent,
+ * such as `not-found`, or `unavailable` when the service did not answer at all.
+ */
+export declare class SbudError extends Error {
+    readonly kind: string;
+    readonly title: string;
+    readonly status?: number | undefined;
+    constructor(kind: string, title: string, status?: number | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/**
+ * A request the service refused or could not answer. `kind` is the problem kind the service sent,
+ * such as `not-found`, or `unavailable` when the service did not answer at all.
+ */
+export class SbudError extends Error {
+    kind;
+    title;
+    status;
+    constructor(kind, title, status) {
+        super(title);
+        this.kind = kind;
+        this.title = title;
+        this.status = status;
+        this.name = "SbudError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SbudClient, type ServiceInfo } from "./client.js";
+export { defaultEndpoint } from "./endpoint.js";
+export { SbudError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SbudClient } from "./client.js";
+export { defaultEndpoint } from "./endpoint.js";
+export { SbudError } from "./errors.js";

package/package.json

@@ -1,6 +1,35 @@
 {
-  "name": "@teatoolkit/sbud",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@teatoolkit/sbud",
+	"version": "0.0.1",
+	"description": "Client for the sbud service, which manages Docker Sandboxes for AI agents. Early preview.",
+	"license": "MIT",
+	"author": "teaToolkit",
+	"private": false,
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"check": "tsc -p tsconfig.json",
+		"test": "npm run check && node --test --test-reporter=spec \"build/test/**/*.test.js\"",
+		"prepack": "npm run build"
+	},
+	"devDependencies": {
+		"@types/node": "20.19.43",
+		"typescript": "5.9.3"
+	}
+}