@reasonlayer/sdk 0.0.1

package/dist/cli/operations.js

@@ -0,0 +1,623 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { z } from "zod/v4";
+import { APPROVAL_STATUSES, FN, isTerminalRunStatus } from "@reasonlayer/protocol";
+import { runTestRun } from "@reasonlayer/runner";
+import { buildWorkflow } from "../bundler/index.js";
+import { RlConvexClient } from "./convex.js";
+import { createCheckout, endLocalSession, readLocalSession, } from "./workspace-local.js";
+import { sdkVersion } from "./sdk-package.js";
+import { uploadStorage } from "./storage-upload.js";
+export function createOperationRuntime(config, client = new RlConvexClient(config)) {
+    return { config, client };
+}
+export const DEFAULT_POLL_INTERVAL_MS = 1000;
+export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+async function readJson(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+function contentTypeFor(path) {
+    if (path.endsWith(".json"))
+        return "application/json";
+    if (path.endsWith(".js") || path.endsWith(".mjs"))
+        return "application/javascript";
+    return "application/octet-stream";
+}
+async function uploadFile(client, token, path, uploadUrlFunction, uploadUrlArgs = {}) {
+    const bytes = await readFile(path);
+    return await uploadStorage(async () => await client.mutation(uploadUrlFunction, { token, ...uploadUrlArgs }), bytes, { contentType: contentTypeFor(path), label: path });
+}
+export async function validateWorkflow(entry) {
+    const temp = await mkdtemp(join(tmpdir(), "rl-validate-"));
+    try {
+        const result = await buildWorkflow(entry, temp);
+        if (!result.ok)
+            return result;
+        return { ok: true, manifest: result.manifest, ir: result.ir };
+    }
+    finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+export async function buildProject(entry, outDir) {
+    const result = await buildWorkflow(entry, outDir);
+    if (!result.ok)
+        return result;
+    return { ok: true, manifest: result.manifest, outDir: result.outDir };
+}
+async function createTestArtifactFromDist(distDir, runtime, flueVersion) {
+    const dist = resolve(distDir);
+    const manifest = await readJson(join(dist, "manifest.json"));
+    const irJson = await readFile(join(dist, manifest.artifacts.ir), "utf8");
+    const { client, config } = runtime;
+    const stepsBundle = await uploadFile(client, config.token, join(dist, manifest.artifacts.steps), FN.testArtifactsGenerateUploadUrl);
+    const agentBundle = manifest.artifacts.agents
+        ? await uploadFile(client, config.token, join(dist, manifest.artifacts.agents), FN.testArtifactsGenerateUploadUrl)
+        : undefined;
+    const created = await client.mutation(FN.testArtifactsCreate, omitUndefined({
+        token: config.token,
+        irJson,
+        stepsBundleId: stepsBundle.storageId,
+        stepsBundleSha256: stepsBundle.sha256,
+        agentBundleId: agentBundle?.storageId,
+        agentBundleSha256: agentBundle?.sha256,
+        sdkVersion: await sdkVersion(),
+        flueVersion,
+    }));
+    return {
+        testArtifactId: created.testArtifactId,
+        workflowId: created.workflowId,
+        inputSchema: JSON.parse(created.inputSchemaJsonText),
+        expiresAt: created.expiresAt,
+    };
+}
+export async function runWorkflow(runtime, options) {
+    const { client, config } = runtime;
+    const latest = await client.query(FN.deploymentsLatestFor, {
+        token: config.token,
+        workflowId: options.workflowId,
+    });
+    if (!latest)
+        throw new Error(`no deployment found for workflow "${options.workflowId}"`);
+    const created = await client.mutation(FN.runsCreate, omitUndefined({
+        token: config.token,
+        deploymentId: latest.deploymentId,
+        input: options.input,
+        runKey: options.runKey,
+    }));
+    if (!options.wait)
+        return created;
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        const run = await client.query(FN.runsGet, { token: config.token, runId: created.runId });
+        if (isTerminalRunStatus(run.status))
+            return { ...run, deduped: created.deduped };
+        await (options.sleep ?? sleep)(options.pollIntervalMs);
+    }
+    throw new Error(`run ${created.runId} did not finish within ${options.timeoutMs}ms`);
+}
+export async function devWorkflow(runtime, options) {
+    const temp = await mkdtemp(join(tmpdir(), "rl-dev-"));
+    try {
+        const built = await buildWorkflow(options.workflow, temp);
+        if (!built.ok)
+            return { ok: false, errors: built.errors };
+        const artifact = await createTestArtifactFromDist(built.outDir, runtime, built.flueVersion);
+        const created = await runtime.client.mutation(FN.runsCreateTest, {
+            token: runtime.config.token,
+            testArtifactId: artifact.testArtifactId,
+            input: options.input,
+            ...(options.runKey !== undefined ? { runKey: options.runKey } : {}),
+        });
+        if (!created.executorToken) {
+            throw new Error("test run executor token was not returned");
+        }
+        options.onRunCreated?.({ runId: created.runId, deduped: created.deduped });
+        const run = await runTestRun({
+            convexUrl: runtime.config.convexUrl,
+            token: runtime.config.token,
+            runId: created.runId,
+            executorToken: created.executorToken,
+            pollIntervalMs: options.pollIntervalMs,
+            ...(options.concurrency !== undefined ? { concurrency: options.concurrency } : {}),
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return {
+            ok: true,
+            ...run,
+            deduped: created.deduped,
+            testArtifactId: artifact.testArtifactId,
+            expiresAt: artifact.expiresAt,
+        };
+    }
+    finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+export async function runOperation(operation, ctx, args) {
+    const validated = z.object(operation.inputSchema).passthrough().safeParse(args);
+    if (!validated.success) {
+        throw new Error(`invalid ${operation.name} input: ${z.prettifyError(validated.error)}`);
+    }
+    const parsed = validated.data;
+    if (!operation.call)
+        return await operation.run(ctx, parsed);
+    const runtime = requireRuntime(ctx);
+    const forwarded = omitUndefined(Object.fromEntries(Object.keys(operation.inputSchema).map((key) => [key, parsed[key]])));
+    return await runtime.client[operation.call.kind](operation.call.fn, {
+        token: runtime.config.token,
+        ...forwarded,
+    });
+}
+function requireRuntime(ctx) {
+    if (!ctx.runtime)
+        throw new Error("operation requires Reasonlayer config");
+    return ctx.runtime;
+}
+function optionalNumberArg(args, key) {
+    const value = args[key];
+    return typeof value === "number" ? value : undefined;
+}
+function optionalStringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+export const operationTable = [
+    {
+        name: "validate",
+        title: "Validate workflow",
+        description: "Compile and bundle a workflow in a temporary directory, returning structured errors.",
+        inputSchema: { workflow: z.string() },
+        surfaces: ["cli"],
+        run: async (_ctx, args) => await validateWorkflow(args["workflow"]),
+    },
+    {
+        name: "whoami",
+        title: "Current org",
+        description: "Return the configured Reasonlayer organization identity.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.orgsWhoami },
+    },
+    {
+        name: "bootstrap_dev_org",
+        title: "Bootstrap dev org",
+        description: "Self-provision a development organization for the token being logged in.",
+        inputSchema: { name: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.orgsBootstrapDev },
+    },
+    {
+        name: "init_workspace",
+        title: "Initialize workflow workspace",
+        description: "Create a draft workflow, materialize a checkout, and start its detached watcher.",
+        inputSchema: { workflowId: z.string(), targetDir: z.string().optional() },
+        surfaces: ["cli"],
+        run: async (ctx, args) => await createCheckout(requireRuntime(ctx), {
+            workflowId: args["workflowId"],
+            mode: "init",
+            ...(optionalStringArg(args, "targetDir") !== undefined
+                ? { targetDir: optionalStringArg(args, "targetDir") }
+                : {}),
+        }),
+    },
+    {
+        name: "pull_workspace",
+        title: "Pull workflow workspace",
+        description: "Materialize the cloud draft head in a fresh checkout and start its watcher.",
+        inputSchema: { workflowId: z.string(), targetDir: z.string().optional() },
+        surfaces: ["cli"],
+        run: async (ctx, args) => await createCheckout(requireRuntime(ctx), {
+            workflowId: args["workflowId"],
+            mode: "pull",
+            ...(optionalStringArg(args, "targetDir") !== undefined
+                ? { targetDir: optionalStringArg(args, "targetDir") }
+                : {}),
+        }),
+    },
+    {
+        name: "done_workspace",
+        title: "Finish workspace session",
+        description: "End the authoring session, stop its watcher, and remove the ephemeral checkout.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        run: async (ctx) => await endLocalSession(requireRuntime(ctx)),
+    },
+    {
+        name: "workspace_status",
+        title: "Workspace status",
+        description: "Read watcher liveness, compile state, and draft-versus-published state.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        run: async (ctx) => {
+            const runtime = requireRuntime(ctx);
+            const session = await readLocalSession();
+            return await runtime.client.query(FN.workspacesStatus, {
+                token: runtime.config.token,
+                workflowId: session.workflowId,
+                sessionId: session.sessionId,
+            });
+        },
+    },
+    {
+        name: "publish_workspace",
+        title: "Publish workspace",
+        description: "Promote the latest green draft artifact to an immutable version.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        run: async (ctx) => {
+            const runtime = requireRuntime(ctx);
+            const session = await readLocalSession();
+            return await runtime.client.mutation(FN.workspacesPublish, {
+                token: runtime.config.token,
+                workflowId: session.workflowId,
+            });
+        },
+    },
+    {
+        name: "list_workflow_versions",
+        title: "List workflow versions",
+        description: "List immutable published versions for a workflow.",
+        inputSchema: { workflowId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.workspacesListVersions },
+    },
+    {
+        name: "publish_workflow_version",
+        title: "Publish previous workflow version",
+        description: "Make a selected immutable version the workflow's published version.",
+        inputSchema: { workflowId: z.string(), versionId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.workspacesRollback },
+    },
+    {
+        name: "build",
+        title: "Build workflow",
+        description: "Compile and bundle a workflow to a local dist directory.",
+        inputSchema: { workflow: z.string(), outDir: z.string().optional() },
+        surfaces: ["cli"],
+        run: async (_ctx, args) => await buildProject(args["workflow"], optionalStringArg(args, "outDir") ?? "dist"),
+    },
+    {
+        name: "run",
+        title: "Run workflow",
+        description: "Start a run for the latest deployment of a workflow and optionally wait for completion.",
+        inputSchema: {
+            workflowId: z.string(),
+            input: z.unknown().optional(),
+            runKey: z.string().optional(),
+            wait: z.boolean().optional(),
+            pollIntervalMs: z.number().optional(),
+            timeoutMs: z.number().optional(),
+        },
+        surfaces: ["cli"],
+        run: async (ctx, args) => await runWorkflow(requireRuntime(ctx), {
+            workflowId: args["workflowId"],
+            input: args["input"] ?? {},
+            ...(optionalStringArg(args, "runKey") !== undefined
+                ? { runKey: optionalStringArg(args, "runKey") }
+                : {}),
+            wait: args["wait"] !== false,
+            pollIntervalMs: optionalNumberArg(args, "pollIntervalMs") ?? DEFAULT_POLL_INTERVAL_MS,
+            timeoutMs: optionalNumberArg(args, "timeoutMs") ?? DEFAULT_RUN_TIMEOUT_MS,
+            ...(typeof args["sleep"] === "function"
+                ? { sleep: args["sleep"] }
+                : {}),
+        }),
+    },
+    {
+        name: "dev",
+        title: "Run workflow from source",
+        description: "Build a workflow from source, create an ephemeral test run, and execute it locally.",
+        inputSchema: {
+            workflow: z.string(),
+            input: z.unknown().optional(),
+            runKey: z.string().optional(),
+            pollIntervalMs: z.number().optional(),
+            timeoutMs: z.number().optional(),
+            concurrency: z.number().optional(),
+        },
+        surfaces: ["cli"],
+        run: async (ctx, args) => await devWorkflow(requireRuntime(ctx), {
+            workflow: args["workflow"],
+            input: args["input"] ?? {},
+            ...(optionalStringArg(args, "runKey") !== undefined
+                ? { runKey: optionalStringArg(args, "runKey") }
+                : {}),
+            pollIntervalMs: optionalNumberArg(args, "pollIntervalMs") ?? DEFAULT_POLL_INTERVAL_MS,
+            timeoutMs: optionalNumberArg(args, "timeoutMs") ?? DEFAULT_RUN_TIMEOUT_MS,
+            ...(optionalNumberArg(args, "concurrency") !== undefined
+                ? { concurrency: optionalNumberArg(args, "concurrency") }
+                : {}),
+            ...(args["signal"] instanceof AbortSignal ? { signal: args["signal"] } : {}),
+            ...(typeof args["onRunCreated"] === "function"
+                ? { onRunCreated: args["onRunCreated"] }
+                : {}),
+        }),
+    },
+    {
+        name: "list_runs",
+        title: "List runs",
+        description: "List recent runs for the configured Reasonlayer org.",
+        inputSchema: { limit: z.number().optional() },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.runsList },
+    },
+    {
+        name: "inspect",
+        title: "Inspect run",
+        description: "Read run, step, usage, and paginated transcript state for a Reasonlayer run.",
+        inputSchema: {
+            runId: z.string(),
+            transcriptCursor: z.string().optional(),
+            transcriptLimit: z.number().optional(),
+        },
+        surfaces: ["cli"],
+        run: async (ctx, args) => {
+            const { client, config } = requireRuntime(ctx);
+            const runId = args["runId"];
+            const [inspection, transcript] = await Promise.all([
+                client.query(FN.runsInspect, { token: config.token, runId }),
+                client.query(FN.transcriptsList, omitUndefined({
+                    token: config.token,
+                    runId,
+                    cursor: optionalStringArg(args, "transcriptCursor"),
+                    limit: optionalNumberArg(args, "transcriptLimit") ?? 100,
+                })),
+            ]);
+            return { ...inspection, transcript };
+        },
+    },
+    {
+        name: "get_deployment",
+        title: "Get deployment",
+        description: "Read deployment metadata, bundle provenance, and environment build status.",
+        inputSchema: { deploymentId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.deploymentsGet },
+    },
+    {
+        name: "cancel_run",
+        title: "Cancel run",
+        description: "Cancel a running Reasonlayer run.",
+        inputSchema: { runId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.runsCancel },
+    },
+    {
+        name: "cancel_step",
+        title: "Cancel step",
+        description: "Cancel a live executable step attempt. The authored retry policy still applies.",
+        inputSchema: { runId: z.string(), stepId: z.string(), invocationKey: z.string().optional() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.runsCancelStep },
+    },
+    {
+        name: "retry_run",
+        title: "Retry run",
+        description: "Retry a failed Reasonlayer run, reusing succeeded step outputs.",
+        inputSchema: { runId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.runsRetry },
+    },
+    {
+        name: "set_secret",
+        title: "Set secret",
+        description: "Set or replace an encrypted org secret.",
+        inputSchema: { name: z.string(), value: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.secretsSet },
+    },
+    {
+        name: "list_secrets",
+        title: "List secrets",
+        description: "List encrypted org secret names and timestamps without exposing values.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.secretsList },
+    },
+    {
+        name: "remove_secret",
+        title: "Remove secret",
+        description: "Delete an encrypted org secret.",
+        inputSchema: { name: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.secretsRemove },
+    },
+    {
+        name: "set_variable",
+        title: "Set workflow variable",
+        description: "Set a structured workflow variable override for future runs.",
+        inputSchema: { workflowId: z.string(), name: z.string(), value: z.unknown() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.variablesSet },
+    },
+    {
+        name: "list_variables",
+        title: "List workflow variables",
+        description: "List declared workflow variables, defaults, and current overrides.",
+        inputSchema: { workflowId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.variablesList },
+    },
+    {
+        name: "remove_variable",
+        title: "Remove workflow variable override",
+        description: "Remove a workflow variable override so its declared default applies.",
+        inputSchema: { workflowId: z.string(), name: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.variablesRemove },
+    },
+    {
+        name: "list_reviews",
+        title: "List reviews",
+        description: "List review approvals for the configured Reasonlayer org.",
+        inputSchema: {
+            status: z.enum(APPROVAL_STATUSES).optional(),
+            limit: z.number().optional(),
+        },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.approvalsList },
+    },
+    {
+        name: "approve_review",
+        title: "Approve review",
+        description: "Resolve a pending review with a decision matching the step output schema.",
+        inputSchema: { approvalId: z.string(), decision: z.unknown() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.approvalsApprove },
+    },
+    {
+        name: "reject_review",
+        title: "Reject review",
+        description: "Reject a pending review and resume the run as a step failure.",
+        inputSchema: { approvalId: z.string(), reason: z.string().optional() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.approvalsReject },
+    },
+    {
+        name: "list_triggers",
+        title: "List triggers",
+        description: "List named workflow triggers and their subscribed countdown state.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.triggersList },
+    },
+    {
+        name: "set_trigger_enabled",
+        title: "Enable or disable trigger",
+        description: "Change operator enablement without changing authored trigger configuration.",
+        inputSchema: { triggerId: z.string(), enabled: z.boolean() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.triggersSetEnabled },
+    },
+    {
+        name: "delete_workflow",
+        title: "Delete workflow",
+        description: "Delete a workflow, its versions, deployments, triggers, and stored artifacts.",
+        inputSchema: { workflowId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.deploymentsDeleteWorkflow },
+    },
+    {
+        name: "create_token",
+        title: "Create token",
+        description: "Create a scoped platform token.",
+        inputSchema: {
+            label: z.string(),
+            scopes: z.array(z.string()),
+            workflowIds: z.array(z.string()).optional(),
+            expiresAt: z.number().optional(),
+        },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.tokensCreate },
+    },
+    {
+        name: "list_tokens",
+        title: "List tokens",
+        description: "List scoped platform tokens without revealing their values.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.tokensList },
+    },
+    {
+        name: "revoke_token",
+        title: "Revoke token",
+        description: "Revoke a scoped platform token.",
+        inputSchema: { tokenId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.tokensRevoke },
+    },
+    {
+        name: "list_devices",
+        title: "List devices",
+        description: "List registered devices for the configured Reasonlayer org.",
+        inputSchema: {},
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.devicesList },
+    },
+    {
+        name: "register_device",
+        title: "Register device",
+        description: "Register a device and return its durable secret once.",
+        inputSchema: {
+            name: z.string(),
+            settings: z.record(z.string(), z.unknown()).optional(),
+        },
+        surfaces: ["cli"],
+        call: { kind: "action", fn: FN.devicesRegister },
+    },
+    {
+        name: "bind_device_handle",
+        title: "Bind device handle",
+        description: "Bind or rebind a workflow device handle to a registered machine.",
+        inputSchema: { handle: z.string(), deviceId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.devicesBindHandle },
+    },
+    {
+        name: "update_device",
+        title: "Update device",
+        description: "Update a registered device's name, enabled state, or settings.",
+        inputSchema: {
+            deviceId: z.string(),
+            name: z.string().optional(),
+            enabled: z.boolean().optional(),
+            settings: z.record(z.string(), z.unknown()).optional(),
+        },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.devicesUpdate },
+    },
+    {
+        name: "rotate_device_secret",
+        title: "Rotate device secret",
+        description: "Rotate a registered device's durable secret. The new secret is returned once.",
+        inputSchema: { deviceId: z.string() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.devicesRotateSecret },
+    },
+    {
+        name: "list_device_profiles",
+        title: "List device profiles",
+        description: "List browser profiles, optionally scoped to one device.",
+        inputSchema: { deviceId: z.string().optional() },
+        surfaces: ["cli"],
+        call: { kind: "query", fn: FN.devicesListProfiles },
+    },
+    {
+        name: "create_device_profile",
+        title: "Create device profile",
+        description: "Create or re-enable a browser profile for a device.",
+        inputSchema: {
+            deviceId: z.string(),
+            profileKey: z.string(),
+            label: z.string().optional(),
+        },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.devicesCreateProfile },
+    },
+    {
+        name: "request_device_profile_login",
+        title: "Request device profile login",
+        description: "Ask a device daemon to complete login for a browser profile.",
+        inputSchema: { profileId: z.string(), message: z.string().optional() },
+        surfaces: ["cli"],
+        call: { kind: "mutation", fn: FN.devicesRequestProfileLogin },
+    },
+];
+export function operationsForSurface(surface) {
+    return operationTable.filter((operation) => operation.surfaces.includes(surface));
+}
+export function operationByName(name) {
+    return operationTable.find((operation) => operation.name === name);
+}
+export function operationForSurfaceByName(surface, name) {
+    return operationsForSurface(surface).find((operation) => operation.name === name);
+}

package/dist/cli/sdk-package.d.ts

@@ -0,0 +1,18 @@
+export declare const SDK_ROOT: string;
+export declare function sdkVersion(): Promise<string>;
+/** A single semver release, with no range operator — what a checkout may pin. */
+export declare const EXACT_VERSION: RegExp;
+/**
+ * The Flue runtime a checkout must install to match this SDK. It is the SDK's
+ * own dependency because the bundled runner resolves Flue from the SDK's tree —
+ * so read it, never copy it. It must be exact: scaffolds write it straight into
+ * a checkout pin, and a range there is not a pin.
+ */
+export declare function pairedFlueRuntimeVersion(): Promise<string>;
+export interface SdkProvenance {
+    version: string;
+    installSource: "installed" | "local checkout";
+    repoRoot?: string;
+    label: string;
+}
+export declare function sdkProvenance(): Promise<SdkProvenance>;

package/dist/cli/sdk-package.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import { dirname, parse, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const MODULE_PATH = fileURLToPath(import.meta.url);
+export const SDK_ROOT = resolve(dirname(MODULE_PATH), "../..");
+let manifestPromise;
+function sdkManifest() {
+    manifestPromise ??= readFile(resolve(SDK_ROOT, "package.json"), "utf8")
+        .then((text) => JSON.parse(text));
+    return manifestPromise;
+}
+export function sdkVersion() {
+    return sdkManifest().then((manifest) => manifest.version);
+}
+/** A single semver release, with no range operator — what a checkout may pin. */
+export const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+ * The Flue runtime a checkout must install to match this SDK. It is the SDK's
+ * own dependency because the bundled runner resolves Flue from the SDK's tree —
+ * so read it, never copy it. It must be exact: scaffolds write it straight into
+ * a checkout pin, and a range there is not a pin.
+ */
+export async function pairedFlueRuntimeVersion() {
+    const spec = (await sdkManifest()).dependencies?.["@flue/runtime"];
+    if (!spec)
+        throw new Error("@reasonlayer/sdk declares no @flue/runtime dependency");
+    if (!EXACT_VERSION.test(spec)) {
+        throw new Error(`@reasonlayer/sdk must depend on an exact @flue/runtime version; found "${spec}"`);
+    }
+    return spec;
+}
+export async function sdkProvenance() {
+    const version = await sdkVersion();
+    const segments = MODULE_PATH.slice(parse(MODULE_PATH).root.length).split(sep);
+    if (segments.includes("node_modules")) {
+        return { version, installSource: "installed", label: `rl ${version} (installed)` };
+    }
+    const repoRoot = resolve(SDK_ROOT, "../..");
+    return {
+        version,
+        installSource: "local checkout",
+        repoRoot,
+        label: `rl ${version} (local checkout: ${repoRoot})`,
+    };
+}