@reasonlayer/sdk 0.0.1

package/dist/cli/keychain.d.ts

@@ -0,0 +1,21 @@
+export declare class KeychainUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class KeychainAccessError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Secret store keyed by account (we pass the Convex deployment URL). */
+export interface KeychainBackend {
+    get(account: string): Promise<string | null>;
+    set(account: string, secret: string): Promise<void>;
+    delete(account: string): Promise<boolean>;
+}
+/** Test seam: swap the OS keychain for an in-memory backend. */
+export declare function setKeychainBackend(backend: KeychainBackend | undefined): void;
+export declare function getToken(account: string): Promise<string | null>;
+export declare function setToken(account: string, token: string): Promise<void>;
+export declare function deleteToken(account: string): Promise<boolean>;

package/dist/cli/keychain.js

@@ -0,0 +1,100 @@
+/**
+ * OS keychain wrapper for the CLI's bearer token. The engine and dashboard tie
+ * identity to WorkOS/scoped tokens (spec §11); this keeps the human token out
+ * of a plaintext dotfile and in the platform secret store (macOS Keychain,
+ * Windows Credential Manager, Linux Secret Service).
+ *
+ * Keyed by the Convex deployment URL so one machine can hold tokens for several
+ * deployments. `get` returns `null` (not an error) when no token is stored.
+ * Failures split into two kinds so callers can act on the difference:
+ *   - {@link KeychainUnavailableError}: the keychain module cannot load at all
+ *     (unsupported platform / missing native binary). Callers fall through to
+ *     the RL_TOKEN env path.
+ *   - {@link KeychainAccessError}: a keychain is present but rejected the
+ *     operation (locked, prompt denied, ambiguous credential, no storage
+ *     backend). Callers surface a diagnostic — this is never silently a token
+ *     "not found".
+ */
+const SERVICE = "reasonlayer-cli";
+export class KeychainUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "KeychainUnavailableError";
+    }
+}
+export class KeychainAccessError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "KeychainAccessError";
+    }
+}
+let override;
+/** Test seam: swap the OS keychain for an in-memory backend. */
+export function setKeychainBackend(backend) {
+    override = backend;
+}
+let entryCtor;
+async function loadEntryCtor() {
+    if (entryCtor)
+        return entryCtor;
+    try {
+        const mod = await import("@napi-rs/keyring");
+        entryCtor = mod.Entry;
+        return entryCtor;
+    }
+    catch (err) {
+        throw new KeychainUnavailableError("the OS keychain module could not be loaded", {
+            cause: err,
+        });
+    }
+}
+function reason(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function osBackend() {
+    return {
+        async get(account) {
+            const Entry = await loadEntryCtor();
+            try {
+                return new Entry(SERVICE, account).getPassword();
+            }
+            catch (err) {
+                throw new KeychainAccessError(`could not read from the OS keychain (${reason(err)})`, {
+                    cause: err,
+                });
+            }
+        },
+        async set(account, secret) {
+            const Entry = await loadEntryCtor();
+            try {
+                new Entry(SERVICE, account).setPassword(secret);
+            }
+            catch (err) {
+                throw new KeychainAccessError(`could not write to the OS keychain (${reason(err)})`, {
+                    cause: err,
+                });
+            }
+        },
+        async delete(account) {
+            const Entry = await loadEntryCtor();
+            try {
+                return new Entry(SERVICE, account).deletePassword();
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function backend() {
+    return override ?? osBackend();
+}
+export function getToken(account) {
+    return backend().get(account);
+}
+export function setToken(account, token) {
+    return backend().set(account, token);
+}
+export function deleteToken(account) {
+    return backend().delete(account);
+}

package/dist/cli/login-browser.d.ts

@@ -0,0 +1,22 @@
+import type { RlxAccount } from "./config.js";
+/**
+ * Browser loopback login (spec §12.2). The CLI opens a listener on
+ * `127.0.0.1:<random port>`, sends the user to the dashboard's `/cli-login`
+ * page with that port and a one-time `state` nonce, and the dashboard — after
+ * authenticating the user through WorkOS AuthKit — POSTs the minted access JWT
+ * back to the loopback. CORS is locked to the dashboard origin and the `state`
+ * nonce binds the callback to this request. No secret is ever typed or pasted.
+ */
+export interface LoopbackCredentials {
+    token: string;
+    account: RlxAccount;
+}
+export interface LoopbackLoginOptions {
+    dashboardUrl: string;
+    /** Test/override seams. */
+    state?: string;
+    timeoutMs?: number;
+    open?: (url: string) => void;
+    onUrl?: (url: string) => void;
+}
+export declare function runLoopbackLogin(options: LoopbackLoginOptions): Promise<LoopbackCredentials>;

package/dist/cli/login-browser.js

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_BODY_BYTES = 64 * 1024;
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        // Best-effort; the URL is also printed for manual opening.
+    }
+}
+function nonceEquals(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            req.destroy();
+            throw new Error("request body too large");
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export function runLoopbackLogin(options) {
+    const state = options.state ?? randomBytes(24).toString("hex");
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const origin = new URL(options.dashboardUrl).origin;
+    return new Promise((resolvePromise, rejectPromise) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            fn();
+        };
+        async function handlePost(req, res) {
+            let payload;
+            try {
+                payload = JSON.parse(await readBody(req));
+            }
+            catch {
+                res.writeHead(400, { "content-type": "application/json" }).end('{"error":"invalid request"}');
+                return;
+            }
+            if (typeof payload.state !== "string" || !nonceEquals(payload.state, state)) {
+                res.writeHead(403, { "content-type": "application/json" }).end('{"error":"state mismatch"}');
+                return;
+            }
+            const accessToken = payload.accessToken;
+            if (!accessToken) {
+                res
+                    .writeHead(400, { "content-type": "application/json" })
+                    .end('{"error":"missing accessToken"}');
+                return;
+            }
+            res.writeHead(200, { "content-type": "application/json" }).end('{"ok":true}');
+            const account = {
+                ...(payload.email !== undefined ? { email: payload.email } : {}),
+                ...(payload.orgId !== undefined ? { orgId: payload.orgId } : {}),
+            };
+            finish(() => resolvePromise({ token: accessToken, account }));
+        }
+        const server = createServer((req, res) => {
+            // Only the dashboard origin may POST the token back to us.
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+            if (req.method === "OPTIONS") {
+                res.writeHead(204).end();
+                return;
+            }
+            if (req.method !== "POST") {
+                res.writeHead(405).end();
+                return;
+            }
+            void handlePost(req, res);
+        });
+        const timer = setTimeout(() => {
+            finish(() => rejectPromise(new Error("browser login timed out")));
+        }, timeoutMs);
+        timer.unref();
+        server.on("error", (err) => finish(() => rejectPromise(err)));
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            const base = options.dashboardUrl.replace(/\/$/, "");
+            const url = `${base}/cli-login?callback_port=${port}&state=${state}`;
+            options.onUrl?.(url);
+            (options.open ?? openBrowser)(url);
+        });
+    });
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1,3 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function formatMcpResult(value: unknown): CallToolResult;
+export declare function startMcpServer(): Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,36 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createOperationRuntime, operationsForSurface, runOperation } from "./operations.js";
+function isStructuredRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function formatMcpResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        structuredContent: isStructuredRecord(value) ? value : { value },
+    };
+}
+function errorResult(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+export async function startMcpServer() {
+    const server = new McpServer({ name: "reasonlayer", version: "0.1.0" });
+    const runtime = createOperationRuntime(await loadConfig());
+    for (const operation of operationsForSurface("mcp")) {
+        server.registerTool(operation.name, {
+            title: operation.title,
+            description: operation.description,
+            inputSchema: operation.inputSchema,
+        }, async (args) => {
+            try {
+                return formatMcpResult(await runOperation(operation, { runtime }, args));
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        });
+    }
+    await server.connect(new StdioServerTransport());
+}

package/dist/cli/operations.d.ts

@@ -0,0 +1,106 @@
+import { z } from "zod/v4";
+import { type BuildManifest } from "../bundler/index.js";
+import type { RlConfig } from "./config.js";
+export interface RunOptions {
+    workflowId: string;
+    input: unknown;
+    runKey?: string;
+    wait: boolean;
+    pollIntervalMs: number;
+    timeoutMs: number;
+    /** Test seam; production uses real timers. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface DevRunOptions {
+    workflow: string;
+    input: unknown;
+    runKey?: string;
+    pollIntervalMs: number;
+    timeoutMs: number;
+    concurrency?: number;
+    signal?: AbortSignal;
+    onRunCreated?: (created: {
+        runId: string;
+        deduped: boolean;
+    }) => void;
+}
+export interface RlClient {
+    query<T>(name: string, args: Record<string, unknown>): Promise<T>;
+    mutation<T>(name: string, args: Record<string, unknown>): Promise<T>;
+    action<T>(name: string, args: Record<string, unknown>): Promise<T>;
+}
+export interface OperationRuntime {
+    config: RlConfig;
+    client: RlClient;
+}
+export declare function createOperationRuntime(config: RlConfig, client?: RlClient): OperationRuntime;
+export declare const DEFAULT_POLL_INTERVAL_MS = 1000;
+export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
+export declare function validateWorkflow(entry: string): Promise<{
+    ok: true;
+    manifest: BuildManifest;
+    ir: unknown;
+} | {
+    ok: false;
+    errors: {
+        stepId?: string;
+        message: string;
+    }[];
+}>;
+export declare function buildProject(entry: string, outDir: string): Promise<{
+    ok: true;
+    manifest: BuildManifest;
+    outDir: string;
+} | {
+    ok: false;
+    errors: {
+        stepId?: string;
+        message: string;
+    }[];
+}>;
+export declare function runWorkflow(runtime: OperationRuntime, options: RunOptions): Promise<unknown>;
+export declare function devWorkflow(runtime: OperationRuntime, options: DevRunOptions): Promise<{
+    ok: false;
+    errors: {
+        stepId?: string;
+        message: string;
+    }[];
+} | ({
+    ok: true;
+    testArtifactId: string;
+    expiresAt: number;
+    deduped: boolean;
+} & Record<string, unknown>)>;
+export type OperationSurface = "cli";
+export interface OperationRunContext {
+    runtime?: OperationRuntime;
+}
+/** A backend function this operation forwards to, with the org token attached. */
+export interface OperationCall {
+    kind: "query" | "mutation" | "action";
+    fn: string;
+}
+interface OperationCommon {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType>;
+    surfaces: readonly OperationSurface[];
+}
+/**
+ * An operation either forwards its parsed input to one backend function
+ * (`call`) or has a local implementation deep enough to name (`run`).
+ */
+export type OperationDefinition = (OperationCommon & {
+    call: OperationCall;
+    run?: undefined;
+}) | (OperationCommon & {
+    call?: undefined;
+    run: (ctx: OperationRunContext, args: Record<string, unknown>) => Promise<unknown>;
+});
+export declare function runOperation(operation: OperationDefinition, ctx: OperationRunContext, args: Record<string, unknown>): Promise<unknown>;
+export declare const operationTable: OperationDefinition[];
+export declare function operationsForSurface(surface: OperationSurface): OperationDefinition[];
+export declare function operationByName(name: string): OperationDefinition | undefined;
+export declare function operationForSurfaceByName(surface: OperationSurface, name: string): OperationDefinition | undefined;
+export {};