swytchcode-runtime 0.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @swytchcode/runtime
+
+Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in TypeScript/JavaScript without shell boilerplate.
+
+**Requires:** The `swytchcode` binary must be installed and on your `PATH`.
+
+By default, the runtime runs Swytchcode in **JSON mode**: the CLI is invoked with `--json` and stdout must be valid JSON; empty stdout or parse failure throws. For **raw** output, use `output: "raw"` (or `raw: true`). For **streaming** output, use the Swytchcode CLI directly; this library does not support stream mode.
+
+## Install
+
+```bash
+npm install @swytchcode/runtime
+```
+
+## Use
+
+### JSON mode (default)
+
+```ts
+import { exec } from "@swytchcode/runtime";
+
+const result = await exec("api.account.create", {
+  email: "test@example.com",
+});
+// result is parsed JSON (unknown)
+```
+
+Equivalent to: `swytchcode exec api.account.create --json` with input on stdin.
+
+### Raw mode
+
+Get stdout as a string instead of parsing JSON:
+
+```ts
+import { exec } from "@swytchcode/runtime";
+
+const output = await exec("api.report.export", { id: "123" }, { raw: true });
+// output is the raw stdout string
+```
+
+Equivalent to: `swytchcode exec api.report.export --raw` with input on stdin.
+
+### Options
+
+- **`cwd`** – Working directory for the process (default: `process.cwd()`).
+- **`env`** – Extra environment variables (merged with `process.env`).
+- **`output`** – `"json"` (default), `"raw"`, or `"stream"`. Default is JSON (stdout must be valid JSON; parse failure throws). Use `"raw"` to get stdout as a string. `"stream"` is not supported and will throw; use the CLI directly for streaming.
+- **`raw`** – If `true`, same as `output: "raw"`. Kept for backward compatibility.
+- **`debug`** – If `true`, log spawn args, cwd, exit status, and stdout/stderr lengths to stderr.
+
+**Debug logs** are also enabled when `SWYTCHCODE_RUNTIME_DEBUG=1` or `SWYTCHCODE_RUNTIME_DEBUG=true` (no code change):
+
+```bash
+SWYTCHCODE_RUNTIME_DEBUG=1 node index.js
+```
+
+Or in code: `exec("shell.integration.list", undefined, { debug: true })`.
+
+### Error handling
+
+Failures throw `SwytchcodeError` (spawn error, non-zero exit, signal, empty stdout in JSON mode, invalid JSON). Use the type guard when you need to narrow:
+
+```ts
+import { exec, isSwytchcodeError } from "@swytchcode/runtime";
+
+try {
+  await exec("api.account.create", { email: "test@example.com" });
+} catch (e) {
+  if (isSwytchcodeError(e)) {
+    console.error(e.message, e.cause);
+  }
+  throw e;
+}
+```
+
+## What this library is
+
+- A thin process wrapper over the Swytchcode shell.
+- A stable call surface: `exec(canonicalId, input?, options?)`.
+- A convenience for developers and IDE agents.
+
+## What this library is not
+
+- An HTTP SDK or API client.
+- A replacement for the shell. All authority stays in the Swytchcode CLI.
+
+This library **must not** and **does not**:
+
+- Read `.swytchcode/*` or parse `tooling.json`.
+- Validate schemas or add retries/timeouts.
+- Call the registry or embed auth logic.
+
+It is a pipe, not a brain.
+
+## For Cursor / IDE agents
+
+Generate code that uses this runtime instead of subprocess boilerplate.
+
+**Preferred:**
+
+```ts
+import { exec } from "@swytchcode/runtime";
+
+export async function createAccount(input: { email: string }) {
+  return exec("api.account.create", input);
+}
+```
+
+**Avoid:** subprocess boilerplate, HTTP calls, or config parsing. Use `exec(...)` and let the CLI handle execution and policy.

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Thrown when `exec()` fails: spawn error, non-zero exit, signal, or invalid JSON output.
+ */
+export declare class SwytchcodeError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Type guard for SwytchcodeError.
+ */
+export declare function isSwytchcodeError(e: unknown): e is SwytchcodeError;

package/dist/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwytchcodeError = void 0;
+exports.isSwytchcodeError = isSwytchcodeError;
+/**
+ * Thrown when `exec()` fails: spawn error, non-zero exit, signal, or invalid JSON output.
+ */
+class SwytchcodeError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "SwytchcodeError";
+        this.cause = cause;
+        Object.setPrototypeOf(this, SwytchcodeError.prototype);
+    }
+}
+exports.SwytchcodeError = SwytchcodeError;
+/**
+ * Type guard for SwytchcodeError.
+ */
+function isSwytchcodeError(e) {
+    return e instanceof SwytchcodeError;
+}

package/dist/exec.d.ts

@@ -0,0 +1,9 @@
+import { ExecOptions, ExecResult } from "./types.js";
+/**
+ * Run `swytchcode exec <canonicalId>` with optional JSON input on stdin.
+ * Default is JSON mode (stdout must be valid JSON; empty or parse failure throws).
+ * Use output: "raw" or raw: true for raw stdout string. Stream mode is not supported.
+ *
+ * Enable logs: pass `{ debug: true }` or set env SWYTCHCODE_RUNTIME_DEBUG=1
+ */
+export declare function exec(canonicalId: string, input?: unknown, options?: ExecOptions): Promise<ExecResult>;

package/dist/exec.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exec = exec;
+const node_child_process_1 = require("node:child_process");
+const errors_js_1 = require("./errors.js");
+const LOG_PREFIX = "[swytchcode-runtime]";
+function isDebug(options) {
+    return (options.debug === true ||
+        process.env.SWYTCHCODE_RUNTIME_DEBUG === "1" ||
+        process.env.SWYTCHCODE_RUNTIME_DEBUG === "true");
+}
+function log(debug, msg, detail) {
+    if (!debug)
+        return;
+    const line = detail ? `${LOG_PREFIX} ${msg} ${detail}\n` : `${LOG_PREFIX} ${msg}\n`;
+    process.stderr.write(line);
+}
+/**
+ * Run `swytchcode exec <canonicalId>` with optional JSON input on stdin.
+ * Default is JSON mode (stdout must be valid JSON; empty or parse failure throws).
+ * Use output: "raw" or raw: true for raw stdout string. Stream mode is not supported.
+ *
+ * Enable logs: pass `{ debug: true }` or set env SWYTCHCODE_RUNTIME_DEBUG=1
+ */
+function exec(canonicalId, input, options = {}) {
+    const debug = isDebug(options);
+    const canonicalIdTrimmed = canonicalId.trim();
+    if (canonicalIdTrimmed.length === 0) {
+        log(debug, "reject:", "canonicalId is empty");
+        return Promise.reject(new errors_js_1.SwytchcodeError("canonicalId must be a non-empty string", undefined));
+    }
+    const outputMode = options.output ?? (options.raw === true ? "raw" : "json");
+    if (outputMode === "stream") {
+        log(debug, "reject:", "stream mode not supported");
+        return Promise.reject(new errors_js_1.SwytchcodeError("Stream mode is not supported; use the Swytchcode CLI directly", undefined));
+    }
+    const raw = outputMode === "raw";
+    const args = ["exec", canonicalIdTrimmed, raw ? "--raw" : "--json"];
+    const cwd = options.cwd ?? process.cwd();
+    const hasInput = input !== undefined && input !== null;
+    log(debug, "spawn:", `swytchcode ${args.join(" ")}`);
+    log(debug, "cwd:", cwd);
+    log(debug, "stdin:", hasInput ? `JSON (${JSON.stringify(input).length} chars)` : "none");
+    const result = (0, node_child_process_1.spawnSync)("swytchcode", args, {
+        cwd,
+        env: { ...process.env, ...options.env },
+        input: hasInput ? JSON.stringify(input) : undefined,
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+    });
+    const stdoutRaw = result.stdout ?? "";
+    const stderrRaw = result.stderr ?? "";
+    const stdout = stdoutRaw.trim();
+    const stderr = stderrRaw.trim();
+    log(debug, "exit status:", String(result.status));
+    log(debug, "exit signal:", String(result.signal ?? "none"));
+    log(debug, "stdout length:", String(stdoutRaw.length));
+    log(debug, "stderr length:", String(stderrRaw.length));
+    if (stdoutRaw.length > 0) {
+        const preview = stdoutRaw.length > 400 ? stdoutRaw.slice(0, 400) + "..." : stdoutRaw;
+        log(debug, "stdout preview:", JSON.stringify(preview));
+    }
+    if (stderrRaw.length > 0) {
+        const preview = stderrRaw.length > 400 ? stderrRaw.slice(0, 400) + "..." : stderrRaw;
+        log(debug, "stderr preview:", JSON.stringify(preview));
+    }
+    if (result.error) {
+        log(debug, "reject:", "spawn error");
+        return Promise.reject(new errors_js_1.SwytchcodeError("Failed to spawn swytchcode", result.error));
+    }
+    if (result.status !== 0) {
+        const message = result.signal != null
+            ? `swytchcode exec failed (signal ${String(result.signal)})`
+            : stderr || "swytchcode exec failed";
+        log(debug, "reject:", `status ${result.status}, ${message.slice(0, 100)}`);
+        return Promise.reject(new errors_js_1.SwytchcodeError(message, result.status ?? result.signal ?? stderr));
+    }
+    if (raw) {
+        log(debug, "resolve:", `raw stdout (${(result.stdout ?? "").length} chars)`);
+        return Promise.resolve(result.stdout ?? "");
+    }
+    // JSON mode: stdout only; no stderr fallback. Empty or invalid → throw.
+    if (stdout.length === 0) {
+        log(debug, "reject:", "empty stdout in JSON mode");
+        return Promise.reject(new errors_js_1.SwytchcodeError("Empty stdout in JSON mode; swytchcode must write JSON to stdout", undefined));
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        log(debug, "resolve:", "parsed JSON ok");
+        return Promise.resolve(parsed);
+    }
+    catch {
+        log(debug, "reject:", "invalid JSON");
+        return Promise.reject(new errors_js_1.SwytchcodeError("Invalid JSON output from swytchcode", stdout));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { exec } from "./exec.js";
+export type { ExecOptions, ExecResult, OutputMode } from "./types.js";
+export { SwytchcodeError, isSwytchcodeError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSwytchcodeError = exports.SwytchcodeError = exports.exec = void 0;
+var exec_js_1 = require("./exec.js");
+Object.defineProperty(exports, "exec", { enumerable: true, get: function () { return exec_js_1.exec; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "SwytchcodeError", { enumerable: true, get: function () { return errors_js_1.SwytchcodeError; } });
+Object.defineProperty(exports, "isSwytchcodeError", { enumerable: true, get: function () { return errors_js_1.isSwytchcodeError; } });

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+/** Output mode: JSON (default), raw string, or stream (not supported in this runtime). */
+export type OutputMode = "json" | "raw" | "stream";
+export interface ExecOptions {
+    /** Working directory for the swytchcode process. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Extra environment variables merged with `process.env`. */
+    env?: Record<string, string>;
+    /**
+     * Output mode. Default is `"json"` (stdout must be valid JSON; parse failure throws).
+     * Use `"raw"` to get stdout as a string. `"stream"` is not supported; use the CLI directly.
+     */
+    output?: OutputMode;
+    /** If true, same as `output: "raw"`. Kept for backward compatibility. */
+    raw?: boolean;
+    /** If true, log spawn/capture details to process.stderr (for debugging). */
+    debug?: boolean;
+}
+/** Result of `exec()` in JSON mode: parsed stdout. In raw mode the result is a string. */
+export type ExecResult = unknown;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "swytchcode-runtime",
+  "version": "0.1.0",
+  "description": "Thin runtime wrapper around the Swytchcode CLI",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/swytchcode/runtime-libraries"
+  },
+  "license": "MIT",
+  "keywords": ["swytchcode", "cli", "runtime", "exec"]
+}