swytchcode-runtime 0.1.0 → 0.1.2

package/README.md

@@ -20,12 +20,30 @@ npm install @swytchcode/runtime
 import { exec } from "@swytchcode/runtime";
 
 const result = await exec("api.account.create", {
-  email: "test@example.com",
+  body: { name: "my-cluster" },
+  Authorization: "Bearer token123",
 });
 // result is parsed JSON (unknown)
 ```
 
-Equivalent to: `swytchcode exec api.account.create --json` with input on stdin.
+Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
+
+**Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
+- **`body`** — Request body (object).
+- **`params`** — Query/path params (object, e.g. `{ id: "cluster-123" }`).
+- **`Authorization`** — Auth header value (e.g. `"Bearer token123"`).
+- **`headers`** — Additional request headers (e.g. `{ "X-Request-Id": "abc-123" }`).
+- Other top-level keys are passed as query params.
+
+Example with body, params, and headers:
+
+```ts
+await exec("api.cluster.get", {
+  params: { id: "cluster-123" },
+  Authorization: "Bearer token123",
+  headers: { "X-Request-Id": "abc-123" },
+});
+```
 
 ### Raw mode
 
@@ -46,8 +64,12 @@ Equivalent to: `swytchcode exec api.report.export --raw` with input on stdin.
 - **`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.
+- **`dryRun`** – If `true`, pass `--dry-run` to the CLI; the CLI outputs request details (method, url, headers, body) instead of calling the server.
+- **`allowRaw`** – If `true`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
 - **`debug`** – If `true`, log spawn args, cwd, exit status, and stdout/stderr lengths to stderr.
 
+This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior (exit codes, output format, pipeline), see the [Swytchcode kernel documentation](https://github.com/swytchcode/swytchcode).
+
 **Debug logs** are also enabled when `SWYTCHCODE_RUNTIME_DEBUG=1` or `SWYTCHCODE_RUNTIME_DEBUG=true` (no code change):
 
 ```bash

package/dist/exec.d.ts

@@ -1,9 +1,12 @@
-import { ExecOptions, ExecResult } from "./types.js";
+import type { ExecArgs, ExecOptions, ExecResult } from "./types.js";
 /**
- * Run `swytchcode exec <canonicalId>` with optional JSON input on stdin.
+ * Run `swytchcode exec <canonicalId>` with optional JSON args 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.
  *
+ * The second argument (input) is the kernel args object sent on stdin: use body, params,
+ * Authorization, and headers so the kernel builds the request correctly. See ExecArgs.
+ *
  * Enable logs: pass `{ debug: true }` or set env SWYTCHCODE_RUNTIME_DEBUG=1
  */
-export declare function exec(canonicalId: string, input?: unknown, options?: ExecOptions): Promise<ExecResult>;
+export declare function exec(canonicalId: string, input?: ExecArgs | unknown, options?: ExecOptions): Promise<ExecResult>;

package/dist/exec.js

@@ -16,10 +16,13 @@ function log(debug, msg, detail) {
     process.stderr.write(line);
 }
 /**
- * Run `swytchcode exec <canonicalId>` with optional JSON input on stdin.
+ * Run `swytchcode exec <canonicalId>` with optional JSON args 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.
  *
+ * The second argument (input) is the kernel args object sent on stdin: use body, params,
+ * Authorization, and headers so the kernel builds the request correctly. See ExecArgs.
+ *
  * Enable logs: pass `{ debug: true }` or set env SWYTCHCODE_RUNTIME_DEBUG=1
  */
 function exec(canonicalId, input, options = {}) {
@@ -36,9 +39,17 @@ function exec(canonicalId, input, options = {}) {
     }
     const raw = outputMode === "raw";
     const args = ["exec", canonicalIdTrimmed, raw ? "--raw" : "--json"];
+    if (options.dryRun === true)
+        args.push("--dry-run");
+    if (options.allowRaw === true)
+        args.push("--allow-raw");
     const cwd = options.cwd ?? process.cwd();
     const hasInput = input !== undefined && input !== null;
     log(debug, "spawn:", `swytchcode ${args.join(" ")}`);
+    if (options.dryRun === true)
+        log(debug, "dry-run:", "enabled");
+    if (options.allowRaw === true)
+        log(debug, "allow-raw:", "enabled");
     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, {

package/dist/index.d.ts

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

package/dist/types.d.ts

@@ -12,8 +12,27 @@ export interface ExecOptions {
     output?: OutputMode;
     /** If true, same as `output: "raw"`. Kept for backward compatibility. */
     raw?: boolean;
+    /** If true, pass `--dry-run` to the CLI; request details are output instead of calling the server. */
+    dryRun?: boolean;
+    /** If true, pass `--allow-raw` to the CLI; required for executing raw methods (disabled by default in kernel). */
+    allowRaw?: 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;
+/**
+ * Tool arguments sent to the kernel on stdin (matches `swytchcode exec` JSON stdin).
+ * - `body`: Request body (object).
+ * - `params`: Query/path params (object).
+ * - `Authorization`: Auth header value (e.g. "Bearer token").
+ * - `headers`: Additional request headers (map of header name to value).
+ * - Other top-level keys are passed as query params.
+ */
+export interface ExecArgs {
+    body?: unknown;
+    params?: Record<string, string>;
+    Authorization?: string;
+    headers?: Record<string, string>;
+    [key: string]: unknown;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swytchcode-runtime",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Thin runtime wrapper around the Swytchcode CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",