@kheleshikhi/studio-agent 0.6.1

package/dist/observation.js

@@ -0,0 +1,66 @@
+import { CliError } from "./types.js";
+export function observationSettings(input) {
+    const mode = input.mode || "semantic";
+    const durationMs = Math.round((input.duration ?? 8) * 1000);
+    const fps = input.fps ?? 4;
+    if (mode !== "semantic" && mode !== "fixed")
+        throw new CliError("Capture mode must be semantic or fixed.", "STUDIO_CAPTURE_SETTINGS_INVALID", 2);
+    if (!Number.isFinite(durationMs) || durationMs < 500 || durationMs > 10_000 ||
+        !Number.isInteger(fps) || fps < 1 || fps > 8 ||
+        input.width < 320 || input.width > 1280 || input.height < 240 || input.height > 960 ||
+        (mode === "fixed" && Math.ceil(durationMs / 1000 * fps) + 1 > 24)) {
+        throw new CliError("Capture is limited to 0.5–10 s, 1–8 fps, 320–1280 × 240–960, and 24 frames.", "STUDIO_CAPTURE_SETTINGS_INVALID", 2);
+    }
+    return { mode, durationMs, fps, width: input.width, height: input.height };
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function serial(value) { return JSON.stringify(value ?? null); }
+/** Selects bounded checkpoints from the real live runtime, never simulated state. */
+export class ObservationSampler {
+    settings;
+    checkpoints = [];
+    previous;
+    lastMotionAt = 0;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    consider(atMs, observation, final = false) {
+        const previous = this.previous;
+        const last = this.checkpoints.at(-1);
+        const stateChanged = previous && serial(previous.active_states) !== serial(observation.active_states);
+        const variablesChanged = previous && serial(previous.host_variables) !== serial(observation.host_variables);
+        const interactionsChanged = previous && serial(previous.interactions) !== serial(observation.interactions);
+        const dispatchChanged = previous && serial(previous.machine_dispatches) !== serial(observation.machine_dispatches);
+        const geometryChanged = previous && previous.geometry_revision !== observation.geometry_revision;
+        const semantic = !!(stateChanged || variablesChanged || interactionsChanged || dispatchChanged);
+        const fixedDue = !last || atMs - last.at_ms >= 1000 / this.settings.fps - 20;
+        const motionDue = geometryChanged && atMs - this.lastMotionAt >= 1000;
+        const selected = !last || final || (this.settings.mode === "fixed" ? fixedDue : semantic || motionDue);
+        this.previous = observation;
+        if (final && last?.at_ms === atMs) {
+            last.label = "END";
+            last.observation = observation;
+            return undefined;
+        }
+        if (!selected || this.checkpoints.length >= (final ? 24 : 23))
+            return undefined;
+        if (motionDue)
+            this.lastMotionAt = atMs;
+        const label = !last ? "START" : final ? "END" : interactionsChanged ? "INTERACTION" : stateChanged ? "STATE CHANGE" : dispatchChanged ? "EVENT" : variablesChanged ? "VARIABLE CHANGE" : motionDue ? "MOTION" : "SAMPLE";
+        const checkpoint = { id: this.checkpoints.length + 1, at_ms: atMs, label, observation };
+        this.checkpoints.push(checkpoint);
+        return checkpoint;
+    }
+}
+export function assertCurrentObservation(observation, sourceHash, revision) {
+    if (observation.status !== "complete" || observation.preview_is_current !== true ||
+        observation.source_hash !== sourceHash || observation.source_revision !== revision) {
+        throw new CliError("The live preview changed or became stale during capture; no current-source evidence was produced.", "STUDIO_CAPTURE_STALE", 3, {
+            expected_source_hash: sourceHash, observed_source_hash: observation.source_hash,
+            expected_revision: revision, observed_revision: observation.source_revision,
+        });
+    }
+}
+//# sourceMappingURL=observation.js.map

package/dist/observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.js","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface TraceIdentity {
+    attemptId?: string;
+    commandId?: string;
+}
+export declare const traceStorage: AsyncLocalStorage<TraceIdentity>;
+export declare function setCliTrace(value: TraceIdentity): void;
+export declare class AgentApi {
+    readonly origin: string;
+    private token?;
+    constructor(origin: string, token?: string | undefined);
+    setToken(value: string | undefined): void;
+    /**
+     * POST one file as multipart form data. The filename is always the neutral
+     * `upload.<extension>`; the caller's local path or name never leaves the machine.
+     */
+    upload<T>(route: string, field: string, extension: string, contentType: string, bytes: Uint8Array): Promise<T>;
+    request<T>(method: string, route: string, body?: unknown, authenticated?: boolean): Promise<T>;
+}
+export declare function daemonRpc<T>(path: string, options?: RequestInit): Promise<T>;

package/dist/protocol.js

@@ -0,0 +1,99 @@
+import { CliError } from "./types.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+export const traceStorage = new AsyncLocalStorage();
+let cliTrace = {};
+export function setCliTrace(value) { cliTrace = value; }
+function traceHeaders(trace) {
+    return {
+        "X-Request-ID": `req_${randomBytes(12).toString("base64url")}`,
+        ...(trace.attemptId ? { "X-NerdBro-Attempt-ID": trace.attemptId } : {}),
+        ...(trace.commandId ? { "X-NerdBro-Command-ID": trace.commandId } : {}),
+    };
+}
+export class AgentApi {
+    origin;
+    token;
+    constructor(origin, token) {
+        this.origin = origin;
+        this.token = token;
+    }
+    setToken(value) {
+        this.token = value;
+    }
+    /**
+     * POST one file as multipart form data. The filename is always the neutral
+     * `upload.<extension>`; the caller's local path or name never leaves the machine.
+     */
+    async upload(route, field, extension, contentType, bytes) {
+        if (!/^[a-z0-9]{1,8}$/.test(extension))
+            throw new CliError("Upload extension is invalid.", "AGENT_UPLOAD_INVALID", 2);
+        const form = new FormData();
+        form.append(field, new Blob([new Uint8Array(bytes)], { type: contentType }), `upload.${extension}`);
+        return this.request("POST", route, form);
+    }
+    async request(method, route, body, authenticated = true) {
+        const headers = { Accept: "application/json", ...traceHeaders(traceStorage.getStore() || {}) };
+        const multipart = body instanceof FormData;
+        if (body !== undefined && !multipart)
+            headers["Content-Type"] = "application/json";
+        if (authenticated) {
+            if (!this.token)
+                throw new CliError("Run `nerdbro connect` first.", "AGENT_AUTH_REQUIRED", 4);
+            headers.Authorization = `Bearer ${this.token}`;
+        }
+        let response;
+        try {
+            response = await fetch(new URL(route, `${this.origin}/`), {
+                method,
+                headers,
+                body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            throw new CliError(`Cannot reach ${this.origin}: ${String(error)}`, "AGENT_NETWORK_FAILURE");
+        }
+        const contentType = response.headers.get("content-type") || "";
+        if (!response.ok) {
+            const detail = contentType.includes("json") ? await response.json().catch(() => ({})) : await response.text();
+            const candidate = typeof detail === "object" && detail && "detail" in detail ? detail.detail : detail;
+            const text = typeof candidate === "string" ? candidate : JSON.stringify(candidate);
+            const code = /[A-Z][A-Z0-9_]{3,}/.exec(text)?.[0] || `HTTP_${response.status}`;
+            const exitCode = response.status === 409 ? 3 : response.status === 401 ? 4 : 1;
+            throw new CliError(text || response.statusText, code, exitCode, candidate);
+        }
+        if (!contentType.includes("json"))
+            return new Uint8Array(await response.arrayBuffer());
+        const payload = (await response.json());
+        return typeof payload === "object" && payload !== null && "data" in payload ? payload.data : payload;
+    }
+}
+export async function daemonRpc(path, options = {}) {
+    const { cleanStaleDaemonMetadata, readDaemonMetadata } = await import("./state.js");
+    await cleanStaleDaemonMetadata();
+    const metadata = await readDaemonMetadata();
+    if (!metadata)
+        throw new CliError("The local agent daemon is not running.", "AGENT_DAEMON_NOT_RUNNING", 4);
+    let response;
+    try {
+        response = await fetch(`http://127.0.0.1:${metadata.port}${path}`, {
+            ...options,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${metadata.rpcSecret}`,
+                ...(cliTrace.attemptId ? { "X-NerdBro-Attempt-ID": cliTrace.attemptId } : {}),
+                ...(cliTrace.commandId ? { "X-NerdBro-Command-ID": cliTrace.commandId } : {}),
+                ...(options.headers || {}),
+            },
+        });
+    }
+    catch {
+        await cleanStaleDaemonMetadata();
+        throw new CliError("The local agent daemon did not respond.", "AGENT_DAEMON_UNAVAILABLE", 4);
+    }
+    const value = (await response.json());
+    if (!response.ok || value.ok === false)
+        throw new CliError(value.message || "Daemon request failed.", value.code, value.exitCode || 1, value.details);
+    return value;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/scenario.d.ts

@@ -0,0 +1,19 @@
+export type DriveStep = {
+    op: "set" | "fire" | "press" | "tap" | "drag" | "play" | "pause" | "seek" | "reset" | "wait" | "assert" | "capture";
+    target?: string;
+    value?: string | number | boolean;
+    path?: string;
+    equals?: string | number | boolean | null;
+    between?: [number, number];
+    timeoutMs?: number;
+    name?: string;
+};
+export type DriveScenario = {
+    version: 1;
+    steps: DriveStep[];
+};
+export declare function parseScenario(value: unknown): DriveScenario;
+export declare function validObservationPath(path: string): boolean;
+export declare function observedValue(observation: Record<string, unknown>, path: string): unknown;
+export declare function matchesObservation(observation: Record<string, unknown>, step: DriveStep): boolean;
+export declare function isDriveCommand(step: DriveStep): boolean;

package/dist/scenario.js

@@ -0,0 +1,90 @@
+import { CliError } from "./types.js";
+const COMMANDS = new Set(["set", "fire", "press", "tap", "drag", "play", "pause", "seek", "reset"]);
+const OPERATIONS = new Set([...COMMANDS, "wait", "assert", "capture"]);
+const PATH_ROOTS = new Set([
+    "active_states", "host_variables", "motion_outputs", "learner_controls",
+    "recent_scene_event", "scene_event_sequence", "scene_clock_seconds",
+    "scene_clock_playing", "machine_dispatches", "math_graph", "runtime_ready",
+    "geometry_instance_ids", "error_summary",
+    "recent_audio_event", "audio_failed_count",
+    "captions", "visual_ready",
+    "gestures",
+]);
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_-]*$/;
+function invalid(message) {
+    throw new CliError(message, "STUDIO_SCENARIO_INVALID", 2);
+}
+export function parseScenario(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid("Scenario must be an object.");
+    const document = value;
+    if (document.version !== 1 || !Array.isArray(document.steps) || !document.steps.length || document.steps.length > 64) {
+        invalid("Scenario requires version 1 and 1–64 steps.");
+    }
+    const steps = document.steps.map((raw, index) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            invalid(`Step ${index} must be an object.`);
+        const step = raw;
+        if (typeof step.op !== "string" || !OPERATIONS.has(step.op))
+            invalid(`Step ${index} has an unsupported operation.`);
+        const allowed = new Set(["op", "target", "value", "path", "equals", "between", "timeoutMs", "name"]);
+        if (Object.keys(step).some((key) => !allowed.has(key)))
+            invalid(`Step ${index} has an unknown field.`);
+        if (["set", "fire", "press", "tap", "drag"].includes(step.op) &&
+            (typeof step.target !== "string" || !IDENTIFIER.test(step.target) || step.target.length > 80)) {
+            invalid(`Step ${index} needs a semantic target id.`);
+        }
+        if (["set", "drag", "seek"].includes(step.op) &&
+            (typeof step.value !== "number" && typeof step.value !== "boolean" && typeof step.value !== "string" ||
+                typeof step.value === "number" && !Number.isFinite(step.value))) {
+            invalid(`Step ${index} needs a finite value.`);
+        }
+        if (typeof step.value === "string" && step.value.length > 160)
+            invalid(`Step ${index} value is too long.`);
+        if (["wait", "assert"].includes(step.op)) {
+            if (typeof step.path !== "string" || !validObservationPath(step.path))
+                invalid(`Step ${index} needs an allowed observation path.`);
+            const hasEquals = Object.hasOwn(step, "equals");
+            const between = step.between;
+            if (hasEquals === (between !== undefined))
+                invalid(`Step ${index} needs exactly one comparison.`);
+            if (between !== undefined && (!Array.isArray(between) || between.length !== 2 ||
+                between.some((n) => typeof n !== "number" || !Number.isFinite(n)) || between[0] > between[1])) {
+                invalid(`Step ${index} has invalid bounds.`);
+            }
+        }
+        if (step.timeoutMs !== undefined && (typeof step.timeoutMs !== "number" || !Number.isInteger(step.timeoutMs) || step.timeoutMs < 1 || step.timeoutMs > 30_000)) {
+            invalid(`Step ${index} timeout must be 1–30000 ms.`);
+        }
+        if (step.name !== undefined && (typeof step.name !== "string" || !/^[A-Za-z0-9_-]{1,60}$/.test(step.name)))
+            invalid(`Step ${index} has invalid capture name.`);
+        return step;
+    });
+    return { version: 1, steps };
+}
+export function validObservationPath(path) {
+    const parts = path.split(".");
+    return parts.length <= 4 && PATH_ROOTS.has(parts[0]) &&
+        parts.slice(1).every((part) => /^[A-Za-z0-9_-]{1,80}$/.test(part));
+}
+export function observedValue(observation, path) {
+    if (!validObservationPath(path))
+        invalid("Observation path is not allowed.");
+    const parts = path.split(".");
+    if (parts[0] === "motion_outputs") {
+        const outputs = observation.motion_outputs;
+        if (outputs && typeof outputs === "object" && Object.hasOwn(outputs, parts.slice(1).join("."))) {
+            return outputs[parts.slice(1).join(".")];
+        }
+    }
+    return parts.reduce((value, key) => value && typeof value === "object" && Object.hasOwn(value, key)
+        ? value[key] : undefined, observation);
+}
+export function matchesObservation(observation, step) {
+    const value = observedValue(observation, step.path || "");
+    if (step.between)
+        return typeof value === "number" && value >= step.between[0] && value <= step.between[1];
+    return value === step.equals;
+}
+export function isDriveCommand(step) { return COMMANDS.has(step.op); }
+//# sourceMappingURL=scenario.js.map

package/dist/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../src/scenario.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,13 @@
+import type { AgentConfig, DaemonMetadata } from "./types.js";
+export declare const DEFAULT_API_ORIGIN = "https://api.nerdbro.org";
+export declare function stateDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export declare function cacheDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export declare function writeDaemonMetadata(value: DaemonMetadata): Promise<void>;
+export declare function readDaemonMetadata(): Promise<DaemonMetadata | null>;
+export declare function removeDaemonMetadata(): Promise<void>;
+export declare function processExists(pid: number): boolean;
+export declare function cleanStaleDaemonMetadata(): Promise<void>;
+export declare function validateOrigin(raw: string): string;
+export declare function readConfig(): Promise<AgentConfig>;
+export declare function writeConfig(config: AgentConfig): Promise<void>;
+export declare function isExecutable(file: string): Promise<boolean>;

package/dist/state.js

@@ -0,0 +1,111 @@
+import { constants } from "node:fs";
+import { access, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { CliError } from "./types.js";
+export const DEFAULT_API_ORIGIN = "https://api.nerdbro.org";
+export function stateDirectory(env = process.env, platform = process.platform) {
+    if (env.NERDBRO_AGENT_STATE_DIR)
+        return path.resolve(env.NERDBRO_AGENT_STATE_DIR);
+    if (platform === "win32") {
+        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent");
+    }
+    if (platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "NerdBro", "Studio Agent");
+    }
+    return path.join(env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), "nerdbro-studio-agent");
+}
+export function cacheDirectory(env = process.env, platform = process.platform) {
+    if (env.NERDBRO_AGENT_CACHE_DIR)
+        return path.resolve(env.NERDBRO_AGENT_CACHE_DIR);
+    if (platform === "win32") {
+        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent", "Cache");
+    }
+    if (platform === "darwin")
+        return path.join(os.homedir(), "Library", "Caches", "NerdBro Studio Agent");
+    return path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "nerdbro-studio-agent");
+}
+function daemonPath() {
+    return path.join(stateDirectory(), "daemon.json");
+}
+function configPath() {
+    return path.join(stateDirectory(), "config.json");
+}
+async function atomicJson(target, value) {
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, target);
+}
+export async function writeDaemonMetadata(value) {
+    await atomicJson(daemonPath(), value);
+}
+export async function readDaemonMetadata() {
+    try {
+        const value = JSON.parse(await readFile(daemonPath(), "utf8"));
+        if (!Number.isInteger(value.pid) || !Number.isInteger(value.port) || !value.rpcSecret)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export async function removeDaemonMetadata() {
+    await unlink(daemonPath()).catch(() => undefined);
+}
+export function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function cleanStaleDaemonMetadata() {
+    const metadata = await readDaemonMetadata();
+    if (metadata && !processExists(metadata.pid))
+        await removeDaemonMetadata();
+}
+export function validateOrigin(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new CliError("Origin must be an absolute URL.", "AGENT_ORIGIN_INVALID", 2);
+    }
+    const local = parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "::1";
+    if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
+        throw new CliError("Non-local Agent origins must use HTTPS.", "AGENT_ORIGIN_INSECURE", 2);
+    }
+    if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) {
+        throw new CliError("Origin must contain only scheme, host, and optional port.", "AGENT_ORIGIN_INVALID", 2);
+    }
+    return parsed.origin;
+}
+export async function readConfig() {
+    try {
+        const value = JSON.parse(await readFile(configPath(), "utf8"));
+        return { apiOrigin: validateOrigin(value.apiOrigin || DEFAULT_API_ORIGIN) };
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        return { apiOrigin: DEFAULT_API_ORIGIN };
+    }
+}
+export async function writeConfig(config) {
+    await atomicJson(configPath(), { apiOrigin: validateOrigin(config.apiOrigin) });
+}
+export async function isExecutable(file) {
+    try {
+        await access(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface DaemonMetadata {
+    pid: number;
+    port: number;
+    rpcSecret: string;
+    startedAt: string;
+    headless: boolean;
+}
+export interface AgentConfig {
+    apiOrigin: string;
+}
+export interface CommandResult {
+    ok: boolean;
+    command: string;
+    [key: string]: unknown;
+}
+export interface ApiEnvelope<T = unknown> {
+    data: T;
+    detail?: string;
+    pagination?: unknown;
+}
+export declare const EXIT_CODE: {
+    readonly failure: 1;
+    readonly usage: 2;
+    readonly conflict: 3;
+    readonly authentication: 4;
+    readonly environment: 5;
+};
+export interface StudioLock {
+    schema: "kheleshikhi.interactive-studio-lock.v1";
+    asset_id: string;
+    server_origin: string;
+    base_snapshot_public_id: string | null;
+    base_revision_public_id: string | null;
+    source_hash: string;
+    checkout_source_hash: string;
+    compiler_version: string;
+    scene_schema: unknown;
+    component_catalogue_checksum: string;
+    behavior_catalogue_checksum: string;
+    checkout_time: string;
+}
+export declare const LIBRARY_KINDS: readonly ["experience", "audio", "component", "behavior"];
+export type LibraryKind = (typeof LIBRARY_KINDS)[number];
+/** Local optimistic-concurrency record for one checked-out Library definition. */
+export interface LibraryLock {
+    schema: "kheleshikhi.library-lock.v1";
+    kind: LibraryKind;
+    stable_id: string;
+    server_origin: string;
+    head_revision_public_id: string | null;
+    source_hash: string;
+    schema_version: string | null;
+    checked_out_at: string;
+    updated_at?: string;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details: unknown;
+    constructor(message: string, code?: string, exitCode?: number, details?: unknown);
+}

package/dist/types.js

@@ -0,0 +1,20 @@
+export const EXIT_CODE = {
+    failure: 1,
+    usage: 2,
+    conflict: 3,
+    authentication: 4,
+    environment: 5,
+};
+export const LIBRARY_KINDS = ["experience", "audio", "component", "behavior"];
+export class CliError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(message, code = "AGENT_COMMAND_FAILED", exitCode = 1, details = {}) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0BA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;IACX,cAAc,EAAE,CAAC;IACjB,WAAW,EAAE,CAAC;CACN,CAAC;AAiBX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC;AAgBvF,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGtB;IACA;IACA;IAJX,YACE,OAAe,EACN,OAAO,sBAAsB,EAC7B,WAAW,CAAC,EACZ,UAAmB,EAAE;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAyB;QAC7B,aAAQ,GAAR,QAAQ,CAAI;QACZ,YAAO,GAAP,OAAO,CAAc;IAGhC,CAAC;CACF"}

package/dist/workspace.d.ts

@@ -0,0 +1,15 @@
+import type { StudioLock } from "./types.js";
+export declare function canonicalJson(value: unknown): string;
+export declare function sourceHash(value: unknown): string;
+export declare class StudioWorkspace {
+    readonly root: string;
+    readonly asset: string;
+    readonly directory: string;
+    readonly sourcePath: string;
+    readonly lockPath: string;
+    constructor(root: string, asset: string);
+    source(): Promise<Record<string, unknown>>;
+    lock(): Promise<StudioLock>;
+    write(source: Record<string, unknown>, lock: StudioLock): Promise<void>;
+    writeLock(lock: StudioLock): Promise<void>;
+}

package/dist/workspace.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./types.js";
+const ASSET_ID = /^[A-Za-z0-9_-]+$/;
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export function sourceHash(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+export class StudioWorkspace {
+    root;
+    asset;
+    directory;
+    sourcePath;
+    lockPath;
+    constructor(root, asset) {
+        this.root = root;
+        this.asset = asset;
+        if (!ASSET_ID.test(asset))
+            throw new CliError("Asset id contains unsafe path characters.", "STUDIO_ASSET_ID_INVALID", 2);
+        this.directory = path.resolve(root, asset);
+        if (path.dirname(this.directory) !== path.resolve(root))
+            throw new CliError("Checkout escaped its workspace.", "STUDIO_WORKSPACE_ESCAPE", 2);
+        this.sourcePath = path.join(this.directory, "source.json");
+        this.lockPath = path.join(this.directory, "studio-lock.json");
+    }
+    async source() {
+        try {
+            const value = JSON.parse(await readFile(this.sourcePath, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("not an object");
+            return value;
+        }
+        catch (error) {
+            throw new CliError(`Cannot read ${this.sourcePath}: ${String(error)}`, "STUDIO_SOURCE_INVALID", 2);
+        }
+    }
+    async lock() {
+        try {
+            const value = JSON.parse(await readFile(this.lockPath, "utf8"));
+            if (value.asset_id !== this.asset || value.schema !== "kheleshikhi.interactive-studio-lock.v1")
+                throw new Error("wrong asset or schema");
+            return value;
+        }
+        catch (error) {
+            throw new CliError(`Cannot read ${this.lockPath}: ${String(error)}`, "STUDIO_LOCK_INVALID", 2);
+        }
+    }
+    async write(source, lock) {
+        await mkdir(this.directory, { recursive: true });
+        await writeFile(this.sourcePath, `${JSON.stringify(source, null, 2)}\n`, "utf8");
+        await writeFile(this.lockPath, `${JSON.stringify(lock, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+    async writeLock(lock) {
+        await writeFile(this.lockPath, `${JSON.stringify(lock, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    }
+}
+//# sourceMappingURL=workspace.js.map