@reasonlayer/sdk 0.0.1-rc.3

package/dist/cli/workspace-local.js

@@ -0,0 +1,310 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { access, lstat, mkdir, readFile, readdir, rm, symlink, writeFile, } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { FN } from "@reasonlayer/protocol";
+import { EXACT_VERSION, pairedFlueRuntimeVersion, SDK_ROOT, sdkProvenance, sdkVersion, } from "./sdk-package.js";
+import { LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION, parseLocalWorkspaceSession, } from "./workspace-session.js";
+const SESSION_PATH = join(".rl", "session.json");
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function assertEmptyTarget(target) {
+    if (!(await pathExists(target)))
+        return;
+    const entries = await readdir(target);
+    if (entries.length > 0)
+        throw new Error(`checkout directory is not empty: ${target}`);
+}
+async function scaffold(target, workflowId) {
+    const [version, flueVersion] = await Promise.all([
+        sdkVersion(),
+        pairedFlueRuntimeVersion(),
+    ]);
+    await mkdir(join(target, "src"), { recursive: true });
+    const files = [
+        ["package.json", `${JSON.stringify({
+                name: workflowId,
+                private: true,
+                type: "module",
+                dependencies: {
+                    "@reasonlayer/sdk": version,
+                    "@flue/runtime": flueVersion,
+                },
+            }, null, 2)}\n`],
+        ["tsconfig.json", `${JSON.stringify({
+                compilerOptions: {
+                    target: "ES2022",
+                    module: "NodeNext",
+                    moduleResolution: "NodeNext",
+                    strict: true,
+                    noEmit: true,
+                },
+                include: ["src/**/*.ts"],
+            }, null, 2)}\n`],
+        [".gitignore", "node_modules/\n.rl/\ndist/\n"],
+        [join("src", "workflow.ts"), `import { defineWorkflow, v } from "@reasonlayer/sdk";
+
+const message = v.object({ message: v.string() });
+
+export default defineWorkflow({
+  id: ${JSON.stringify(workflowId)},
+  input: message,
+  output: message,
+})
+  .code("echo", {
+    output: message,
+    host: { kind: "cloud" },
+    run: (input: { message: string }) => input,
+  })
+  .output((steps) => steps.echo);
+`],
+    ];
+    await Promise.all(files.map(async ([path, contents]) => await writeFile(join(target, path), contents)));
+    return files.length;
+}
+const INSTALL_TIMEOUT_MS = 180_000;
+async function checkoutToolchainPins(target) {
+    const manifestPath = join(target, "package.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    const pins = { sdkVersion: "", flueVersion: "" };
+    for (const [name, key] of [
+        ["@reasonlayer/sdk", "sdkVersion"],
+        ["@flue/runtime", "flueVersion"],
+    ]) {
+        const pin = manifest.dependencies?.[name];
+        if (typeof pin !== "string" || !EXACT_VERSION.test(pin)) {
+            throw new Error(`${manifestPath} must pin ${name} to an exact version (found ${typeof pin === "string" ? `"${pin}"` : "no dependency"}); a range is not a pin, so edit it back to a single version like "0.1.0"`);
+        }
+        pins[key] = pin;
+    }
+    return pins;
+}
+async function installCheckoutToolchain(target) {
+    await new Promise((resolveInstall, rejectInstall) => {
+        const child = spawn("npm", ["install", "--no-audit", "--no-fund", "--package-lock=true"], { cwd: target, env: process.env });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            rejectInstall(new Error(`failed to install the checkout toolchain: npm install did not finish within ${INSTALL_TIMEOUT_MS / 1000}s`));
+        }, INSTALL_TIMEOUT_MS);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => (stdout += chunk));
+        child.stderr.on("data", (chunk) => (stderr += chunk));
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            rejectInstall(new Error(`failed to install the checkout toolchain: ${error.message}`));
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolveInstall();
+                return;
+            }
+            const diagnostic = stderr.trim() || stdout.trim();
+            rejectInstall(new Error(`failed to install the checkout toolchain: npm install exited ${code ?? "without a status"}${diagnostic ? `: ${diagnostic}` : ""}`));
+        });
+    });
+}
+async function linkLocalCheckoutToolchain(target) {
+    const links = [
+        [join(target, "node_modules", "@reasonlayer", "sdk"), SDK_ROOT],
+        [join(target, "node_modules", "@flue", "runtime"), join(SDK_ROOT, "node_modules", "@flue", "runtime")],
+    ];
+    for (const [link, source] of links) {
+        await mkdir(dirname(link), { recursive: true });
+        await rm(link, { recursive: true, force: true });
+        await symlink(source, link, "dir");
+    }
+}
+async function materializeCheckoutToolchain(target) {
+    const pins = await checkoutToolchainPins(target);
+    const provenance = await sdkProvenance();
+    if (provenance.installSource === "installed") {
+        await installCheckoutToolchain(target);
+        return;
+    }
+    const [version, flueVersion] = await Promise.all([
+        sdkVersion(),
+        pairedFlueRuntimeVersion(),
+    ]);
+    if (pins.sdkVersion !== version || pins.flueVersion !== flueVersion) {
+        throw new Error(`local SDK cannot materialize checkout toolchain ${pins.sdkVersion} / ${pins.flueVersion}; expected ${version} / ${flueVersion}`);
+    }
+    await linkLocalCheckoutToolchain(target);
+}
+async function materializeCloudFiles(runtime, started, target) {
+    const files = await runtime.client.query(FN.workspacesCheckout, {
+        token: started.authoringToken,
+        sessionId: started.sessionId,
+    });
+    for (const file of files) {
+        const path = resolve(target, file.path);
+        const withinTarget = relative(resolve(target), path);
+        if (!withinTarget || withinTarget.startsWith("..") || isAbsolute(withinTarget)) {
+            throw new Error(`invalid workspace path from server: ${file.path}`);
+        }
+        const response = await fetch(file.url);
+        if (!response.ok)
+            throw new Error(`failed to download ${file.path} (HTTP ${response.status})`);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        if (sha256 !== file.sha256 || bytes.byteLength !== file.size) {
+            throw new Error(`downloaded workspace blob failed verification for ${file.path}`);
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, bytes);
+    }
+    return files.length;
+}
+async function writeSession(state) {
+    const path = join(state.checkoutPath, SESSION_PATH);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    return path;
+}
+export async function startDaemon(sessionPath) {
+    const checkoutPath = dirname(dirname(sessionPath));
+    const script = join(checkoutPath, "node_modules", "@reasonlayer", "sdk", "dist", "cli", "watcher-process.js");
+    try {
+        await access(script);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`checkout SDK is not installed: missing ${script}`);
+        }
+        throw error;
+    }
+    const logPath = join(dirname(sessionPath), "watcher.log");
+    const logFd = openSync(logPath, "a", 0o600);
+    try {
+        const child = spawn(process.execPath, [script, sessionPath], {
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            env: process.env,
+        });
+        if (!child.pid)
+            throw new Error("watcher daemon did not start");
+        child.unref();
+        return child.pid;
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
+export async function createCheckout(runtime, options) {
+    const checkoutPath = resolve(options.targetDir ?? join(process.cwd(), options.workflowId));
+    await assertEmptyTarget(checkoutPath);
+    await mkdir(checkoutPath, { recursive: true });
+    const checkoutId = randomUUID();
+    const started = await runtime.client.mutation(FN.workspacesStartSession, {
+        token: runtime.config.token,
+        workflowId: options.workflowId,
+        machineLabel: `${hostname()} (${process.platform})`,
+        checkoutId,
+        mode: options.mode,
+    });
+    try {
+        const files = options.mode === "init"
+            ? await scaffold(checkoutPath, options.workflowId)
+            : await materializeCloudFiles(runtime, started, checkoutPath);
+        await materializeCheckoutToolchain(checkoutPath);
+        const state = {
+            schemaVersion: LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION,
+            workflowId: options.workflowId,
+            sessionId: started.sessionId,
+            checkoutId,
+            checkoutPath,
+            convexUrl: runtime.config.convexUrl,
+            authoringToken: started.authoringToken,
+            credentialExpiresAt: started.expiresAt,
+        };
+        const sessionPath = await writeSession(state);
+        const daemonPid = await startDaemon(sessionPath);
+        await writeSession({ ...state, daemonPid });
+        return { checkoutPath, sessionId: started.sessionId, daemonPid, files };
+    }
+    catch (error) {
+        await runtime.client.mutation(FN.workspacesEndSession, {
+            token: started.authoringToken,
+            sessionId: started.sessionId,
+        }).catch(() => undefined);
+        await rm(checkoutPath, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function findCheckoutRoot(cwd = process.cwd()) {
+    let current = resolve(cwd);
+    for (;;) {
+        if (await pathExists(join(current, SESSION_PATH)))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error("not inside a Reasonlayer checkout");
+        current = parent;
+    }
+}
+export async function readLocalSession(cwd = process.cwd()) {
+    const root = await findCheckoutRoot(cwd);
+    const sessionPath = join(root, SESSION_PATH);
+    const source = relative(cwd, sessionPath) || sessionPath;
+    const state = parseLocalWorkspaceSession(await readFile(sessionPath, "utf8"), source);
+    return { ...state, checkoutPath: root };
+}
+export async function endLocalSession(runtime) {
+    const state = await readLocalSession();
+    if (!state.daemonPid) {
+        throw new Error("cannot finish safely: checkout watcher pid is missing; checkout was preserved");
+    }
+    try {
+        process.kill(state.daemonPid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code === "ESRCH") {
+            throw new Error("cannot finish safely: checkout watcher is not running; checkout was preserved");
+        }
+        throw error;
+    }
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(state.daemonPid, 0);
+        }
+        catch (error) {
+            if (error.code === "ESRCH")
+                break;
+            throw error;
+        }
+        await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+    }
+    try {
+        process.kill(state.daemonPid, 0);
+        throw new Error("cannot finish safely: watcher did not drain checkout changes; checkout was preserved");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    await runtime.client.mutation(FN.workspacesEndSession, {
+        token: runtime.config.token,
+        sessionId: state.sessionId,
+    });
+    await rm(state.checkoutPath, { recursive: true, force: true });
+    return {
+        workflowId: state.workflowId,
+        sessionId: state.sessionId,
+        checkoutPath: state.checkoutPath,
+    };
+}

package/dist/cli/workspace-session.d.ts

@@ -0,0 +1,13 @@
+export declare const LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION = 1;
+export interface LocalWorkspaceSession {
+    schemaVersion: typeof LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION;
+    workflowId: string;
+    sessionId: string;
+    checkoutId: string;
+    checkoutPath: string;
+    convexUrl: string;
+    authoringToken: string;
+    credentialExpiresAt: number;
+    daemonPid?: number;
+}
+export declare function parseLocalWorkspaceSession(text: string, source: string): LocalWorkspaceSession;

package/dist/cli/workspace-session.js

@@ -0,0 +1,12 @@
+export const LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION = 1;
+export function parseLocalWorkspaceSession(text, source) {
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`invalid Reasonlayer checkout session in ${source}`);
+    }
+    const schemaVersion = value.schemaVersion;
+    if (schemaVersion !== LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION) {
+        throw new Error(`unsupported Reasonlayer checkout session schemaVersion ${String(schemaVersion)} in ${source}; expected ${LOCAL_WORKSPACE_SESSION_SCHEMA_VERSION}`);
+    }
+    return value;
+}

package/dist/compile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * compileWorkflow (spec §4.4): lower a WorkflowDefinition to WorkflowIR.
+ * Every selector is validated against the step graph; wrong wiring is a
+ * compile error, not a runtime surprise. Returns { ok, ir, codeRefs,
+ * agentRefs } or { ok: false, errors } — it never throws for authoring
+ * mistakes.
+ */
+import type { CompileResult, WorkflowDefinition } from "./types.js";
+export interface CompileWorkflowOptions {
+    /**
+     * Base directory used to resolve environment file sources. Build paths pass
+     * the workflow entry directory so customer file content is captured before
+     * deploy; runner cold-start compiles can omit this because they only need
+     * executable references.
+     */
+    environmentFileBaseDir?: string;
+    inlineEnvironmentFiles?: boolean;
+    /**
+     * Emitted runtime bundles already consumed the build-time IR and only need
+     * executable refs at cold start. They can omit environment lowering to avoid
+     * repeating build-time hashing and file reads at runner startup.
+     */
+    omitEnvironments?: boolean;
+}
+/** IR step ids must be safe as JS export names in the emitted bundles. */
+export declare function exportNameFor(stepId: string): string;
+export declare function compileWorkflow(definition: WorkflowDefinition, options?: CompileWorkflowOptions): CompileResult;