@sapiom/sandbox-preview 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @sapiom/sandbox-preview
+
+## 0.1.2
+
+### Patch Changes
+
+- 41e9ecd: New package: the client flow for deploying a web-app preview to a Sapiom sandbox and getting a live URL.
+
+  Reads the project's `sapiom.json` (`type: "sandbox"` resource), provisions the sandbox if needed, ships the code — either a local directory upload or a Sapiom git repository — and calls the server-side deploy op to build, start, and expose a public preview URL. Returns `{ name, url, status, logs }`; a non-`deployed` status carries the build/start log tail so a crash-on-boot is visible to fix and retry.
+
+  Includes a zod-validated `sapiom.json` schema carrying a config version, so a malformed or hand-edited file fails with an actionable message rather than a confusing downstream error. Exposes `configureSandbox` (validate typed input and write the resource) and `checkSandboxes` (validate a project's sandbox resources without deploying) for building tooling on top.
+
+- Updated dependencies [41e9ecd]
+  - @sapiom/tools@0.17.2

package/dist/cjs/config.d.ts

@@ -0,0 +1,12 @@
+import { type SandboxConfigBody } from './schema.js';
+import type { SandboxConfig } from './types.js';
+export declare const CONFIG_FILE = "sapiom.json";
+export declare function readSandboxes(dir: string): Record<string, SandboxConfig>;
+export declare function getSandbox(dir: string, name?: string): SandboxConfig;
+export declare function configureSandbox(dir: string, name: string, body: SandboxConfigBody): SandboxConfig;
+export declare const writeSandbox: (dir: string, cfg: SandboxConfig) => SandboxConfig;
+export declare function checkSandboxes(dir: string): {
+    ok: boolean;
+    sandboxes: string[];
+    issues: string[];
+};

package/dist/cjs/config.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSandbox = exports.CONFIG_FILE = void 0;
+exports.readSandboxes = readSandboxes;
+exports.getSandbox = getSandbox;
+exports.configureSandbox = configureSandbox;
+exports.checkSandboxes = checkSandboxes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+const schema_js_1 = require("./schema.js");
+exports.CONFIG_FILE = 'sapiom.json';
+function readFile(dir) {
+    const file = node_path_1.default.join(dir, exports.CONFIG_FILE);
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch {
+        throw new errors_js_1.PreviewOperationError({ code: 'BAD_CONFIG', message: `${exports.CONFIG_FILE} is not valid JSON.` });
+    }
+    if (typeof parsed.version === 'number' && parsed.version > schema_js_1.CONFIG_VERSION) {
+        throw new errors_js_1.PreviewOperationError({
+            code: 'UNSUPPORTED_CONFIG_VERSION',
+            message: `${exports.CONFIG_FILE} is version ${parsed.version}, but this tool supports up to ${schema_js_1.CONFIG_VERSION}.`,
+            hint: 'Upgrade the Sapiom SDK/CLI.',
+        });
+    }
+    return parsed;
+}
+function parseSandboxEntry(name, entry) {
+    const result = schema_js_1.storedSandboxSchema.safeParse(entry);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((i) => `${['resources', name, ...i.path].join('.')}: ${i.message}`)
+            .join('; ');
+        throw new errors_js_1.PreviewOperationError({
+            code: 'INVALID_SANDBOX',
+            message: `Invalid sandbox resource "${name}" in ${exports.CONFIG_FILE}.`,
+            hint: detail,
+        });
+    }
+    const { type: _type, ...body } = result.data;
+    return { name, ...body };
+}
+function readSandboxes(dir) {
+    const cfg = readFile(dir);
+    const resources = cfg?.resources ?? {};
+    const out = {};
+    for (const [name, entry] of Object.entries(resources)) {
+        if (entry?.type !== 'sandbox')
+            continue;
+        out[name] = parseSandboxEntry(name, entry);
+    }
+    return out;
+}
+function getSandbox(dir, name) {
+    const sandboxes = readSandboxes(dir);
+    const names = Object.keys(sandboxes);
+    if (name) {
+        const found = sandboxes[name];
+        if (!found) {
+            throw new errors_js_1.PreviewOperationError({
+                code: 'NO_SANDBOX',
+                message: `No sandbox named '${name}' in ${exports.CONFIG_FILE}.`,
+                hint: names.length ? `Known sandboxes: ${names.join(', ')}.` : undefined,
+            });
+        }
+        return found;
+    }
+    if (names.length === 0) {
+        throw new errors_js_1.PreviewOperationError({
+            code: 'NO_SANDBOX',
+            message: `No sandbox resources defined in ${exports.CONFIG_FILE}.`,
+            hint: 'Add one with sapiom_dev_sandbox_configure (or a "type":"sandbox" resource).',
+        });
+    }
+    if (names.length > 1) {
+        throw new errors_js_1.PreviewOperationError({
+            code: 'AMBIGUOUS_SANDBOX',
+            message: `Multiple sandboxes defined (${names.join(', ')}); specify which one.`,
+            hint: 'Pass a name, e.g. `sapiom sandbox preview <name>`.',
+        });
+    }
+    return sandboxes[names[0]];
+}
+function configureSandbox(dir, name, body) {
+    const parsed = schema_js_1.storedSandboxSchema.safeParse({ type: 'sandbox', ...body });
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        throw new errors_js_1.PreviewOperationError({
+            code: 'INVALID_SANDBOX',
+            message: `Invalid sandbox configuration for "${name}".`,
+            hint: detail,
+        });
+    }
+    const existing = readFile(dir) ?? {};
+    const next = {
+        version: schema_js_1.CONFIG_VERSION,
+        ...existing,
+        resources: { ...(existing.resources ?? {}), [name]: parsed.data },
+    };
+    next.version = schema_js_1.CONFIG_VERSION;
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(dir, exports.CONFIG_FILE), JSON.stringify(next, null, 2) + '\n');
+    return { name, ...body };
+}
+const writeSandbox = (dir, cfg) => {
+    const { name, ...body } = cfg;
+    return configureSandbox(dir, name, body);
+};
+exports.writeSandbox = writeSandbox;
+function checkSandboxes(dir) {
+    const issues = [];
+    const cfg = readFile(dir);
+    const resources = cfg?.resources ?? {};
+    const found = [];
+    for (const [name, entry] of Object.entries(resources)) {
+        if (entry?.type !== 'sandbox')
+            continue;
+        found.push(name);
+        const r = schema_js_1.storedSandboxSchema.safeParse(entry);
+        if (!r.success) {
+            for (const i of r.error.issues)
+                issues.push(`resources.${name}.${i.path.join('.')}: ${i.message}`);
+        }
+    }
+    return { ok: issues.length === 0, sandboxes: found, issues };
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,15 @@
+export interface StructuredError {
+    code: string;
+    message: string;
+    step?: string;
+    hint?: string;
+    docsUrl?: string;
+}
+export declare class PreviewOperationError extends Error {
+    readonly code: string;
+    readonly step?: string;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+    constructor(err: StructuredError);
+    toStructured(): StructuredError;
+}

package/dist/cjs/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewOperationError = void 0;
+class PreviewOperationError extends Error {
+    constructor(err) {
+        super(err.message);
+        this.name = 'PreviewOperationError';
+        this.code = err.code;
+        this.step = err.step;
+        this.hint = err.hint;
+        this.docsUrl = err.docsUrl;
+    }
+    toStructured() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.step ? { step: this.step } : {}),
+            ...(this.hint ? { hint: this.hint } : {}),
+            ...(this.docsUrl ? { docsUrl: this.docsUrl } : {}),
+        };
+    }
+}
+exports.PreviewOperationError = PreviewOperationError;

package/dist/cjs/git-push.d.ts

@@ -0,0 +1 @@
+export declare function pushLocalDir(sourceDir: string, cloneUrl: string, token: string, branch?: string): void;

package/dist/cjs/git-push.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushLocalDir = pushLocalDir;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+function pushLocalDir(sourceDir, cloneUrl, token, branch = 'main') {
+    const gitDir = (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'sbxprev-git-'));
+    const git = (args) => {
+        try {
+            (0, node_child_process_1.execFileSync)('git', ['--git-dir', gitDir, '--work-tree', sourceDir, ...args], { stdio: 'pipe' });
+        }
+        catch (err) {
+            const stderr = err.stderr?.toString().trim();
+            throw new errors_js_1.PreviewOperationError({
+                code: 'GIT_PUSH_FAILED',
+                message: `git ${args[0]} failed while pushing to the Sapiom repo.`,
+                hint: stderr || (err instanceof Error ? err.message : String(err)),
+            });
+        }
+    };
+    try {
+        git(['init', '-q', '-b', branch]);
+        (0, node_fs_1.mkdirSync)(node_path_1.default.join(gitDir, 'info'), { recursive: true });
+        (0, node_fs_1.writeFileSync)(node_path_1.default.join(gitDir, 'info', 'exclude'), 'node_modules/\n.git/\n');
+        git(['add', '-A']);
+        git(['-c', 'user.email=preview@sapiom.ai', '-c', 'user.name=sapiom-preview', 'commit', '-q', '-m', 'preview']);
+        git(['-c', `http.extraHeader=x-sapiom-git-token: ${token}`, 'push', '--force', cloneUrl, `HEAD:${branch}`]);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(gitDir, { recursive: true, force: true });
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,8 @@
+export { previewSandbox } from './preview.js';
+export type { PreviewSandboxOptions } from './preview.js';
+export { getSandbox, readSandboxes, writeSandbox, configureSandbox, checkSandboxes, CONFIG_FILE } from './config.js';
+export { sandboxConfigBodySchema, storedSandboxSchema, CONFIG_VERSION } from './schema.js';
+export type { SandboxConfigBody } from './schema.js';
+export { PreviewOperationError } from './errors.js';
+export type { StructuredError } from './errors.js';
+export type { SandboxConfig, SandboxSourceSpec, PreviewResult } from './types.js';

package/dist/cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewOperationError = exports.CONFIG_VERSION = exports.storedSandboxSchema = exports.sandboxConfigBodySchema = exports.CONFIG_FILE = exports.checkSandboxes = exports.configureSandbox = exports.writeSandbox = exports.readSandboxes = exports.getSandbox = exports.previewSandbox = void 0;
+var preview_js_1 = require("./preview.js");
+Object.defineProperty(exports, "previewSandbox", { enumerable: true, get: function () { return preview_js_1.previewSandbox; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "getSandbox", { enumerable: true, get: function () { return config_js_1.getSandbox; } });
+Object.defineProperty(exports, "readSandboxes", { enumerable: true, get: function () { return config_js_1.readSandboxes; } });
+Object.defineProperty(exports, "writeSandbox", { enumerable: true, get: function () { return config_js_1.writeSandbox; } });
+Object.defineProperty(exports, "configureSandbox", { enumerable: true, get: function () { return config_js_1.configureSandbox; } });
+Object.defineProperty(exports, "checkSandboxes", { enumerable: true, get: function () { return config_js_1.checkSandboxes; } });
+Object.defineProperty(exports, "CONFIG_FILE", { enumerable: true, get: function () { return config_js_1.CONFIG_FILE; } });
+var schema_js_1 = require("./schema.js");
+Object.defineProperty(exports, "sandboxConfigBodySchema", { enumerable: true, get: function () { return schema_js_1.sandboxConfigBodySchema; } });
+Object.defineProperty(exports, "storedSandboxSchema", { enumerable: true, get: function () { return schema_js_1.storedSandboxSchema; } });
+Object.defineProperty(exports, "CONFIG_VERSION", { enumerable: true, get: function () { return schema_js_1.CONFIG_VERSION; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "PreviewOperationError", { enumerable: true, get: function () { return errors_js_1.PreviewOperationError; } });

package/dist/cjs/preview.d.ts

@@ -0,0 +1,9 @@
+import type { PreviewResult } from './types.js';
+export interface PreviewSandboxOptions {
+    dir: string;
+    name?: string;
+    apiKey?: string;
+    servicesBaseUrl?: string;
+    log?: (message: string) => void;
+}
+export declare function previewSandbox(opts: PreviewSandboxOptions): Promise<PreviewResult>;

package/dist/cjs/preview.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewSandbox = previewSandbox;
+const node_path_1 = __importDefault(require("node:path"));
+const tools_1 = require("@sapiom/tools");
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+const git_push_js_1 = require("./git-push.js");
+const RUNNING_TIMEOUT_MS = 120000;
+const RUNNING_POLL_MS = 2000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function previewSandbox(opts) {
+    const cfg = (0, config_js_1.getSandbox)(opts.dir, opts.name);
+    const log = opts.log ?? (() => { });
+    const sapiom = (0, tools_1.createClient)({ apiKey: opts.apiKey });
+    const baseUrl = opts.servicesBaseUrl;
+    const sub = cfg.source.path ?? '.';
+    const sourceDir = node_path_1.default.resolve(opts.dir, sub);
+    let deploySource;
+    if (cfg.source.kind === 'git') {
+        const slug = cfg.source.slug;
+        log(`ensuring repo "${slug}" …`);
+        const repo = await sapiom.repositories.get(slug).catch(() => null);
+        const cloneUrl = repo?.cloneUrl ?? (await sapiom.repositories.create(slug)).cloneUrl;
+        log(`pushing ${sub} → repo "${slug}" …`);
+        (0, git_push_js_1.pushLocalDir)(sourceDir, cloneUrl, opts.apiKey ?? '');
+        deploySource = { kind: 'git', repo: slug };
+    }
+    log(`ensuring sandbox "${cfg.name}" …`);
+    await ensureRunning(sapiom, cfg, baseUrl, log);
+    const box = sapiom.sandboxes.attach(cfg.name, baseUrl ? { baseUrl } : {});
+    if (cfg.source.kind === 'upload') {
+        log(`uploading ${sub} …`);
+        await box.uploadDir(sourceDir);
+    }
+    log('deploying …');
+    const res = await box.deployPreview({
+        ...(deploySource ? { source: deploySource } : {}),
+        build: cfg.build,
+        start: cfg.start,
+        port: cfg.port,
+        env: cfg.env,
+    });
+    return { name: cfg.name, url: res.url, status: res.status, logs: res.logs };
+}
+async function ensureRunning(sapiom, cfg, baseUrl, log) {
+    const getOpts = baseUrl ? { baseUrl } : {};
+    const existing = await sapiom.sandboxes.get(cfg.name, getOpts).catch(() => null);
+    if (!existing) {
+        log(`creating sandbox "${cfg.name}" …`);
+        const createArgs = {
+            name: cfg.name,
+            port: cfg.port,
+            ...(cfg.tier ? { tier: cfg.tier } : {}),
+            ...(cfg.ttl ? { ttl: cfg.ttl } : {}),
+            ...(baseUrl ? { baseUrl } : {}),
+        };
+        await sapiom.sandboxes.create(createArgs);
+    }
+    const deadline = Date.now() + RUNNING_TIMEOUT_MS;
+    for (;;) {
+        const info = await sapiom.sandboxes.get(cfg.name, getOpts);
+        if (info.status === 'running')
+            return;
+        if (info.status === 'failed') {
+            throw new errors_js_1.PreviewOperationError({
+                code: 'SANDBOX_FAILED',
+                message: `Sandbox '${cfg.name}' failed to start.`,
+                hint: info.error,
+            });
+        }
+        if (Date.now() > deadline) {
+            throw new errors_js_1.PreviewOperationError({
+                code: 'SANDBOX_NOT_READY',
+                message: `Sandbox '${cfg.name}' did not reach 'running' in time (status: ${info.status}).`,
+            });
+        }
+        await sleep(RUNNING_POLL_MS);
+    }
+}

package/dist/cjs/schema.d.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+export declare const CONFIG_VERSION = 1;
+export declare const sandboxConfigBodySchema: z.ZodObject<{
+    source: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "upload";
+        path?: string | undefined;
+    }, {
+        kind: "upload";
+        path?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"git">;
+        slug: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    }, {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    }>]>;
+    build: z.ZodOptional<z.ZodString>;
+    start: z.ZodString;
+    port: z.ZodNumber;
+    tier: z.ZodOptional<z.ZodEnum<["xs", "s", "m", "l", "xl"]>>;
+    ttl: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    source: {
+        kind: "upload";
+        path?: string | undefined;
+    } | {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    };
+    start: string;
+    port: number;
+    build?: string | undefined;
+    tier?: "xs" | "s" | "m" | "l" | "xl" | undefined;
+    ttl?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    source: {
+        kind: "upload";
+        path?: string | undefined;
+    } | {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    };
+    start: string;
+    port: number;
+    build?: string | undefined;
+    tier?: "xs" | "s" | "m" | "l" | "xl" | undefined;
+    ttl?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+export type SandboxConfigBody = z.infer<typeof sandboxConfigBodySchema>;
+export declare const storedSandboxSchema: z.ZodObject<{
+    source: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "upload";
+        path?: string | undefined;
+    }, {
+        kind: "upload";
+        path?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"git">;
+        slug: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    }, {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    }>]>;
+    build: z.ZodOptional<z.ZodString>;
+    start: z.ZodString;
+    port: z.ZodNumber;
+    tier: z.ZodOptional<z.ZodEnum<["xs", "s", "m", "l", "xl"]>>;
+    ttl: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+} & {
+    type: z.ZodLiteral<"sandbox">;
+}, "strip", z.ZodTypeAny, {
+    type: "sandbox";
+    source: {
+        kind: "upload";
+        path?: string | undefined;
+    } | {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    };
+    start: string;
+    port: number;
+    build?: string | undefined;
+    tier?: "xs" | "s" | "m" | "l" | "xl" | undefined;
+    ttl?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: "sandbox";
+    source: {
+        kind: "upload";
+        path?: string | undefined;
+    } | {
+        kind: "git";
+        slug: string;
+        path?: string | undefined;
+    };
+    start: string;
+    port: number;
+    build?: string | undefined;
+    tier?: "xs" | "s" | "m" | "l" | "xl" | undefined;
+    ttl?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>;

package/dist/cjs/schema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storedSandboxSchema = exports.sandboxConfigBodySchema = exports.CONFIG_VERSION = void 0;
+const zod_1 = require("zod");
+exports.CONFIG_VERSION = 1;
+const sourceSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('upload'), path: zod_1.z.string().optional() }),
+    zod_1.z.object({ kind: zod_1.z.literal('git'), slug: zod_1.z.string().min(1), path: zod_1.z.string().optional() }),
+]);
+exports.sandboxConfigBodySchema = zod_1.z.object({
+    source: sourceSchema,
+    build: zod_1.z.string().optional(),
+    start: zod_1.z.string().min(1, 'start (the server command) is required'),
+    port: zod_1.z.number().int().min(1).max(65535),
+    tier: zod_1.z.enum(['xs', 's', 'm', 'l', 'xl']).optional(),
+    ttl: zod_1.z.string().optional(),
+    env: zod_1.z.record(zod_1.z.string()).optional(),
+});
+exports.storedSandboxSchema = exports.sandboxConfigBodySchema.extend({ type: zod_1.z.literal('sandbox') });

package/dist/cjs/types.d.ts

@@ -0,0 +1,11 @@
+import type { SandboxConfigBody } from './schema.js';
+export type SandboxSourceSpec = SandboxConfigBody['source'];
+export type SandboxConfig = {
+    name: string;
+} & SandboxConfigBody;
+export interface PreviewResult {
+    name: string;
+    url: string | null;
+    status: string;
+    logs: string;
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/config.d.ts

@@ -0,0 +1,12 @@
+import { type SandboxConfigBody } from './schema.js';
+import type { SandboxConfig } from './types.js';
+export declare const CONFIG_FILE = "sapiom.json";
+export declare function readSandboxes(dir: string): Record<string, SandboxConfig>;
+export declare function getSandbox(dir: string, name?: string): SandboxConfig;
+export declare function configureSandbox(dir: string, name: string, body: SandboxConfigBody): SandboxConfig;
+export declare const writeSandbox: (dir: string, cfg: SandboxConfig) => SandboxConfig;
+export declare function checkSandboxes(dir: string): {
+    ok: boolean;
+    sandboxes: string[];
+    issues: string[];
+};

package/dist/esm/config.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { PreviewOperationError } from './errors.js';
+import { CONFIG_VERSION, storedSandboxSchema } from './schema.js';
+export const CONFIG_FILE = 'sapiom.json';
+function readFile(dir) {
+    const file = path.join(dir, CONFIG_FILE);
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new PreviewOperationError({ code: 'BAD_CONFIG', message: `${CONFIG_FILE} is not valid JSON.` });
+    }
+    if (typeof parsed.version === 'number' && parsed.version > CONFIG_VERSION) {
+        throw new PreviewOperationError({
+            code: 'UNSUPPORTED_CONFIG_VERSION',
+            message: `${CONFIG_FILE} is version ${parsed.version}, but this tool supports up to ${CONFIG_VERSION}.`,
+            hint: 'Upgrade the Sapiom SDK/CLI.',
+        });
+    }
+    return parsed;
+}
+function parseSandboxEntry(name, entry) {
+    const result = storedSandboxSchema.safeParse(entry);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((i) => `${['resources', name, ...i.path].join('.')}: ${i.message}`)
+            .join('; ');
+        throw new PreviewOperationError({
+            code: 'INVALID_SANDBOX',
+            message: `Invalid sandbox resource "${name}" in ${CONFIG_FILE}.`,
+            hint: detail,
+        });
+    }
+    const { type: _type, ...body } = result.data;
+    return { name, ...body };
+}
+export function readSandboxes(dir) {
+    const cfg = readFile(dir);
+    const resources = cfg?.resources ?? {};
+    const out = {};
+    for (const [name, entry] of Object.entries(resources)) {
+        if (entry?.type !== 'sandbox')
+            continue;
+        out[name] = parseSandboxEntry(name, entry);
+    }
+    return out;
+}
+export function getSandbox(dir, name) {
+    const sandboxes = readSandboxes(dir);
+    const names = Object.keys(sandboxes);
+    if (name) {
+        const found = sandboxes[name];
+        if (!found) {
+            throw new PreviewOperationError({
+                code: 'NO_SANDBOX',
+                message: `No sandbox named '${name}' in ${CONFIG_FILE}.`,
+                hint: names.length ? `Known sandboxes: ${names.join(', ')}.` : undefined,
+            });
+        }
+        return found;
+    }
+    if (names.length === 0) {
+        throw new PreviewOperationError({
+            code: 'NO_SANDBOX',
+            message: `No sandbox resources defined in ${CONFIG_FILE}.`,
+            hint: 'Add one with sapiom_dev_sandbox_configure (or a "type":"sandbox" resource).',
+        });
+    }
+    if (names.length > 1) {
+        throw new PreviewOperationError({
+            code: 'AMBIGUOUS_SANDBOX',
+            message: `Multiple sandboxes defined (${names.join(', ')}); specify which one.`,
+            hint: 'Pass a name, e.g. `sapiom sandbox preview <name>`.',
+        });
+    }
+    return sandboxes[names[0]];
+}
+export function configureSandbox(dir, name, body) {
+    const parsed = storedSandboxSchema.safeParse({ type: 'sandbox', ...body });
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        throw new PreviewOperationError({
+            code: 'INVALID_SANDBOX',
+            message: `Invalid sandbox configuration for "${name}".`,
+            hint: detail,
+        });
+    }
+    const existing = readFile(dir) ?? {};
+    const next = {
+        version: CONFIG_VERSION,
+        ...existing,
+        resources: { ...(existing.resources ?? {}), [name]: parsed.data },
+    };
+    next.version = CONFIG_VERSION;
+    writeFileSync(path.join(dir, CONFIG_FILE), JSON.stringify(next, null, 2) + '\n');
+    return { name, ...body };
+}
+export const writeSandbox = (dir, cfg) => {
+    const { name, ...body } = cfg;
+    return configureSandbox(dir, name, body);
+};
+export function checkSandboxes(dir) {
+    const issues = [];
+    const cfg = readFile(dir);
+    const resources = cfg?.resources ?? {};
+    const found = [];
+    for (const [name, entry] of Object.entries(resources)) {
+        if (entry?.type !== 'sandbox')
+            continue;
+        found.push(name);
+        const r = storedSandboxSchema.safeParse(entry);
+        if (!r.success) {
+            for (const i of r.error.issues)
+                issues.push(`resources.${name}.${i.path.join('.')}: ${i.message}`);
+        }
+    }
+    return { ok: issues.length === 0, sandboxes: found, issues };
+}